feat(analysis): add frame statistics, colour temperature and exposure processor

FrameStatistics: trimmed log2-luminance mean (fine weighted histogram),
256-bin log histogram, clip fractions, channel means, CCT, Laplacian
variance sharpness, Immerkaer noise, mask-weighted region statistics,
black/white/duplicate helpers. ColorTemperature: McCamy seed refined to
the nearest Krystek Planckian-locus point with a |Duv| <= 0.02 check.
ExposureProcessor: SIMD EV/white-balance/region gains and hue-preserving
highlight soft clip.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:51:43 +00:00
1 parent cce38c3927
commit 40870e12dc
5 files changed
+702

No files matched your search

+51
View File
@@ -0,0 +1,51 @@
using Titano.Core.Imaging;
namespace Titano.Core.Analysis;
/// <summary>Builds the reduced-size images that analysis passes measure.</summary>
public static class AnalysisImage
{
/// <summary>
/// Area-average (box) downscale by the smallest integer factor that brings the long edge to at most
/// <paramref name="maxLongEdge"/>. Exact for flat fields; trailing rows/columns that do not fill a block are
/// dropped. Returns a copy when no reduction is needed.
/// </summary>
public static ImageBuffer Downscale(ImageBuffer source, int maxLongEdge)
{
ArgumentNullException.ThrowIfNull(source);
ArgumentOutOfRangeException.ThrowIfLessThan(maxLongEdge, 1);
var factor = (Math.Max(source.Width, source.Height) + maxLongEdge - 1) / maxLongEdge;
if (factor <= 1) return source.Clone();
var fx = Math.Min(factor, source.Width);
var fy = Math.Min(factor, source.Height);
var width = source.Width / fx;
var height = source.Height / fy;
var result = new ImageBuffer(width, height, source.Channels, clear: false);
var scale = 1f / (fx * fy);
void Row(int index)
{
var c = index / height;
var y = index % height;
var target = result.Row(c, y);
target.Clear();
for (var dy = 0; dy < fy; dy++)
{
var src = source.Row(c, y * fy + dy);
for (var x = 0; x < width; x++)
{
var block = src.Slice(x * fx, fx);
var sum = 0f;
foreach (var v in block) sum += v;
target[x] += sum;
}
}
foreach (ref var v in target) v *= scale;
}
var rows = height * source.Channels;
if ((long)source.PlaneLength * source.Channels >= 1 << 20) Parallel.For(0, rows, Row);
else for (var i = 0; i < rows; i++) Row(i);
return result;
}
}
@@ -0,0 +1,118 @@
using Titano.Core.Mathematics;
namespace Titano.Core.Analysis;
/// <summary>Correlated colour temperature of a near-Planckian colour.</summary>
/// <param name="Kelvin">CCT: temperature of the nearest Planckian-locus point in CIE 1960 uv.</param>
/// <param name="McCamyKelvin">McCamy's cubic estimate the search started from.</param>
/// <param name="Duv">Signed uv distance from the locus (positive towards green).</param>
public readonly record struct ColorTemperatureEstimate(double Kelvin, double McCamyKelvin, double Duv);
/// <summary>
/// Colour temperature from chromaticity: McCamy (1992) cubic as the starting point, refined to the closest point
/// of the Planckian locus (Krystek 1985 rational approximation, 1000–15000 K) in CIE 1960 uv. Colours farther than
/// <see cref="MaxDuv"/> from the locus have no meaningful CCT and are rejected.
/// </summary>
public static class ColorTemperature
{
/// <summary>Validity limit on |Duv| (ANSI C78.377 uses ±0.02 as the edge of "white" light).</summary>
public const double MaxDuv = 0.02;
public const double MinKelvin = 1000;
public const double MaxKelvin = 15000;
/// <summary>McCamy's cubic CCT approximation from CIE 1931 xy (epicentre 0.3320, 0.1858).</summary>
public static double McCamy(Chromaticity xy)
{
var n = (xy.X - 0.3320) / (0.1858 - xy.Y);
return ((449 * n + 3525) * n + 6823.3) * n + 5520.33;
}
/// <summary>Planckian locus in CIE 1960 uv (Krystek 1985; |Δu|, |Δv| &lt; 1e-4 over 1000–15000 K).</summary>
public static (double U, double V) PlanckianUv(double kelvin)
{
var t = kelvin;
var u = (0.860117757 + 1.54118254e-4 * t + 1.28641212e-7 * t * t) / (1 + 8.42420235e-4 * t + 7.08145163e-7 * t * t);
var v = (0.317398726 + 4.22806245e-5 * t + 4.20481691e-8 * t * t) / (1 - 2.89741816e-5 * t + 1.61456053e-7 * t * t);
return (u, v);
}
public static Chromaticity PlanckianChromaticity(double kelvin)
{
var (u, v) = PlanckianUv(kelvin);
return Chromaticity.FromUv1960(u, v);
}
/// <summary>Linear Rec.709 RGB of a Planckian radiator's chromaticity, scaled to luminance 1.</summary>
public static Vector3D PlanckianRgb(double kelvin) => Matrix3.XyzToRec709 * PlanckianChromaticity(kelvin).ToXyz();
/// <summary>Estimate from a chromaticity; null outside the locus range or beyond <see cref="MaxDuv"/>.</summary>
public static ColorTemperatureEstimate? Estimate(Chromaticity xy)
{
if (!double.IsFinite(xy.X) || !double.IsFinite(xy.Y) || !(xy.Y > 0)) return null;
var mcCamy = McCamy(xy);
if (!(mcCamy >= MinKelvin && mcCamy <= MaxKelvin)) return null;
var (u, v) = xy.ToUv1960();
// Golden-section search in mireds (the locus is far more uniform in 1/T) around the McCamy seed.
var seed = 1e6 / mcCamy;
double lo = Math.Max(1e6 / MaxKelvin, seed - 40), hi = Math.Min(1e6 / MinKelvin, seed + 40);
const double ratio = 0.6180339887498949;
var a = hi - ratio * (hi - lo);
var b = lo + ratio * (hi - lo);
double fa = Distance2(u, v, a), fb = Distance2(u, v, b);
while (hi - lo > 1e-7)
{
if (fa <= fb)
{
hi = b;
b = a;
fb = fa;
a = hi - ratio * (hi - lo);
fa = Distance2(u, v, a);
}
else
{
lo = a;
a = b;
fa = fb;
b = lo + ratio * (hi - lo);
fb = Distance2(u, v, b);
}
}
var kelvin = 1e6 / (0.5 * (lo + hi));
var duv = SignedDistance(u, v, kelvin);
if (!(Math.Abs(duv) <= MaxDuv)) return null;
return new ColorTemperatureEstimate(kelvin, mcCamy, duv);
}
/// <summary>Estimate from mean linear Rec.709 RGB; null for non-positive or off-locus colours.</summary>
public static ColorTemperatureEstimate? Estimate(double red, double green, double blue)
{
if (!(red > 0 && green > 0 && blue > 0) || !double.IsFinite(red + green + blue)) return null;
return Estimate(Chromaticity.FromXyz(Matrix3.Rec709ToXyz * new Vector3D(red, green, blue)));
}
private static double Distance2(double u, double v, double mired)
{
var (pu, pv) = PlanckianUv(1e6 / mired);
return (u - pu) * (u - pu) + (v - pv) * (v - pv);
}
/// <summary>Distance to the locus point at <paramref name="kelvin"/>, signed by the side of the locus normal
/// that points to larger v (the green side).</summary>
private static double SignedDistance(double u, double v, double kelvin)
{
var (pu, pv) = PlanckianUv(kelvin);
var (qu, qv) = PlanckianUv(kelvin * 1.001);
// Normal to the locus tangent, oriented towards +v.
double nu = pv - qv, nv = qu - pu;
if (nv < 0)
{
nu = -nu;
nv = -nv;
}
var distance = Math.Sqrt((u - pu) * (u - pu) + (v - pv) * (v - pv));
return (u - pu) * nu + (v - pv) * nv >= 0 ? distance : -distance;
}
}
@@ -0,0 +1,149 @@
using System.Numerics;
using System.Runtime.InteropServices;
using Titano.Core.Imaging;
namespace Titano.Core.Analysis;
/// <summary>Per-channel multiplicative gains in linear light (white balance).</summary>
public readonly record struct ChannelGains(double Red, double Green, double Blue)
{
public static ChannelGains Identity { get; } = new(1, 1, 1);
}
/// <summary>
/// Applies per-frame corrections to linear-light images in place: an EV gain, white-balance channel gains, sky/land
/// gains blended through a soft mask, and an optional hue-preserving highlight soft clip. Vectorised with
/// <see cref="Vector{T}"/>; large images are split across cores. A fourth (alpha) channel is left untouched.
/// </summary>
public static class ExposureProcessor
{
private const int ParallelThreshold = 1 << 20;
private const int Chunk = 1 << 16;
/// <param name="softClipKnee">When set (0 &lt; knee &lt; 1), values above the knee roll off smoothly towards 1.</param>
public static void Apply(ImageBuffer image, double ev, ChannelGains? gains = null, double? softClipKnee = null)
{
ArgumentNullException.ThrowIfNull(image);
var factors = Factors(image, ev, gains);
var knee = Knee(softClipKnee);
ForChunks(image.PlaneLength, (start, length) =>
{
for (var c = 0; c < factors.Length; c++) Scale(image.Plane(c).Slice(start, length), factors[c]);
if (knee is { } k && image.Channels >= 3) SoftClip(image, start, length, k);
});
}
/// <summary>
/// Sky/land correction: per pixel the gain is 2^landEv + m·(2^skyEv − 2^landEv) with m the sky weight, i.e.
/// gains blend linearly across the feathered transition.
/// </summary>
public static void ApplyRegion(ImageBuffer image, ReadOnlyMemory<float> skyMask, double skyEv, double landEv, ChannelGains? gains = null, double? softClipKnee = null)
{
ArgumentNullException.ThrowIfNull(image);
if (skyMask.Length != image.PlaneLength) throw new ArgumentException("Mask must have one weight per pixel.", nameof(skyMask));
if (!double.IsFinite(skyEv)) throw new ArgumentOutOfRangeException(nameof(skyEv));
var land = Factors(image, landEv, gains);
var sky = Factors(image, skyEv, gains);
var knee = Knee(softClipKnee);
ForChunks(image.PlaneLength, (start, length) =>
{
var m = skyMask.Span.Slice(start, length);
for (var c = 0; c < land.Length; c++) Blend(image.Plane(c).Slice(start, length), m, land[c], sky[c] - land[c]);
if (knee is { } k && image.Channels >= 3) SoftClip(image, start, length, k);
});
}
/// <summary>Scalar reference of the soft clip: identity up to the knee, then knee + e/(1 + e/(1 − knee)) with
/// e = value − knee, which is C¹ at the knee and approaches 1 asymptotically.</summary>
public static float SoftClip(float value, float knee)
{
if (!(value > knee)) return value;
var excess = value - knee;
return knee + excess / (1 + excess / (1 - knee));
}
private static float[] Factors(ImageBuffer image, double ev, ChannelGains? gains)
{
if (!double.IsFinite(ev)) throw new ArgumentOutOfRangeException(nameof(ev));
var scale = Math.Pow(2, ev);
if (image.Channels == 1) return [(float)scale];
var g = gains ?? ChannelGains.Identity;
if (!(g.Red > 0 && g.Green > 0 && g.Blue > 0) || !double.IsFinite(g.Red + g.Green + g.Blue))
throw new ArgumentOutOfRangeException(nameof(gains), "Gains must be positive and finite.");
return [(float)(scale * g.Red), (float)(scale * g.Green), (float)(scale * g.Blue)];
}
private static float? Knee(double? knee)
{
if (knee is not { } k) return null;
if (!(k > 0 && k < 1)) throw new ArgumentOutOfRangeException(nameof(knee), "Knee must lie in (0, 1).");
return (float)k;
}
private static void ForChunks(int length, Action<int, int> body)
{
if (length < ParallelThreshold)
{
body(0, length);
return;
}
var chunks = (length + Chunk - 1) / Chunk;
Parallel.For(0, chunks, i =>
{
var start = i * Chunk;
body(start, Math.Min(Chunk, length - start));
});
}
private static void Scale(Span<float> data, float factor)
{
var vectors = MemoryMarshal.Cast<float, Vector<float>>(data);
var f = new Vector<float>(factor);
for (var i = 0; i < vectors.Length; i++) vectors[i] *= f;
for (var i = vectors.Length * Vector<float>.Count; i < data.Length; i++) data[i] *= factor;
}
private static void Blend(Span<float> data, ReadOnlySpan<float> mask, float baseFactor, float delta)
{
var vectors = MemoryMarshal.Cast<float, Vector<float>>(data);
var masks = MemoryMarshal.Cast<float, Vector<float>>(mask);
var b = new Vector<float>(baseFactor);
var d = new Vector<float>(delta);
for (var i = 0; i < vectors.Length; i++) vectors[i] *= b + masks[i] * d;
for (var i = vectors.Length * Vector<float>.Count; i < data.Length; i++) data[i] *= baseFactor + mask[i] * delta;
}
/// <summary>Compresses the largest channel with <see cref="SoftClip(float, float)"/> and scales all three
/// channels by the same ratio, so hue and saturation are kept.</summary>
private static void SoftClip(ImageBuffer image, int start, int length, float knee)
{
var r = image.Plane(0).Slice(start, length);
var g = image.Plane(1).Slice(start, length);
var b = image.Plane(2).Slice(start, length);
var vr = MemoryMarshal.Cast<float, Vector<float>>(r);
var vg = MemoryMarshal.Cast<float, Vector<float>>(g);
var vb = MemoryMarshal.Cast<float, Vector<float>>(b);
var k = new Vector<float>(knee);
var inverseRange = new Vector<float>(1 / (1 - knee));
for (var i = 0; i < vr.Length; i++)
{
var m = Vector.Max(vr[i], Vector.Max(vg[i], vb[i]));
if (!Vector.GreaterThanAny(m, k)) continue;
var excess = m - k;
var ratio = (k + excess / (Vector<float>.One + excess * inverseRange)) / m;
var s = Vector.ConditionalSelect(Vector.GreaterThan(m, k), ratio, Vector<float>.One);
vr[i] *= s;
vg[i] *= s;
vb[i] *= s;
}
for (var i = vr.Length * Vector<float>.Count; i < length; i++)
{
var m = MathF.Max(r[i], MathF.Max(g[i], b[i]));
if (!(m > knee)) continue;
var s = SoftClip(m, knee) / m;
r[i] *= s;
g[i] *= s;
b[i] *= s;
}
}
}
+268
View File
@@ -0,0 +1,268 @@
using Titano.Core.Imaging;
using Titano.Core.Mathematics;
namespace Titano.Core.Analysis;
/// <summary>Thresholds for <see cref="FrameStatistics.Measure"/>.</summary>
public sealed record FrameStatisticsOptions
{
public static FrameStatisticsOptions Default { get; } = new();
/// <summary>Weight fraction trimmed from the dark end of the log-luminance distribution.</summary>
public double TrimLow { get; init; } = 0.02;
/// <summary>Weight fraction trimmed from the bright end.</summary>
public double TrimHigh { get; init; } = 0.02;
/// <summary>A pixel is crushed when every channel is below this linear level (1/1024 ≈ −10 EV).</summary>
public double ClipLowLevel { get; init; } = 1.0 / 1024;
/// <summary>A pixel is clipped when any channel reaches this fraction of <see cref="WhiteLevel"/>.</summary>
public double ClipHighFraction { get; init; } = 0.98;
public double WhiteLevel { get; init; } = 1.0;
}
/// <summary>
/// Per-frame (or per-region) measurements of the deep analysis (BRIEF §10.2), taken in one pass over a
/// downscaled linear-light image (see <see cref="AnalysisImage"/>) plus one 3×3 neighbourhood pass.
/// </summary>
public sealed record FrameStatistics
{
public const int HistogramBins = 256;
/// <summary>Lower edge of the log-luminance histogram, in EV relative to linear 1.0.</summary>
public const double HistogramMinEv = -14;
/// <summary>Upper edge of the log-luminance histogram, in EV relative to linear 1.0.</summary>
public const double HistogramMaxEv = 2;
public int Width { get; init; }
public int Height { get; init; }
/// <summary>Total sample weight: pixel count, or the mask sum for region statistics.</summary>
public double Weight { get; init; }
/// <summary>Mean of log2 luminance after trimming both tails (luminance floored at 2⁻¹⁴).</summary>
public double MeanLogLuminance { get; init; }
/// <summary>Weight fraction per bin of log2 luminance over [−14, +2) EV; sums to 1.</summary>
public double[] Histogram { get; init; } = [];
public double ClipLowFraction { get; init; }
public double ClipHighFraction { get; init; }
public double MeanRed { get; init; }
public double MeanGreen { get; init; }
public double MeanBlue { get; init; }
/// <summary>Correlated colour temperature of the mean colour; null when it is not near-Planckian.</summary>
public ColorTemperatureEstimate? ColorTemperature { get; init; }
/// <summary>Variance of the 4-neighbour Laplacian of sRGB-encoded luminance (focus/blur measure).</summary>
public double Sharpness { get; init; }
/// <summary>Noise standard deviation of sRGB-encoded luminance, Immerkær (1996) fast estimator.</summary>
public double Noise { get; init; }
/// <summary>Nearly every pixel is crushed (lens cap, missed exposure).</summary>
public bool IsBlack(double fraction = 0.95) => ClipLowFraction >= fraction;
/// <summary>Nearly every pixel is clipped (blown exposure).</summary>
public bool IsWhite(double fraction = 0.95) => ClipHighFraction >= fraction;
/// <summary>
/// True when two frames have practically identical statistics (histogram, level, colour, detail, noise): a
/// cheap duplicate test before any pixel or hash comparison.
/// </summary>
public static bool AreLikelyDuplicates(FrameStatistics a, FrameStatistics b, double tolerance = 1e-6)
{
ArgumentNullException.ThrowIfNull(a);
ArgumentNullException.ThrowIfNull(b);
if (a.Width != b.Width || a.Height != b.Height || a.Histogram.Length != b.Histogram.Length) return false;
static bool Close(double x, double y, double tolerance) => Math.Abs(x - y) <= tolerance * (1 + Math.Abs(x) + Math.Abs(y));
return Close(a.MeanLogLuminance, b.MeanLogLuminance, tolerance)
&& Statistics.ChiSquareDistance(a.Histogram, b.Histogram) <= tolerance
&& Close(a.MeanRed, b.MeanRed, tolerance)
&& Close(a.MeanGreen, b.MeanGreen, tolerance)
&& Close(a.MeanBlue, b.MeanBlue, tolerance)
&& Close(a.Sharpness, b.Sharpness, tolerance)
&& Close(a.Noise, b.Noise, tolerance);
}
/// <summary>Measures an image, optionally weighted by a per-pixel <paramref name="mask"/> in [0, 1].</summary>
public static FrameStatistics Measure(ImageBuffer image, ReadOnlySpan<float> mask = default, FrameStatisticsOptions? options = null)
{
ArgumentNullException.ThrowIfNull(image);
options ??= FrameStatisticsOptions.Default;
ValidateMask(image, mask);
var n = image.PlaneLength;
var r = image.Plane(0);
var g = image.Channels >= 3 ? image.Plane(1) : r;
var b = image.Channels >= 3 ? image.Plane(2) : r;
var low = (float)options.ClipLowLevel;
var high = (float)(options.ClipHighFraction * options.WhiteLevel);
var histogram = new LogHistogram();
var encoded = new float[n];
double weight = 0, clipLow = 0, clipHigh = 0, sumR = 0, sumG = 0, sumB = 0;
for (var i = 0; i < n; i++)
{
var w = mask.IsEmpty ? 1f : mask[i];
var y = ColorSpace.Luminance(r[i], g[i], b[i]);
encoded[i] = ColorSpace.EncodeFast(y);
if (!(w > 0)) continue;
weight += w;
histogram.Add(y, w);
var max = MathF.Max(r[i], MathF.Max(g[i], b[i]));
if (max < low) clipLow += w;
if (max >= high) clipHigh += w;
sumR += w * r[i];
sumG += w * g[i];
sumB += w * b[i];
}
var (sharpness, noise) = Detail(encoded, image.Width, image.Height, mask);
var inverse = weight > 0 ? 1 / weight : double.NaN;
var meanR = sumR * inverse;
var meanG = sumG * inverse;
var meanB = sumB * inverse;
return new FrameStatistics
{
Width = image.Width,
Height = image.Height,
Weight = weight,
MeanLogLuminance = histogram.TrimmedMean(options.TrimLow, options.TrimHigh),
Histogram = histogram.Coarse(HistogramBins),
ClipLowFraction = clipLow * inverse,
ClipHighFraction = clipHigh * inverse,
MeanRed = meanR,
MeanGreen = meanG,
MeanBlue = meanB,
ColorTemperature = image.Channels >= 3 ? Analysis.ColorTemperature.Estimate(meanR, meanG, meanB) : null,
Sharpness = sharpness,
Noise = noise,
};
}
/// <summary>Only the trimmed mean of log2 luminance (the deflicker signal), optionally mask-weighted.</summary>
public static double MeasureLogLuminance(ImageBuffer image, ReadOnlySpan<float> mask = default, double trimLow = 0.02, double trimHigh = 0.02)
{
ArgumentNullException.ThrowIfNull(image);
ValidateMask(image, mask);
var r = image.Plane(0);
var g = image.Channels >= 3 ? image.Plane(1) : r;
var b = image.Channels >= 3 ? image.Plane(2) : r;
var histogram = new LogHistogram();
for (var i = 0; i < r.Length; i++)
{
var w = mask.IsEmpty ? 1f : mask[i];
if (w > 0) histogram.Add(ColorSpace.Luminance(r[i], g[i], b[i]), w);
}
return histogram.TrimmedMean(trimLow, trimHigh);
}
private static void ValidateMask(ImageBuffer image, ReadOnlySpan<float> mask)
{
if (!mask.IsEmpty && mask.Length != image.PlaneLength)
throw new ArgumentException("Mask must have one weight per pixel.", nameof(mask));
}
/// <summary>Laplacian variance and Immerkær noise σ over interior pixels, weighted by the mask at the centre.</summary>
private static (double Sharpness, double Noise) Detail(float[] e, int width, int height, ReadOnlySpan<float> mask)
{
if (width < 3 || height < 3) return (0, 0);
double sw = 0, sl = 0, sl2 = 0, sn = 0;
for (var y = 1; y < height - 1; y++)
{
var row = y * width;
for (var x = 1; x < width - 1; x++)
{
var i = row + x;
var w = mask.IsEmpty ? 1f : mask[i];
if (!(w > 0)) continue;
double up = e[i - width], down = e[i + width], left = e[i - 1], right = e[i + 1], c = e[i];
var laplacian = up + down + left + right - 4 * c;
var immerkaer = e[i - width - 1] + e[i - width + 1] + e[i + width - 1] + e[i + width + 1]
- 2 * (up + down + left + right) + 4 * c;
sw += w;
sl += w * laplacian;
sl2 += w * laplacian * laplacian;
sn += w * Math.Abs(immerkaer);
}
}
if (!(sw > 0)) return (0, 0);
var mean = sl / sw;
return (Math.Max(0, sl2 / sw - mean * mean), Math.Sqrt(Math.PI / 2) / 6 * sn / sw);
}
/// <summary>
/// Weighted histogram of log2 luminance with 1/256 EV bins over [−14, +2) that also keeps the weighted sum of
/// the exact log values per bin, so trimmed means are exact except for the one partially trimmed bin per tail.
/// </summary>
private sealed class LogHistogram
{
private const int BinsPerEv = 256;
private const int Count = (int)(HistogramMaxEv - HistogramMinEv) * BinsPerEv;
private readonly double[] _weight = new double[Count];
private readonly double[] _sum = new double[Count];
public void Add(float luminance, float weight)
{
var log = luminance > 6.1035156e-05f ? Math.Log2(luminance) : HistogramMinEv;
var bin = (int)((log - HistogramMinEv) * BinsPerEv);
bin = Math.Clamp(bin, 0, Count - 1);
_weight[bin] += weight;
_sum[bin] += weight * log;
}
public double TrimmedMean(double trimLow, double trimHigh)
{
if (!(trimLow >= 0 && trimHigh >= 0 && trimLow + trimHigh < 1))
throw new ArgumentOutOfRangeException(nameof(trimLow), "Trim fractions must be ≥ 0 and sum below 1.");
double total = 0;
foreach (var w in _weight) total += w;
if (!(total > 0)) return double.NaN;
var kept = (double[])_weight.Clone();
var remaining = trimLow * total;
for (var i = 0; i < Count && remaining > 0; i++)
{
var take = Math.Min(kept[i], remaining);
kept[i] -= take;
remaining -= take;
}
remaining = trimHigh * total;
for (var i = Count - 1; i >= 0 && remaining > 0; i--)
{
var take = Math.Min(kept[i], remaining);
kept[i] -= take;
remaining -= take;
}
double keptWeight = 0, keptSum = 0;
for (var i = 0; i < Count; i++)
{
if (!(kept[i] > 0)) continue;
keptWeight += kept[i];
keptSum += _sum[i] * (kept[i] / _weight[i]);
}
return keptWeight > 0 ? keptSum / keptWeight : double.NaN;
}
/// <summary>Normalised coarse histogram (bins must divide the fine bin count).</summary>
public double[] Coarse(int bins)
{
var result = new double[bins];
var group = Count / bins;
double total = 0;
for (var i = 0; i < Count; i++)
{
result[i / group] += _weight[i];
total += _weight[i];
}
if (total > 0)
{
for (var i = 0; i < bins; i++) result[i] /= total;
}
return result;
}
}
}
@@ -0,0 +1,116 @@
using Titano.Core.Analysis;
using Titano.Core.Imaging;
using Titano.Testing;
namespace Titano.Core.Tests.Analysis;
public sealed class ExposureProcessorTests
{
// 37 × 5 = 185 pixels: not a multiple of any vector width, so the scalar tail runs too.
private static ImageBuffer Ramp(int width = 37, int height = 5, int channels = 3)
{
var image = new ImageBuffer(width, height, channels);
var data = image.Data;
for (var i = 0; i < data.Length; i++) data[i] = 0.001f * (i % 997);
return image;
}
[Test]
public void EvAndChannelGainsMultiply()
{
using var image = Ramp();
using var original = image.Clone();
ExposureProcessor.Apply(image, 1, new ChannelGains(1.5, 1, 0.5));
float[] factors = [3, 2, 1];
for (var c = 0; c < 3; c++)
{
for (var i = 0; i < image.PlaneLength; i++)
Assert.Approximately(factors[c] * original.Plane(c)[i], image.Plane(c)[i], 1e-6);
}
Assert.Throws<ArgumentOutOfRangeException>(() => ExposureProcessor.Apply(image, double.NaN));
Assert.Throws<ArgumentOutOfRangeException>(() => ExposureProcessor.Apply(image, 0, new ChannelGains(0, 1, 1)));
}
[Test]
public void SingleChannelAndAlphaAreHandled()
{
using var grey = Ramp(channels: 1);
using var greyOriginal = grey.Clone();
ExposureProcessor.Apply(grey, -1, new ChannelGains(4, 4, 4));
Assert.Approximately(0.5 * greyOriginal.Plane(0)[100], grey.Plane(0)[100], 1e-7);
using var rgba = Ramp(channels: 4);
using var rgbaOriginal = rgba.Clone();
ExposureProcessor.Apply(rgba, 2);
Assert.SequenceEqual(rgbaOriginal.Plane(3).ToArray(), rgba.Plane(3).ToArray());
Assert.Approximately(4 * rgbaOriginal.Plane(2)[50], rgba.Plane(2)[50], 1e-6);
}
[Test]
public void RegionGainsBlendThroughTheMask()
{
using var image = new ImageBuffer(37, 5, 3);
image.Data.Fill(0.1f);
var mask = new float[image.PlaneLength];
for (var i = 0; i < mask.Length; i++) mask[i] = (i % 3) * 0.5f;
ExposureProcessor.ApplyRegion(image, mask, skyEv: 1, landEv: -1);
for (var i = 0; i < mask.Length; i++)
{
var expected = 0.1 * (0.5 + mask[i] * (2 - 0.5));
Assert.Approximately(expected, image.Plane(1)[i], 1e-7);
}
Assert.Throws<ArgumentException>(() => ExposureProcessor.ApplyRegion(image, new float[3], 0, 0));
}
[Test]
public void SoftClipIsSmoothBoundedAndKeepsHue()
{
const float knee = 0.8f;
Assert.Equal(0.5f, ExposureProcessor.SoftClip(0.5f, knee));
Assert.Approximately(knee, ExposureProcessor.SoftClip(knee + 1e-6f, knee), 1e-5);
var values = Enumerable.Range(0, 400).Select(i => (double)ExposureProcessor.SoftClip(i * 0.05f, knee)).ToList();
Assert.Monotonic(values);
Assert.Less(values.Max(), 1);
// Slope 1 at the knee (C¹): the secant over h above it is 1 / (1 + h / (1 − knee)).
var slope = (ExposureProcessor.SoftClip(knee + 1e-3f, knee) - knee) / 1e-3f;
Assert.Approximately(1 / (1 + 1e-3 / (1 - knee)), slope, 1e-3);
using var image = new ImageBuffer(37, 5, 3);
for (var i = 0; i < image.PlaneLength; i++)
{
image.Plane(0)[i] = 0.02f * i;
image.Plane(1)[i] = 0.01f * i;
image.Plane(2)[i] = 0.005f * i;
}
ExposureProcessor.Apply(image, 0, softClipKnee: knee);
for (var i = 1; i < image.PlaneLength; i++)
{
var r = image.Plane(0)[i];
Assert.LessOrEqual(r, 1);
Assert.Approximately(2, r / image.Plane(1)[i], 1e-4);
Assert.Approximately(2, image.Plane(1)[i] / image.Plane(2)[i], 1e-4);
Assert.Approximately(ExposureProcessor.SoftClip(0.02f * i, knee), r, 1e-5);
}
}
[Test]
public void LargeImagesTakeTheParallelPathWithTheSameResult()
{
using var image = new ImageBuffer(1100, 1000, 3);
var data = image.Data;
for (var i = 0; i < data.Length; i++) data[i] = (i % 1000) * 0.0012f;
using var expected = image.Clone();
ExposureProcessor.Apply(image, 0.5, softClipKnee: 0.9);
var gain = (float)Math.Pow(2, 0.5);
foreach (var index in new[] { 0, 12345, 777_777, 1_099_999 })
{
var r = expected.Plane(0)[index] * gain;
var g = expected.Plane(1)[index] * gain;
var b = expected.Plane(2)[index] * gain;
var m = Math.Max(r, Math.Max(g, b));
var s = m > 0.9f ? ExposureProcessor.SoftClip(m, 0.9f) / m : 1;
Assert.Approximately(r * s, image.Plane(0)[index], 1e-5);
Assert.Approximately(b * s, image.Plane(2)[index], 1e-5);
}
}
}