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:
5 files changed
+702
No files matched your search
@@ -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| < 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 < knee < 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;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user