From 40870e12dc1fc50d87f645ea5897d2bb59840a3b Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:51:43 +0000 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Core/Analysis/AnalysisImage.cs | 51 ++++ src/Titano.Core/Analysis/ColorTemperature.cs | 118 ++++++++ src/Titano.Core/Analysis/ExposureProcessor.cs | 149 ++++++++++ src/Titano.Core/Analysis/FrameStatistics.cs | 268 ++++++++++++++++++ .../Analysis/ExposureProcessorTests.cs | 116 ++++++++ 5 files changed, 702 insertions(+) create mode 100644 src/Titano.Core/Analysis/AnalysisImage.cs create mode 100644 src/Titano.Core/Analysis/ColorTemperature.cs create mode 100644 src/Titano.Core/Analysis/ExposureProcessor.cs create mode 100644 src/Titano.Core/Analysis/FrameStatistics.cs create mode 100644 tests/Titano.Core.Tests/Analysis/ExposureProcessorTests.cs 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); + } + } +}