diff --git a/src/Titano.Core/Analysis/AnalysisImage.cs b/src/Titano.Core/Analysis/AnalysisImage.cs
new file mode 100644
index 00000000..ffbb24e9
--- /dev/null
+++ b/src/Titano.Core/Analysis/AnalysisImage.cs
@@ -0,0 +1,51 @@
+using Titano.Core.Imaging;
+
+namespace Titano.Core.Analysis;
+
+/// Builds the reduced-size images that analysis passes measure.
+public static class AnalysisImage
+{
+ ///
+ /// Area-average (box) downscale by the smallest integer factor that brings the long edge to at most
+ /// . Exact for flat fields; trailing rows/columns that do not fill a block are
+ /// dropped. Returns a copy when no reduction is needed.
+ ///
+ 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;
+ }
+}
diff --git a/src/Titano.Core/Analysis/ColorTemperature.cs b/src/Titano.Core/Analysis/ColorTemperature.cs
new file mode 100644
index 00000000..ff446f2e
--- /dev/null
+++ b/src/Titano.Core/Analysis/ColorTemperature.cs
@@ -0,0 +1,118 @@
+using Titano.Core.Mathematics;
+
+namespace Titano.Core.Analysis;
+
+/// Correlated colour temperature of a near-Planckian colour.
+/// CCT: temperature of the nearest Planckian-locus point in CIE 1960 uv.
+/// McCamy's cubic estimate the search started from.
+/// Signed uv distance from the locus (positive towards green).
+public readonly record struct ColorTemperatureEstimate(double Kelvin, double McCamyKelvin, double Duv);
+
+///
+/// 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
+/// from the locus have no meaningful CCT and are rejected.
+///
+public static class ColorTemperature
+{
+ /// Validity limit on |Duv| (ANSI C78.377 uses ±0.02 as the edge of "white" light).
+ public const double MaxDuv = 0.02;
+
+ public const double MinKelvin = 1000;
+ public const double MaxKelvin = 15000;
+
+ /// McCamy's cubic CCT approximation from CIE 1931 xy (epicentre 0.3320, 0.1858).
+ 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;
+ }
+
+ /// Planckian locus in CIE 1960 uv (Krystek 1985; |Δu|, |Δv| < 1e-4 over 1000–15000 K).
+ 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);
+ }
+
+ /// Linear Rec.709 RGB of a Planckian radiator's chromaticity, scaled to luminance 1.
+ public static Vector3D PlanckianRgb(double kelvin) => Matrix3.XyzToRec709 * PlanckianChromaticity(kelvin).ToXyz();
+
+ /// Estimate from a chromaticity; null outside the locus range or beyond .
+ 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);
+ }
+
+ /// Estimate from mean linear Rec.709 RGB; null for non-positive or off-locus colours.
+ 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);
+ }
+
+ /// Distance to the locus point at , signed by the side of the locus normal
+ /// that points to larger v (the green side).
+ 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;
+ }
+}
diff --git a/src/Titano.Core/Analysis/ExposureProcessor.cs b/src/Titano.Core/Analysis/ExposureProcessor.cs
new file mode 100644
index 00000000..06b1b7f7
--- /dev/null
+++ b/src/Titano.Core/Analysis/ExposureProcessor.cs
@@ -0,0 +1,149 @@
+using System.Numerics;
+using System.Runtime.InteropServices;
+using Titano.Core.Imaging;
+
+namespace Titano.Core.Analysis;
+
+/// Per-channel multiplicative gains in linear light (white balance).
+public readonly record struct ChannelGains(double Red, double Green, double Blue)
+{
+ public static ChannelGains Identity { get; } = new(1, 1, 1);
+}
+
+///
+/// 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
+/// ; large images are split across cores. A fourth (alpha) channel is left untouched.
+///
+public static class ExposureProcessor
+{
+ private const int ParallelThreshold = 1 << 20;
+ private const int Chunk = 1 << 16;
+
+ /// When set (0 < knee < 1), values above the knee roll off smoothly towards 1.
+ 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);
+ });
+ }
+
+ ///
+ /// 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.
+ ///
+ public static void ApplyRegion(ImageBuffer image, ReadOnlyMemory 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);
+ });
+ }
+
+ /// 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.
+ 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 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 data, float factor)
+ {
+ var vectors = MemoryMarshal.Cast>(data);
+ var f = new Vector(factor);
+ for (var i = 0; i < vectors.Length; i++) vectors[i] *= f;
+ for (var i = vectors.Length * Vector.Count; i < data.Length; i++) data[i] *= factor;
+ }
+
+ private static void Blend(Span data, ReadOnlySpan mask, float baseFactor, float delta)
+ {
+ var vectors = MemoryMarshal.Cast>(data);
+ var masks = MemoryMarshal.Cast>(mask);
+ var b = new Vector(baseFactor);
+ var d = new Vector(delta);
+ for (var i = 0; i < vectors.Length; i++) vectors[i] *= b + masks[i] * d;
+ for (var i = vectors.Length * Vector.Count; i < data.Length; i++) data[i] *= baseFactor + mask[i] * delta;
+ }
+
+ /// Compresses the largest channel with and scales all three
+ /// channels by the same ratio, so hue and saturation are kept.
+ 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>(r);
+ var vg = MemoryMarshal.Cast>(g);
+ var vb = MemoryMarshal.Cast>(b);
+ var k = new Vector(knee);
+ var inverseRange = new Vector(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.One + excess * inverseRange)) / m;
+ var s = Vector.ConditionalSelect(Vector.GreaterThan(m, k), ratio, Vector.One);
+ vr[i] *= s;
+ vg[i] *= s;
+ vb[i] *= s;
+ }
+ for (var i = vr.Length * Vector.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;
+ }
+ }
+}
diff --git a/src/Titano.Core/Analysis/FrameStatistics.cs b/src/Titano.Core/Analysis/FrameStatistics.cs
new file mode 100644
index 00000000..e817906d
--- /dev/null
+++ b/src/Titano.Core/Analysis/FrameStatistics.cs
@@ -0,0 +1,268 @@
+using Titano.Core.Imaging;
+using Titano.Core.Mathematics;
+
+namespace Titano.Core.Analysis;
+
+/// Thresholds for .
+public sealed record FrameStatisticsOptions
+{
+ public static FrameStatisticsOptions Default { get; } = new();
+
+ /// Weight fraction trimmed from the dark end of the log-luminance distribution.
+ public double TrimLow { get; init; } = 0.02;
+
+ /// Weight fraction trimmed from the bright end.
+ public double TrimHigh { get; init; } = 0.02;
+
+ /// A pixel is crushed when every channel is below this linear level (1/1024 ≈ −10 EV).
+ public double ClipLowLevel { get; init; } = 1.0 / 1024;
+
+ /// A pixel is clipped when any channel reaches this fraction of .
+ public double ClipHighFraction { get; init; } = 0.98;
+
+ public double WhiteLevel { get; init; } = 1.0;
+}
+
+///
+/// Per-frame (or per-region) measurements of the deep analysis (BRIEF §10.2), taken in one pass over a
+/// downscaled linear-light image (see ) plus one 3×3 neighbourhood pass.
+///
+public sealed record FrameStatistics
+{
+ public const int HistogramBins = 256;
+
+ /// Lower edge of the log-luminance histogram, in EV relative to linear 1.0.
+ public const double HistogramMinEv = -14;
+
+ /// Upper edge of the log-luminance histogram, in EV relative to linear 1.0.
+ public const double HistogramMaxEv = 2;
+
+ public int Width { get; init; }
+ public int Height { get; init; }
+
+ /// Total sample weight: pixel count, or the mask sum for region statistics.
+ public double Weight { get; init; }
+
+ /// Mean of log2 luminance after trimming both tails (luminance floored at 2⁻¹⁴).
+ public double MeanLogLuminance { get; init; }
+
+ /// Weight fraction per bin of log2 luminance over [−14, +2) EV; sums to 1.
+ 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; }
+
+ /// Correlated colour temperature of the mean colour; null when it is not near-Planckian.
+ public ColorTemperatureEstimate? ColorTemperature { get; init; }
+
+ /// Variance of the 4-neighbour Laplacian of sRGB-encoded luminance (focus/blur measure).
+ public double Sharpness { get; init; }
+
+ /// Noise standard deviation of sRGB-encoded luminance, Immerkær (1996) fast estimator.
+ public double Noise { get; init; }
+
+ /// Nearly every pixel is crushed (lens cap, missed exposure).
+ public bool IsBlack(double fraction = 0.95) => ClipLowFraction >= fraction;
+
+ /// Nearly every pixel is clipped (blown exposure).
+ public bool IsWhite(double fraction = 0.95) => ClipHighFraction >= fraction;
+
+ ///
+ /// True when two frames have practically identical statistics (histogram, level, colour, detail, noise): a
+ /// cheap duplicate test before any pixel or hash comparison.
+ ///
+ 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);
+ }
+
+ /// Measures an image, optionally weighted by a per-pixel in [0, 1].
+ public static FrameStatistics Measure(ImageBuffer image, ReadOnlySpan 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,
+ };
+ }
+
+ /// Only the trimmed mean of log2 luminance (the deflicker signal), optionally mask-weighted.
+ public static double MeasureLogLuminance(ImageBuffer image, ReadOnlySpan 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 mask)
+ {
+ if (!mask.IsEmpty && mask.Length != image.PlaneLength)
+ throw new ArgumentException("Mask must have one weight per pixel.", nameof(mask));
+ }
+
+ /// Laplacian variance and Immerkær noise σ over interior pixels, weighted by the mask at the centre.
+ private static (double Sharpness, double Noise) Detail(float[] e, int width, int height, ReadOnlySpan 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);
+ }
+
+ ///
+ /// 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.
+ ///
+ 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;
+ }
+
+ /// Normalised coarse histogram (bins must divide the fine bin count).
+ 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;
+ }
+ }
+}
diff --git a/tests/Titano.Core.Tests/Analysis/ExposureProcessorTests.cs b/tests/Titano.Core.Tests/Analysis/ExposureProcessorTests.cs
new file mode 100644
index 00000000..a4ad4bdc
--- /dev/null
+++ b/tests/Titano.Core.Tests/Analysis/ExposureProcessorTests.cs
@@ -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(() => ExposureProcessor.Apply(image, double.NaN));
+ Assert.Throws(() => 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(() => 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);
+ }
+ }
+}