diff --git a/src/Titano.Core/Codecs/Dng/DngColorProfile.cs b/src/Titano.Core/Codecs/Dng/DngColorProfile.cs
new file mode 100644
index 00000000..dfc7cdd0
--- /dev/null
+++ b/src/Titano.Core/Codecs/Dng/DngColorProfile.cs
@@ -0,0 +1,239 @@
+using Titano.Core.Mathematics;
+
+namespace Titano.Core.Codecs.Dng;
+
+/// Result of : white balance and the matrix to linear Rec.709.
+/// Camera response to the scene white, largest entry 1 (white-balance multipliers are its reciprocals).
+/// Scene white chromaticity found by the iterative solve.
+/// Correlated colour temperature of (Robertson), in kelvin.
+/// White-balanced camera RGB (raw ÷ neutral) → linear Rec.709 (D65), BaselineExposure included.
+/// White-balanced camera RGB → CIE XYZ (D65 adapted, Y = 1 at white), for demosaic metrics.
+public sealed record DngColorSolution(Vector3D CameraNeutral, Chromaticity White, double Temperature, Matrix3 BalancedToRec709, Matrix3 BalancedToXyz);
+
+///
+/// Camera colour description of a DNG (or of a native RAW with a tabulated matrix) and the colour math of DNG 1.6
+/// chapter 6 "Mapping Camera Color Space to CIE XYZ Space": ColorMatrix1/2 and CameraCalibration1/2 interpolated by
+/// inverse correlated colour temperature between CalibrationIlluminant1/2, AnalogBalance, the iterative white solve for
+/// AsShotNeutral (or the neutral implied by AsShotWhiteXY), ForwardMatrix1/2 when present, then Bradford adaptation from
+/// the D50 profile connection space to D65 and the XYZ → Rec.709 matrix.
+///
+public sealed class DngColorProfile
+{
+ /// Default scene white when the file records none: D55, as the DNG SDK assumes.
+ public static Chromaticity DefaultWhite { get; } = new(0.3324, 0.3474);
+
+ public Matrix3? ColorMatrix1 { get; init; }
+ public Matrix3? ColorMatrix2 { get; init; }
+ public Matrix3? CameraCalibration1 { get; init; }
+ public Matrix3? CameraCalibration2 { get; init; }
+ public Matrix3? ForwardMatrix1 { get; init; }
+ public Matrix3? ForwardMatrix2 { get; init; }
+
+ /// Exif LightSource codes of the two calibrations (0 = unknown).
+ public int CalibrationIlluminant1 { get; init; }
+
+ public int CalibrationIlluminant2 { get; init; }
+ public Vector3D AnalogBalance { get; init; } = new(1, 1, 1);
+ public Vector3D? AsShotNeutral { get; init; }
+ public Chromaticity? AsShotWhite { get; init; }
+
+ /// Exposure offset in EV applied to the rendered values (DNG BaselineExposure).
+ public double BaselineExposure { get; init; }
+
+ /// Solves white balance and builds the output matrices.
+ /// No usable colour matrix (missing, singular or non-finite).
+ public DngColorSolution Solve(ICollection warnings)
+ {
+ if (ColorMatrix1 is not { } cm1 || !Usable(cm1)) throw new InvalidDataException("DNG: ColorMatrix1 missing or singular");
+ Chromaticity white;
+ Vector3D neutral;
+ if (AsShotNeutral is { } asShot && asShot.X > 0 && asShot.Y > 0 && asShot.Z > 0)
+ {
+ neutral = Normalize(asShot);
+ white = NeutralToXy(neutral);
+ }
+ else
+ {
+ if (AsShotWhite is { } xy && xy.X > 0 && xy.Y > 0 && xy.X + xy.Y < 1)
+ {
+ white = xy;
+ }
+ else
+ {
+ white = DefaultWhite;
+ warnings.Add("DNG: no as-shot white balance; D55 assumed");
+ }
+ neutral = Normalize(XyzToCamera(white) * white.ToXyz());
+ }
+ // Clamp like the DNG SDK so a degenerate neutral cannot produce infinite multipliers.
+ neutral = new Vector3D(double.Clamp(neutral.X, 0.001, 1), double.Clamp(neutral.Y, 0.001, 1), double.Clamp(neutral.Z, 0.001, 1));
+
+ var cameraToPcs = CameraToPcs(white, neutral);
+ var d50 = Chromaticity.D50.ToXyz();
+ var d65 = Chromaticity.D65.ToXyz();
+ var balancedToD65 = Matrix3.BradfordAdaptation(d50, d65) * cameraToPcs * Matrix3.Diagonal(neutral.X, neutral.Y, neutral.Z);
+ var gain = double.Exp2(BaselineExposure);
+ var toRec709 = Scale(Matrix3.XyzToRec709 * balancedToD65, gain);
+ return new DngColorSolution(neutral, white, Temperature(white), toRec709, balancedToD65);
+ }
+
+ /// XYZ → camera at the given scene white: AnalogBalance · CameraCalibration · ColorMatrix, both interpolated
+ /// by the white's inverse temperature (DNG §6 "Translating White Balance xy Coordinates to Camera Neutral").
+ public Matrix3 XyzToCamera(Chromaticity white)
+ {
+ var g = Weight(white);
+ var cm = Blend(ColorMatrix1!.Value, ColorMatrix2, g);
+ var cc = Blend(CameraCalibration1 ?? Matrix3.Identity, CameraCalibration2 ?? (CameraCalibration1 is null ? null : Matrix3.Identity), g);
+ return Matrix3.Diagonal(AnalogBalance.X, AnalogBalance.Y, AnalogBalance.Z) * cc * cm;
+ }
+
+ /// Iterative white solve of DNG §6 "Translating Camera Neutral Coordinates to White Balance xy Coordinates":
+ /// start at D50, map the neutral through the inverse of the matrix interpolated at the current estimate, repeat until it
+ /// moves less than 1e-7 (30 passes at most; a two-value oscillation is averaged).
+ public Chromaticity NeutralToXy(Vector3D neutral)
+ {
+ const int maxPasses = 30;
+ var last = Chromaticity.D50;
+ for (var pass = 0; pass < maxPasses; pass++)
+ {
+ if (!XyzToCamera(last).TryInvert(out var cameraToXyz)) return last;
+ var next = Chromaticity.FromXyz(cameraToXyz * neutral);
+ if (!double.IsFinite(next.X) || !double.IsFinite(next.Y) || next.Y <= 0) return last;
+ if (double.Abs(next.X - last.X) + double.Abs(next.Y - last.Y) < 1e-7) return next;
+ if (pass == maxPasses - 1) next = new Chromaticity((last.X + next.X) / 2, (last.Y + next.Y) / 2);
+ last = next;
+ }
+ return last;
+ }
+
+ /// Camera → XYZ(D50) with the white-balanced neutral mapping to the D50 white (Y = 1): through the
+ /// interpolated ForwardMatrix when present, otherwise the inverse of ColorMatrix adapted from D50 to the scene white
+ /// (DNG §6 "Camera to XYZ (D50) Transform").
+ private Matrix3 CameraToPcs(Chromaticity white, Vector3D neutral)
+ {
+ var d50 = Chromaticity.D50.ToXyz();
+ if (ForwardMatrix1 is { } fm1 && Usable(fm1))
+ {
+ var g = Weight(white);
+ var fm = NormalizeForward(Blend(fm1, ForwardMatrix2 is { } fm2 && Usable(fm2) ? fm2 : null, g), d50);
+ var cc = Blend(CameraCalibration1 ?? Matrix3.Identity, CameraCalibration2 ?? (CameraCalibration1 is null ? null : Matrix3.Identity), g);
+ var individualToReference = (Matrix3.Diagonal(AnalogBalance.X, AnalogBalance.Y, AnalogBalance.Z) * cc).Inverse();
+ var reference = individualToReference * neutral;
+ return fm * Matrix3.Diagonal(1 / reference.X, 1 / reference.Y, 1 / reference.Z) * individualToReference;
+ }
+ var pcsToCamera = XyzToCamera(white) * Matrix3.BradfordAdaptation(d50, white.ToXyz());
+ var atWhite = pcsToCamera * d50;
+ var scale = double.Max(atWhite.X, double.Max(atWhite.Y, atWhite.Z));
+ if (!(scale > 0)) throw new InvalidDataException("DNG: colour matrix maps white outside the camera gamut");
+ return Scale(pcsToCamera, 1 / scale).Inverse();
+ }
+
+ /// Weight of calibration 1 for a scene white: 1 at or below its temperature, 0 at or above calibration 2's,
+ /// linear in inverse temperature between (DNG §6 "Linear Interpolation Based on Correlated Color Temperature").
+ private double Weight(Chromaticity white)
+ {
+ if (ColorMatrix2 is null) return 1;
+ var t1 = IlluminantTemperature(CalibrationIlluminant1);
+ var t2 = IlluminantTemperature(CalibrationIlluminant2);
+ if (t1 <= 0 || t2 <= 0 || t1 == t2) return 1;
+ var t = Temperature(white);
+ var swap = t1 > t2;
+ var (lo, hi) = swap ? (t2, t1) : (t1, t2);
+ double g;
+ if (t <= lo) g = 1;
+ else if (t >= hi) g = 0;
+ else g = (1 / t - 1 / hi) / (1 / lo - 1 / hi);
+ return swap ? 1 - g : g;
+ }
+
+ /// Temperatures the DNG SDK assigns to the Exif LightSource codes (fluorescents use the band centre); 0 when unknown.
+ public static double IlluminantTemperature(int lightSource) => lightSource switch
+ {
+ 17 or 3 => 2850,
+ 24 => 3200,
+ 23 => 5000,
+ 20 or 1 or 9 or 4 or 18 => 5500,
+ 21 or 19 or 10 => 6500,
+ 22 or 11 => 7500,
+ 12 => (5700 + 7100) / 2.0,
+ 13 => (4600 + 5500) / 2.0,
+ 14 or 2 => (3800 + 4500) / 2.0,
+ 15 => (3250 + 3800) / 2.0,
+ 16 => (2600 + 3250) / 2.0,
+ _ => 0,
+ };
+
+ /// Correlated colour temperature by Robertson's method (isotemperature lines in CIE 1960 uv,
+ /// Wyszecki & Stiles table) as the DNG SDK computes it; results clamp to 1 667–100 000 K.
+ public static double Temperature(Chromaticity xy)
+ {
+ var d = 1.5 - xy.X + 6 * xy.Y;
+ var u = 2 * xy.X / d;
+ var v = 3 * xy.Y / d;
+ double lastDt = 0;
+ var table = Robertson;
+ for (var i = 1; i < table.Length; i++)
+ {
+ var (_, tu, tv, slope) = table[i];
+ var len = double.Sqrt(1 + slope * slope);
+ double du = 1 / len, dv = slope / len;
+ var dt = -(u - tu) * dv + (v - tv) * du;
+ if (dt <= 0 || i == table.Length - 1)
+ {
+ if (dt > 0) dt = 0;
+ dt = -dt;
+ var f = i == 1 ? 0 : dt / (lastDt + dt);
+ return 1e6 / (table[i - 1].Mired * f + table[i].Mired * (1 - f));
+ }
+ lastDt = dt;
+ }
+ return 1e6 / table[^1].Mired;
+ }
+
+ /// Robertson (1968) isotemperature lines: mired, u, v, slope.
+ private static readonly (double Mired, double U, double V, double Slope)[] Robertson =
+ [
+ (0, 0.18006, 0.26352, -0.24341), (10, 0.18066, 0.26589, -0.25479), (20, 0.18133, 0.26846, -0.26876),
+ (30, 0.18208, 0.27119, -0.28539), (40, 0.18293, 0.27407, -0.30470), (50, 0.18388, 0.27709, -0.32675),
+ (60, 0.18494, 0.28021, -0.35156), (70, 0.18611, 0.28342, -0.37915), (80, 0.18740, 0.28668, -0.40955),
+ (90, 0.18880, 0.28997, -0.44278), (100, 0.19032, 0.29326, -0.47888), (125, 0.19462, 0.30141, -0.58204),
+ (150, 0.19962, 0.30921, -0.70471), (175, 0.20525, 0.31647, -0.84901), (200, 0.21142, 0.32312, -1.0182),
+ (225, 0.21807, 0.32909, -1.2168), (250, 0.22511, 0.33439, -1.4512), (275, 0.23247, 0.33904, -1.7298),
+ (300, 0.24010, 0.34308, -2.0637), (325, 0.24702, 0.34655, -2.4681), (350, 0.25591, 0.34951, -2.9641),
+ (375, 0.26400, 0.35200, -3.5814), (400, 0.27218, 0.35407, -4.3633), (425, 0.28039, 0.35577, -5.3762),
+ (450, 0.28863, 0.35714, -6.7262), (475, 0.29685, 0.35823, -8.5955), (500, 0.30505, 0.35907, -11.324),
+ (525, 0.31320, 0.35968, -15.628), (550, 0.32129, 0.36011, -23.325), (575, 0.32931, 0.36038, -40.770),
+ (600, 0.33724, 0.36051, -116.45),
+ ];
+
+ /// Rows scaled so that the camera neutral (1, 1, 1) maps exactly to the D50 white (DNG SDK NormalizeForwardMatrix).
+ private static Matrix3 NormalizeForward(Matrix3 m, Vector3D d50)
+ {
+ var one = m * new Vector3D(1, 1, 1);
+ if (!(one.X > 0 && one.Y > 0 && one.Z > 0)) return m;
+ return Matrix3.Diagonal(d50.X / one.X, d50.Y / one.Y, d50.Z / one.Z) * m;
+ }
+
+ private static Matrix3 Blend(Matrix3 a, Matrix3? b, double weightA)
+ {
+ if (b is not { } m || weightA >= 1) return a;
+ var wb = 1 - weightA;
+ return new Matrix3(
+ a.M11 * weightA + m.M11 * wb, a.M12 * weightA + m.M12 * wb, a.M13 * weightA + m.M13 * wb,
+ a.M21 * weightA + m.M21 * wb, a.M22 * weightA + m.M22 * wb, a.M23 * weightA + m.M23 * wb,
+ a.M31 * weightA + m.M31 * wb, a.M32 * weightA + m.M32 * wb, a.M33 * weightA + m.M33 * wb);
+ }
+
+ private static Matrix3 Scale(Matrix3 m, double s) => new(
+ m.M11 * s, m.M12 * s, m.M13 * s, m.M21 * s, m.M22 * s, m.M23 * s, m.M31 * s, m.M32 * s, m.M33 * s);
+
+ private static Vector3D Normalize(Vector3D v)
+ {
+ var max = double.Max(v.X, double.Max(v.Y, v.Z));
+ if (!(max > 0) || !double.IsFinite(max)) throw new InvalidDataException("DNG: camera neutral is not positive");
+ return new Vector3D(v.X / max, v.Y / max, v.Z / max);
+ }
+
+ private static bool Usable(Matrix3 m) =>
+ double.IsFinite(m.Determinant) && m.TryInvert(out _);
+}
diff --git a/src/Titano.Core/Codecs/Dng/DngOpcodes.cs b/src/Titano.Core/Codecs/Dng/DngOpcodes.cs
new file mode 100644
index 00000000..ca0dba5f
--- /dev/null
+++ b/src/Titano.Core/Codecs/Dng/DngOpcodes.cs
@@ -0,0 +1,712 @@
+using System.Buffers.Binary;
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Imaging;
+
+namespace Titano.Core.Codecs.Dng;
+
+///
+/// Image an opcode list runs on (DNG 1.6 §7): list 1 sees the stored raw values divided by 65535, list 2 the linearised
+/// mosaic (0 = black, 1 = white), list 3 the demosaiced planes. Coordinates of opcode parameters are full-resolution
+/// stage coordinates; a binned (half-size) image covers stage pixels per buffer pixel.
+///
+internal sealed class OpcodeImage(ImageBuffer pixels, int left, int top, int step, CfaPattern? cfa)
+{
+ public ImageBuffer Pixels { get; set; } = pixels;
+
+ /// Stage coordinates of buffer pixel (0, 0)'s block.
+ public int Left { get; set; } = left;
+
+ public int Top { get; set; } = top;
+
+ /// Stage pixels per buffer pixel along each axis (1 at full resolution).
+ public int Step { get; } = step;
+
+ /// CFA of a mosaic, anchored at buffer pixel (0, 0); null for planar images.
+ public CfaPattern? Cfa { get; set; } = cfa;
+
+ /// Per-pixel clip flags that must stay aligned with (trimmed together).
+ public byte[]? ClipMask { get; set; }
+
+ public int Width => Pixels.Width;
+ public int Height => Pixels.Height;
+
+ /// Stage bounds covered by the buffer.
+ public RawRect Bounds => new(Left, Top, Left + Width * Step, Top + Height * Step);
+
+ /// Stage coordinate of a buffer column's centre (integer at full resolution).
+ public double StageX(int x) => Left + x * Step + (Step - 1) / 2.0;
+
+ public double StageY(int y) => Top + y * Step + (Step - 1) / 2.0;
+
+ /// Buffer coordinate of a stage coordinate.
+ public double BufferX(double stageX) => (stageX - Left - (Step - 1) / 2.0) / Step;
+
+ public double BufferY(double stageY) => (stageY - Top - (Step - 1) / 2.0) / Step;
+}
+
+/// One parsed opcode. Flag bit 0 marks it optional, bit 1 "may be skipped for previews".
+internal abstract class DngOpcode(uint id, uint flags)
+{
+ public uint Id { get; } = id;
+ public uint Flags { get; } = flags;
+ public bool Optional => (Flags & 1) != 0;
+
+ /// True when the opcode works on value magnitudes in a way that does not commute with white-balance scaling.
+ public virtual bool NeedsUnbalancedValues => false;
+
+ public abstract string Name { get; }
+
+ public abstract void Apply(OpcodeImage image, ICollection warnings, CancellationToken cancellationToken);
+}
+
+///
+/// DNG opcode lists (DNG 1.6 chapter 7, big-endian): WarpRectilinear (1), FixVignetteRadial (3), FixBadPixelsConstant (4),
+/// FixBadPixelsList (5), TrimBounds (6), MapTable (7), MapPolynomial (8), GainMap (9), DeltaPerRow/Column (10/11) and
+/// ScalePerRow/Column (12/13). Other opcodes (WarpFisheye, WarpRectilinear2, vendor extensions) are skipped with a warning
+/// that says whether the file marked them optional.
+///
+internal static class DngOpcodes
+{
+ private const int MaxOpcodes = 256;
+ private const long MaxGainMapPoints = 1 << 22;
+
+ /// Parses an OpcodeList tag value; malformed opcodes are dropped with a warning.
+ public static List Parse(byte[]? data, int list, ICollection warnings)
+ {
+ var result = new List();
+ if (data is null || data.Length < 4) return result;
+ var count = BinaryPrimitives.ReadUInt32BigEndian(data);
+ var pos = 4;
+ for (var i = 0; i < count && i < MaxOpcodes; i++)
+ {
+ if (pos + 16 > data.Length)
+ {
+ warnings.Add($"DNG: opcode list {list} truncated");
+ break;
+ }
+ var id = BinaryPrimitives.ReadUInt32BigEndian(data.AsSpan(pos));
+ var flags = BinaryPrimitives.ReadUInt32BigEndian(data.AsSpan(pos + 8));
+ var size = BinaryPrimitives.ReadUInt32BigEndian(data.AsSpan(pos + 12));
+ pos += 16;
+ if (size > data.Length - pos)
+ {
+ warnings.Add($"DNG: opcode list {list} truncated");
+ break;
+ }
+ var reader = new ParamReader(data.AsSpan(pos, (int)size));
+ pos += (int)size;
+ var op = Create(id, flags, ref reader);
+ if (op is null)
+ {
+ warnings.Add((flags & 1) != 0
+ ? $"DNG: optional opcode {id} in list {list} not supported; skipped"
+ : $"DNG: required opcode {id} in list {list} not supported; skipped, rendering may differ");
+ }
+ else if (!reader.Ok)
+ {
+ warnings.Add($"DNG: opcode {op.Name} in list {list} has malformed parameters; skipped");
+ }
+ else
+ {
+ result.Add(op);
+ }
+ }
+ return result;
+ }
+
+ /// Applies every opcode in order.
+ public static void Apply(IReadOnlyList opcodes, OpcodeImage image, ICollection warnings, CancellationToken cancellationToken)
+ {
+ foreach (var op in opcodes)
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+ op.Apply(image, warnings, cancellationToken);
+ }
+ }
+
+ private static DngOpcode? Create(uint id, uint flags, ref ParamReader r) => id switch
+ {
+ 1 => WarpRectilinear.Read(flags, ref r),
+ 3 => new FixVignetteRadial(flags, r.F64(), r.F64(), r.F64(), r.F64(), r.F64(), r.F64(), r.F64()),
+ 4 => FixBadPixelsConstant.Read(flags, ref r),
+ 5 => FixBadPixelsList.Read(flags, ref r),
+ 6 => TrimBounds.Read(flags, ref r),
+ 7 => MapTable.Read(flags, ref r),
+ 8 => MapPolynomial.Read(flags, ref r),
+ 9 => GainMap.Read(flags, ref r),
+ 10 or 11 or 12 or 13 => PerLine.Read(id, flags, ref r),
+ _ => null,
+ };
+
+ /// Big-endian parameter reader that turns overruns into = false instead of throwing.
+ internal ref struct ParamReader(ReadOnlySpan data)
+ {
+ private readonly ReadOnlySpan _data = data;
+ private int _pos;
+
+ public bool Ok { get; private set; } = true;
+ public int Remaining => _data.Length - _pos;
+
+ public uint U32() => Take(4) ? BinaryPrimitives.ReadUInt32BigEndian(_data[(_pos - 4)..]) : 0;
+
+ /// A 32-bit coordinate limited to the int range.
+ public uint Bounded()
+ {
+ var v = U32();
+ if (v > int.MaxValue / 4) Ok = false;
+ return v;
+ }
+
+ public ushort U16() => Take(2) ? BinaryPrimitives.ReadUInt16BigEndian(_data[(_pos - 2)..]) : (ushort)0;
+
+ public float F32() => Take(4) ? BinaryPrimitives.ReadSingleBigEndian(_data[(_pos - 4)..]) : 0;
+
+ public double F64()
+ {
+ var v = Take(8) ? BinaryPrimitives.ReadDoubleBigEndian(_data[(_pos - 8)..]) : 0;
+ if (!double.IsFinite(v)) Ok = false;
+ return v;
+ }
+
+ public void Fail() => Ok = false;
+
+ private bool Take(int n)
+ {
+ if (!Ok || _pos + n > _data.Length)
+ {
+ Ok = false;
+ return false;
+ }
+ _pos += n;
+ return true;
+ }
+ }
+
+ /// Area of effect shared by the per-pixel opcodes: rectangle, plane range and row/column pitch.
+ internal readonly record struct AreaSpec(RawRect Area, int Plane, int Planes, int RowPitch, int ColPitch)
+ {
+ public static AreaSpec Read(ref ParamReader r)
+ {
+ var top = (int)r.Bounded();
+ var left = (int)r.Bounded();
+ var bottom = (int)r.Bounded();
+ var right = (int)r.Bounded();
+ var plane = (int)r.Bounded();
+ var planes = (int)r.Bounded();
+ var rowPitch = (int)r.Bounded();
+ var colPitch = (int)r.Bounded();
+ if (rowPitch < 1 || colPitch < 1 || planes < 1) r.Fail();
+ return new AreaSpec(new RawRect(left, top, right, bottom), plane, planes, rowPitch, colPitch);
+ }
+
+ /// Visits every affected (plane, buffer x, buffer y, stage x, stage y) on the pitch grid; rows run in
+ /// parallel, so may only touch its own pixel.
+ public void ForEach(OpcodeImage image, Action pixel, ICollection warnings, string name, CancellationToken cancellationToken)
+ {
+ if (image.Step != 1 && (RowPitch != 1 || ColPitch != 1))
+ {
+ warnings.Add($"DNG: {name} with pitch cannot apply to a binned image; skipped");
+ return;
+ }
+ var area = Area.Intersect(image.Bounds);
+ if (area.IsEmpty) return;
+ var lastPlane = int.Min(image.Pixels.Channels, Plane + Planes);
+ var firstRow = Area.Top + Ceil(area.Top - Area.Top, RowPitch);
+ var firstCol = Area.Left + Ceil(area.Left - Area.Left, ColPitch);
+ var rowStep = RowPitch * image.Step;
+ var colStep = ColPitch * image.Step;
+ var rows = (area.Bottom - firstRow + rowStep - 1) / rowStep;
+ if (rows <= 0 || firstCol >= area.Right) return;
+ var plane = Plane;
+ Parallel.For(0, rows, new ParallelOptions { CancellationToken = cancellationToken }, k =>
+ {
+ var sy = firstRow + k * rowStep;
+ var y = (int)double.Round(image.BufferY(sy));
+ if ((uint)y >= (uint)image.Height) return;
+ for (var p = plane; p < lastPlane; p++)
+ {
+ for (var sx = firstCol; sx < area.Right; sx += colStep)
+ {
+ var x = (int)double.Round(image.BufferX(sx));
+ if ((uint)x < (uint)image.Width) pixel(p, x, y, sx, sy);
+ }
+ }
+ });
+ }
+
+ private static int Ceil(int offset, int pitch) => (offset + pitch - 1) / pitch * pitch;
+ }
+
+ /// Distance from the normalised optical centre to the farthest corner of the stage bounds.
+ private static (double Cx, double Cy, double MaxDistance) Centre(RawRect bounds, double cx, double cy)
+ {
+ var x = bounds.Left + cx * bounds.Width;
+ var y = bounds.Top + cy * bounds.Height;
+ var m = 0.0;
+ foreach (var (px, py) in (ReadOnlySpan<(int, int)>)[(bounds.Left, bounds.Top), (bounds.Right, bounds.Top), (bounds.Left, bounds.Bottom), (bounds.Right, bounds.Bottom)])
+ m = double.Max(m, double.Hypot(px - x, py - y));
+ return (x, y, double.Max(m, 1e-9));
+ }
+
+ /// WarpRectilinear: radial (kr0–kr3) and tangential (kt0, kt1) distortion per plane, mapping each corrected
+ /// pixel to its source position; resampled with Catmull-Rom.
+ private sealed class WarpRectilinear(uint flags, double[][] coefficients, double cx, double cy) : DngOpcode(1, flags)
+ {
+ public override string Name => "WarpRectilinear";
+
+ public static WarpRectilinear? Read(uint flags, ref ParamReader r)
+ {
+ var n = r.U32();
+ if (n is < 1 or > 4)
+ {
+ r.Fail();
+ return new WarpRectilinear(flags, [], 0, 0);
+ }
+ var k = new double[n][];
+ for (var i = 0; i < n; i++) k[i] = [r.F64(), r.F64(), r.F64(), r.F64(), r.F64(), r.F64()];
+ return new WarpRectilinear(flags, k, r.F64(), r.F64());
+ }
+
+ public override void Apply(OpcodeImage image, ICollection warnings, CancellationToken cancellationToken)
+ {
+ if (image.Cfa is not null)
+ {
+ warnings.Add("DNG: WarpRectilinear on mosaic data is not supported; skipped");
+ return;
+ }
+ var src = image.Pixels;
+ var dst = new ImageBuffer(src.Width, src.Height, src.Channels, clear: false);
+ var (cxs, cys, m) = Centre(image.Bounds, cx, cy);
+ Parallel.For(0, src.Height, new ParallelOptions { CancellationToken = cancellationToken }, y =>
+ {
+ var sy = image.StageY(y);
+ for (var p = 0; p < src.Channels; p++)
+ {
+ var k = coefficients[int.Min(p, coefficients.Length - 1)];
+ var plane = src.Plane(p);
+ var row = dst.Row(p, y);
+ for (var x = 0; x < src.Width; x++)
+ {
+ var dx = (image.StageX(x) - cxs) / m;
+ var dy = (sy - cys) / m;
+ var r2 = dx * dx + dy * dy;
+ var f = k[0] + r2 * (k[1] + r2 * (k[2] + r2 * k[3]));
+ var tx = k[4] * 2 * dx * dy + k[5] * (r2 + 2 * dx * dx);
+ var ty = k[5] * 2 * dx * dy + k[4] * (r2 + 2 * dy * dy);
+ var xs = image.BufferX(cxs + m * (f * dx + tx));
+ var ys = image.BufferY(cys + m * (f * dy + ty));
+ row[x] = Sampling.CatmullRom(plane, src.Width, src.Height, xs, ys);
+ }
+ }
+ });
+ src.Dispose();
+ image.Pixels = dst;
+ }
+ }
+
+ /// FixVignetteRadial: gain 1 + k0·r² + k1·r⁴ + k2·r⁶ + k3·r⁸ + k4·r¹⁰ about the normalised centre.
+ private sealed class FixVignetteRadial(uint flags, double k0, double k1, double k2, double k3, double k4, double cx, double cy) : DngOpcode(3, flags)
+ {
+ public override string Name => "FixVignetteRadial";
+
+ public override void Apply(OpcodeImage image, ICollection warnings, CancellationToken cancellationToken)
+ {
+ var (cxs, cys, m) = Centre(image.Bounds, cx, cy);
+ var pixels = image.Pixels;
+ Parallel.For(0, pixels.Height, new ParallelOptions { CancellationToken = cancellationToken }, y =>
+ {
+ var dy = (image.StageY(y) - cys) / m;
+ for (var x = 0; x < pixels.Width; x++)
+ {
+ var dx = (image.StageX(x) - cxs) / m;
+ var r2 = dx * dx + dy * dy;
+ var gain = (float)(1 + r2 * (k0 + r2 * (k1 + r2 * (k2 + r2 * (k3 + r2 * k4)))));
+ for (var p = 0; p < pixels.Channels; p++) pixels.Row(p, y)[x] *= gain;
+ }
+ });
+ }
+ }
+
+ /// FixBadPixelsConstant: pixels whose 16-bit value equals the constant are replaced from good neighbours.
+ /// The BayerPhase parameter is not needed: the frame's own CFA pattern identifies same-colour neighbours.
+ private sealed class FixBadPixelsConstant(uint flags, uint constant) : DngOpcode(4, flags)
+ {
+ public override string Name => "FixBadPixelsConstant";
+ public override bool NeedsUnbalancedValues => true;
+
+ public static FixBadPixelsConstant Read(uint flags, ref ParamReader r)
+ {
+ var constant = r.U32();
+ r.U32();
+ return new FixBadPixelsConstant(flags, constant);
+ }
+
+ public override void Apply(OpcodeImage image, ICollection warnings, CancellationToken cancellationToken)
+ {
+ if (constant > 65535) return;
+ var pixels = image.Pixels;
+ var bad = new List<(int X, int Y)>();
+ for (var y = 0; y < pixels.Height; y++)
+ {
+ for (var x = 0; x < pixels.Width; x++)
+ {
+ for (var p = 0; p < pixels.Channels; p++)
+ {
+ if (Sampling.Code16(pixels.Row(p, y)[x]) != constant) continue;
+ bad.Add((x, y));
+ break;
+ }
+ }
+ }
+ BadPixelRepair.Repair(image, bad);
+ }
+ }
+
+ /// FixBadPixelsList: listed points (row, column) and rectangles are replaced from good neighbours.
+ private sealed class FixBadPixelsList(uint flags, (int Row, int Col)[] points, RawRect[] rects) : DngOpcode(5, flags)
+ {
+ private const int MaxEntries = 1 << 22;
+
+ public override string Name => "FixBadPixelsList";
+
+ public static FixBadPixelsList Read(uint flags, ref ParamReader r)
+ {
+ r.U32();
+ var pointCount = r.U32();
+ var rectCount = r.U32();
+ if (pointCount > MaxEntries || rectCount > MaxEntries || (long)pointCount * 8 + (long)rectCount * 16 > r.Remaining)
+ {
+ r.Fail();
+ return new FixBadPixelsList(flags, [], []);
+ }
+ var points = new (int, int)[pointCount];
+ for (var i = 0; i < points.Length; i++) points[i] = ((int)r.Bounded(), (int)r.Bounded());
+ var rects = new RawRect[rectCount];
+ for (var i = 0; i < rects.Length; i++)
+ {
+ var top = (int)r.Bounded();
+ var left = (int)r.Bounded();
+ var bottom = (int)r.Bounded();
+ var right = (int)r.Bounded();
+ rects[i] = new RawRect(left, top, right, bottom);
+ }
+ return new FixBadPixelsList(flags, points, rects);
+ }
+
+ public override void Apply(OpcodeImage image, ICollection warnings, CancellationToken cancellationToken)
+ {
+ if (image.Step != 1)
+ {
+ warnings.Add("DNG: FixBadPixelsList cannot apply to a binned image; skipped");
+ return;
+ }
+ var bad = new List<(int X, int Y)>();
+ var bounds = image.Bounds;
+ foreach (var (row, col) in points)
+ {
+ if (col >= bounds.Left && col < bounds.Right && row >= bounds.Top && row < bounds.Bottom) bad.Add((col - image.Left, row - image.Top));
+ }
+ foreach (var rect in rects)
+ {
+ var r = rect.Intersect(bounds);
+ for (var y = r.Top; y < r.Bottom && bad.Count < MaxEntries; y++)
+ {
+ for (var x = r.Left; x < r.Right; x++) bad.Add((x - image.Left, y - image.Top));
+ }
+ }
+ BadPixelRepair.Repair(image, bad);
+ }
+ }
+
+ /// TrimBounds: crops the image to a stage rectangle.
+ private sealed class TrimBounds(uint flags, RawRect bounds) : DngOpcode(6, flags)
+ {
+ public override string Name => "TrimBounds";
+
+ public static TrimBounds Read(uint flags, ref ParamReader r)
+ {
+ var top = (int)r.Bounded();
+ var left = (int)r.Bounded();
+ var bottom = (int)r.Bounded();
+ var right = (int)r.Bounded();
+ return new TrimBounds(flags, new RawRect(left, top, right, bottom));
+ }
+
+ public override void Apply(OpcodeImage image, ICollection warnings, CancellationToken cancellationToken)
+ {
+ var b = bounds.Intersect(image.Bounds);
+ var x0 = (int)double.Ceiling(image.BufferX(b.Left) - 1e-9);
+ var y0 = (int)double.Ceiling(image.BufferY(b.Top) - 1e-9);
+ var x1 = int.Min(image.Width, (int)double.Floor(image.BufferX(b.Right - 1) + 1e-9) + 1);
+ var y1 = int.Min(image.Height, (int)double.Floor(image.BufferY(b.Bottom - 1) + 1e-9) + 1);
+ x0 = int.Max(0, x0);
+ y0 = int.Max(0, y0);
+ if (x1 - x0 <= 0 || y1 - y0 <= 0)
+ {
+ warnings.Add("DNG: TrimBounds outside the image; skipped");
+ return;
+ }
+ if (x0 == 0 && y0 == 0 && x1 == image.Width && y1 == image.Height) return;
+ var src = image.Pixels;
+ var dst = new ImageBuffer(x1 - x0, y1 - y0, src.Channels, clear: false);
+ for (var p = 0; p < src.Channels; p++)
+ {
+ for (var y = y0; y < y1; y++) src.Row(p, y).Slice(x0, x1 - x0).CopyTo(dst.Row(p, y - y0));
+ }
+ if (image.ClipMask is { } mask)
+ {
+ var trimmed = new byte[dst.PlaneLength];
+ for (var y = y0; y < y1; y++) mask.AsSpan(y * src.Width + x0, x1 - x0).CopyTo(trimmed.AsSpan((y - y0) * dst.Width));
+ image.ClipMask = trimmed;
+ }
+ if (image.Cfa is { } cfa) image.Cfa = cfa.Shift(x0, y0);
+ image.Left += x0 * image.Step;
+ image.Top += y0 * image.Step;
+ src.Dispose();
+ image.Pixels = dst;
+ }
+ }
+
+ /// MapTable: 16-bit lookup over the area (inputs beyond the table use its last entry).
+ private sealed class MapTable(uint flags, AreaSpec area, ushort[] table) : DngOpcode(7, flags)
+ {
+ public override string Name => "MapTable";
+ public override bool NeedsUnbalancedValues => true;
+
+ public static MapTable Read(uint flags, ref ParamReader r)
+ {
+ var area = AreaSpec.Read(ref r);
+ var size = r.U32();
+ if (size is < 1 or > 65536 || size * 2 > r.Remaining)
+ {
+ r.Fail();
+ return new MapTable(flags, area, [0]);
+ }
+ var table = new ushort[size];
+ for (var i = 0; i < table.Length; i++) table[i] = r.U16();
+ return new MapTable(flags, area, table);
+ }
+
+ public override void Apply(OpcodeImage image, ICollection warnings, CancellationToken cancellationToken)
+ {
+ var pixels = image.Pixels;
+ var last = table.Length - 1;
+ area.ForEach(image, (p, x, y, _, _) =>
+ {
+ var row = pixels.Row(p, y);
+ row[x] = table[int.Min(Sampling.Code16(row[x]), last)] / 65535f;
+ }, warnings, Name, cancellationToken);
+ }
+ }
+
+ /// MapPolynomial: out = Σ cᵢ·inⁱ on normalised values.
+ private sealed class MapPolynomial(uint flags, AreaSpec area, double[] coefficients) : DngOpcode(8, flags)
+ {
+ public override string Name => "MapPolynomial";
+ public override bool NeedsUnbalancedValues => true;
+
+ public static MapPolynomial Read(uint flags, ref ParamReader r)
+ {
+ var area = AreaSpec.Read(ref r);
+ var degree = r.U32();
+ if (degree > 8)
+ {
+ r.Fail();
+ return new MapPolynomial(flags, area, [0]);
+ }
+ var c = new double[degree + 1];
+ for (var i = 0; i < c.Length; i++) c[i] = r.F64();
+ return new MapPolynomial(flags, area, c);
+ }
+
+ public override void Apply(OpcodeImage image, ICollection warnings, CancellationToken cancellationToken)
+ {
+ var pixels = image.Pixels;
+ area.ForEach(image, (p, x, y, _, _) =>
+ {
+ var row = pixels.Row(p, y);
+ double v = row[x], acc = 0;
+ for (var i = coefficients.Length - 1; i >= 0; i--) acc = acc * v + coefficients[i];
+ row[x] = (float)acc;
+ }, warnings, Name, cancellationToken);
+ }
+ }
+
+ /// GainMap: a grid of gains (normalised origin and spacing over the image bounds), bilinearly interpolated
+ /// and clamped at the grid edges, multiplied into the area.
+ private sealed class GainMap(uint flags, AreaSpec area, int pointsV, int pointsH, double spacingV, double spacingH, double originV, double originH, int mapPlanes, float[] gains) : DngOpcode(9, flags)
+ {
+ public override string Name => "GainMap";
+
+ public static GainMap Read(uint flags, ref ParamReader r)
+ {
+ var area = AreaSpec.Read(ref r);
+ var pv = r.U32();
+ var ph = r.U32();
+ var sv = r.F64();
+ var sh = r.F64();
+ var ov = r.F64();
+ var oh = r.F64();
+ var planes = r.U32();
+ var count = (long)pv * ph * planes;
+ if (pv < 1 || ph < 1 || planes < 1 || count > MaxGainMapPoints || count * 4 > r.Remaining || !(sv > 0) || !(sh > 0))
+ {
+ r.Fail();
+ return new GainMap(flags, area, 1, 1, 1, 1, 0, 0, 1, [1]);
+ }
+ var gains = new float[count];
+ for (var i = 0; i < gains.Length; i++) gains[i] = r.F32();
+ return new GainMap(flags, area, (int)pv, (int)ph, sv, sh, ov, oh, (int)planes, gains);
+ }
+
+ public override void Apply(OpcodeImage image, ICollection warnings, CancellationToken cancellationToken)
+ {
+ var pixels = image.Pixels;
+ var bounds = image.Bounds;
+ area.ForEach(image, (p, x, y, _, _) =>
+ {
+ var plane = int.Min(p - area.Plane, mapPlanes - 1);
+ var (r0, r1, fr) = Index((image.StageY(y) - bounds.Top) / bounds.Height, originV, spacingV, pointsV);
+ var (c0, c1, fc) = Index((image.StageX(x) - bounds.Left) / bounds.Width, originH, spacingH, pointsH);
+ var g00 = gains[(r0 * pointsH + c0) * mapPlanes + plane];
+ var g01 = gains[(r0 * pointsH + c1) * mapPlanes + plane];
+ var g10 = gains[(r1 * pointsH + c0) * mapPlanes + plane];
+ var g11 = gains[(r1 * pointsH + c1) * mapPlanes + plane];
+ var top = g00 + (g01 - g00) * fc;
+ var bottom = g10 + (g11 - g10) * fc;
+ pixels.Row(p, y)[x] *= (float)(top + (bottom - top) * fr);
+ }, warnings, Name, cancellationToken);
+ }
+
+ private static (int I0, int I1, double Fraction) Index(double position, double origin, double spacing, int points)
+ {
+ var f = (position - origin) / spacing;
+ if (!(f > 0)) return (0, 0, 0);
+ if (f >= points - 1) return (points - 1, points - 1, 0);
+ var i = (int)f;
+ return (i, i + 1, f - i);
+ }
+ }
+
+ /// DeltaPerRow/Column (offsets, normalised units) and ScalePerRow/Column (gains), one value per pitch step.
+ private sealed class PerLine(uint id, uint flags, AreaSpec area, float[] values) : DngOpcode(id, flags)
+ {
+ public override string Name => Id switch { 10 => "DeltaPerRow", 11 => "DeltaPerColumn", 12 => "ScalePerRow", _ => "ScalePerColumn" };
+ public override bool NeedsUnbalancedValues => Id is 10 or 11;
+
+ public static PerLine Read(uint id, uint flags, ref ParamReader r)
+ {
+ var area = AreaSpec.Read(ref r);
+ var count = r.U32();
+ if (count > 1 << 20 || count * 4 > r.Remaining)
+ {
+ r.Fail();
+ return new PerLine(id, flags, area, []);
+ }
+ var values = new float[count];
+ for (var i = 0; i < values.Length; i++) values[i] = r.F32();
+ return new PerLine(id, flags, area, values);
+ }
+
+ public override void Apply(OpcodeImage image, ICollection warnings, CancellationToken cancellationToken)
+ {
+ var pixels = image.Pixels;
+ var perRow = Id is 10 or 12;
+ var add = Id is 10 or 11;
+ area.ForEach(image, (p, x, y, sx, sy) =>
+ {
+ var index = perRow ? (sy - area.Area.Top) / area.RowPitch : (sx - area.Area.Left) / area.ColPitch;
+ if ((uint)index >= (uint)values.Length) return;
+ ref var v = ref pixels.Row(p, y)[x];
+ v = add ? v + values[index] : v * values[index];
+ }, warnings, Name, cancellationToken);
+ }
+ }
+}
+
+/// Bad-pixel replacement shared by the FixBadPixels opcodes: mean of the nearest good pixels of the same CFA colour
+/// (5×5, widened to 9×9 when needed), or of the 8 neighbours per plane for planar images.
+internal static class BadPixelRepair
+{
+ public static void Repair(OpcodeImage image, List<(int X, int Y)> bad)
+ {
+ if (bad.Count == 0) return;
+ var pixels = image.Pixels;
+ int w = pixels.Width, h = pixels.Height;
+ var isBad = new HashSet(bad.Count);
+ foreach (var (x, y) in bad) isBad.Add((long)y * w + x);
+ var replacements = new float[bad.Count * pixels.Channels];
+ for (var i = 0; i < bad.Count; i++)
+ {
+ var (x, y) = bad[i];
+ for (var p = 0; p < pixels.Channels; p++)
+ {
+ var plane = pixels.Plane(p);
+ var value = plane[y * w + x];
+ for (var radius = image.Cfa is null ? 1 : 2; radius <= 4; radius += 2)
+ {
+ double sum = 0;
+ var n = 0;
+ for (var dy = -radius; dy <= radius; dy++)
+ {
+ for (var dx = -radius; dx <= radius; dx++)
+ {
+ int nx = x + dx, ny = y + dy;
+ if ((dx | dy) == 0 || (uint)nx >= (uint)w || (uint)ny >= (uint)h || isBad.Contains((long)ny * w + nx)) continue;
+ if (image.Cfa is { } cfa && cfa.ColorAt(nx, ny) != cfa.ColorAt(x, y)) continue;
+ sum += plane[ny * w + nx];
+ n++;
+ }
+ }
+ if (n > 0)
+ {
+ value = (float)(sum / n);
+ break;
+ }
+ }
+ replacements[i * pixels.Channels + p] = value;
+ }
+ }
+ for (var i = 0; i < bad.Count; i++)
+ {
+ var (x, y) = bad[i];
+ for (var p = 0; p < pixels.Channels; p++) pixels.Plane(p)[y * w + x] = replacements[i * pixels.Channels + p];
+ // A repaired sample no longer carries the sensor's clipping (a hot pixel is not a highlight).
+ if (image.ClipMask is { } mask) mask[y * w + x] = 0;
+ }
+ }
+}
+
+/// Sampling helpers for the opcode and pipeline stages.
+internal static class Sampling
+{
+ /// Normalised value → 16-bit code (rounded, clamped), the integer domain of MapTable and FixBadPixelsConstant.
+ public static int Code16(float v) => v >= 1f ? 65535 : v > 0f ? (int)(v * 65535f + 0.5f) : 0;
+
+ /// Catmull-Rom interpolation of a plane at a fractional position (edges clamped; far outside reads the edge).
+ public static float CatmullRom(ReadOnlySpan plane, int width, int height, double x, double y)
+ {
+ x = double.Clamp(x, -2, width + 1);
+ y = double.Clamp(y, -2, height + 1);
+ var ix = (int)double.Floor(x);
+ var iy = (int)double.Floor(y);
+ var (x0, x1, x2, x3) = Weights((float)(x - ix));
+ var (y0, y1, y2, y3) = Weights((float)(y - iy));
+ int c0 = int.Clamp(ix - 1, 0, width - 1), c1 = int.Clamp(ix, 0, width - 1), c2 = int.Clamp(ix + 1, 0, width - 1), c3 = int.Clamp(ix + 2, 0, width - 1);
+ var sum = 0f;
+ for (var j = 0; j < 4; j++)
+ {
+ var o = int.Clamp(iy - 1 + j, 0, height - 1) * width;
+ var r = x0 * plane[o + c0] + x1 * plane[o + c1] + x2 * plane[o + c2] + x3 * plane[o + c3];
+ sum += r * (j switch { 0 => y0, 1 => y1, 2 => y2, _ => y3 });
+ }
+ return sum;
+ }
+
+ private static (float, float, float, float) Weights(float t)
+ {
+ var t2 = t * t;
+ var t3 = t2 * t;
+ return (0.5f * (-t3 + 2 * t2 - t), 0.5f * (3 * t3 - 5 * t2 + 2), 0.5f * (-3 * t3 + 4 * t2 + t), 0.5f * (t3 - t2));
+ }
+}
diff --git a/src/Titano.Core/Codecs/Dng/DngReader.cs b/src/Titano.Core/Codecs/Dng/DngReader.cs
new file mode 100644
index 00000000..a56db315
--- /dev/null
+++ b/src/Titano.Core/Codecs/Dng/DngReader.cs
@@ -0,0 +1,258 @@
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Codecs.Tiff;
+using Titano.Core.Mathematics;
+using Titano.Core.Metadata.Tiff;
+
+namespace Titano.Core.Codecs.Dng;
+
+///
+/// Reads the raw image description of a DNG (DNG 1.6 chapters 4–6) into a : the full-resolution
+/// CFA (PhotometricInterpretation 32803) or LinearRaw (34892) IFD among IFD0 and its SubIFDs; compression 1, 7 (lossless
+/// JPEG, including two-component interleaved tiles), 8 (Deflate with integer or floating-point predictors) and 34892
+/// (lossy JPEG); CFA pattern and plane colours; LinearizationTable; BlackLevel with BlackLevelRepeatDim and DeltaH/V;
+/// WhiteLevel; ActiveArea; DefaultCropOrigin/Size and DefaultScale; the colour tags; OpcodeList1–3; Orientation.
+/// Raster tags are taken from the raw IFD (falling back to IFD0), colour tags from IFD0 (falling back to the raw IFD).
+///
+internal static class DngReader
+{
+ private const uint PhotometricCfa = 32803, PhotometricLinearRaw = 34892;
+ private const ushort CameraCalibrationSignature = 0xC6F3, ProfileCalibrationSignature = 0xC6F4;
+ private const long MaxPixels = 1L << 28;
+ private const int MaxSubIfds = 16;
+
+ /// Not a DNG, no supported raw IFD, or inconsistent tags.
+ public static RawFrame Read(Stream stream)
+ {
+ var r = TiffReader.Open(stream) ?? throw new InvalidDataException("DNG: missing TIFF header");
+ var chain = r.ReadChain();
+ if (chain.Count == 0) throw new InvalidDataException("DNG: no image directory");
+ var ifd0 = chain[0];
+ if (!ifd0.Has(TiffTags.DngVersion)) throw new InvalidDataException("DNG: DNGVersion missing");
+ var raw = FindRawIfd(r, chain) ?? throw new InvalidDataException("DNG: no full-resolution CFA or LinearRaw image");
+
+ var width = (int)long.Min(r.GetUInt(raw, TiffTags.ImageWidth) ?? 0, int.MaxValue);
+ var height = (int)long.Min(r.GetUInt(raw, TiffTags.ImageLength) ?? 0, int.MaxValue);
+ if (width <= 0 || height <= 0 || (long)width * height > MaxPixels) throw new InvalidDataException($"DNG: unsupported raster size {width}x{height}");
+ var spp = (int)(r.GetUInt(raw, TiffTags.SamplesPerPixel) ?? 1);
+ var photometric = r.GetUInt(raw, TiffTags.PhotometricInterpretation);
+ var compression = r.GetUInt(raw, TiffTags.Compression) ?? 1;
+ if (compression is not (1 or 7 or 8 or 34892)) throw new InvalidDataException($"DNG: compression {compression} is not supported");
+ if (compression is 1 or 7) RequirePayload(r, raw, (long)width * height * spp);
+ var floating = (r.GetUInt(raw, TiffTags.SampleFormat) ?? 1) == 3;
+ var bits = (int)(r.GetUInt(raw, TiffTags.BitsPerSample) ?? 16);
+
+ CfaPattern? cfa = null;
+ if (photometric == PhotometricCfa)
+ {
+ if (spp != 1) throw new InvalidDataException("DNG: CFA data must have one sample per pixel");
+ cfa = ReadCfa(r, raw);
+ }
+ else if (spp is not (1 or 3))
+ {
+ throw new InvalidDataException($"DNG: LinearRaw with {spp} samples per pixel is not supported");
+ }
+
+ var activeArea = new RawRect(0, 0, width, height);
+ if (Values(r, raw, ifd0, TiffTags.ActiveArea, 4) is [var top, var left, var bottom, var right, ..])
+ {
+ activeArea = new RawRect((int)left, (int)top, (int)right, (int)bottom).Intersect(activeArea);
+ if (activeArea.IsEmpty) throw new InvalidDataException("DNG: empty ActiveArea");
+ }
+
+ var warnings = new List();
+ var frame = new RawFrame
+ {
+ Decoder = "managed-dng",
+ Width = width,
+ Height = height,
+ SamplesPerPixel = spp,
+ Cfa = cfa,
+ ActiveArea = activeArea,
+ DefaultCrop = ReadCrop(r, raw, ifd0, activeArea),
+ DefaultScale = Values(r, raw, ifd0, TiffTags.DefaultScale, 2) is [var sh, var sv, ..] && sh > 0 && sv > 0 && sh < 16 && sv < 16 ? (sh, sv) : (1, 1),
+ Linearization = ReadLinearization(r, raw, ifd0),
+ Black = ReadBlack(r, raw, ifd0, spp, activeArea, warnings),
+ White = ReadWhite(r, raw, ifd0, spp, floating ? 1.0 : bits is >= 1 and <= 16 ? (1 << bits) - 1 : 65535),
+ Color = ReadColor(r, ifd0, raw, spp == 1 && cfa is null, warnings),
+ OpcodeList1 = Bytes(r, raw, ifd0, TiffTags.OpcodeList1),
+ OpcodeList2 = Bytes(r, raw, ifd0, TiffTags.OpcodeList2),
+ OpcodeList3 = Bytes(r, raw, ifd0, TiffTags.OpcodeList3),
+ Orientation = (int)(r.GetUInt(ifd0, TiffTags.Orientation) ?? 1) is var o and >= 1 and <= 8 ? o : 1,
+ Make = r.GetString(ifd0, TiffTags.Make),
+ Model = r.GetString(ifd0, TiffTags.Model) ?? r.GetString(ifd0, TiffTags.UniqueCameraModel),
+ Loader = new TiffRasterLoader(r, raw),
+ };
+ frame.Warnings.AddRange(warnings);
+ frame.Warnings.AddRange(r.Warnings);
+ return frame;
+ }
+
+ /// Uncompressed and lossless-JPEG data hold at least one bit per sample; checked before the raster is allocated
+ /// so a corrupted size cannot trigger a huge allocation.
+ private static void RequirePayload(TiffReader r, Ifd raw, long samples)
+ {
+ var counts = r.GetUInts(raw, raw.Has(TiffTags.TileByteCounts) ? TiffTags.TileByteCounts : TiffTags.StripByteCounts);
+ long total = 0;
+ foreach (var c in counts ?? []) total += c;
+ if (total * 8 < samples) throw new InvalidDataException("DNG: image data too short for the raster");
+ }
+
+ /// First IFD with NewSubfileType 0 and a CFA/LinearRaw photometric: IFD0, its SubIFDs (two levels), the chain.
+ private static Ifd? FindRawIfd(TiffReader r, IReadOnlyList chain)
+ {
+ var visited = new HashSet();
+ foreach (var ifd in chain) visited.Add(ifd.Position);
+ var queue = new List<(Ifd Ifd, int Depth)> { (chain[0], 0) };
+ for (var i = 0; i < queue.Count; i++)
+ {
+ var (ifd, depth) = queue[i];
+ if (IsRaw(r, ifd)) return ifd;
+ if (depth < 2 && ifd.Entries.TryGetValue(TiffTags.SubIfds, out var sub) && sub.Count <= MaxSubIfds)
+ {
+ foreach (var offset in r.GetUInts(sub) ?? [])
+ {
+ if (r.ReadIfd(offset, visited) is { } child) queue.Add((child, depth + 1));
+ }
+ }
+ }
+ foreach (var ifd in chain)
+ {
+ if (IsRaw(r, ifd)) return ifd;
+ }
+ return null;
+ }
+
+ private static bool IsRaw(TiffReader r, Ifd ifd) =>
+ (r.GetUInt(ifd, TiffTags.NewSubfileType) ?? 0) == 0
+ && r.GetUInt(ifd, TiffTags.PhotometricInterpretation) is PhotometricCfa or PhotometricLinearRaw;
+
+ private static CfaPattern ReadCfa(TiffReader r, Ifd raw)
+ {
+ if ((r.GetUInt(raw, TiffTags.CfaLayout) ?? 1) != 1) throw new InvalidDataException("DNG: non-rectangular CFA layouts are not supported");
+ var dim = IfdValue.UInts(r, raw, TiffTags.CfaRepeatPatternDim) ?? [2, 2];
+ if (dim.Length < 2) throw new InvalidDataException("DNG: bad CFARepeatPatternDim");
+ int rows = (int)dim[0], cols = (int)dim[1];
+ if (rows is < 1 or > CfaPattern.MaxSize || cols is < 1 or > CfaPattern.MaxSize) throw new InvalidDataException($"DNG: CFA pattern {rows}x{cols} is not supported");
+ var pattern = IfdValue.UInts(r, raw, TiffTags.CfaPattern) ?? throw new InvalidDataException("DNG: CFAPattern missing");
+ if (pattern.Length < rows * cols) throw new InvalidDataException("DNG: CFAPattern too short");
+ var planeColor = IfdValue.UInts(r, raw, TiffTags.CfaPlaneColor) ?? [0, 1, 2];
+ var colors = new byte[rows * cols];
+ for (var i = 0; i < colors.Length; i++)
+ {
+ // CFAPattern holds colour codes (0 red, 1 green, 2 blue, 3+ CMY/white); CFAPlaneColor names the planes.
+ var code = pattern[i];
+ if (code > 2 || planeColor.Length != 3 || Array.IndexOf(planeColor, code) < 0)
+ throw new InvalidDataException("DNG: only red/green/blue CFAs are supported");
+ colors[i] = (byte)code;
+ }
+ return new CfaPattern(cols, rows, colors);
+ }
+
+ private static RawRect? ReadCrop(TiffReader r, Ifd raw, Ifd ifd0, RawRect active)
+ {
+ if (Values(r, raw, ifd0, TiffTags.DefaultCropOrigin, 2) is not [var ox, var oy, ..] || Values(r, raw, ifd0, TiffTags.DefaultCropSize, 2) is not [var cw, var ch, ..])
+ return null;
+ var crop = new RawRect((int)double.Round(ox), (int)double.Round(oy), (int)double.Round(ox + cw), (int)double.Round(oy + ch))
+ .Intersect(new RawRect(0, 0, active.Width, active.Height));
+ return crop.IsEmpty ? null : crop;
+ }
+
+ private static ushort[]? ReadLinearization(TiffReader r, Ifd raw, Ifd ifd0)
+ {
+ var ifd = raw.Has(TiffTags.LinearizationTable) ? raw : ifd0;
+ if (!ifd.Entries.TryGetValue(TiffTags.LinearizationTable, out var e) || e.Count is 0 or > 65536) return null;
+ return r.GetUInts(e) is { } values ? Array.ConvertAll(values, v => (ushort)uint.Min(v, 65535)) : null;
+ }
+
+ private static RawBlackLevel ReadBlack(TiffReader r, Ifd raw, Ifd ifd0, int spp, RawRect active, ICollection warnings)
+ {
+ var dim = Values(r, raw, ifd0, TiffTags.BlackLevelRepeatDim, 2) is [var dr, var dc, ..] ? ((int)dr, (int)dc) : (1, 1);
+ var (rows, cols) = dim;
+ if (rows is < 1 or > 64 || cols is < 1 or > 64)
+ {
+ warnings.Add("DNG: bad BlackLevelRepeatDim ignored");
+ (rows, cols) = (1, 1);
+ }
+ var values = new float[rows * cols * spp];
+ if (Doubles(r, raw, ifd0, TiffTags.BlackLevel, 1 << 14) is { Length: > 0 } black)
+ {
+ if (black.Length != values.Length && black.Length != 1) warnings.Add($"DNG: BlackLevel has {black.Length} values, {values.Length} expected");
+ for (var i = 0; i < values.Length; i++) values[i] = (float)black[black.Length == values.Length ? i : i % black.Length];
+ }
+ var deltaH = Doubles(r, raw, ifd0, TiffTags.BlackLevelDeltaH, 1 << 20) is { } h && h.Length >= active.Width ? Array.ConvertAll(h, v => (float)v) : null;
+ var deltaV = Doubles(r, raw, ifd0, TiffTags.BlackLevelDeltaV, 1 << 20) is { } v && v.Length >= active.Height ? Array.ConvertAll(v, x => (float)x) : null;
+ return new RawBlackLevel(rows, cols, values, deltaH, deltaV);
+ }
+
+ private static double[] ReadWhite(TiffReader r, Ifd raw, Ifd ifd0, int spp, double fallback)
+ {
+ var white = new double[spp];
+ var tag = Doubles(r, raw, ifd0, TiffTags.WhiteLevel, 16);
+ for (var i = 0; i < spp; i++) white[i] = tag is { Length: > 0 } t ? t[int.Min(i, t.Length - 1)] : fallback;
+ return white;
+ }
+
+ private static DngColorProfile ReadColor(TiffReader r, Ifd ifd0, Ifd raw, bool monochrome, ICollection warnings)
+ {
+ Matrix3? M(ushort tag) => Doubles(r, ifd0, raw, tag, 64) is { Length: 9 } m ? new Matrix3(m[0], m[1], m[2], m[3], m[4], m[5], m[6], m[7], m[8]) : null;
+ Mathematics.Vector3D? V(ushort tag) => Doubles(r, ifd0, raw, tag, 16) is { Length: 3 } v ? new Mathematics.Vector3D(v[0], v[1], v[2]) : null;
+ var baseline = Doubles(r, ifd0, raw, TiffTags.BaselineExposure, 1) is [var b] && double.Abs(b) < 16 ? b : 0;
+ if (monochrome) return new DngColorProfile { BaselineExposure = baseline };
+
+ // CameraCalibration only applies when its signature matches the profile's (DNG §6, "CameraCalibrationSignature").
+ var useCalibration = r.GetString(ifd0, CameraCalibrationSignature) == r.GetString(ifd0, ProfileCalibrationSignature);
+ if (!useCalibration && (ifd0.Has(TiffTags.CameraCalibration1) || ifd0.Has(TiffTags.CameraCalibration2)))
+ warnings.Add("DNG: CameraCalibration ignored (signature does not match the profile)");
+ var cm1 = M(TiffTags.ColorMatrix1) ?? throw new InvalidDataException("DNG: ColorMatrix1 missing");
+ return new DngColorProfile
+ {
+ ColorMatrix1 = cm1,
+ ColorMatrix2 = M(TiffTags.ColorMatrix2),
+ CameraCalibration1 = useCalibration ? M(TiffTags.CameraCalibration1) : null,
+ CameraCalibration2 = useCalibration ? M(TiffTags.CameraCalibration2) : null,
+ ForwardMatrix1 = M(TiffTags.ForwardMatrix1),
+ ForwardMatrix2 = M(TiffTags.ForwardMatrix2),
+ CalibrationIlluminant1 = (int)(r.GetUInt(ifd0, TiffTags.CalibrationIlluminant1) ?? 0),
+ CalibrationIlluminant2 = (int)(r.GetUInt(ifd0, TiffTags.CalibrationIlluminant2) ?? 0),
+ AnalogBalance = V(TiffTags.AnalogBalance) is { } ab && ab.X > 0 && ab.Y > 0 && ab.Z > 0 ? ab : new(1, 1, 1),
+ AsShotNeutral = V(TiffTags.AsShotNeutral),
+ AsShotWhite = Doubles(r, ifd0, raw, TiffTags.AsShotWhiteXy, 2) is [var x, var y] ? new Chromaticity(x, y) : null,
+ BaselineExposure = baseline,
+ };
+ }
+
+ private static byte[]? Bytes(TiffReader r, Ifd raw, Ifd ifd0, ushort tag)
+ {
+ var ifd = raw.Has(tag) ? raw : ifd0;
+ return ifd.Entries.TryGetValue(tag, out var e) ? r.ReadBytes(e) : null;
+ }
+
+ /// Finite numeric values of a tag from the first IFD that has it, or null (also when there are more than ).
+ private static double[]? Doubles(TiffReader r, Ifd first, Ifd second, ushort tag, int max)
+ {
+ var ifd = first.Has(tag) ? first : second;
+ if (!ifd.Entries.TryGetValue(tag, out var e) || e.Count == 0 || e.Count > max) return null;
+ var values = r.GetDoubles(e);
+ if (values is null) return null;
+ foreach (var v in values)
+ {
+ if (!double.IsFinite(v)) return null;
+ }
+ return values;
+ }
+
+ private static double[]? Values(TiffReader r, Ifd first, Ifd second, ushort tag, int count) =>
+ Doubles(r, first, second, tag, 16) is { } v && v.Length >= count && v.All(x => x >= 0 && x < int.MaxValue / 2) ? v : null;
+}
+
+/// Loads a TIFF/DNG raster IFD through .
+internal sealed class TiffRasterLoader(TiffReader reader, Ifd ifd) : RawLoader
+{
+ public override RawSamples Load(Stream stream, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ var raster = TiffImageReader.ReadRaster(reader, ifd, new TiffDecodeOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism });
+ var samples = new RawSamples(raster.Width, raster.Height, raster.SamplesPerPixel, raster.Samples, raster.FloatSamples);
+ samples.Warnings.AddRange(raster.Warnings);
+ return samples;
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/AhdDemosaic.cs b/src/Titano.Core/Codecs/Raw/AhdDemosaic.cs
new file mode 100644
index 00000000..79008691
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/AhdDemosaic.cs
@@ -0,0 +1,245 @@
+using System.Buffers;
+using Titano.Core.Imaging;
+using Titano.Core.Mathematics;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// Adaptive Homogeneity-Directed demosaicing (K. Hirakawa, T. W. Parks, "Adaptive homogeneity-directed demosaicing
+/// algorithm", IEEE Trans. Image Processing 14(3), 2005), in the formulation of dcraw's ahd_interpolate:
+/// green is interpolated horizontally and vertically (gradient-corrected, limited to its two neighbours), red and blue
+/// follow by colour-difference interpolation in each direction, both candidates are converted to CIELab, and each pixel
+/// takes the direction whose 3×3 neighbourhood is most homogeneous (Lab distances within adaptive luminance and chroma
+/// thresholds), or the average on a tie. Works on float data in tiles processed in parallel; a 5-pixel border is
+/// bilinear.
+///
+internal static unsafe class AhdDemosaic
+{
+ private const int Ts = 256;
+ private const int LutSize = 1 << 16;
+ private const float LutScale = LutSize / 2f;
+
+ /// CIELab f(t) for t in [0, 2): cube root above (6/29)³, the linear toe below.
+ private static readonly float[] LabF = BuildLabF();
+
+ /// White-balanced camera RGB → XYZ (white at Y = 1), used only for the Lab metric.
+ public static ImageBuffer Run(ImageBuffer mosaic, CfaPattern cfa, Matrix3 balancedToXyz, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ if (!cfa.IsBayer) throw new ArgumentException("Bayer pattern expected", nameof(cfa));
+ int w = mosaic.Width, h = mosaic.Height;
+ if (w < 16 || h < 16) return Demosaic.Bilinear(mosaic, cfa, maxDegreeOfParallelism, cancellationToken);
+ var output = new ImageBuffer(w, h, 3, clear: false);
+ Demosaic.BilinearBorder(mosaic, cfa, output, 5);
+
+ // Rows of the matrix are divided by the white's XYZ so that Lab sees X/Xn, Y/Yn, Z/Zn directly.
+ var white = balancedToXyz * new Vector3D(1, 1, 1);
+ var m = new float[9];
+ double[] rows = [balancedToXyz.M11, balancedToXyz.M12, balancedToXyz.M13, balancedToXyz.M21, balancedToXyz.M22, balancedToXyz.M23, balancedToXyz.M31, balancedToXyz.M32, balancedToXyz.M33];
+ double[] whites = [white.X, white.Y, white.Z];
+ for (var i = 0; i < 9; i++) m[i] = (float)(rows[i] / (whites[i / 3] > 0 ? whites[i / 3] : 1));
+
+ var tops = new List();
+ for (var top = 2; top < h - 5; top += Ts - 6) tops.Add(top);
+ var lefts = new List();
+ for (var left = 2; left < w - 5; left += Ts - 6) lefts.Add(left);
+ var options = new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism, CancellationToken = cancellationToken };
+ var colors = new int[4];
+ for (var i = 0; i < 4; i++) colors[i] = cfa.ColorAt(i & 1, i >> 1);
+ Parallel.For(0, tops.Count * lefts.Count, options, () => new Workspace(), (t, _, ws) =>
+ {
+ Tile(mosaic, output, colors, m, tops[t / lefts.Count], lefts[t % lefts.Count], ws);
+ return ws;
+ }, ws => ws.Dispose());
+ return output;
+ }
+
+ /// Per-thread tile buffers: two directional RGB and Lab images plus homogeneity counts.
+ private sealed class Workspace : IDisposable
+ {
+ public readonly float[] Rgb = ArrayPool.Shared.Rent(6 * Ts * Ts);
+ public readonly float[] Lab = ArrayPool.Shared.Rent(6 * Ts * Ts);
+ public readonly byte[] Homo = ArrayPool.Shared.Rent(2 * Ts * Ts);
+
+ public void Dispose()
+ {
+ ArrayPool.Shared.Return(Rgb);
+ ArrayPool.Shared.Return(Lab);
+ ArrayPool.Shared.Return(Homo);
+ }
+ }
+
+ private static void Tile(ImageBuffer mosaic, ImageBuffer output, int[] colors, float[] xyz, int top, int left, Workspace ws)
+ {
+ int w = mosaic.Width, h = mosaic.Height;
+ const int plane = Ts * Ts;
+ fixed (float* image = mosaic.Storage, rgbBase = ws.Rgb, labBase = ws.Lab, mat = xyz, lut = LabF)
+ fixed (byte* homoBase = ws.Homo)
+ fixed (float* outBase = output.Storage)
+ {
+ // Direction d: R, G, B planes at rgbBase + (3d + c)·plane; Lab likewise.
+ var rowEnd = int.Min(top + Ts, h - 2);
+ var colEnd = int.Min(left + Ts, w - 2);
+
+ // 1. Green horizontally and vertically at red/blue sites.
+ for (var row = top; row < rowEnd; row++)
+ {
+ var col = left + (Color(colors, left, row) == 1 ? 1 : 0);
+ var gh = rgbBase + plane + (row - top) * Ts - left;
+ var gv = rgbBase + 4 * plane + (row - top) * Ts - left;
+ for (; col < colEnd; col += 2)
+ {
+ var pix = image + row * w + col;
+ var val = ((pix[-1] + pix[0] + pix[1]) * 2 - pix[-2] - pix[2]) * 0.25f;
+ gh[col] = Limit(val, pix[-1], pix[1]);
+ val = ((pix[-w] + pix[0] + pix[w]) * 2 - pix[-2 * w] - pix[2 * w]) * 0.25f;
+ gv[col] = Limit(val, pix[-w], pix[w]);
+ }
+ }
+
+ // 2. Red and blue in each direction, then CIELab.
+ rowEnd = int.Min(top + Ts - 1, h - 3);
+ colEnd = int.Min(left + Ts - 1, w - 3);
+ for (var d = 0; d < 2; d++)
+ {
+ var rgb = rgbBase + 3 * d * plane;
+ var lab = labBase + 3 * d * plane;
+ for (var row = top + 1; row < rowEnd; row++)
+ {
+ for (var col = left + 1; col < colEnd; col++)
+ {
+ var pix = image + row * w + col;
+ var i = (row - top) * Ts + col - left;
+ var r = rgb + i;
+ var own = Color(colors, col, row);
+ float red, green, blue;
+ if (own == 1)
+ {
+ // Colour of the vertical neighbours; the horizontal ones carry the other one.
+ var vertical = Color(colors, col, row + 1);
+ var h0 = pix[0] + (pix[-1] + pix[1] - r[plane - 1] - r[plane + 1]) * 0.5f;
+ var v0 = pix[0] + (pix[-w] + pix[w] - r[plane - Ts] - r[plane + Ts]) * 0.5f;
+ green = pix[0];
+ if (vertical == 0) (red, blue) = (v0, h0);
+ else (red, blue) = (h0, v0);
+ }
+ else
+ {
+ green = r[plane];
+ var opposite = green + (pix[-w - 1] + pix[-w + 1] + pix[w - 1] + pix[w + 1]
+ - r[plane - Ts - 1] - r[plane - Ts + 1] - r[plane + Ts - 1] - r[plane + Ts + 1]) * 0.25f;
+ (red, blue) = own == 0 ? (pix[0], opposite) : (opposite, pix[0]);
+ }
+ red = float.Max(red, 0f);
+ blue = float.Max(blue, 0f);
+ r[0] = red;
+ r[plane] = green;
+ r[2 * plane] = blue;
+ var fx = F(lut, mat[0] * red + mat[1] * green + mat[2] * blue);
+ var fy = F(lut, mat[3] * red + mat[4] * green + mat[5] * blue);
+ var fz = F(lut, mat[6] * red + mat[7] * green + mat[8] * blue);
+ var l = lab + i;
+ l[0] = 116f * fy - 16f;
+ l[plane] = 500f * (fx - fy);
+ l[2 * plane] = 200f * (fy - fz);
+ }
+ }
+ }
+
+ // 3. Homogeneity: neighbours within adaptive luminance and chroma thresholds.
+ new Span(homoBase, 2 * plane).Clear();
+ rowEnd = int.Min(top + Ts - 2, h - 4);
+ colEnd = int.Min(left + Ts - 2, w - 4);
+ var labH = labBase;
+ var labV = labBase + 3 * plane;
+ for (var row = top + 2; row < rowEnd; row++)
+ {
+ for (var col = left + 2; col < colEnd; col++)
+ {
+ var i = (row - top) * Ts + col - left;
+ var lh = labH + i;
+ var lv = labV + i;
+ float lh0 = Diff(lh, -1), lh1 = Diff(lh, 1), lh2 = Diff(lh, -Ts), lh3 = Diff(lh, Ts);
+ float lv0 = Diff(lv, -1), lv1 = Diff(lv, 1), lv2 = Diff(lv, -Ts), lv3 = Diff(lv, Ts);
+ float ah0 = Chroma(lh, -1, plane), ah1 = Chroma(lh, 1, plane), ah2 = Chroma(lh, -Ts, plane), ah3 = Chroma(lh, Ts, plane);
+ float av0 = Chroma(lv, -1, plane), av1 = Chroma(lv, 1, plane), av2 = Chroma(lv, -Ts, plane), av3 = Chroma(lv, Ts, plane);
+ var leps = float.Min(float.Max(lh0, lh1), float.Max(lv2, lv3));
+ var abeps = float.Min(float.Max(ah0, ah1), float.Max(av2, av3));
+ homoBase[i] = (byte)(Count(lh0, ah0, leps, abeps) + Count(lh1, ah1, leps, abeps) + Count(lh2, ah2, leps, abeps) + Count(lh3, ah3, leps, abeps));
+ homoBase[plane + i] = (byte)(Count(lv0, av0, leps, abeps) + Count(lv1, av1, leps, abeps) + Count(lv2, av2, leps, abeps) + Count(lv3, av3, leps, abeps));
+ }
+ }
+
+ // 4. Most homogeneous direction over 3×3 (average on a tie).
+ rowEnd = int.Min(top + Ts - 3, h - 5);
+ colEnd = int.Min(left + Ts - 3, w - 5);
+ var outPlane = w * h;
+ for (var row = top + 3; row < rowEnd; row++)
+ {
+ for (var col = left + 3; col < colEnd; col++)
+ {
+ var i = (row - top) * Ts + col - left;
+ int hm0 = 0, hm1 = 0;
+ for (var k = -Ts; k <= Ts; k += Ts)
+ {
+ var p = homoBase + i + k;
+ hm0 += p[-1] + p[0] + p[1];
+ hm1 += p[plane - 1] + p[plane] + p[plane + 1];
+ }
+ var o = outBase + row * w + col;
+ var a = rgbBase + i;
+ var b = rgbBase + 3 * plane + i;
+ if (hm0 > hm1)
+ {
+ o[0] = a[0];
+ o[outPlane] = a[plane];
+ o[2 * outPlane] = a[2 * plane];
+ }
+ else if (hm1 > hm0)
+ {
+ o[0] = b[0];
+ o[outPlane] = b[plane];
+ o[2 * outPlane] = b[2 * plane];
+ }
+ else
+ {
+ o[0] = (a[0] + b[0]) * 0.5f;
+ o[outPlane] = (a[plane] + b[plane]) * 0.5f;
+ o[2 * outPlane] = (a[2 * plane] + b[2 * plane]) * 0.5f;
+ }
+ }
+ }
+ }
+ }
+
+ private static int Color(int[] colors, int x, int y) => colors[(y & 1) << 1 | x & 1];
+
+ private static float Limit(float v, float a, float b) => a < b ? float.Clamp(v, a, b) : float.Clamp(v, b, a);
+
+ private static float F(float* lut, float t)
+ {
+ var i = (int)(t * LutScale);
+ return lut[i < 0 ? 0 : i >= LutSize ? LutSize - 1 : i];
+ }
+
+ private static float Diff(float* l, int offset) => float.Abs(l[0] - l[offset]);
+
+ private static float Chroma(float* l, int offset, int plane)
+ {
+ var da = l[plane] - l[plane + offset];
+ var db = l[2 * plane] - l[2 * plane + offset];
+ return da * da + db * db;
+ }
+
+ private static int Count(float l, float ab, float leps, float abeps) => l <= leps && ab <= abeps ? 1 : 0;
+
+ private static float[] BuildLabF()
+ {
+ var lut = new float[LutSize];
+ for (var i = 0; i < LutSize; i++)
+ {
+ var t = i / (double)LutScale;
+ lut[i] = (float)(t > 216.0 / 24389 ? double.Cbrt(t) : (24389.0 / 27 * t + 16) / 116);
+ }
+ return lut;
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/ArwReader.cs b/src/Titano.Core/Codecs/Raw/ArwReader.cs
new file mode 100644
index 00000000..f055db04
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/ArwReader.cs
@@ -0,0 +1,136 @@
+using System.Buffers.Binary;
+using Titano.Core.Metadata.Tiff;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// Sony ARW: the CFA SubIFD holds uncompressed 16-bit words (or packed samples) or ARW2 "cRAW" (Compression 32767 with
+/// one byte per pixel): 16-pixel blocks of one colour storing an 11-bit maximum and minimum with their positions and
+/// fourteen 7-bit deltas scaled by a shift, expanded through the tone curve of tag 0x7010 (dcraw
+/// sony_arw2_load_raw). Black and white come from tags 0x7310/0x787F when present (14-bit scale), otherwise
+/// 512 and the curve's top (cRAW) or 16383. As-shot white balance sits in the encrypted SR2 block, which is not read: ARW files develop with daylight
+/// balance. ARW1 (DSLR-A100) and the lossless ARW 5.0 codec are not supported.
+///
+internal static class ArwReader
+{
+ private const uint CompressionSony = 32767;
+ private const ushort ToneCurveTag = 0x7010;
+ private const ushort BlackLevelTag = 0x7310;
+ private const ushort WhiteLevelTag = 0x787F;
+
+ public static RawFrame Read(Stream stream)
+ {
+ var r = TiffReader.Open(stream) ?? throw new InvalidDataException("ARW: missing TIFF header");
+ var chain = r.ReadChain();
+ if (chain.Count == 0) throw new InvalidDataException("ARW: no image directory");
+ var ifd0 = chain[0];
+ var raw = NefReader.FindCfa(r, ifd0) ?? throw new InvalidDataException("ARW: CFA image missing");
+ var (width, height) = NativeRaw.Size(r.GetUInt(raw, TiffTags.ImageWidth) ?? 0, r.GetUInt(raw, TiffTags.ImageLength) ?? 0);
+ var bits = (int)(r.GetUInt(raw, TiffTags.BitsPerSample) ?? 0);
+ var compression = r.GetUInt(raw, TiffTags.Compression) ?? 1;
+ var (offset, length) = NefReader.Strip(r, raw);
+ var warnings = new List();
+ var cfa = NativeRaw.TiffEpCfa(r, raw);
+ if (cfa is null)
+ {
+ cfa = CfaPattern.Bayer("RGGB");
+ warnings.Add("ARW: CFA pattern missing; RGGB assumed");
+ }
+ if (!cfa.IsBayer) throw new InvalidDataException("ARW: only Bayer sensors are supported");
+
+ RawLoader loader;
+ double black, white;
+ if (compression == CompressionSony && length == (long)width * height)
+ {
+ if (width < 32 || width % 32 != 0) throw new InvalidDataException("ARW: cRAW width must be a multiple of 32");
+ var curve = ToneCurve(r, raw, ifd0);
+ loader = new Arw2Loader(offset, width, height, curve);
+ // Sensor saturation is the largest 11-bit code through the curve.
+ (black, white) = (512, curve[0x7FF << 1]);
+ }
+ else if (length >= (long)width * height * 2)
+ {
+ loader = new PlainRawLoader(offset, length, width, height, 16, words: true, littleEndian: r.LittleEndian);
+ (black, white) = (512, 16383);
+ }
+ else if (compression == 1 && bits is 12 or 14 && length >= ((long)width * bits + 7) / 8 * height)
+ {
+ loader = new PlainRawLoader(offset, length, width, height, bits, words: false, littleEndian: false);
+ (black, white) = (128 << (bits - 12), (1 << bits) - 1);
+ }
+ else
+ {
+ throw new InvalidDataException($"ARW: compression {compression} with {length} bytes is not supported");
+ }
+
+ var blackLevel = IfdValue.UInts(r, raw, BlackLevelTag) is { Length: 4 } b
+ ? NativeRaw.Black2x2(cfa, [b[0], b[1], b[2], b[3]])
+ : NativeRaw.Black(black);
+ if (IfdValue.UInts(r, raw, WhiteLevelTag) is { Length: > 0 } w) white = w.Max();
+ return NativeRaw.Frame("managed-arw", width, height, cfa, new RawRect(0, 0, width, height), blackLevel, white, null,
+ (int)(r.GetUInt(ifd0, TiffTags.Orientation) ?? 1), r.GetString(ifd0, TiffTags.Make), r.GetString(ifd0, TiffTags.Model), loader, warnings);
+ }
+
+ /// Tone curve from the four breakpoints of tag 0x7010: slopes 1, 2, 4, 8, 16 between 0, the breakpoints and 4095.
+ private static ushort[] ToneCurve(TiffReader r, Ifd raw, Ifd ifd0)
+ {
+ Span knots = [0, 0, 0, 0, 0, 4095];
+ if ((IfdValue.UInts(r, raw, ToneCurveTag) ?? IfdValue.UInts(r, ifd0, ToneCurveTag)) is { Length: >= 4 } t)
+ {
+ for (var i = 0; i < 4; i++) knots[i + 1] = (int)(t[i] >> 2 & 0xFFF);
+ }
+ var curve = new ushort[0x1000];
+ for (var i = 0; i < curve.Length; i++) curve[i] = (ushort)i;
+ for (var i = 0; i < 5; i++)
+ {
+ for (var j = knots[i] + 1; j <= knots[i + 1] && j < curve.Length; j++) curve[j] = (ushort)(curve[j - 1] + (1 << i));
+ }
+ return curve;
+ }
+
+ private sealed class Arw2Loader(long offset, int width, int height, ushort[] curve) : RawLoader
+ {
+ public override RawSamples Load(Stream stream, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ var data = NativeRaw.ReadPayload(stream, offset, (long)width * height);
+ var samples = new ushort[width * height];
+ Parallel.For(0, height, new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism, CancellationToken = cancellationToken }, row =>
+ {
+ // One spare byte: the last delta of a block is read as a 16-bit word that reaches one byte past it.
+ Span line = stackalloc byte[width + 2];
+ line.Clear();
+ data.AsSpan(row * width, width).CopyTo(line);
+ Span pix = stackalloc int[16];
+ var dst = samples.AsSpan(row * width, width);
+ var dp = 0;
+ for (var col = 0; col < width - 30; dp += 16)
+ {
+ var val = BinaryPrimitives.ReadUInt32LittleEndian(line[dp..]);
+ int max = (int)(val & 0x7FF), min = (int)(val >> 11 & 0x7FF), imax = (int)(val >> 22 & 0xF), imin = (int)(val >> 26 & 0xF);
+ var sh = 0;
+ while (sh < 4 && 0x80 << sh <= max - min) sh++;
+ var bit = 30;
+ for (var i = 0; i < 16; i++)
+ {
+ if (i == imax)
+ {
+ pix[i] = max;
+ }
+ else if (i == imin)
+ {
+ pix[i] = min;
+ }
+ else
+ {
+ pix[i] = int.Min(((BinaryPrimitives.ReadUInt16LittleEndian(line[(dp + (bit >> 3))..]) >> (bit & 7) & 0x7F) << sh) + min, 0x7FF);
+ bit += 7;
+ }
+ }
+ for (var i = 0; i < 16; i++, col += 2) dst[col] = curve[pix[i] << 1];
+ col -= (col & 1) != 0 ? 1 : 31;
+ }
+ });
+ return new RawSamples(width, height, 1, samples, null);
+ }
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/CameraMatrices.cs b/src/Titano.Core/Codecs/Raw/CameraMatrices.cs
new file mode 100644
index 00000000..bc1967f1
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/CameraMatrices.cs
@@ -0,0 +1,114 @@
+using Titano.Core.Mathematics;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// Camera colour matrices (XYZ → camera, D65 calibration, values × 10 000) for bodies whose native RAW files Titano
+/// develops, keyed by the normalised "Brand Model" name. The numbers are the public adobe_coeff table of Dave Coffin's
+/// dcraw (public-domain origin, also carried by LibRaw), which reproduces the ColorMatrix2 values Adobe DNG Converter
+/// writes for these cameras; they are data, not code. A body missing here is decoded through its embedded preview.
+///
+internal static class CameraMatrices
+{
+ private static readonly Dictionary Table = Build();
+
+ /// Matrix for a normalised camera name (see ), or null.
+ public static Matrix3? Find(string? cameraName)
+ {
+ if (cameraName is null || !Table.TryGetValue(cameraName, out var m)) return null;
+ return new Matrix3(m[0] / 1e4, m[1] / 1e4, m[2] / 1e4, m[3] / 1e4, m[4] / 1e4, m[5] / 1e4, m[6] / 1e4, m[7] / 1e4, m[8] / 1e4);
+ }
+
+ /// Normalised names with an entry (for diagnostics and tests).
+ public static IEnumerable Names => Table.Keys;
+
+ private static Dictionary Build()
+ {
+ var t = new Dictionary(StringComparer.OrdinalIgnoreCase);
+ void Add(short[] m, params string[] names)
+ {
+ foreach (var n in names) t[n] = m;
+ }
+
+ // Canon (CR2).
+ Add([6347, -479, -972, -8297, 15954, 2480, -1968, 2131, 7649], "Canon EOS 5D");
+ Add([4716, 603, -830, -7798, 15474, 2480, -1496, 1937, 6651], "Canon EOS 5D Mark II");
+ Add([6722, -635, -963, -4287, 12460, 2028, -908, 2162, 5668], "Canon EOS 5D Mark III");
+ Add([6446, -366, -864, -4436, 12204, 2513, -952, 2496, 6348], "Canon EOS 5D Mark IV");
+ Add([6250, -711, -808, -5153, 12794, 2636, -1249, 2198, 5610], "Canon EOS 5DS", "Canon EOS 5DS R");
+ Add([7034, -804, -1014, -4420, 12564, 2058, -851, 1994, 5758], "Canon EOS 6D", "Canon EOS 70D");
+ Add([6875, -970, -932, -4691, 12459, 2501, -874, 1953, 5809], "Canon EOS 6D Mark II");
+ Add([6844, -996, -856, -3876, 11761, 2396, -593, 1772, 6198], "Canon EOS 7D");
+ Add([7268, -1082, -969, -4186, 11839, 2663, -825, 2029, 5839], "Canon EOS 7D Mark II");
+ Add([6071, -747, -856, -7653, 15365, 2441, -2025, 2553, 7315], "Canon EOS 40D");
+ Add([4920, 616, -593, -6493, 13964, 2784, -1774, 3178, 7005], "Canon EOS 50D");
+ Add([6719, -994, -925, -4408, 12426, 2211, -887, 2129, 6051], "Canon EOS 60D");
+ Add([7457, -671, -937, -4849, 12495, 2643, -1213, 2354, 5492], "Canon EOS 80D");
+ Add([6941, -1164, -857, -3825, 11597, 2534, -416, 1540, 6039], "Canon EOS 550D", "Canon EOS Rebel T2i", "Canon EOS Kiss X4");
+ Add([6461, -907, -882, -4300, 12184, 2378, -819, 1944, 5931], "Canon EOS 600D", "Canon EOS Rebel T3i", "Canon EOS Kiss X5",
+ "Canon EOS 1200D", "Canon EOS Rebel T5", "Canon EOS Kiss X70");
+ Add([6602, -841, -939, -4472, 12458, 2247, -975, 2039, 6148], "Canon EOS 650D", "Canon EOS Rebel T4i", "Canon EOS Kiss X6i",
+ "Canon EOS 700D", "Canon EOS Rebel T5i", "Canon EOS Kiss X7i", "Canon EOS 100D", "Canon EOS Rebel SL1", "Canon EOS Kiss X7", "Canon EOS M");
+ Add([6362, -823, -847, -4426, 12109, 2616, -743, 1857, 5635], "Canon EOS 750D", "Canon EOS Rebel T6i", "Canon EOS Kiss X8i",
+ "Canon EOS 760D", "Canon EOS Rebel T6s", "Canon EOS 8000D");
+ Add([7377, -742, -998, -4235, 11981, 2549, -673, 1918, 5538], "Canon EOS 77D", "Canon EOS 9000D", "Canon EOS 800D", "Canon EOS Rebel T7i", "Canon EOS Kiss X9i");
+ Add([6847, -614, -1014, -4669, 12737, 2139, -1197, 2488, 6846], "Canon EOS-1D X");
+ Add([7596, -978, -967, -4808, 12571, 2503, -1398, 2567, 5752], "Canon EOS-1D X Mark II");
+
+ // Nikon (NEF).
+ Add([7309, -1403, -519, -8474, 16008, 2622, -2434, 2826, 8064], "Nikon D90");
+ Add([9030, -1992, -715, -8465, 16302, 2255, -2689, 3217, 8069], "Nikon D300", "Nikon D300S");
+ Add([8139, -2171, -663, -8747, 16541, 2295, -1925, 2008, 8093], "Nikon D3", "Nikon D700");
+ Add([8828, -2406, -694, -4874, 12603, 2541, -660, 1509, 7587], "Nikon D3S");
+ Add([7171, -1986, -648, -8085, 15555, 2718, -2170, 2512, 7457], "Nikon D3X");
+ Add([8598, -2848, -857, -5618, 13606, 2195, -1002, 1773, 7137], "Nikon D4", "Nikon Df");
+ Add([9200, -3522, -992, -5755, 13803, 2117, -753, 1486, 6338], "Nikon D5");
+ Add([7911, -2167, -813, -5327, 13150, 2408, -1288, 2483, 7968], "Nikon D3100");
+ Add([7013, -1408, -635, -5268, 12902, 2640, -1470, 2801, 7379], "Nikon D3200");
+ Add([6988, -1384, -714, -5631, 13410, 2447, -1485, 2204, 7318], "Nikon D3300", "Nikon D3400", "Nikon D5300");
+ Add([8198, -2239, -724, -4871, 12389, 2798, -1043, 2050, 7181], "Nikon D5100", "Nikon D7000");
+ Add([8322, -3112, -1047, -6367, 14342, 2179, -988, 1638, 6394], "Nikon D5200", "Nikon D7100", "Nikon D7200");
+ Add([8821, -2938, -785, -4178, 12142, 2287, -824, 1651, 6860], "Nikon D5500", "Nikon D5600");
+ Add([8813, -3210, -1036, -4703, 12868, 2021, -1054, 1940, 6129], "Nikon D500", "Nikon D7500");
+ Add([8178, -2245, -609, -4857, 12394, 2776, -1207, 2086, 7298], "Nikon D600", "Nikon D610");
+ Add([9020, -2890, -715, -4535, 12436, 2348, -934, 1919, 7086], "Nikon D750");
+ Add([7866, -2108, -555, -4869, 12483, 2681, -1176, 2069, 7501], "Nikon D800", "Nikon D800E");
+ Add([9369, -3195, -791, -4488, 12430, 2301, -893, 1796, 6872], "Nikon D810");
+ Add([10405, -3755, -1270, -5461, 13787, 1793, -1040, 2015, 6785], "Nikon D850", "Nikon Z 7");
+ Add([8210, -2534, -683, -5355, 13338, 2212, -1143, 1929, 6464], "Nikon Z 6");
+
+ // Sony (ARW).
+ Add([5271, -712, -347, -6153, 13653, 2763, -1601, 2366, 7242], "Sony ILCE-7", "Sony ILCE-7M2");
+ Add([7374, -2389, -551, -5435, 13162, 2519, -1006, 1795, 6552], "Sony ILCE-7M3");
+ Add([4913, -541, -202, -6130, 13513, 2906, -1564, 2151, 7183], "Sony ILCE-7R");
+ Add([6629, -1900, -483, -4618, 12349, 2550, -622, 1381, 6514], "Sony ILCE-7RM2");
+ Add([6640, -1847, -503, -5238, 13010, 2474, -993, 1673, 6527], "Sony ILCE-7RM3");
+ Add([5838, -1430, -246, -3497, 11477, 2297, -748, 1885, 5778], "Sony ILCE-7S", "Sony ILCE-7SM2");
+ Add([5991, -1456, -455, -4764, 12135, 2980, -707, 1425, 6701], "Sony ILCE-6000", "Sony ILCE-5100", "Sony SLT-A57");
+ Add([5973, -1695, -419, -3826, 11797, 2293, -639, 1398, 5789], "Sony ILCE-6300", "Sony ILCE-6500", "Sony ILCE-6400");
+ Add([5491, -1192, -363, -4951, 12342, 2948, -911, 1722, 7192], "Sony NEX-7", "Sony SLT-A65", "Sony SLT-A77");
+ Add([8651, -2754, -1057, -3464, 12207, 1373, -568, 1398, 4434], "Sony DSC-RX100");
+ Add([6596, -2079, -562, -4782, 13016, 1933, -970, 1581, 5181], "Sony DSC-RX100M2");
+
+ // Pentax (PEF).
+ Add([9566, -2863, -803, -7170, 15172, 2112, -818, 803, 9705], "Pentax K10D");
+ Add([9427, -2714, -868, -7493, 16092, 1373, -2199, 3264, 7180], "Pentax K20D");
+ Add([9142, -2947, -678, -8648, 16967, 1663, -2224, 2898, 8615], "Pentax K-7");
+ Add([8713, -2833, -743, -4342, 11900, 2772, -722, 1543, 6247], "Pentax K-5");
+ Add([8170, -2725, -639, -4440, 12017, 2744, -771, 1465, 6599], "Pentax K-5 II", "Pentax K-5 II s");
+ Add([8843, -2837, -625, -5025, 12644, 2668, -411, 1234, 7410], "Pentax K-x");
+ Add([9895, -3077, -850, -5304, 13035, 2521, -883, 1768, 6936], "Pentax K-r");
+ Add([8710, -2632, -1167, -3995, 12301, 1881, -981, 1719, 6535], "Pentax K-30");
+ Add([7415, -2052, -721, -5186, 12788, 2682, -1446, 2157, 6773], "Pentax K-3");
+ Add([8596, -2981, -639, -4202, 12046, 2431, -685, 1424, 6122], "Pentax K-1");
+
+ // Fujifilm (RAF).
+ Add([10413, -3996, -993, -3721, 11640, 2361, -733, 1540, 6011], "Fujifilm X-E1", "Fujifilm X-Pro1", "Fujifilm X-M1");
+ Add([10592, -4262, -1008, -3514, 11355, 2465, -870, 2025, 6386], "Fujifilm X100S", "Fujifilm X20");
+ Add([8458, -2451, -855, -4597, 12447, 2407, -1475, 2482, 6526], "Fujifilm X-T1", "Fujifilm X-E2", "Fujifilm X-T10", "Fujifilm X100T", "Fujifilm X30");
+ Add([11434, -4948, -1210, -3746, 12042, 1903, -666, 1479, 5235], "Fujifilm X-T2", "Fujifilm X-Pro2", "Fujifilm X-T20", "Fujifilm X100F", "Fujifilm X-E3");
+ Add([13426, -6334, -1177, -4244, 12136, 2371, -580, 1303, 5980], "Fujifilm X-T3", "Fujifilm X-T30");
+ Add([11086, -4555, -839, -3512, 11310, 2517, -815, 1341, 5940], "Fujifilm X-A1");
+ return t;
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/CfaPattern.cs b/src/Titano.Core/Codecs/Raw/CfaPattern.cs
new file mode 100644
index 00000000..5ec30b97
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/CfaPattern.cs
@@ -0,0 +1,143 @@
+using System.Text;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// Colour filter array layout (DNG 1.6 §"CFARepeatPatternDim"/"CFAPattern"): the colour of every cell of a pattern
+/// that repeats over the image, 0 = red, 1 = green, 2 = blue. The origin is the top-left pixel of the image the pattern
+/// is attached to (the DNG active area); re-anchors it for a sub-image.
+///
+public sealed class CfaPattern
+{
+ public const int MaxSize = 8;
+
+ private readonly byte[] _colors;
+
+ /// The size is outside 1–8, a colour is not 0–2, or a primary is missing.
+ public CfaPattern(int width, int height, ReadOnlySpan colors)
+ {
+ if (width is < 1 or > MaxSize || height is < 1 or > MaxSize || colors.Length < width * height)
+ throw new InvalidDataException($"CFA: unsupported pattern size {width}x{height}");
+ Span seen = stackalloc bool[3];
+ foreach (var c in colors[..(width * height)])
+ {
+ if (c > 2) throw new InvalidDataException($"CFA: colour {c} is not red, green or blue");
+ seen[c] = true;
+ }
+ if (!seen[0] || !seen[1] || !seen[2]) throw new InvalidDataException("CFA: pattern lacks a primary colour");
+ (Width, Height, _colors) = Reduce(width, height, colors[..(width * height)]);
+ }
+
+ /// Repeat width after reduction to the smallest period (a 4×4 Bayer description becomes 2×2).
+ public int Width { get; }
+
+ public int Height { get; }
+
+ /// A 2×2 pattern with one red, one blue and two diagonal greens.
+ public bool IsBayer => Width == 2 && Height == 2 && (_colors[0] == 1 && _colors[3] == 1 || _colors[1] == 1 && _colors[2] == 1);
+
+ /// Block edge for colour binning (half-size decoding): 2 for Bayer, 3 when every aligned 3×3 block holds all
+ /// three primaries (X-Trans), 0 when the pattern cannot be binned.
+ public int BinSize
+ {
+ get
+ {
+ if (IsBayer) return 2;
+ if (Width % 3 != 0 || Height % 3 != 0) return 0;
+ for (var by = 0; by < Height; by += 3)
+ {
+ for (var bx = 0; bx < Width; bx += 3)
+ {
+ var mask = 0;
+ for (var y = 0; y < 3; y++)
+ {
+ for (var x = 0; x < 3; x++) mask |= 1 << ColorAt(bx + x, by + y);
+ }
+ if (mask != 7) return 0;
+ }
+ }
+ return 3;
+ }
+ }
+
+ /// Colour at image coordinates (non-negative).
+ public int ColorAt(int x, int y) => _colors[y % Height * Width + x % Width];
+
+ /// Pattern of the sub-image whose top-left pixel is (, ) here.
+ public CfaPattern Shift(int dx, int dy)
+ {
+ var colors = new byte[Width * Height];
+ for (var y = 0; y < Height; y++)
+ {
+ for (var x = 0; x < Width; x++) colors[y * Width + x] = (byte)ColorAt(x + PositiveModulo(dx, Width), y + PositiveModulo(dy, Height));
+ }
+ return new CfaPattern(Width, Height, colors);
+ }
+
+ /// Bayer pattern from its top-left 2×2 letters ("RGGB", "BGGR", "GRBG", "GBRG").
+ public static CfaPattern Bayer(string layout)
+ {
+ if (layout.Length != 4) throw new ArgumentException("Four letters expected", nameof(layout));
+ var colors = new byte[4];
+ for (var i = 0; i < 4; i++)
+ {
+ colors[i] = char.ToUpperInvariant(layout[i]) switch
+ {
+ 'R' => 0,
+ 'G' => 1,
+ 'B' => 2,
+ _ => throw new ArgumentException("Letters must be R, G or B", nameof(layout)),
+ };
+ }
+ return new CfaPattern(2, 2, colors);
+ }
+
+ public override string ToString()
+ {
+ var sb = new StringBuilder(Width * Height + 8);
+ for (var i = 0; i < Width * Height; i++) sb.Append("RGB"[_colors[i]]);
+ return Width == 2 && Height == 2 ? sb.ToString() : $"{Width}x{Height}:{sb}";
+ }
+
+ private static int PositiveModulo(int value, int m) => (value % m + m) % m;
+
+ private static (int Width, int Height, byte[] Colors) Reduce(int width, int height, ReadOnlySpan colors)
+ {
+ var w = width;
+ for (var p = 1; p < width; p++)
+ {
+ if (width % p == 0 && Periodic(colors, width, height, p, 0))
+ {
+ w = p;
+ break;
+ }
+ }
+ var h = height;
+ for (var p = 1; p < height; p++)
+ {
+ if (height % p == 0 && Periodic(colors, width, height, 0, p))
+ {
+ h = p;
+ break;
+ }
+ }
+ var reduced = new byte[w * h];
+ for (var y = 0; y < h; y++)
+ {
+ for (var x = 0; x < w; x++) reduced[y * w + x] = colors[y * width + x];
+ }
+ return (w, h, reduced);
+ }
+
+ private static bool Periodic(ReadOnlySpan colors, int width, int height, int px, int py)
+ {
+ for (var y = 0; y < height; y++)
+ {
+ for (var x = 0; x < width; x++)
+ {
+ if (colors[y * width + x] != colors[(y + py) % height * width + (x + px) % width]) return false;
+ }
+ }
+ return true;
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/Cr2Reader.cs b/src/Titano.Core/Codecs/Raw/Cr2Reader.cs
new file mode 100644
index 00000000..25684416
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/Cr2Reader.cs
@@ -0,0 +1,161 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Mathematics;
+using Titano.Core.Metadata.Tiff;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// Canon CR2: the fourth IFD holds one lossless-JPEG (SOF3) strip whose samples are laid out in vertical slices
+/// (tag 0xC640 cr2_slice = count, slice width, last slice width; dcraw lossless_jpeg_load_raw). The MakerNote
+/// supplies SensorInfo (0x00E0: sensor borders, i.e. the active area) and ColorData (0x4001: as-shot RGGB levels at a
+/// version-dependent offset). Black is measured on the masked left columns. sRAW/mRAW (subsampled YCbCr) is not
+/// supported and falls back to the preview.
+///
+internal static class Cr2Reader
+{
+ private const ushort SliceTag = 0xC640;
+ private const ushort SensorInfoTag = 0x00E0;
+ private const ushort ColorDataTag = 0x4001;
+ private const int RawIfdIndex = 3;
+ private const int HeaderProbeBytes = 64 * 1024;
+
+ public static RawFrame Read(Stream stream)
+ {
+ var r = TiffReader.Open(stream) ?? throw new InvalidDataException("CR2: missing TIFF header");
+ var chain = r.ReadChain();
+ if (chain.Count <= RawIfdIndex) throw new InvalidDataException("CR2: raw IFD missing");
+ var ifd0 = chain[0];
+ var raw = chain[RawIfdIndex];
+ var offset = r.GetUInt(raw, TiffTags.StripOffsets) ?? throw new InvalidDataException("CR2: raw strip missing");
+ var length = r.GetUInt(raw, TiffTags.StripByteCounts) ?? throw new InvalidDataException("CR2: raw strip length missing");
+ if (offset + (long)length > stream.Length || length < 16) throw new InvalidDataException("CR2: raw strip outside the file");
+
+ var head = NativeRaw.ReadPayload(stream, offset, long.Min(length, HeaderProbeBytes));
+ JpegInfo info;
+ try
+ {
+ info = JpegDecoder.ReadInfo(head);
+ }
+ catch (InvalidDataException ex)
+ {
+ throw new InvalidDataException("CR2: raw strip is not a JPEG: " + ex.Message);
+ }
+ if (info.Process != JpegProcess.Lossless) throw new InvalidDataException("CR2: raw strip is not lossless JPEG");
+ if (info.Sampling.Any(s => s != (1, 1))) throw new InvalidDataException("CR2: sRAW/mRAW is not supported");
+ var rawWidth = (long)info.Width * info.Components;
+ var slices = IfdValue.UInts(r, raw, SliceTag);
+ if (slices is [var count, var sliceWidth, var lastWidth, ..] && count + sliceWidth + lastWidth > 0)
+ {
+ if (count * (long)sliceWidth + lastWidth != rawWidth || lastWidth == 0 || count > 0 && sliceWidth == 0)
+ throw new InvalidDataException("CR2: slice layout does not match the JPEG frame");
+ }
+ else
+ {
+ slices = null;
+ }
+ var (width, height) = NativeRaw.Size(rawWidth, info.Height);
+ NativeRaw.RequireBits(length, (long)width * height);
+
+ var make = r.GetString(ifd0, TiffTags.Make);
+ var model = r.GetString(ifd0, TiffTags.Model);
+ var warnings = new List();
+ var makerNote = MakerNote(r, ifd0);
+ var active = new RawRect(0, 0, width, height);
+ if (makerNote is not null && IfdValue.UInts(r, makerNote, SensorInfoTag) is { Length: >= 9 } sensor)
+ {
+ // SensorInfo borders are inclusive pixel indices.
+ var area = new RawRect((int)sensor[5], (int)sensor[6], (int)sensor[7] + 1, (int)sensor[8] + 1).Intersect(active);
+ if (!area.IsEmpty && sensor[7] > sensor[5] && sensor[8] > sensor[6]) active = area;
+ else warnings.Add("CR2: SensorInfo borders ignored");
+ }
+ else
+ {
+ warnings.Add("CR2: SensorInfo missing; full raster used");
+ }
+ var cfa = CfaPattern.Bayer("RGGB").Shift(active.Left, active.Top);
+ var white = (1 << info.Precision) - 1;
+ var loader = new Cr2Loader(offset, length, width, height, slices, active);
+ return NativeRaw.Frame("managed-cr2", width, height, cfa, active, NativeRaw.Black(0), white,
+ Multipliers(r, makerNote), (int)(r.GetUInt(ifd0, TiffTags.Orientation) ?? 1), make, model, loader, warnings);
+ }
+
+ /// Canon MakerNote: a plain IFD inside the Exif IFD, offsets relative to the TIFF header.
+ private static Ifd? MakerNote(TiffReader r, Ifd ifd0)
+ {
+ if (NativeRaw.ExifIfd(r, ifd0) is not { } exif || !exif.Entries.TryGetValue(TiffTags.MakerNote, out var note) || note.IsInline) return null;
+ return r.ReadIfd(note.ValueOffset);
+ }
+
+ /// As-shot RGGB levels from ColorData; the offset (in 16-bit words) depends on the record's length (dcraw).
+ private static Vector3D? Multipliers(TiffReader r, Ifd? makerNote)
+ {
+ if (makerNote is null || !makerNote.Entries.TryGetValue(ColorDataTag, out var e) || e.Count <= 500 || e.Count > 8192) return null;
+ var data = r.GetUInts(e);
+ if (data is null) return null;
+ var at = data.Length switch { 582 => 25, 653 => 34, 5120 => 71, _ => 63 };
+ if (at + 4 > data.Length) return null;
+ double red = data[at], green = (data[at + 1] + data[at + 2]) / 2.0, blue = data[at + 3];
+ return red > 0 && green > 0 && blue > 0 ? new Vector3D(red / green, 1, blue / green) : null;
+ }
+
+ /// Decodes the strip, places samples by slice, and measures black on the masked columns left of the active area.
+ private sealed class Cr2Loader(long offset, long length, int width, int height, uint[]? slices, RawRect active) : RawLoader
+ {
+ public override RawSamples Load(Stream stream, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ var data = NativeRaw.ReadPayload(stream, offset, length);
+ var jpeg = JpegLosslessDecoder.Decode(data);
+ var src = jpeg.Samples;
+ if ((long)jpeg.Width * jpeg.Components != width || jpeg.Height != height) throw new InvalidDataException("CR2: JPEG frame changed size");
+ cancellationToken.ThrowIfCancellationRequested();
+ ushort[] samples;
+ if (slices is null)
+ {
+ samples = src;
+ }
+ else
+ {
+ samples = new ushort[src.Length];
+ int count = (int)slices[0], sliceWidth = (int)slices[1], lastWidth = (int)slices[2];
+ var perSlice = (long)sliceWidth * height;
+ Parallel.For(0, count + 1, new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism, CancellationToken = cancellationToken }, s =>
+ {
+ var w = s < count ? sliceWidth : lastWidth;
+ var start = s * perSlice;
+ for (var row = 0; row < height; row++)
+ {
+ src.AsSpan((int)(start + (long)row * w), w).CopyTo(samples.AsSpan(row * width + s * sliceWidth, w));
+ }
+ });
+ }
+ var result = new RawSamples(width, height, 1, samples, null);
+ result.MeasuredBlack = MaskedBlack(samples, result.Warnings);
+ return result;
+ }
+
+ /// Per-CFA-colour mean of the masked columns (4 px away from both edges of the mask).
+ private RawBlackLevel MaskedBlack(ushort[] samples, List warnings)
+ {
+ if (active.Left < 12)
+ {
+ warnings.Add("CR2: no masked columns; black level 0 assumed");
+ return NativeRaw.Black(0);
+ }
+ Span sum = stackalloc double[4];
+ Span n = stackalloc long[4];
+ for (var y = active.Top; y < active.Bottom; y++)
+ {
+ for (var x = 4; x < active.Left - 4; x++)
+ {
+ // Cell index relative to the active area's CFA phase.
+ var cell = ((y - active.Top) & 1) * 2 + ((x - active.Left) & 1);
+ sum[cell] += samples[y * width + x];
+ n[cell]++;
+ }
+ }
+ var values = new float[4];
+ for (var i = 0; i < 4; i++) values[i] = n[i] > 0 ? (float)(sum[i] / n[i]) : 0f;
+ return new RawBlackLevel(2, 2, values, null, null);
+ }
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/Demosaic.cs b/src/Titano.Core/Codecs/Raw/Demosaic.cs
new file mode 100644
index 00000000..ee3987a6
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/Demosaic.cs
@@ -0,0 +1,202 @@
+using Titano.Core.Imaging;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// Fast CFA reconstructions: bilinear for Bayer mosaics (Draft quality), a colour-difference neighbourhood interpolation
+/// for any other pattern (X-Trans), and colour binning (half/third size). Inputs are single-plane mosaics with the pattern
+/// anchored at pixel (0, 0); outputs are R, G, B planes.
+///
+internal static class Demosaic
+{
+ /// Bilinear interpolation of a Bayer mosaic: missing greens from the 4 orthogonal neighbours, red/blue from the
+ /// 2 or 4 nearest of their colour. Borders mirror around the edge pixel, which preserves the CFA phase.
+ public static ImageBuffer Bilinear(ImageBuffer mosaic, CfaPattern cfa, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ if (!cfa.IsBayer) throw new ArgumentException("Bayer pattern expected", nameof(cfa));
+ int w = mosaic.Width, h = mosaic.Height;
+ var output = new ImageBuffer(w, h, 3, clear: false);
+ var options = new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism, CancellationToken = cancellationToken };
+ Parallel.For(0, h, options, y =>
+ {
+ var interior = y >= 1 && y < h - 1;
+ for (var x = 0; x < w; x++)
+ {
+ if (interior && x >= 1 && x < w - 1) BilinearInterior(mosaic, cfa, output, x, y);
+ else BilinearAt(mosaic, cfa, output, x, y);
+ }
+ });
+ return output;
+ }
+
+ /// Bilinear values for the pixels within of the border (AHD leaves them to this).
+ public static void BilinearBorder(ImageBuffer mosaic, CfaPattern cfa, ImageBuffer output, int band)
+ {
+ int w = mosaic.Width, h = mosaic.Height;
+ for (var y = 0; y < h; y++)
+ {
+ var edgeRow = y < band || y >= h - band;
+ for (var x = 0; x < w; x++)
+ {
+ if (!edgeRow && x == band) x = int.Max(x, w - band);
+ if (x < w) BilinearAt(mosaic, cfa, output, x, y);
+ }
+ }
+ }
+
+ private static void BilinearInterior(ImageBuffer mosaic, CfaPattern cfa, ImageBuffer output, int x, int y)
+ {
+ var m = mosaic.Plane(0);
+ var w = mosaic.Width;
+ var i = y * w + x;
+ var c = cfa.ColorAt(x, y);
+ float r, g, b;
+ if (c == 1)
+ {
+ var horizontal = (m[i - 1] + m[i + 1]) * 0.5f;
+ var vertical = (m[i - w] + m[i + w]) * 0.5f;
+ g = m[i];
+ if (cfa.ColorAt(x + 1, y) == 0) (r, b) = (horizontal, vertical);
+ else (r, b) = (vertical, horizontal);
+ }
+ else
+ {
+ g = (m[i - 1] + m[i + 1] + m[i - w] + m[i + w]) * 0.25f;
+ var diagonal = (m[i - w - 1] + m[i - w + 1] + m[i + w - 1] + m[i + w + 1]) * 0.25f;
+ (r, b) = c == 0 ? (m[i], diagonal) : (diagonal, m[i]);
+ }
+ output.Plane(0)[i] = r;
+ output.Plane(1)[i] = g;
+ output.Plane(2)[i] = b;
+ }
+
+ private static void BilinearAt(ImageBuffer mosaic, CfaPattern cfa, ImageBuffer output, int x, int y)
+ {
+ Span sum = stackalloc float[3];
+ Span count = stackalloc int[3];
+ var own = cfa.ColorAt(x, y);
+ for (var dy = -1; dy <= 1; dy++)
+ {
+ for (var dx = -1; dx <= 1; dx++)
+ {
+ // Greens come from orthogonal neighbours only; the diagonal ones belong to the other green rows.
+ var sx = Mirror(x + dx, mosaic.Width);
+ var sy = Mirror(y + dy, mosaic.Height);
+ var c = cfa.ColorAt(sx, sy);
+ if (c == own && (dx | dy) != 0) continue;
+ if (c == 1 && dx != 0 && dy != 0) continue;
+ sum[c] += mosaic.Plane(0)[sy * mosaic.Width + sx];
+ count[c]++;
+ }
+ }
+ var i = y * mosaic.Width + x;
+ for (var c = 0; c < 3; c++) output.Plane(c)[i] = count[c] > 0 ? sum[c] / count[c] : 0f;
+ }
+
+ private static int Mirror(int v, int size) => v < 0 ? int.Min(-v, size - 1) : v >= size ? int.Max(2 * size - 2 - v, 0) : v;
+
+ ///
+ /// Colour-difference interpolation for any CFA (used for X-Trans): green from the greens of the 3×3 neighbourhood, then
+ /// red and blue as interpolated green plus the mean (colour − green) difference of their own 3×3 samples (5×5 when the
+ /// 3×3 holds none). Simpler than Markesteijn's X-Trans algorithm but artefact-free on smooth content.
+ ///
+ public static ImageBuffer Neighbourhood(ImageBuffer mosaic, CfaPattern cfa, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ int w = mosaic.Width, h = mosaic.Height;
+ var output = new ImageBuffer(w, h, 3, clear: false);
+ var m = mosaic.Storage;
+ var green = output.Storage.AsMemory(w * h, w * h);
+ var options = new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism, CancellationToken = cancellationToken };
+ Parallel.For(0, h, options, y =>
+ {
+ var g = green.Span;
+ for (var x = 0; x < w; x++)
+ {
+ g[y * w + x] = cfa.ColorAt(x, y) == 1 ? m[y * w + x] : Mean(m, w, h, cfa, x, y, 1, null);
+ }
+ });
+ Parallel.For(0, h, options, y =>
+ {
+ var g = green.Span;
+ var red = output.Row(0, y);
+ var blue = output.Row(2, y);
+ for (var x = 0; x < w; x++)
+ {
+ var own = cfa.ColorAt(x, y);
+ var gv = g[y * w + x];
+ red[x] = own == 0 ? m[y * w + x] : float.Max(0f, gv + Mean(m, w, h, cfa, x, y, 0, g));
+ blue[x] = own == 2 ? m[y * w + x] : float.Max(0f, gv + Mean(m, w, h, cfa, x, y, 2, g));
+ }
+ });
+ return output;
+ }
+
+ /// Mean of colour samples around (x, y) — of (sample − green) when
+ /// is given — over 3×3, widened to 5×5 when the 3×3 holds none.
+ private static float Mean(float[] m, int w, int h, CfaPattern cfa, int x, int y, int color, Span green)
+ {
+ for (var r = 1; r <= 2; r++)
+ {
+ var sum = 0f;
+ var n = 0;
+ for (var dy = -r; dy <= r; dy++)
+ {
+ var sy = y + dy;
+ if ((uint)sy >= (uint)h) continue;
+ for (var dx = -r; dx <= r; dx++)
+ {
+ var sx = x + dx;
+ if ((uint)sx >= (uint)w || (dx | dy) == 0 || cfa.ColorAt(sx, sy) != color) continue;
+ var i = sy * w + sx;
+ sum += green.IsEmpty ? m[i] : m[i] - green[i];
+ n++;
+ }
+ }
+ if (n > 0) return sum / n;
+ }
+ return 0f;
+ }
+
+ ///
+ /// Colour binning: each aligned × block becomes one RGB pixel holding the
+ /// mean of its samples of each colour (dcraw's half-size mode for Bayer; one third for X-Trans). Partial blocks at the
+ /// right/bottom edge are dropped.
+ ///
+ public static ImageBuffer Bin(ImageBuffer mosaic, CfaPattern cfa, int size, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ int w = mosaic.Width / size, h = mosaic.Height / size;
+ if (w < 1 || h < 1) throw new InvalidDataException("RAW: image too small to bin");
+ var output = new ImageBuffer(w, h, 3, clear: false);
+ var src = mosaic.Storage;
+ var stride = mosaic.Width;
+ var options = new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism, CancellationToken = cancellationToken };
+ Parallel.For(0, h, options, by =>
+ {
+ Span sum = stackalloc float[3];
+ Span count = stackalloc int[3];
+ var r = output.Row(0, by);
+ var g = output.Row(1, by);
+ var b = output.Row(2, by);
+ for (var bx = 0; bx < w; bx++)
+ {
+ sum.Clear();
+ count.Clear();
+ for (var dy = 0; dy < size; dy++)
+ {
+ var y = by * size + dy;
+ for (var dx = 0; dx < size; dx++)
+ {
+ var x = bx * size + dx;
+ var c = cfa.ColorAt(x, y);
+ sum[c] += src[y * stride + x];
+ count[c]++;
+ }
+ }
+ r[bx] = sum[0] / count[0];
+ g[bx] = sum[1] / count[1];
+ b[bx] = sum[2] / count[2];
+ }
+ });
+ return output;
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/HighlightReconstruction.cs b/src/Titano.Core/Codecs/Raw/HighlightReconstruction.cs
new file mode 100644
index 00000000..76c18f88
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/HighlightReconstruction.cs
@@ -0,0 +1,120 @@
+using Titano.Core.Imaging;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// Clip-aware highlight reconstruction on white-balanced camera RGB. Per pixel, the channels whose raw samples clipped
+/// (bit c of the clip map) are only known to be at least their clip level; they are raised to the mean of the unclipped
+/// channels when that is larger (a near-white highlight that clipped green first comes back neutral instead of magenta),
+/// then the pixel is desaturated toward a grey at its brightest channel as the unclipped channels approach their own clip
+/// levels. Fully clipped pixels become that grey at no less than the highest clip level. Pixels without clipped samples
+/// are untouched.
+///
+internal static class HighlightReconstruction
+{
+ /// Fraction of its clip level at which an unclipped channel starts pulling the pixel toward white.
+ private const float DesaturationStart = 0.7f;
+
+ /// White-balanced camera RGB, modified in place.
+ /// Per pixel: bit c set when channel c is built from clipped raw samples.
+ /// Clip level of each channel in 's units (the white-balance multipliers
+ /// when raw white is 1).
+ public static void Apply(ImageBuffer rgb, byte[] clipBits, ReadOnlySpan clipLevels, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ var levels = clipLevels.ToArray();
+ var top = float.Max(levels[0], float.Max(levels[1], levels[2]));
+ int w = rgb.Width;
+ Parallel.For(0, rgb.Height, new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism, CancellationToken = cancellationToken }, y =>
+ {
+ var r = rgb.Row(0, y);
+ var g = rgb.Row(1, y);
+ var b = rgb.Row(2, y);
+ var bits = clipBits.AsSpan(y * w, w);
+ Span v = stackalloc float[3];
+ for (var x = 0; x < w; x++)
+ {
+ var clipped = bits[x] & 7;
+ if (clipped == 0) continue;
+ v[0] = r[x];
+ v[1] = g[x];
+ v[2] = b[x];
+ if (clipped == 7)
+ {
+ var level = float.Max(top, float.Max(v[0], float.Max(v[1], v[2])));
+ r[x] = g[x] = b[x] = level;
+ continue;
+ }
+ float sum = 0, closeness = float.MaxValue;
+ var n = 0;
+ for (var c = 0; c < 3; c++)
+ {
+ if ((clipped & 1 << c) != 0) continue;
+ sum += v[c];
+ n++;
+ closeness = float.Min(closeness, v[c] / levels[c]);
+ }
+ var estimate = sum / n;
+ for (var c = 0; c < 3; c++)
+ {
+ if ((clipped & 1 << c) != 0) v[c] = float.Max(v[c], estimate);
+ }
+ var t = float.Clamp((closeness - DesaturationStart) / (1 - DesaturationStart), 0f, 1f);
+ t = t * t * (3 - 2 * t);
+ var grey = float.Max(v[0], float.Max(v[1], v[2]));
+ r[x] = v[0] + (grey - v[0]) * t;
+ g[x] = v[1] + (grey - v[1]) * t;
+ b[x] = v[2] + (grey - v[2]) * t;
+ }
+ });
+ }
+
+ /// Channel clip bits of a demosaiced image: the OR of the mosaic's clip flags over each pixel's 3×3
+ /// neighbourhood (the samples its interpolation draws on).
+ public static byte[] Dilate(byte[] mask, int width, int height)
+ {
+ var horizontal = new byte[mask.Length];
+ for (var y = 0; y < height; y++)
+ {
+ var o = y * width;
+ for (var x = 0; x < width; x++)
+ {
+ var v = mask[o + x];
+ if (x > 0) v |= mask[o + x - 1];
+ if (x < width - 1) v |= mask[o + x + 1];
+ horizontal[o + x] = v;
+ }
+ }
+ var result = new byte[mask.Length];
+ for (var y = 0; y < height; y++)
+ {
+ var o = y * width;
+ for (var x = 0; x < width; x++)
+ {
+ var v = horizontal[o + x];
+ if (y > 0) v |= horizontal[o - width + x];
+ if (y < height - 1) v |= horizontal[o + width + x];
+ result[o + x] = v;
+ }
+ }
+ return result;
+ }
+
+ /// Clip bits of a binned image: the OR over each × block.
+ public static byte[] Bin(byte[] mask, int width, int size, int outWidth, int outHeight)
+ {
+ var result = new byte[outWidth * outHeight];
+ for (var by = 0; by < outHeight; by++)
+ {
+ for (var bx = 0; bx < outWidth; bx++)
+ {
+ byte v = 0;
+ for (var dy = 0; dy < size; dy++)
+ {
+ for (var dx = 0; dx < size; dx++) v |= mask[(by * size + dy) * width + bx * size + dx];
+ }
+ result[by * outWidth + bx] = v;
+ }
+ }
+ return result;
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/NativeRaw.cs b/src/Titano.Core/Codecs/Raw/NativeRaw.cs
new file mode 100644
index 00000000..632c46cb
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/NativeRaw.cs
@@ -0,0 +1,252 @@
+using Titano.Core.Codecs.Dng;
+using Titano.Core.Mathematics;
+using Titano.Core.Metadata.Tiff;
+
+namespace Titano.Core.Codecs.Raw;
+
+/// Shared pieces of the native (non-DNG) RAW readers: camera naming, frame construction, MakerNote access and
+/// bounded payload reads.
+internal static class NativeRaw
+{
+ /// Largest raw raster accepted (256 megapixels).
+ public const long MaxPixels = 1L << 28;
+
+ /// "Brand Model" as keyed in : "NIKON CORPORATION" + "NIKON D850" → "Nikon D850".
+ public static string? CameraName(string? make, string? model)
+ {
+ if (string.IsNullOrWhiteSpace(model)) return null;
+ var m = make?.Trim() ?? string.Empty;
+ string brand;
+ if (m.StartsWith("Canon", StringComparison.OrdinalIgnoreCase)) brand = "Canon";
+ else if (m.StartsWith("NIKON", StringComparison.OrdinalIgnoreCase)) brand = "Nikon";
+ else if (m.StartsWith("SONY", StringComparison.OrdinalIgnoreCase)) brand = "Sony";
+ else if (m.StartsWith("PENTAX", StringComparison.OrdinalIgnoreCase) || m.StartsWith("RICOH", StringComparison.OrdinalIgnoreCase) || m.StartsWith("ASAHI", StringComparison.OrdinalIgnoreCase)) brand = "Pentax";
+ else if (m.StartsWith("FUJIFILM", StringComparison.OrdinalIgnoreCase)) brand = "Fujifilm";
+ else brand = m.Split(' ', StringSplitOptions.RemoveEmptyEntries).FirstOrDefault() ?? string.Empty;
+ var words = model.Split(' ', StringSplitOptions.RemoveEmptyEntries).ToList();
+ if (words.Count > 1 && (words[0].Equals(brand, StringComparison.OrdinalIgnoreCase) || words[0].Equals("PENTAX", StringComparison.OrdinalIgnoreCase)))
+ words.RemoveAt(0);
+ return words.Count == 0 ? null : $"{brand} {string.Join(' ', words)}";
+ }
+
+ /// Builds the frame of a native RAW developed with a tabulated D65 matrix.
+ /// As-shot white-balance multipliers (R, G, B); null falls back to daylight.
+ /// The body has no colour matrix (the caller falls back to the preview).
+ public static RawFrame Frame(string decoder, int width, int height, CfaPattern cfa, RawRect active, RawBlackLevel black, double white,
+ Vector3D? multipliers, int orientation, string? make, string? model, RawLoader loader, IEnumerable warnings)
+ {
+ var name = CameraName(make, model);
+ var matrix = CameraMatrices.Find(name) ?? throw new InvalidDataException($"RAW: no colour matrix for {name ?? "unknown camera"}");
+ if (active.IsEmpty || active.Left < 0 || active.Top < 0 || active.Right > width || active.Bottom > height)
+ throw new InvalidDataException("RAW: sensor area outside the raster");
+ Vector3D? neutral = multipliers is { } m && m.X > 0 && m.Y > 0 && m.Z > 0 && double.IsFinite(m.X + m.Y + m.Z)
+ ? new Vector3D(1 / m.X, 1 / m.Y, 1 / m.Z)
+ : null;
+ var frame = new RawFrame
+ {
+ Decoder = decoder,
+ Width = width,
+ Height = height,
+ Cfa = cfa,
+ ActiveArea = active,
+ Black = black,
+ White = [white],
+ DetectSaturation = true,
+ Color = new DngColorProfile
+ {
+ ColorMatrix1 = matrix,
+ CalibrationIlluminant1 = 21,
+ AsShotNeutral = neutral,
+ AsShotWhite = neutral is null ? Chromaticity.D65 : null,
+ },
+ Orientation = orientation is >= 1 and <= 8 ? orientation : 1,
+ Make = make,
+ Model = model,
+ Loader = loader,
+ };
+ frame.Warnings.AddRange(warnings);
+ if (neutral is null) frame.Warnings.Add("RAW: as-shot white balance unavailable; daylight assumed");
+ return frame;
+ }
+
+ /// Validated raster size.
+ public static (int Width, int Height) Size(long width, long height)
+ {
+ if (width <= 0 || height <= 0 || width * height > MaxPixels) throw new InvalidDataException($"RAW: unsupported raster size {width}x{height}");
+ return ((int)width, (int)height);
+ }
+
+ /// Rejects entropy-coded payloads too short to hold one bit per sample, before the raster is allocated (a
+ /// corrupted size must not trigger a huge allocation).
+ public static void RequireBits(long payloadBytes, long samples)
+ {
+ if (payloadBytes * 8 < samples) throw new InvalidDataException("RAW: compressed data too short for the raster");
+ }
+
+ /// Uniform black level for every CFA cell.
+ public static RawBlackLevel Black(double value) => new(1, 1, [(float)value], null, null);
+
+ /// Black level of a 2×2 CFA from values in R, G1, G2, B order, re-anchored at the active area.
+ public static RawBlackLevel Black2x2(CfaPattern cfa, ReadOnlySpan rggb)
+ {
+ var values = new float[4];
+ for (var y = 0; y < 2; y++)
+ {
+ for (var x = 0; x < 2; x++)
+ {
+ var c = cfa.ColorAt(x, y);
+ // The second green of a 2×2 cell is the one sharing a row with blue.
+ var index = c == 0 ? 0 : c == 2 ? 3 : cfa.ColorAt(x ^ 1, y) == 0 ? 1 : 2;
+ values[y * 2 + x] = (float)rggb[index];
+ }
+ }
+ return new RawBlackLevel(2, 2, values, null, null);
+ }
+
+ /// Exif IFD of IFD0, or null.
+ public static Ifd? ExifIfd(TiffReader r, Ifd ifd0) => r.GetUInt(ifd0, TiffTags.ExifIfd) is { } offset and > 0 ? r.ReadIfd(offset) : null;
+
+ /// Reads bytes at an absolute position (bounded by the stream).
+ public static byte[] ReadPayload(Stream stream, long position, long length)
+ {
+ if (position < 0 || length <= 0 || length > int.MaxValue || position > stream.Length - length)
+ throw new InvalidDataException("RAW: image data outside the file");
+ var data = new byte[length];
+ stream.Position = position;
+ stream.ReadExactly(data);
+ return data;
+ }
+
+ /// CFA pattern from TIFF/EP CFARepeatPatternDim/CFAPattern tags (as written in NEF/ARW/PEF raw IFDs), or null.
+ public static CfaPattern? TiffEpCfa(TiffReader r, Ifd ifd)
+ {
+ if (IfdValue.UInts(r, ifd, TiffTags.CfaPattern) is not { } pattern) return null;
+ var dim = IfdValue.UInts(r, ifd, TiffTags.CfaRepeatPatternDim) ?? [2, 2];
+ if (dim.Length < 2 || dim[0] is < 1 or > CfaPattern.MaxSize || dim[1] is < 1 or > CfaPattern.MaxSize || pattern.Length < dim[0] * dim[1]) return null;
+ var colors = new byte[dim[0] * dim[1]];
+ for (var i = 0; i < colors.Length; i++)
+ {
+ if (pattern[i] > 2) return null;
+ colors[i] = (byte)pattern[i];
+ }
+ try
+ {
+ return new CfaPattern((int)dim[1], (int)dim[0], colors);
+ }
+ catch (InvalidDataException)
+ {
+ return null;
+ }
+ }
+}
+
+/// Uncompressed raw payloads: 16-bit words (either byte order, optionally holding the value shifted left by
+/// bits) or MSB-first packed samples (TIFF convention).
+internal sealed class PlainRawLoader(long offset, long length, int width, int height, int bits, bool words, bool littleEndian, int shift = 0) : RawLoader
+{
+ public override RawSamples Load(Stream stream, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ var rowBytes = words ? width * 2L : (width * (long)bits + 7) / 8;
+ if (rowBytes * height > length) throw new InvalidDataException("RAW: image data truncated");
+ var data = NativeRaw.ReadPayload(stream, offset, rowBytes * height);
+ var samples = new ushort[width * height];
+ var mask = (1 << bits) - 1;
+ Parallel.For(0, height, new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism, CancellationToken = cancellationToken }, y =>
+ {
+ var row = data.AsSpan((int)(y * rowBytes), (int)rowBytes);
+ var dst = samples.AsSpan(y * width, width);
+ if (words)
+ {
+ for (var x = 0; x < width; x++)
+ dst[x] = (ushort)((littleEndian ? row[2 * x] | row[2 * x + 1] << 8 : row[2 * x] << 8 | row[2 * x + 1]) >> shift & mask);
+ return;
+ }
+ long bit = 0;
+ for (var x = 0; x < width; x++, bit += bits)
+ {
+ var b = (int)(bit >> 3);
+ // Up to 16 bits spanning at most three bytes.
+ var window = row[b] << 16 | (b + 1 < row.Length ? row[b + 1] << 8 : 0) | (b + 2 < row.Length ? row[b + 2] : 0);
+ dst[x] = (ushort)(window >> (24 - (int)(bit & 7) - bits) & mask);
+ }
+ });
+ return new RawSamples(width, height, 1, samples, null);
+ }
+}
+
+/// MSB-first bit reader without byte stuffing (Nikon and Pentax Huffman streams). Reading past the end yields
+/// zero bits and sets .
+internal ref struct MsbBitReader(ReadOnlySpan data)
+{
+ private readonly ReadOnlySpan _data = data;
+ private int _pos;
+ private ulong _buffer;
+ private int _bits;
+
+ public readonly bool Overrun => _pos > _data.Length + 8;
+
+ /// Next bits (n ≤ 32) without consuming them.
+ public uint Peek(int n)
+ {
+ if (n == 0) return 0;
+ while (_bits < n)
+ {
+ _buffer = _buffer << 8 | (_pos < _data.Length ? _data[_pos] : 0u);
+ _pos++;
+ _bits += 8;
+ }
+ return (uint)(_buffer >> (_bits - n)) & (uint)((1UL << n) - 1);
+ }
+
+ public void Skip(int n) => _bits -= n;
+
+ public uint Read(int n)
+ {
+ var v = Peek(n);
+ _bits -= n;
+ return v;
+ }
+}
+
+/// Huffman lookup in dcraw's make_decoder layout: code-length counts for lengths 1–16 followed by symbols,
+/// codes assigned canonically; each table entry is (length << 8 | symbol) indexed by the next bits.
+internal sealed class HuffmanTable
+{
+ private readonly ushort[] _lut;
+
+ public HuffmanTable(ReadOnlySpan countsAndSymbols)
+ {
+ var bits = 16;
+ while (bits > 0 && countsAndSymbols[bits - 1] == 0) bits--;
+ if (bits == 0) throw new InvalidDataException("RAW: empty Huffman table");
+ Bits = bits;
+ _lut = new ushort[1 << bits];
+ var h = 0;
+ var symbol = 16;
+ for (var len = 1; len <= bits; len++)
+ {
+ for (var i = 0; i < countsAndSymbols[len - 1]; i++, symbol++)
+ {
+ var value = symbol < countsAndSymbols.Length ? countsAndSymbols[symbol] : (byte)0;
+ for (var j = 0; j < 1 << (bits - len) && h < _lut.Length; j++) _lut[h++] = (ushort)(len << 8 | value);
+ }
+ }
+ }
+
+ /// Wraps a prebuilt lookup (Pentax tables).
+ public HuffmanTable(ushort[] lut, int bits)
+ {
+ _lut = lut;
+ Bits = bits;
+ }
+
+ public int Bits { get; }
+
+ /// Decodes one symbol.
+ public int Decode(ref MsbBitReader reader)
+ {
+ var entry = _lut[reader.Peek(Bits)];
+ reader.Skip(entry >> 8);
+ return entry & 0xFF;
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/NefReader.cs b/src/Titano.Core/Codecs/Raw/NefReader.cs
new file mode 100644
index 00000000..1b71277b
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/NefReader.cs
@@ -0,0 +1,235 @@
+using System.Buffers.Binary;
+using Titano.Core.Mathematics;
+using Titano.Core.Metadata.Tiff;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// Nikon NEF: the CFA SubIFD is uncompressed (16-bit words or MSB-packed samples) or Nikon-compressed (Compression
+/// 34713): lossy type 1, lossless and lossy type 2 including the "after split" variant, decoded as dcraw's
+/// nikon_load_raw does from the MakerNote decode info (0x0096: version, vertical predictors, tone curve, split row)
+/// with Nikon's six Huffman trees and two-column horizontal prediction. White balance comes from MakerNote 0x000C, black
+/// from 0x003D. Packed 12-bit "uncompressed" variants, YUV NEFs and the high-efficiency (TicoRAW) codec are not supported
+/// and fall back to the preview.
+///
+internal static class NefReader
+{
+ private const ushort WbLevelsTag = 0x000C;
+ private const ushort BlackLevelTag = 0x003D;
+ private const ushort DecodeInfoTag = 0x0096;
+ private const uint CompressionNikon = 34713;
+
+ /// Nikon Huffman trees (dcraw nikon_tree): 16 code-length counts, then the symbols (len | shift << 4).
+ internal static readonly byte[][] Trees =
+ [
+ [0, 1, 5, 1, 1, 1, 1, 1, 1, 2, 0, 0, 0, 0, 0, 0, 5, 4, 3, 6, 2, 7, 1, 0, 8, 9, 11, 10, 12, 0, 0, 0],
+ [0, 1, 5, 1, 1, 1, 1, 1, 1, 2, 0, 0, 0, 0, 0, 0, 0x39, 0x5a, 0x38, 0x27, 0x16, 5, 4, 3, 2, 1, 0, 11, 12, 12, 0, 0],
+ [0, 1, 4, 2, 3, 1, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 5, 4, 6, 3, 7, 2, 8, 1, 9, 0, 10, 11, 12, 0, 0, 0],
+ [0, 1, 4, 3, 1, 1, 1, 1, 1, 2, 0, 0, 0, 0, 0, 0, 5, 6, 4, 7, 8, 3, 9, 2, 1, 0, 10, 11, 12, 13, 14, 0],
+ [0, 1, 5, 1, 1, 1, 1, 1, 1, 1, 2, 0, 0, 0, 0, 0, 8, 0x5c, 0x4b, 0x3a, 0x29, 7, 6, 5, 4, 3, 2, 1, 0, 13, 14, 0],
+ [0, 1, 4, 2, 2, 3, 1, 2, 0, 0, 0, 0, 0, 0, 0, 0, 7, 6, 8, 5, 9, 4, 10, 3, 11, 12, 2, 0, 1, 13, 14, 0],
+ ];
+
+ public static RawFrame Read(Stream stream)
+ {
+ var r = TiffReader.Open(stream) ?? throw new InvalidDataException("NEF: missing TIFF header");
+ var chain = r.ReadChain();
+ if (chain.Count == 0) throw new InvalidDataException("NEF: no image directory");
+ var ifd0 = chain[0];
+ var raw = FindCfa(r, ifd0) ?? throw new InvalidDataException("NEF: CFA image missing");
+ var (width, height) = NativeRaw.Size(r.GetUInt(raw, TiffTags.ImageWidth) ?? 0, r.GetUInt(raw, TiffTags.ImageLength) ?? 0);
+ var bits = (int)(r.GetUInt(raw, TiffTags.BitsPerSample) ?? 0);
+ if (bits is not (12 or 14)) throw new InvalidDataException($"NEF: {bits}-bit data is not supported");
+ var (offset, length) = Strip(r, raw);
+ var compression = r.GetUInt(raw, TiffTags.Compression) ?? 1;
+ var note = MakerNote(stream, r, ifd0);
+ var warnings = new List();
+ var cfa = NativeRaw.TiffEpCfa(r, raw);
+ if (cfa is null)
+ {
+ cfa = CfaPattern.Bayer("RGGB");
+ warnings.Add("NEF: CFA pattern missing; RGGB assumed");
+ }
+ if (!cfa.IsBayer) throw new InvalidDataException("NEF: only Bayer sensors are supported");
+
+ RawLoader loader;
+ double white = (1 << bits) - 1;
+ if (compression == CompressionNikon && length != (long)width * height * 2)
+ {
+ if (note is not { } mn || !mn.Ifd.Entries.TryGetValue(DecodeInfoTag, out var meta) || mn.Reader.ReadBytes(meta) is not { } info)
+ throw new InvalidDataException("NEF: compressed data without decode information");
+ NativeRaw.RequireBits(length, (long)width * height);
+ var decode = DecodeInfo.Parse(info, mn.Reader.LittleEndian, bits);
+ white = decode.White;
+ loader = new NikonHuffmanLoader(offset, length, width, height, decode);
+ }
+ else if (compression == CompressionNikon)
+ {
+ // Unpacked data under the Nikon compression tag: big-endian words holding the value shifted left by 4 (LibRaw).
+ loader = new PlainRawLoader(offset, length, width, height, bits, words: true, littleEndian: false, shift: 4);
+ }
+ else if (compression == 1 && length >= (long)width * height * 2)
+ {
+ loader = new PlainRawLoader(offset, length, width, height, bits, words: true, littleEndian: r.LittleEndian);
+ }
+ else if (compression == 1 && length >= ((long)width * bits + 7) / 8 * height)
+ {
+ loader = new PlainRawLoader(offset, length, width, height, bits, words: false, littleEndian: false);
+ }
+ else
+ {
+ throw new InvalidDataException($"NEF: compression {compression} with {length} bytes is not supported");
+ }
+
+ var black = NativeRaw.Black(0);
+ if (note is { } n && IfdValue.UInts(n.Reader, n.Ifd, BlackLevelTag) is { Length: 4 } b)
+ {
+ // Stored on a 14-bit scale whatever the bit depth.
+ black = NativeRaw.Black2x2(cfa, [b[0] >> (14 - bits), b[1] >> (14 - bits), b[2] >> (14 - bits), b[3] >> (14 - bits)]);
+ }
+ Vector3D? multipliers = note is { } w && IfdValue.Doubles(w.Reader, w.Ifd, WbLevelsTag, 2) is [var red, var blue, ..] ? new Vector3D(red, 1, blue) : null;
+ return NativeRaw.Frame("managed-nef", width, height, cfa, new RawRect(0, 0, width, height), black, white, multipliers,
+ (int)(r.GetUInt(ifd0, TiffTags.Orientation) ?? 1), r.GetString(ifd0, TiffTags.Make), r.GetString(ifd0, TiffTags.Model), loader, warnings);
+ }
+
+ /// The full-resolution CFA IFD: IFD0 or one of its SubIFDs.
+ internal static Ifd? FindCfa(TiffReader r, Ifd ifd0)
+ {
+ bool IsRaw(Ifd ifd) => (r.GetUInt(ifd, TiffTags.NewSubfileType) ?? 0) == 0 && r.GetUInt(ifd, TiffTags.PhotometricInterpretation) == 32803;
+ if (IsRaw(ifd0)) return ifd0;
+ if (!ifd0.Entries.TryGetValue(TiffTags.SubIfds, out var sub) || sub.Count > 16) return null;
+ foreach (var offset in r.GetUInts(sub) ?? [])
+ {
+ if (r.ReadIfd(offset) is { } child && IsRaw(child)) return child;
+ }
+ return null;
+ }
+
+ /// Absolute position and length of the image data (several strips must be contiguous).
+ internal static (long Offset, long Length) Strip(TiffReader r, Ifd ifd)
+ {
+ var offsets = IfdValue.UInts(r, ifd, TiffTags.StripOffsets) ?? r.GetUInts(ifd, TiffTags.StripOffsets);
+ var counts = IfdValue.UInts(r, ifd, TiffTags.StripByteCounts) ?? r.GetUInts(ifd, TiffTags.StripByteCounts);
+ if (offsets is not { Length: > 0 } || counts is null || counts.Length < offsets.Length) throw new InvalidDataException("RAW: strip offsets missing");
+ long length = 0;
+ for (var i = 0; i < offsets.Length; i++)
+ {
+ if (offsets[i] != offsets[0] + length) throw new InvalidDataException("RAW: non-contiguous strips are not supported");
+ length += counts[i];
+ }
+ var offset = r.Base + offsets[0];
+ if (offset + length > r.StreamLength) throw new InvalidDataException("RAW: image data outside the file");
+ return (offset, length);
+ }
+
+ /// Nikon type-3 MakerNote: "Nikon\0", version, then an embedded TIFF header 10 bytes in.
+ private static (TiffReader Reader, Ifd Ifd)? MakerNote(Stream stream, TiffReader r, Ifd ifd0)
+ {
+ if (NativeRaw.ExifIfd(r, ifd0) is not { } exif || !exif.Entries.TryGetValue(TiffTags.MakerNote, out var e) || e.IsInline || e.Count < 18) return null;
+ var start = e.ValuePosition(r.Base);
+ var head = r.ReadRelative(start - r.Base, 6);
+ if (head is null || !head.AsSpan().SequenceEqual("Nikon\0"u8)) return null;
+ var reader = TiffReader.Open(stream, start + 10);
+ return reader?.ReadIfd(reader.FirstIfdOffset) is { } ifd ? (reader, ifd) : null;
+ }
+
+ /// Parsed MakerNote 0x0096: Huffman tree, initial vertical predictors, tone curve and split row.
+ internal sealed record DecodeInfo(int Tree, ushort[] Predictors, ushort[] Curve, int Split, double White)
+ {
+ public static DecodeInfo Parse(byte[] meta, bool littleEndian, int bits)
+ {
+ if (meta.Length < 12) throw new InvalidDataException("NEF: decode information truncated");
+ var pos = 0;
+ ushort U16()
+ {
+ if (pos + 2 > meta.Length) throw new InvalidDataException("NEF: decode information truncated");
+ var v = littleEndian ? BinaryPrimitives.ReadUInt16LittleEndian(meta.AsSpan(pos)) : BinaryPrimitives.ReadUInt16BigEndian(meta.AsSpan(pos));
+ pos += 2;
+ return v;
+ }
+ int ver0 = meta[0], ver1 = meta[1];
+ pos = ver0 == 0x49 || ver1 == 0x58 ? 2 + 2110 : 2;
+ var tree = (ver0 == 0x46 ? 2 : 0) + (bits == 14 ? 3 : 0);
+ ushort[] predictors = [U16(), U16(), U16(), U16()];
+ var max = 1 << bits & 0x7FFF;
+ var curve = new ushort[0x10000];
+ for (var i = 0; i < curve.Length; i++) curve[i] = (ushort)i;
+ var size = U16();
+ var step = size > 1 ? max / (size - 1) : 0;
+ var split = 0;
+ var top = max;
+ if (ver0 == 0x44 && ver1 == 0x20 && step > 0)
+ {
+ // Lossy type 2: curve sampled every 'step' codes, linearly interpolated; split row at offset 562.
+ for (var i = 0; i < size; i++) curve[int.Min(i * step, curve.Length - 1)] = U16();
+ for (var i = 0; i < max; i++)
+ {
+ var k = i % step;
+ var a = i - k;
+ curve[i] = (ushort)((curve[a] * (step - k) + curve[int.Min(a + step, curve.Length - 1)] * k) / step);
+ }
+ if (meta.Length >= 564)
+ {
+ pos = 562;
+ split = U16();
+ }
+ }
+ else if (ver0 != 0x46 && size <= 0x4001)
+ {
+ // Lossy type 1: the curve is stored in full.
+ for (var i = 0; i < size; i++) curve[i] = U16();
+ top = size;
+ }
+ double white = 0;
+ for (var i = 0; i < int.Max(top, 1); i++) white = double.Max(white, curve[i]);
+ return new DecodeInfo(tree, predictors, curve, split, white);
+ }
+ }
+
+ /// dcraw nikon_load_raw.
+ private sealed class NikonHuffmanLoader(long offset, long length, int width, int height, DecodeInfo info) : RawLoader
+ {
+ public override RawSamples Load(Stream stream, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ var data = NativeRaw.ReadPayload(stream, offset, length);
+ var samples = new ushort[width * height];
+ var huff = new HuffmanTable(Trees[info.Tree]);
+ var reader = new MsbBitReader(data);
+ Span vpred = stackalloc ushort[4];
+ info.Predictors.CopyTo(vpred);
+ Span hpred = stackalloc ushort[2];
+ var curve = info.Curve;
+ for (var row = 0; row < height; row++)
+ {
+ if (info.Split > 0 && row == info.Split && info.Tree + 1 < Trees.Length) huff = new HuffmanTable(Trees[info.Tree + 1]);
+ if ((row & 63) == 0) cancellationToken.ThrowIfCancellationRequested();
+ var dst = samples.AsSpan(row * width, width);
+ for (var col = 0; col < width; col++)
+ {
+ var symbol = huff.Decode(ref reader);
+ int len = symbol & 15, shl = symbol >> 4;
+ var diff = 0;
+ if (len > 0)
+ {
+ diff = (int)(((reader.Read(int.Max(len - shl, 0)) << 1) + 1) << shl >> 1);
+ if ((diff & 1 << (len - 1)) == 0) diff -= (1 << len) - (shl == 0 ? 1 : 0);
+ }
+ ushort predicted;
+ if (col < 2)
+ {
+ ref var v = ref vpred[(row & 1) * 2 + col];
+ v = (ushort)(v + diff);
+ predicted = hpred[col] = v;
+ }
+ else
+ {
+ predicted = hpred[col & 1] = (ushort)(hpred[col & 1] + diff);
+ }
+ dst[col] = curve[int.Clamp((short)predicted, 0, 0x3FFF)];
+ }
+ if (reader.Overrun) throw new InvalidDataException($"NEF: compressed data ends at row {row}");
+ }
+ return new RawSamples(width, height, 1, samples, null);
+ }
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/PefReader.cs b/src/Titano.Core/Codecs/Raw/PefReader.cs
new file mode 100644
index 00000000..7c8f73b2
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/PefReader.cs
@@ -0,0 +1,149 @@
+using System.Buffers.Binary;
+using Titano.Core.Mathematics;
+using Titano.Core.Metadata.Tiff;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// Pentax PEF: the CFA image in IFD0 is uncompressed or Pentax-Huffman coded (Compression 65535): a code table from
+/// MakerNote 0x0220 (code values left-aligned in 12 bits and their lengths, dcraw pentax_load_raw), JPEG-style
+/// difference magnitudes, and two-column horizontal prediction seeded per row parity. Black (0x0200) and as-shot RGGB
+/// levels (0x0201) come from the "AOC" MakerNote, whose offsets are relative to the TIFF header.
+///
+internal static class PefReader
+{
+ private const uint CompressionPentax = 65535;
+ private const ushort BlackPointTag = 0x0200;
+ private const ushort WhiteBalanceTag = 0x0201;
+ private const ushort HuffmanTag = 0x0220;
+
+ public static RawFrame Read(Stream stream)
+ {
+ var r = TiffReader.Open(stream) ?? throw new InvalidDataException("PEF: missing TIFF header");
+ var chain = r.ReadChain();
+ if (chain.Count == 0) throw new InvalidDataException("PEF: no image directory");
+ var ifd0 = chain[0];
+ var raw = NefReader.FindCfa(r, ifd0) ?? throw new InvalidDataException("PEF: CFA image missing");
+ var (width, height) = NativeRaw.Size(r.GetUInt(raw, TiffTags.ImageWidth) ?? 0, r.GetUInt(raw, TiffTags.ImageLength) ?? 0);
+ var bits = (int)(r.GetUInt(raw, TiffTags.BitsPerSample) ?? 0);
+ if (bits is not (12 or 14)) throw new InvalidDataException($"PEF: {bits}-bit data is not supported");
+ var compression = r.GetUInt(raw, TiffTags.Compression) ?? 1;
+ var (offset, length) = NefReader.Strip(r, raw);
+ var note = MakerNote(stream, r, ifd0);
+ var warnings = new List();
+ var cfa = NativeRaw.TiffEpCfa(r, raw);
+ if (cfa is null)
+ {
+ cfa = CfaPattern.Bayer("RGGB");
+ warnings.Add("PEF: CFA pattern missing; RGGB assumed");
+ }
+ if (!cfa.IsBayer) throw new InvalidDataException("PEF: only Bayer sensors are supported");
+
+ RawLoader loader;
+ if (compression == CompressionPentax)
+ {
+ if (note is not { } mn || !mn.Ifd.Entries.TryGetValue(HuffmanTag, out var e) || mn.Reader.ReadBytes(e) is not { } table)
+ throw new InvalidDataException("PEF: Huffman table missing");
+ NativeRaw.RequireBits(length, (long)width * height);
+ loader = new PentaxLoader(offset, length, width, height, bits, Table(table, mn.Reader.LittleEndian));
+ }
+ else if (compression == 1 && length >= (long)width * height * 2)
+ {
+ loader = new PlainRawLoader(offset, length, width, height, bits, words: true, littleEndian: r.LittleEndian);
+ }
+ else if (compression == 1 && length >= ((long)width * bits + 7) / 8 * height)
+ {
+ loader = new PlainRawLoader(offset, length, width, height, bits, words: false, littleEndian: false);
+ }
+ else
+ {
+ throw new InvalidDataException($"PEF: compression {compression} is not supported");
+ }
+
+ var black = note is { } n && IfdValue.UInts(n.Reader, n.Ifd, BlackPointTag) is { Length: 4 } b
+ ? NativeRaw.Black2x2(cfa, [b[0], b[1], b[2], b[3]])
+ : NativeRaw.Black(0);
+ Vector3D? multipliers = note is { } w && IfdValue.UInts(w.Reader, w.Ifd, WhiteBalanceTag) is { Length: 4 } wb && wb[1] + wb[2] > 0
+ ? new Vector3D(wb[0] * 2.0 / (wb[1] + wb[2]), 1, wb[3] * 2.0 / (wb[1] + wb[2]))
+ : null;
+ return NativeRaw.Frame("managed-pef", width, height, cfa, new RawRect(0, 0, width, height), black, (1 << bits) - 1, multipliers,
+ (int)(r.GetUInt(ifd0, TiffTags.Orientation) ?? 1), r.GetString(ifd0, TiffTags.Make), r.GetString(ifd0, TiffTags.Model), loader, warnings);
+ }
+
+ /// "AOC\0" + byte order ("MM"/"II", else the file's) + IFD; offsets relative to the file's TIFF header.
+ private static (TiffReader Reader, Ifd Ifd)? MakerNote(Stream stream, TiffReader r, Ifd ifd0)
+ {
+ if (NativeRaw.ExifIfd(r, ifd0) is not { } exif || !exif.Entries.TryGetValue(TiffTags.MakerNote, out var e) || e.IsInline || e.Count < 8) return null;
+ var start = e.ValuePosition(r.Base);
+ var head = r.ReadRelative(start - r.Base, 6);
+ if (head is null || !head.AsSpan(0, 4).SequenceEqual("AOC\0"u8)) return null;
+ var littleEndian = head[4] == 'I' && head[5] == 'I' || !(head[4] == 'M' && head[5] == 'M') && r.LittleEndian;
+ var reader = TiffReader.ForEmbedded(stream, r.Base, littleEndian);
+ return reader.ReadIfd((uint)(start + 6 - r.Base)) is { } ifd ? (reader, ifd) : null;
+ }
+
+ /// 12-bit lookup from MakerNote 0x0220: a code count, 12 skipped bytes, left-aligned code values (16-bit) and
+ /// code lengths (8-bit); every 12-bit prefix of a code maps to (length, difference magnitude).
+ internal static HuffmanTable Table(byte[] table, bool littleEndian)
+ {
+ if (table.Length < 14) throw new InvalidDataException("PEF: Huffman table truncated");
+ ushort U16(int at) => littleEndian ? BinaryPrimitives.ReadUInt16LittleEndian(table.AsSpan(at)) : BinaryPrimitives.ReadUInt16BigEndian(table.AsSpan(at));
+ var depth = (U16(0) + 12) & 15;
+ if (table.Length < 14 + depth * 3) throw new InvalidDataException("PEF: Huffman table truncated");
+ var lut = new ushort[4096];
+ for (var c = 0; c < depth; c++)
+ {
+ int code = U16(14 + 2 * c), len = table[14 + 2 * depth + c];
+ if (code > 4095 || len > 12) continue;
+ var end = (code + (4096 >> len) - 1) & 4095;
+ for (var i = code; i <= end; i++) lut[i] = (ushort)(len << 8 | c);
+ }
+ return new HuffmanTable(lut, 12);
+ }
+
+ private sealed class PentaxLoader(long offset, long length, int width, int height, int bits, HuffmanTable huff) : RawLoader
+ {
+ public override RawSamples Load(Stream stream, int maxDegreeOfParallelism, CancellationToken cancellationToken)
+ {
+ var data = NativeRaw.ReadPayload(stream, offset, length);
+ var samples = new ushort[width * height];
+ var reader = new MsbBitReader(data);
+ Span vpred = stackalloc int[4];
+ Span hpred = stackalloc int[2];
+ var limit = (1 << bits) - 1;
+ var outOfRange = false;
+ for (var row = 0; row < height; row++)
+ {
+ if ((row & 63) == 0) cancellationToken.ThrowIfCancellationRequested();
+ var dst = samples.AsSpan(row * width, width);
+ for (var col = 0; col < width; col++)
+ {
+ var len = huff.Decode(ref reader);
+ var diff = 0;
+ if (len == 16)
+ {
+ diff = -32768;
+ }
+ else if (len > 0)
+ {
+ diff = (int)reader.Read(len);
+ if ((diff & 1 << (len - 1)) == 0) diff -= (1 << len) - 1;
+ }
+ int value;
+ if (col < 2) value = hpred[col] = vpred[(row & 1) * 2 + col] += diff;
+ else value = hpred[col & 1] += diff;
+ if ((uint)value > (uint)limit)
+ {
+ outOfRange = true;
+ value = int.Clamp(value, 0, limit);
+ }
+ dst[col] = (ushort)value;
+ }
+ if (reader.Overrun) throw new InvalidDataException($"PEF: compressed data ends at row {row}");
+ }
+ var result = new RawSamples(width, height, 1, samples, null);
+ if (outOfRange) result.Warnings.Add("PEF: predicted values outside the bit depth were clamped");
+ return result;
+ }
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/RafReader.cs b/src/Titano.Core/Codecs/Raw/RafReader.cs
new file mode 100644
index 00000000..c7a34290
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/RafReader.cs
@@ -0,0 +1,115 @@
+using System.Buffers.Binary;
+using Titano.Core.Mathematics;
+using Titano.Core.Metadata;
+using Titano.Core.Metadata.Tiff;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// Fujifilm RAF, uncompressed: the header's CFA offset (0x64) points to a big-endian TIFF block whose FujiIFD (0xF000)
+/// gives the raster size (0xF001/0xF002), bit depth (0xF003), the data offset relative to that block (0xF007), its length
+/// (0xF008) and black levels (0xF00A); the RAF directory supplies the crop (0x0110 top-left, 0x0111 size), the 6×6
+/// colour layout (0x0131, stored reversed, anchored at the raster origin; Bayer bodies describe their 2×2 pattern the same
+/// way) and the as-shot GRGB levels (0x2FF0). Samples are little-endian 16-bit words whatever the block's byte order, as
+/// LibRaw reads them. Compressed RAFs and
+/// SuperCCD (45°) layouts are not supported and fall back to the preview.
+///
+internal static class RafReader
+{
+ private const int HeaderLength = 0x6C;
+ private const int MaxDirectoryBytes = 1 << 20;
+ private const ushort FullSizeRecord = 0x0100, CropTopLeftRecord = 0x0110, CropSizeRecord = 0x0111;
+ private const ushort LayoutRecord = 0x0130, CfaRecord = 0x0131, WhiteBalanceRecord = 0x2FF0;
+ private const ushort FujiIfdTag = 0xF000, WidthTag = 0xF001, HeightTag = 0xF002, BitsTag = 0xF003;
+ private const ushort OffsetTag = 0xF007, LengthTag = 0xF008, BlackTag = 0xF00A;
+
+ public static RawFrame Read(Stream stream)
+ {
+ var header = new byte[HeaderLength];
+ stream.Position = 0;
+ if (stream.ReadAtLeast(header, HeaderLength, throwOnEndOfStream: false) < HeaderLength || !header.AsSpan().StartsWith("FUJIFILMCCD-RAW "u8))
+ throw new InvalidDataException("RAF: header missing");
+ var records = Directory(stream, BinaryPrimitives.ReadUInt32BigEndian(header.AsSpan(0x5C)), BinaryPrimitives.ReadUInt32BigEndian(header.AsSpan(0x60)));
+ if (records.TryGetValue(LayoutRecord, out var layout) && layout.Length >= 2 && (layout[1] & 8) == 0)
+ throw new InvalidDataException("RAF: SuperCCD layouts are not supported");
+ if (!records.TryGetValue(CfaRecord, out var pattern) || pattern.Length < 36) throw new InvalidDataException("RAF: colour layout record missing");
+
+ var blockBase = BinaryPrimitives.ReadUInt32BigEndian(header.AsSpan(0x64));
+ var r = TiffReader.Open(stream, blockBase) ?? throw new InvalidDataException("RAF: raw block is not TIFF-structured");
+ var fuji = r.ReadIfd(r.FirstIfdOffset) is { } top && r.GetUInt(top, FujiIfdTag) is { } sub ? r.ReadIfd(sub) : null;
+ if (fuji is null) throw new InvalidDataException("RAF: FujiIFD missing");
+ var (width, height) = NativeRaw.Size(r.GetUInt(fuji, WidthTag) ?? 0, r.GetUInt(fuji, HeightTag) ?? 0);
+ var bits = (int)(r.GetUInt(fuji, BitsTag) ?? 0);
+ if (bits is < 12 or > 16) throw new InvalidDataException($"RAF: {bits}-bit data is not supported");
+ var offset = blockBase + (long)(r.GetUInt(fuji, OffsetTag) ?? 0);
+ var length = (long)(r.GetUInt(fuji, LengthTag) ?? 0);
+ if (length < (long)width * height * 2) throw new InvalidDataException("RAF: compressed RAF is not supported");
+
+ var warnings = new List();
+ var active = new RawRect(0, 0, width, height);
+ if (records.TryGetValue(CropTopLeftRecord, out var tl) && tl.Length >= 4 && records.TryGetValue(CropSizeRecord, out var size) && size.Length >= 4)
+ {
+ int top0 = BinaryPrimitives.ReadUInt16BigEndian(tl), left0 = BinaryPrimitives.ReadUInt16BigEndian(tl.AsSpan(2));
+ int h = BinaryPrimitives.ReadUInt16BigEndian(size), w = BinaryPrimitives.ReadUInt16BigEndian(size.AsSpan(2));
+ var crop = new RawRect(left0, top0, left0 + w, top0 + h).Intersect(active);
+ if (!crop.IsEmpty) active = crop;
+ }
+ var colors = new byte[36];
+ for (var i = 0; i < 36; i++) colors[35 - i] = (byte)(pattern[i] & 3);
+ var cfa = new CfaPattern(6, 6, colors).Shift(active.Left, active.Top);
+
+ var black = NativeRaw.Black(1024 >> (14 - int.Min(bits, 14)));
+ if (fuji.Entries.TryGetValue(BlackTag, out var be) && be.Count is > 0 and <= 64 && r.GetUInts(be) is { } levels)
+ {
+ if (levels.Length >= 36)
+ {
+ // A 6×6 grid anchored at the raster origin, re-anchored at the active area.
+ var grid = new float[36];
+ for (var y = 0; y < 6; y++)
+ {
+ for (var x = 0; x < 6; x++) grid[y * 6 + x] = levels[(y + active.Top) % 6 * 6 + (x + active.Left) % 6];
+ }
+ black = new RawBlackLevel(6, 6, grid, null, null);
+ }
+ else
+ {
+ black = NativeRaw.Black(levels.Average(v => (double)v));
+ }
+ }
+ else
+ {
+ warnings.Add("RAF: black level missing; default used");
+ }
+
+ Vector3D? multipliers = null;
+ if (records.TryGetValue(WhiteBalanceRecord, out var wb) && wb.Length >= 8)
+ {
+ double g = BinaryPrimitives.ReadUInt16BigEndian(wb), red = BinaryPrimitives.ReadUInt16BigEndian(wb.AsSpan(2)), blue = BinaryPrimitives.ReadUInt16BigEndian(wb.AsSpan(6));
+ if (g > 0) multipliers = new Vector3D(red / g, 1, blue / g);
+ }
+ var metadata = MetadataReader.Read(stream, "frame.raf");
+ var loader = new PlainRawLoader(offset, length, width, height, 16, words: true, littleEndian: true);
+ return NativeRaw.Frame("managed-raf", width, height, cfa, active, black, (1 << bits) - 1, multipliers, metadata.Orientation,
+ metadata.Make ?? "FUJIFILM", metadata.Model, loader, warnings);
+ }
+
+ /// RAF directory: u32 record count, then (u16 tag, u16 size, data) records, big-endian.
+ private static Dictionary Directory(Stream stream, uint offset, uint length)
+ {
+ var result = new Dictionary();
+ if (offset < HeaderLength || length < 4 || length > MaxDirectoryBytes || offset > stream.Length - length) throw new InvalidDataException("RAF: directory missing");
+ var data = NativeRaw.ReadPayload(stream, offset, length);
+ var count = BinaryPrimitives.ReadUInt32BigEndian(data);
+ var pos = 4;
+ for (var i = 0; i < count && pos + 4 <= data.Length; i++)
+ {
+ var tag = BinaryPrimitives.ReadUInt16BigEndian(data.AsSpan(pos));
+ var size = BinaryPrimitives.ReadUInt16BigEndian(data.AsSpan(pos + 2));
+ pos += 4;
+ if (pos + size > data.Length) break;
+ result.TryAdd(tag, data.AsSpan(pos, size).ToArray());
+ pos += size;
+ }
+ return result;
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/RawDecoder.cs b/src/Titano.Core/Codecs/Raw/RawDecoder.cs
new file mode 100644
index 00000000..5f2848d3
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/RawDecoder.cs
@@ -0,0 +1,132 @@
+using Titano.Core.Codecs.Dng;
+using Titano.Core.Imaging;
+using Titano.Core.Metadata;
+
+namespace Titano.Core.Codecs.Raw;
+
+/// Demosaic quality: AHD for renders and proxies, bilinear for thumbnails and analysis.
+public enum DemosaicQuality
+{
+ /// Bilinear (Bayer) — fast, slightly soft, some colour fringing on fine detail.
+ Draft,
+
+ /// Adaptive homogeneity-directed (Bayer); X-Trans always uses the neighbourhood interpolation.
+ Best,
+}
+
+/// Options for .
+public sealed record RawDecodeOptions
+{
+ public static RawDecodeOptions Default { get; } = new();
+
+ public DemosaicQuality Quality { get; init; } = DemosaicQuality.Best;
+
+ /// Target long edge (0 = full size). When the CFA can be binned (half size for Bayer, one third for X-Trans)
+ /// and the binned image keeps at least this long edge, blocks are binned into RGB pixels instead of demosaiced. The
+ /// result is not resized further; linear (already demosaiced) data is always developed at full size.
+ public int MaxLongEdge { get; init; }
+
+ /// Rotate/flip according to the file's orientation.
+ public bool ApplyOrientation { get; init; } = true;
+
+ /// Worker limit (-1 = all cores).
+ public int MaxDegreeOfParallelism { get; init; } = -1;
+}
+
+/// What a RAW container holds, read without decoding its pixels.
+/// Container format.
+/// Decoder that would develop it ("managed-dng", "managed-cr2"…).
+/// Developed width at full size, after crop and orientation.
+/// Developed height at full size, after crop and orientation.
+/// CFA pattern ("RGGB", "6x6:…") or "linear".
+/// Exif orientation applied when requested.
+public sealed record RawImageInfo(ImageFileFormat Format, string Decoder, string? Make, string? Model, int Width, int Height, string Layout, int Orientation);
+
+/// Result of : native support plus the reason when unsupported.
+public sealed record RawProbe(RawImageInfo? Info, string? Reason, IReadOnlyList Warnings)
+{
+ public bool IsSupported => Info is not null;
+}
+
+/// A developed RAW: linear Rec.709 (D65) RGB, BaselineExposure applied. Dispose to return the pixels to the pool.
+public sealed class RawDecodeResult(ImageBuffer image, RawImageInfo info, IReadOnlyList warnings) : IDisposable
+{
+ public ImageBuffer Image { get; } = image;
+ public RawImageInfo Info { get; } = info;
+ public IReadOnlyList Warnings { get; } = warnings;
+
+ public void Dispose() => Image.Dispose();
+}
+
+///
+/// Managed RAW decoding (BRIEF §8.2): DNG (CFA and LinearRaw) through , and the native containers
+/// Canon CR2, Nikon NEF, Sony ARW, Pentax PEF and Fujifilm RAF, all developed by the same pipeline. Bodies or encodings
+/// without support are reported by so callers can fall back to the embedded preview.
+///
+public static class RawDecoder
+{
+ /// Formats with a managed decoder (individual files may still be unsupported).
+ public static IReadOnlyList Formats { get; } =
+ [ImageFileFormat.Dng, ImageFileFormat.Cr2, ImageFileFormat.Nef, ImageFileFormat.Arw, ImageFileFormat.Pef, ImageFileFormat.Raf];
+
+ /// Parses the container and decides whether it can be developed natively; never reads the pixel payload.
+ public static RawProbe Probe(Stream stream, string? fileName = null)
+ {
+ ArgumentNullException.ThrowIfNull(stream);
+ var warnings = new List();
+ try
+ {
+ var (format, frame) = Open(stream, fileName);
+ warnings.AddRange(frame.Warnings);
+ return new RawProbe(Describe(format, frame, RawDecodeOptions.Default), null, warnings);
+ }
+ catch (InvalidDataException ex)
+ {
+ return new RawProbe(null, ex.Message, warnings);
+ }
+ catch (IOException ex)
+ {
+ return new RawProbe(null, "I/O error: " + ex.Message, warnings);
+ }
+ }
+
+ /// Develops the RAW in (readable and seekable).
+ /// Breaks signature ties between formats sharing a container (see ).
+ /// Malformed file, or a body/encoding without native support.
+ public static RawDecodeResult Decode(Stream stream, string? fileName = null, RawDecodeOptions? options = null, CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(stream);
+ var o = options ?? RawDecodeOptions.Default;
+ var (format, frame) = Open(stream, fileName);
+ cancellationToken.ThrowIfCancellationRequested();
+ var samples = frame.Loader.Load(stream, o.MaxDegreeOfParallelism, cancellationToken);
+ var warnings = new List(frame.Warnings);
+ warnings.AddRange(samples.Warnings);
+ var image = RawDeveloper.Develop(frame, samples, o, warnings, cancellationToken);
+ return new RawDecodeResult(image, Describe(format, frame, o), warnings);
+ }
+
+ private static (ImageFileFormat Format, RawFrame Frame) Open(Stream stream, string? fileName)
+ {
+ if (!stream.CanSeek || !stream.CanRead) throw new ArgumentException("The stream must be readable and seekable.", nameof(stream));
+ var format = ImageSignature.Detect(stream, fileName);
+ var frame = format switch
+ {
+ ImageFileFormat.Dng => DngReader.Read(stream),
+ ImageFileFormat.Cr2 => Cr2Reader.Read(stream),
+ ImageFileFormat.Nef => NefReader.Read(stream),
+ ImageFileFormat.Arw => ArwReader.Read(stream),
+ ImageFileFormat.Pef => PefReader.Read(stream),
+ ImageFileFormat.Raf => RafReader.Read(stream),
+ _ => throw new InvalidDataException($"RAW: no managed decoder for {format}"),
+ };
+ return (format, frame);
+ }
+
+ private static RawImageInfo Describe(ImageFileFormat format, RawFrame frame, RawDecodeOptions options)
+ {
+ var (w, h) = frame.OutputSize;
+ if (options.ApplyOrientation && frame.Orientation is >= 5 and <= 8) (w, h) = (h, w);
+ return new RawImageInfo(format, frame.Decoder, frame.Make, frame.Model, w, h, frame.Cfa?.ToString() ?? "linear", frame.Orientation);
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/RawDeveloper.cs b/src/Titano.Core/Codecs/Raw/RawDeveloper.cs
new file mode 100644
index 00000000..33eac0fa
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/RawDeveloper.cs
@@ -0,0 +1,358 @@
+using Titano.Core.Codecs.Dng;
+using Titano.Core.Imaging;
+using Titano.Core.Mathematics;
+
+namespace Titano.Core.Codecs.Raw;
+
+///
+/// The raw development pipeline shared by DNG and the native RAW readers (BRIEF §8.2; DNG 1.6 chapter 5 "Mapping Raw
+/// Values to Linear Reference Values" and chapter 6): OpcodeList1 on stored values → linearisation table, black level
+/// (repeat pattern + row/column deltas) and white scaling to 0..1 over the active area, with a clip map of saturated
+/// samples → OpcodeList2 → white-balance multipliers → demosaic (AHD, bilinear, neighbourhood or binning) → highlight
+/// reconstruction → OpcodeList3 → default crop → camera → linear Rec.709 matrix with BaselineExposure → default scale →
+/// orientation.
+///
+internal static class RawDeveloper
+{
+ /// Normalised level at or above which a sample counts as clipped.
+ private const float ClipThreshold = 0.999f;
+
+ /// A pile-up of samples at the data maximum counts as sensor saturation only above this fraction of the white level.
+ private const double SaturationFloor = 0.75;
+
+ /// Samples that must sit at the data maximum for it to count as saturation rather than the brightest detail.
+ private const int SaturationPileUp = 16;
+
+ public static ImageBuffer Develop(RawFrame frame, RawSamples samples, RawDecodeOptions options, ICollection warnings, CancellationToken cancellationToken)
+ {
+ if (samples.Width != frame.Width || samples.Height != frame.Height || samples.SamplesPerPixel != frame.SamplesPerPixel)
+ throw new InvalidDataException("RAW: decoded payload does not match the declared raster");
+ var dop = options.MaxDegreeOfParallelism;
+ var spp = frame.SamplesPerPixel;
+ var active = frame.ActiveArea;
+ var black = samples.MeasuredBlack ?? frame.Black;
+ var white = frame.White;
+ var saturation = frame.DetectSaturation && frame.Linearization is null && spp == 1 ? Saturation(samples, active, black, white[0]) : 1f;
+
+ var list1 = DngOpcodes.Parse(frame.OpcodeList1, 1, warnings);
+ ImageBuffer? stage1 = null;
+ if (list1.Count > 0)
+ {
+ stage1 = ToStage1(samples, dop, cancellationToken);
+ var image = new OpcodeImage(stage1, 0, 0, 1, spp == 1 ? frame.Cfa?.Shift(-active.Left, -active.Top) : null);
+ DngOpcodes.Apply(list1, image, warnings, cancellationToken);
+ stage1 = image.Pixels;
+ if (stage1.Width != samples.Width || stage1.Height != samples.Height)
+ {
+ stage1.Dispose();
+ throw new InvalidDataException("RAW: OpcodeList1 changed the raster size");
+ }
+ }
+
+ ImageBuffer linear;
+ byte[]? clip;
+ try
+ {
+ (linear, clip) = Linearize(frame, samples, stage1, black, white, saturation * ClipThreshold, dop, cancellationToken);
+ }
+ finally
+ {
+ stage1?.Dispose();
+ }
+
+ var stage = new OpcodeImage(linear, 0, 0, 1, frame.Cfa) { ClipMask = clip };
+ try
+ {
+ DngOpcodes.Apply(DngOpcodes.Parse(frame.OpcodeList2, 2, warnings), stage, warnings, cancellationToken);
+ return frame.Cfa is null && spp == 1
+ ? DevelopMonochrome(frame, stage, options, warnings, cancellationToken)
+ : DevelopColour(frame, stage, saturation, options, warnings, cancellationToken);
+ }
+ finally
+ {
+ stage.Pixels.Dispose();
+ }
+ }
+
+ private static ImageBuffer DevelopColour(RawFrame frame, OpcodeImage stage, float saturation, RawDecodeOptions options, ICollection warnings, CancellationToken cancellationToken)
+ {
+ var dop = options.MaxDegreeOfParallelism;
+ var colour = frame.Color.Solve(warnings);
+ var n = colour.CameraNeutral;
+ float[] wb = [(float)(1 / n.X), (float)(1 / n.Y), (float)(1 / n.Z)];
+
+ ImageBuffer rgb;
+ byte[]? bits = null;
+ var step = 1;
+ if (stage.Cfa is { } cfa)
+ {
+ ScaleMosaic(stage.Pixels, cfa, wb, dop, cancellationToken);
+ var bin = cfa.BinSize;
+ if (options.MaxLongEdge <= 0 || int.Max(stage.Width, stage.Height) / int.Max(bin, 1) < options.MaxLongEdge) bin = 0;
+ if (bin > 0)
+ {
+ rgb = Demosaic.Bin(stage.Pixels, cfa, bin, dop, cancellationToken);
+ step = bin;
+ if (stage.ClipMask is { } mask) bits = HighlightReconstruction.Bin(mask, stage.Width, bin, rgb.Width, rgb.Height);
+ }
+ else
+ {
+ rgb = !cfa.IsBayer ? Demosaic.Neighbourhood(stage.Pixels, cfa, dop, cancellationToken)
+ : options.Quality == DemosaicQuality.Best ? AhdDemosaic.Run(stage.Pixels, cfa, colour.BalancedToXyz, dop, cancellationToken)
+ : Demosaic.Bilinear(stage.Pixels, cfa, dop, cancellationToken);
+ if (stage.ClipMask is { } mask) bits = HighlightReconstruction.Dilate(mask, stage.Width, stage.Height);
+ }
+ }
+ else
+ {
+ rgb = stage.Pixels.Clone();
+ for (var c = 0; c < 3; c++) Scale(rgb.Plane(c), wb[c]);
+ bits = stage.ClipMask;
+ }
+
+ var image = new OpcodeImage(rgb, stage.Left, stage.Top, step, null);
+ try
+ {
+ if (bits is not null) HighlightReconstruction.Apply(rgb, bits, [wb[0] * saturation, wb[1] * saturation, wb[2] * saturation], dop, cancellationToken);
+ var list3 = DngOpcodes.Parse(frame.OpcodeList3, 3, warnings);
+ if (list3.Count > 0)
+ {
+ // Value-mapping opcodes are defined on unbalanced camera values; gains and warps commute with the multipliers.
+ var unbalance = list3.Exists(o => o.NeedsUnbalancedValues);
+ if (unbalance) ScalePlanes(image.Pixels, [1 / wb[0], 1 / wb[1], 1 / wb[2]]);
+ DngOpcodes.Apply(list3, image, warnings, cancellationToken);
+ if (unbalance) ScalePlanes(image.Pixels, wb);
+ }
+ }
+ catch
+ {
+ image.Pixels.Dispose();
+ throw;
+ }
+ var cropped = Crop(frame, image);
+ try
+ {
+ ApplyMatrix(cropped, colour.BalancedToRec709, dop, cancellationToken);
+ }
+ catch
+ {
+ cropped.Dispose();
+ throw;
+ }
+ return Finish(frame, cropped, options);
+ }
+
+ private static ImageBuffer DevelopMonochrome(RawFrame frame, OpcodeImage stage, RawDecodeOptions options, ICollection warnings, CancellationToken cancellationToken)
+ {
+ var image = new OpcodeImage(stage.Pixels.Clone(), stage.Left, stage.Top, 1, null);
+ try
+ {
+ DngOpcodes.Apply(DngOpcodes.Parse(frame.OpcodeList3, 3, warnings), image, warnings, cancellationToken);
+ }
+ catch
+ {
+ image.Pixels.Dispose();
+ throw;
+ }
+ ImageBuffer rgb;
+ using (var cropped = Crop(frame, image))
+ {
+ Scale(cropped.Plane(0), (float)double.Exp2(frame.Color.BaselineExposure));
+ rgb = PixelConvert.GrayToRgb(cropped);
+ }
+ return Finish(frame, rgb, options);
+ }
+
+ /// Default scale, then orientation. Takes ownership of : returns it when nothing
+ /// changes, otherwise a new buffer (the input is disposed).
+ private static ImageBuffer Finish(RawFrame frame, ImageBuffer image, RawDecodeOptions options)
+ {
+ var current = image;
+ try
+ {
+ var (sh, sv) = frame.DefaultScale;
+ if (sh != sv && sh > 0 && sv > 0)
+ {
+ // Only the ratio matters for square output pixels; stretch the axis with the larger factor.
+ var ratio = sh / sv;
+ var (w, h) = ratio > 1 ? ((int)double.Round(current.Width * ratio), current.Height) : (current.Width, (int)double.Round(current.Height / ratio));
+ current = Replace(current, Resampler.Resize(current, int.Max(1, w), int.Max(1, h)));
+ }
+ if (options.ApplyOrientation && frame.Orientation is >= 2 and <= 8)
+ current = Replace(current, PixelConvert.ApplyOrientation(current, frame.Orientation));
+ return current;
+ }
+ catch
+ {
+ current.Dispose();
+ throw;
+ }
+ }
+
+ private static ImageBuffer Replace(ImageBuffer old, ImageBuffer next)
+ {
+ old.Dispose();
+ return next;
+ }
+
+ /// Stored values as floats divided by 65535 (the stage-1 domain of the opcodes), sample planes split.
+ private static ImageBuffer ToStage1(RawSamples samples, int dop, CancellationToken cancellationToken)
+ {
+ int w = samples.Width, h = samples.Height, spp = samples.SamplesPerPixel;
+ var image = new ImageBuffer(w, h, spp == 1 ? 1 : 3, clear: false);
+ Parallel.For(0, h, new ParallelOptions { MaxDegreeOfParallelism = dop, CancellationToken = cancellationToken }, y =>
+ {
+ for (var s = 0; s < image.Channels; s++)
+ {
+ var row = image.Row(s, y);
+ var o = (long)y * w * spp + s;
+ for (var x = 0; x < w; x++) row[x] = samples[o + (long)x * spp] / 65535f;
+ }
+ });
+ return image;
+ }
+
+ /// Linear reference values over the active area plus a clip map (bit = CFA colour or sample plane), or null
+ /// when nothing clipped.
+ private static (ImageBuffer Image, byte[]? Clip) Linearize(RawFrame frame, RawSamples samples, ImageBuffer? stage1, RawBlackLevel black, double[] white, float clipLevel, int dop, CancellationToken cancellationToken)
+ {
+ var active = frame.ActiveArea;
+ int w = active.Width, h = active.Height, spp = frame.SamplesPerPixel;
+ var planes = spp == 1 ? 1 : 3;
+ var image = new ImageBuffer(w, h, planes, clear: false);
+ var clip = new byte[w * h];
+ var anyClip = 0;
+ var table = frame.Linearization;
+ var scale = new float[planes];
+ for (var s = 0; s < planes; s++)
+ {
+ var range = white[int.Min(s, white.Length - 1)] - black.Max(s, spp);
+ if (!(range > 0)) throw new InvalidDataException("RAW: white level not above black level");
+ scale[s] = (float)(1 / range);
+ }
+ var cfa = frame.Cfa;
+ Parallel.For(0, h, new ParallelOptions { MaxDegreeOfParallelism = dop, CancellationToken = cancellationToken }, y =>
+ {
+ var sy = active.Top + y;
+ var blackRow = y % black.RepeatRows * black.RepeatColumns * spp;
+ var deltaV = black.DeltaV is { } dv && y < dv.Length ? dv[y] : 0f;
+ var rowClip = 0;
+ for (var s = 0; s < planes; s++)
+ {
+ var row = image.Row(s, y);
+ var source = stage1 is null ? default : stage1.Row(s, sy);
+ var o = (long)sy * samples.Width * spp + s;
+ for (var x = 0; x < w; x++)
+ {
+ var sx = active.Left + x;
+ var v = source.IsEmpty ? samples[o + (long)sx * spp] : source[sx] * 65535f;
+ if (table is not null) v = table[int.Clamp((int)(v + 0.5f), 0, table.Length - 1)];
+ var b = black.Values[blackRow + x % black.RepeatColumns * spp + s] + deltaV
+ + (black.DeltaH is { } dh && x < dh.Length ? dh[x] : 0f);
+ var value = (v - b) * scale[s];
+ row[x] = value;
+ if (value >= clipLevel)
+ {
+ clip[y * w + x] |= (byte)(1 << (cfa is null ? s : cfa.ColorAt(x, y)));
+ rowClip = 1;
+ }
+ }
+ }
+ if (rowClip != 0) Volatile.Write(ref anyClip, 1);
+ });
+ return (image, anyClip != 0 ? clip : null);
+ }
+
+ /// Normalised saturation level of a native RAW: the data maximum when at least
+ /// samples reach it and it lies between and 1 of the white level, else 1. It only moves
+ /// the clip threshold; scaling stays tied to the white level so brightness never depends on frame content.
+ private static float Saturation(RawSamples samples, RawRect active, RawBlackLevel black, double white)
+ {
+ var max = 0f;
+ var count = 0;
+ for (var y = active.Top; y < active.Bottom; y++)
+ {
+ var o = (long)y * samples.Width;
+ for (var x = active.Left; x < active.Right; x++)
+ {
+ var v = samples[o + x];
+ if (v > max + 1)
+ {
+ max = v;
+ count = 1;
+ }
+ else if (v >= max - 1)
+ {
+ count++;
+ max = float.Max(max, v);
+ }
+ }
+ }
+ if (count < SaturationPileUp || max >= white || max < white * SaturationFloor) return 1f;
+ var floor = black.Max(0, 1);
+ return (float)double.Clamp((max - 1 - floor) / (white - floor), 0.5, 1);
+ }
+
+ private static void ScaleMosaic(ImageBuffer mosaic, CfaPattern cfa, float[] wb, int dop, CancellationToken cancellationToken)
+ {
+ Parallel.For(0, mosaic.Height, new ParallelOptions { MaxDegreeOfParallelism = dop, CancellationToken = cancellationToken }, y =>
+ {
+ var row = mosaic.Row(0, y);
+ Span phase = stackalloc float[CfaPattern.MaxSize];
+ for (var i = 0; i < cfa.Width; i++) phase[i] = wb[cfa.ColorAt(i, y)];
+ for (var x = 0; x < row.Length; x++) row[x] *= phase[x % cfa.Width];
+ });
+ }
+
+ private static void ScalePlanes(ImageBuffer image, float[] factors)
+ {
+ for (var c = 0; c < 3; c++) Scale(image.Plane(c), factors[c]);
+ }
+
+ private static void Scale(Span values, float factor)
+ {
+ for (var i = 0; i < values.Length; i++) values[i] *= factor;
+ }
+
+ /// Default crop (stage coordinates relative to the active area) intersected with what the opcodes left. Takes
+ /// ownership of the image's pixels: returns them when nothing is cut, otherwise a new buffer (the input is disposed).
+ private static ImageBuffer Crop(RawFrame frame, OpcodeImage image)
+ {
+ var crop = frame.DefaultCrop ?? new RawRect(0, 0, frame.ActiveArea.Width, frame.ActiveArea.Height);
+ var area = crop.Intersect(image.Bounds);
+ if (area.IsEmpty) area = image.Bounds;
+ var x0 = int.Clamp((int)double.Ceiling(image.BufferX(area.Left) - 1e-9), 0, image.Width - 1);
+ var y0 = int.Clamp((int)double.Ceiling(image.BufferY(area.Top) - 1e-9), 0, image.Height - 1);
+ var x1 = int.Clamp((int)double.Floor(image.BufferX(area.Right - 1) + 1e-9) + 1, x0 + 1, image.Width);
+ var y1 = int.Clamp((int)double.Floor(image.BufferY(area.Bottom - 1) + 1e-9) + 1, y0 + 1, image.Height);
+ var src = image.Pixels;
+ if (x0 == 0 && y0 == 0 && x1 == src.Width && y1 == src.Height) return src;
+ var dst = new ImageBuffer(x1 - x0, y1 - y0, src.Channels, clear: false);
+ for (var c = 0; c < src.Channels; c++)
+ {
+ for (var y = y0; y < y1; y++) src.Row(c, y).Slice(x0, x1 - x0).CopyTo(dst.Row(c, y - y0));
+ }
+ src.Dispose();
+ return dst;
+ }
+
+ private static void ApplyMatrix(ImageBuffer image, Matrix3 m, int dop, CancellationToken cancellationToken)
+ {
+ float m11 = (float)m.M11, m12 = (float)m.M12, m13 = (float)m.M13;
+ float m21 = (float)m.M21, m22 = (float)m.M22, m23 = (float)m.M23;
+ float m31 = (float)m.M31, m32 = (float)m.M32, m33 = (float)m.M33;
+ Parallel.For(0, image.Height, new ParallelOptions { MaxDegreeOfParallelism = dop, CancellationToken = cancellationToken }, y =>
+ {
+ var r = image.Row(0, y);
+ var g = image.Row(1, y);
+ var b = image.Row(2, y);
+ for (var x = 0; x < r.Length; x++)
+ {
+ float vr = r[x], vg = g[x], vb = b[x];
+ r[x] = m11 * vr + m12 * vg + m13 * vb;
+ g[x] = m21 * vr + m22 * vg + m23 * vb;
+ b[x] = m31 * vr + m32 * vg + m33 * vb;
+ }
+ });
+ }
+}
diff --git a/src/Titano.Core/Codecs/Raw/RawFrame.cs b/src/Titano.Core/Codecs/Raw/RawFrame.cs
new file mode 100644
index 00000000..3fc24b4d
--- /dev/null
+++ b/src/Titano.Core/Codecs/Raw/RawFrame.cs
@@ -0,0 +1,141 @@
+using Titano.Core.Codecs.Dng;
+
+namespace Titano.Core.Codecs.Raw;
+
+/// Integer rectangle (left, top inclusive; right, bottom exclusive).
+public readonly record struct RawRect(int Left, int Top, int Right, int Bottom)
+{
+ public int Width => Right - Left;
+ public int Height => Bottom - Top;
+ public bool IsEmpty => Width <= 0 || Height <= 0;
+
+ public RawRect Intersect(RawRect other) => new(
+ int.Max(Left, other.Left), int.Max(Top, other.Top), int.Min(Right, other.Right), int.Min(Bottom, other.Bottom));
+
+ public override string ToString() => $"{Left},{Top} {Width}x{Height}";
+}
+
+/// Black level description (DNG BlackLevelRepeatDim, BlackLevel, BlackLevelDeltaH/V), relative to the active area.
+internal sealed class RawBlackLevel
+{
+ public static RawBlackLevel Zero(int samplesPerPixel) => new(1, 1, new float[samplesPerPixel], null, null);
+
+ public RawBlackLevel(int repeatRows, int repeatColumns, float[] values, float[]? deltaH, float[]? deltaV)
+ {
+ RepeatRows = repeatRows;
+ RepeatColumns = repeatColumns;
+ Values = values;
+ DeltaH = deltaH;
+ DeltaV = deltaV;
+ }
+
+ public int RepeatRows { get; }
+ public int RepeatColumns { get; }
+
+ /// rows × columns × samples-per-pixel values, sample index fastest.
+ public float[] Values { get; }
+
+ public float[]? DeltaH { get; }
+ public float[]? DeltaV { get; }
+
+ /// Largest black level of a sample plane, deltas included (the white-scaling reference of the DNG SDK).
+ public float Max(int sample, int samplesPerPixel)
+ {
+ var max = float.MinValue;
+ for (var i = sample; i < Values.Length; i += samplesPerPixel) max = float.Max(max, Values[i]);
+ return max + (DeltaH is { Length: > 0 } h ? MaxOf(h) : 0) + (DeltaV is { Length: > 0 } v ? MaxOf(v) : 0);
+ }
+
+ private static float MaxOf(float[] values)
+ {
+ var max = float.MinValue;
+ foreach (var v in values) max = float.Max(max, v);
+ return max;
+ }
+}
+
+/// Decoded raw samples as stored in the file: interleaved, × ×
+/// , integers or floats.
+internal sealed class RawSamples(int width, int height, int samplesPerPixel, ushort[]? integers, float[]? floats)
+{
+ public int Width { get; } = width;
+ public int Height { get; } = height;
+ public int SamplesPerPixel { get; } = samplesPerPixel;
+ public ushort[]? Integers { get; } = integers;
+ public float[]? Floats { get; } = floats;
+ public List Warnings { get; } = [];
+
+ /// Black level measured by the loader (e.g. from masked sensor columns), overriding the frame's own.
+ public RawBlackLevel? MeasuredBlack { get; set; }
+
+ public float this[long index] => Integers is { } i ? i[index] : Floats![index];
+}
+
+/// Reads the pixel payload of one container; created by the container parser, run by the pipeline.
+internal abstract class RawLoader
+{
+ /// The payload is malformed or uses an unsupported encoding.
+ public abstract RawSamples Load(Stream stream, int maxDegreeOfParallelism, CancellationToken cancellationToken);
+}
+
+///
+/// Everything the development pipeline needs about one raw image, independent of the container: raster geometry, CFA,
+/// linearisation, black/white levels, crops, colour profile, opcode lists and orientation. Built by the DNG reader and the
+/// native RAW readers without touching the pixel payload.
+///
+internal sealed class RawFrame
+{
+ /// Decoder name for logs ("managed-dng", "managed-cr2"…).
+ public required string Decoder { get; init; }
+
+ public required int Width { get; init; }
+ public required int Height { get; init; }
+
+ /// 1 for CFA and monochrome data, 3 for LinearRaw RGB.
+ public int SamplesPerPixel { get; init; } = 1;
+
+ /// CFA layout anchored at the active area's top-left; null for linear (already demosaiced) data.
+ public CfaPattern? Cfa { get; init; }
+
+ /// Image area holding valid pixels, in stored coordinates.
+ public required RawRect ActiveArea { get; init; }
+
+ /// Final crop relative to the active area (DNG DefaultCropOrigin/Size); null = the whole active area.
+ public RawRect? DefaultCrop { get; init; }
+
+ /// DNG DefaultScale (horizontal, vertical) for non-square pixels.
+ public (double H, double V) DefaultScale { get; init; } = (1, 1);
+
+ public ushort[]? Linearization { get; init; }
+ public required RawBlackLevel Black { get; init; }
+
+ /// White level per sample plane, in linearised units.
+ public required double[] White { get; init; }
+
+ /// Find the clip threshold in the data: native RAWs state a nominal bit-depth maximum while sensors saturate
+ /// earlier. Only clip detection uses it; the white level keeps scaling every frame the same (no flicker).
+ public bool DetectSaturation { get; init; }
+
+ public required DngColorProfile Color { get; init; }
+ public byte[]? OpcodeList1 { get; init; }
+ public byte[]? OpcodeList2 { get; init; }
+ public byte[]? OpcodeList3 { get; init; }
+
+ /// Exif orientation 1–8.
+ public int Orientation { get; init; } = 1;
+
+ public string? Make { get; init; }
+ public string? Model { get; init; }
+ public required RawLoader Loader { get; init; }
+ public List Warnings { get; } = [];
+
+ /// Size of the developed image before orientation (active area or default crop, default scale applied).
+ public (int Width, int Height) OutputSize
+ {
+ get
+ {
+ var crop = DefaultCrop ?? new RawRect(0, 0, ActiveArea.Width, ActiveArea.Height);
+ return (int.Max(1, (int)double.Round(crop.Width * DefaultScale.H)), int.Max(1, (int)double.Round(crop.Height * DefaultScale.V)));
+ }
+ }
+}
diff --git a/src/Titano.Core/Imaging/Decoders/DecoderFactory.cs b/src/Titano.Core/Imaging/Decoders/DecoderFactory.cs
new file mode 100644
index 00000000..78a0cfaa
--- /dev/null
+++ b/src/Titano.Core/Imaging/Decoders/DecoderFactory.cs
@@ -0,0 +1,45 @@
+namespace Titano.Core.Imaging.Decoders;
+
+/// One row of the "Settings › Formats" table: the best tier a decoder chain reaches for a format, and who
+/// delivers it.
+/// Format with its family and extensions.
+/// Best tier across the chain's providers.
+/// Name of the provider delivering that tier ("wic", "managed"), null when unavailable.
+public sealed record FormatSupport(ImageFormatInfo Format, DecodeTier Tier, string? Provider);
+
+///
+/// Builds the decoder chains of BRIEF §8.2. The desktop client tries the Windows provider (WIC) first and the managed
+/// one second ( keeps that order among providers offering the same tier); the server and
+/// render nodes without WIC use the managed provider alone.
+///
+public static class DecoderFactory
+{
+ /// Client chain: (WIC on Windows; null elsewhere) then managed.
+ public static ImageDecoder CreateClient(IImageDecoderProvider? windowsProvider) =>
+ new(windowsProvider is null ? [new ManagedDecoderProvider()] : [windowsProvider, new ManagedDecoderProvider()]);
+
+ /// Server chain: managed decoders only.
+ public static ImageDecoder CreateServer() => new([new ManagedDecoderProvider()]);
+
+ /// Per-format tier on this machine for every known format, in order.
+ public static IReadOnlyList DescribeFormats(ImageDecoder decoder)
+ {
+ ArgumentNullException.ThrowIfNull(decoder);
+ var rows = new List();
+ foreach (var info in ImageFormatInfo.Known)
+ {
+ var tier = DecodeTier.Unavailable;
+ string? provider = null;
+ foreach (var p in decoder.Providers)
+ {
+ if (p.TierFor(info.Format) is { } t && t < tier)
+ {
+ tier = t;
+ provider = p.Name;
+ }
+ }
+ rows.Add(new FormatSupport(info, tier, provider));
+ }
+ return rows;
+ }
+}
diff --git a/src/Titano.Core/Imaging/Decoders/ManagedDecoderProvider.cs b/src/Titano.Core/Imaging/Decoders/ManagedDecoderProvider.cs
new file mode 100644
index 00000000..9b8c7e2f
--- /dev/null
+++ b/src/Titano.Core/Imaging/Decoders/ManagedDecoderProvider.cs
@@ -0,0 +1,218 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Codecs.Png;
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Codecs.Tiff;
+using Titano.Core.Diagnostics;
+using Titano.Core.Metadata;
+
+namespace Titano.Core.Imaging.Decoders;
+
+/// Tier a provider would use for one specific file, with the reason when it is not native.
+/// Format detected from the file's signature (extension only breaks ties).
+/// Best tier available for this file.
+/// Decoder that would produce it ("managed-cr2", "managed-preview"…), null when unavailable.
+/// Why the native tier is not used (unsupported body or encoding), else null.
+/// Full-size width that tier delivers (developed RAW, preview or image size), oriented; 0 when unknown.
+/// Full-size height, oriented; 0 when unknown.
+public sealed record FileTier(ImageFileFormat Format, DecodeTier Tier, string? Decoder, string? Reason, int Width, int Height);
+
+///
+/// The managed decoder (BRIEF §8.2), available on every platform and the only one on the server: JPEG, PNG and TIFF
+/// natively; DNG and the supported camera RAWs (CR2, NEF, ARW, PEF, RAF) through ; every other
+/// RAW, CR3 and HEIF through the largest suitable embedded JPEG preview; nothing for formats without either.
+/// fast paths: JPEG DCT scaling and RAW CFA binning when
+/// allows, bilinear demosaicing for thumbnails and analysis, and to skip native
+/// RAW development. Results fit within MaxLongEdge (never upscaled) and are always RGB.
+///
+public sealed class ManagedDecoderProvider : IImageDecoderProvider
+{
+ private const string LogCategory = "Decode";
+ private const int FileBufferSize = 1 << 16;
+ private const long MaxPreviewBytes = 256L << 20;
+
+ public string Name => "managed";
+
+ public DecodeTier? TierFor(ImageFileFormat format)
+ {
+ var info = ImageFormatInfo.Of(format);
+ if (format is ImageFileFormat.Jpeg or ImageFileFormat.Png or ImageFileFormat.Tiff || RawDecoder.Formats.Contains(format)) return DecodeTier.Native;
+ return info.Family is ImageFamily.CameraRaw or ImageFamily.Heif ? DecodeTier.EmbeddedPreview : null;
+ }
+
+ /// Decodes the file, or returns null when it has no decodable pixels here (no native decoder and no preview).
+ /// A JPEG, PNG or TIFF is malformed.
+ /// The file cannot be read.
+ public DecodedImage? Decode(DecodeRequest request, CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(request);
+ cancellationToken.ThrowIfCancellationRequested();
+ using var stream = Open(request.Path);
+ var format = ImageSignature.Detect(stream, request.Path);
+ var family = ImageFormatInfo.Of(format).Family;
+ var result = family switch
+ {
+ ImageFamily.Jpeg => request.ForcePreview && Preview(stream, request, adequateOnly: true, cancellationToken) is { } p ? p : Jpeg(stream, request),
+ ImageFamily.Png => Png(stream, request),
+ ImageFamily.Tiff => Tiff(stream, request),
+ ImageFamily.Dng or ImageFamily.CameraRaw => Raw(stream, format, request, cancellationToken),
+ ImageFamily.Heif => request.AllowPreview || request.ForcePreview ? Preview(stream, request, adequateOnly: false, cancellationToken) : null,
+ _ => null,
+ };
+ Log.Debug(LogCategory, $"{Path.GetFileName(request.Path)}: {(result is null ? "unavailable" : $"{result.Tier} via {result.Decoder}")}");
+ return result;
+ }
+
+ /// The tier this provider would use for the file at , without decoding pixels.
+ public FileTier Probe(string path)
+ {
+ using var stream = Open(path);
+ var format = ImageSignature.Detect(stream, path);
+ var family = ImageFormatInfo.Of(format).Family;
+ if (family is ImageFamily.Jpeg or ImageFamily.Png or ImageFamily.Tiff)
+ {
+ var (w, h) = MetadataReader.Read(stream, path).OrientedSize;
+ var decoder = family switch { ImageFamily.Jpeg => "managed-jpeg", ImageFamily.Png => "managed-png", _ => "managed-tiff" };
+ return new FileTier(format, DecodeTier.Native, decoder, null, w, h);
+ }
+ if (family is not (ImageFamily.Dng or ImageFamily.CameraRaw or ImageFamily.Heif))
+ return new FileTier(format, DecodeTier.Unavailable, null, $"no managed decoder for {format}", 0, 0);
+ string reason;
+ if (RawDecoder.Formats.Contains(format))
+ {
+ var probe = RawDecoder.Probe(stream, path);
+ if (probe.Info is { } info) return new FileTier(format, DecodeTier.Native, info.Decoder, null, info.Width, info.Height);
+ reason = probe.Reason ?? "unsupported";
+ }
+ else
+ {
+ reason = $"no managed decoder for {format}";
+ }
+ var metadata = MetadataReader.Read(stream, path);
+ if (metadata.LargestPreview is not { } preview) return new FileTier(format, DecodeTier.Unavailable, null, reason + "; no embedded preview", 0, 0);
+ var (pw, ph) = PixelConvert.OrientedSize(preview.Width, preview.Height, metadata.Orientation);
+ return new FileTier(format, DecodeTier.EmbeddedPreview, "managed-preview", reason, pw, ph);
+ }
+
+ private static FileStream Open(string path) =>
+ new(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, FileBufferSize, FileOptions.RandomAccess);
+
+ private static DecodedImage Jpeg(Stream stream, DecodeRequest request)
+ {
+ var data = ReadAll(stream);
+ var info = JpegDecoder.ReadInfo(data);
+ var image = JpegDecoder.DecodeToLinear(data, new JpegDecodeOptions { MaxLongEdge = request.MaxLongEdge }, expandGray: true);
+ var orientation = request.ApplyOrientation ? MetadataReader.Read(stream, request.Path).Orientation : 1;
+ return Finish(image, orientation, request, info.Width, info.Height, DecodeTier.Native, "managed-jpeg");
+ }
+
+ private static DecodedImage Png(Stream stream, DecodeRequest request)
+ {
+ var data = ReadAll(stream);
+ var image = PngDecoder.DecodeToLinear(data, expandGray: true);
+ var orientation = request.ApplyOrientation ? MetadataReader.Read(stream, request.Path).Orientation : 1;
+ return Finish(image, orientation, request, image.Width, image.Height, DecodeTier.Native, "managed-png");
+ }
+
+ private static DecodedImage Tiff(Stream stream, DecodeRequest request)
+ {
+ var decoded = TiffImageReader.Decode(stream);
+ var image = decoded;
+ if (decoded.Channels == 1)
+ {
+ image = PixelConvert.GrayToRgb(decoded);
+ decoded.Dispose();
+ }
+ var orientation = request.ApplyOrientation ? MetadataReader.Read(stream, request.Path).Orientation : 1;
+ return Finish(image, orientation, request, image.Width, image.Height, DecodeTier.Native, "managed-tiff");
+ }
+
+ private static DecodedImage? Raw(Stream stream, ImageFileFormat format, DecodeRequest request, CancellationToken cancellationToken)
+ {
+ if (!request.ForcePreview && RawDecoder.Formats.Contains(format))
+ {
+ try
+ {
+ var options = new RawDecodeOptions
+ {
+ Quality = request.Purpose is DecodePurpose.Thumbnail or DecodePurpose.Analysis ? DemosaicQuality.Draft : DemosaicQuality.Best,
+ MaxLongEdge = request.MaxLongEdge,
+ ApplyOrientation = request.ApplyOrientation,
+ };
+ var raw = RawDecoder.Decode(stream, request.Path, options, cancellationToken);
+ foreach (var warning in raw.Warnings) Log.Debug(LogCategory, $"{Path.GetFileName(request.Path)}: {warning}");
+ return Finish(raw.Image, 1, request, raw.Info.Width, raw.Info.Height, DecodeTier.Native, raw.Info.Decoder, oriented: true);
+ }
+ catch (InvalidDataException ex) when (request.AllowPreview)
+ {
+ Log.Debug(LogCategory, $"{Path.GetFileName(request.Path)}: native decode unavailable ({ex.Message}); trying the embedded preview");
+ }
+ }
+ return request.AllowPreview || request.ForcePreview ? Preview(stream, request, adequateOnly: false, cancellationToken) : null;
+ }
+
+ /// Embedded-preview tier: the smallest preview whose long edge still reaches MaxLongEdge (the largest when none
+ /// does or no limit is set; null then if ), decoded with DCT scaling and oriented like the
+ /// main image.
+ private static DecodedImage? Preview(Stream stream, DecodeRequest request, bool adequateOnly, CancellationToken cancellationToken)
+ {
+ var metadata = MetadataReader.Read(stream, request.Path, cancellationToken: cancellationToken);
+ if (metadata.Previews.Count == 0) return null;
+ EmbeddedPreview? adequate = null;
+ foreach (var p in metadata.Previews)
+ {
+ if (request.MaxLongEdge > 0 && int.Max(p.Width, p.Height) >= request.MaxLongEdge) adequate = p;
+ }
+ if (adequate is null && adequateOnly) return null;
+ var preview = adequate ?? metadata.Previews[0];
+ if (preview.Length > MaxPreviewBytes || preview.Offset < 0 || preview.Offset > stream.Length - preview.Length)
+ throw new InvalidDataException("Preview: embedded JPEG outside the file");
+ var data = new byte[preview.Length];
+ stream.Position = preview.Offset;
+ stream.ReadExactly(data);
+ var image = JpegDecoder.DecodeToLinear(data, new JpegDecodeOptions { MaxLongEdge = request.MaxLongEdge }, expandGray: true);
+ var orientation = request.ApplyOrientation ? metadata.Orientation : 1;
+ return Finish(image, orientation, request, preview.Width, preview.Height, DecodeTier.EmbeddedPreview, "managed-preview");
+ }
+
+ /// Applies orientation, fits within MaxLongEdge, and wraps the result (takes ownership of ).
+ private static DecodedImage Finish(ImageBuffer image, int orientation, DecodeRequest request, int sourceWidth, int sourceHeight, DecodeTier tier, string decoder, bool oriented = false)
+ {
+ var current = image;
+ try
+ {
+ if (orientation is >= 2 and <= 8)
+ {
+ var rotated = PixelConvert.ApplyOrientation(current, orientation);
+ current.Dispose();
+ current = rotated;
+ }
+ if (!oriented) (sourceWidth, sourceHeight) = PixelConvert.OrientedSize(sourceWidth, sourceHeight, orientation);
+ if (request.MaxLongEdge > 0)
+ {
+ var (w, h) = Resampler.FitWithin(current.Width, current.Height, request.MaxLongEdge);
+ if (w != current.Width || h != current.Height)
+ {
+ var filter = request.Purpose == DecodePurpose.Thumbnail ? ResampleFilter.Box : ResampleFilter.Auto;
+ var resized = Resampler.Resize(current, w, h, filter);
+ current.Dispose();
+ current = resized;
+ }
+ }
+ return new DecodedImage(current, tier, decoder, sourceWidth, sourceHeight);
+ }
+ catch
+ {
+ current.Dispose();
+ throw;
+ }
+ }
+
+ private static byte[] ReadAll(Stream stream)
+ {
+ if (stream.Length > int.MaxValue) throw new InvalidDataException("Image file too large");
+ var data = new byte[stream.Length];
+ stream.Position = 0;
+ stream.ReadExactly(data);
+ return data;
+ }
+}
diff --git a/src/Titano.Core/Imaging/FrameWindow.cs b/src/Titano.Core/Imaging/FrameWindow.cs
new file mode 100644
index 00000000..157d81d5
--- /dev/null
+++ b/src/Titano.Core/Imaging/FrameWindow.cs
@@ -0,0 +1,487 @@
+using System.Runtime.InteropServices;
+using Microsoft.Win32.SafeHandles;
+
+namespace Titano.Core.Imaging;
+
+/// Options for .
+public sealed record FrameWindowOptions
+{
+ /// Frames before the render position that stay available (temporal filters look back).
+ public int Behind { get; init; } = 2;
+
+ /// Frames after the render position decoded in the background.
+ public int Ahead { get; init; } = 4;
+
+ /// Upper bound on the bytes of decoded frames held in memory, in-flight decodes included.
+ public long MemoryBudget { get; init; } = 1L << 30;
+
+ /// Directory of the spill file (null: the system temporary directory).
+ public string? SpillDirectory { get; init; }
+
+ /// Background decodes running at once.
+ public int MaxConcurrentLoads { get; init; } = 2;
+}
+
+/// Counters of a , for diagnostics and the memory self-tests.
+public readonly record struct FrameWindowStatistics(long LiveBytes, long PeakLiveBytes, int Loads, int SpillWrites, int SpillReads, long SpillFileBytes);
+
+/// A frame kept resident while the lease is held. The image must not be modified (it may be shared with a spill copy).
+public sealed class FrameLease : IDisposable
+{
+ private FrameWindow? _window;
+
+ internal FrameLease(FrameWindow window, int index, ImageBuffer image)
+ {
+ _window = window;
+ Index = index;
+ Image = image;
+ }
+
+ public int Index { get; }
+ public ImageBuffer Image { get; }
+
+ public void Dispose() => Interlocked.Exchange(ref _window, null)?.Release(Index);
+}
+
+///
+/// Sliding window of decoded frames around the render position (BRIEF §8.4). Frames from position − Behind to
+/// position + Ahead are kept; those ahead are decoded on background tasks as the memory budget allows. When a
+/// demanded frame needs room, unleased frames outside the window are dropped first, then in-window frames farthest from
+/// the position are evicted to a spill file and read back on demand (cheaper than decoding a RAW again). Live memory
+/// therefore stays within (exceeded only by frames the caller holds
+/// leases on), and the spill file within the window's size: both are independent of the sequence length.
+/// The spill file stores raw float32 planes: renders stay bit-identical whether or not a frame was spilled (a
+/// float16 spill would halve disk traffic but make output depend on memory pressure). It is deleted on disposal,
+/// including after cancellation, and opened delete-on-close as a backstop.
+///
+public sealed class FrameWindow : IDisposable, IAsyncDisposable
+{
+ private readonly Func> _loader;
+ private readonly FrameWindowOptions _options;
+ private readonly Lock _gate = new();
+ private readonly SemaphoreSlim _demand = new(1, 1);
+ private readonly CancellationTokenSource _cts = new();
+ private readonly Dictionary _slots = [];
+ private SpillFile? _spill;
+ private long _liveBytes, _peakLiveBytes, _estimate;
+ private int _position, _backgroundLoads, _loads, _spillWrites, _spillReads;
+ private bool _disposed;
+
+ /// Frames in the sequence.
+ /// Decodes frame i; called on background threads, at most once per residency.
+ public FrameWindow(int frameCount, Func> loader, FrameWindowOptions? options = null)
+ {
+ ArgumentOutOfRangeException.ThrowIfNegative(frameCount);
+ ArgumentNullException.ThrowIfNull(loader);
+ _options = options ?? new FrameWindowOptions();
+ ArgumentOutOfRangeException.ThrowIfNegative(_options.Behind);
+ ArgumentOutOfRangeException.ThrowIfNegative(_options.Ahead);
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(_options.MemoryBudget);
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(_options.MaxConcurrentLoads);
+ Count = frameCount;
+ _loader = loader;
+ }
+
+ public int Count { get; }
+
+ public int Position
+ {
+ get
+ {
+ lock (_gate) return _position;
+ }
+ }
+
+ /// Path of the spill file once created (it is removed on disposal).
+ public string? SpillPath
+ {
+ get
+ {
+ lock (_gate) return _spill?.Path;
+ }
+ }
+
+ public FrameWindowStatistics Statistics
+ {
+ get
+ {
+ lock (_gate) return new FrameWindowStatistics(_liveBytes, _peakLiveBytes, _loads, _spillWrites, _spillReads, _spill?.Length ?? 0);
+ }
+ }
+
+ /// Moves the render position: frames that left the window are released and read-ahead starts.
+ public void MoveTo(int position)
+ {
+ ArgumentOutOfRangeException.ThrowIfNegative(position);
+ lock (_gate)
+ {
+ ObjectDisposedException.ThrowIf(_disposed, this);
+ _position = position;
+ foreach (var slot in _slots.Values.ToList())
+ {
+ if (!InWindow(slot.Index) && slot.Leases == 0 && slot.Loading is null && !slot.Spilling) Drop(slot);
+ }
+ ScheduleReadAhead();
+ }
+ }
+
+ /// Returns frame , decoding it (or reading it back from the spill file) when needed.
+ /// Does not move the window.
+ /// Cancelled, or the window was disposed.
+ public async ValueTask GetAsync(int index, CancellationToken cancellationToken = default)
+ {
+ ArgumentOutOfRangeException.ThrowIfNegative(index);
+ ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual(index, Count);
+ using var linked = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, _cts.Token);
+ var token = linked.Token;
+ while (true)
+ {
+ token.ThrowIfCancellationRequested();
+ Task? pending;
+ lock (_gate)
+ {
+ ObjectDisposedException.ThrowIf(_disposed, this);
+ if (_slots.TryGetValue(index, out var slot) && slot.Image is { } image)
+ {
+ slot.Leases++;
+ return new FrameLease(this, index, image);
+ }
+ pending = slot?.Loading;
+ }
+ if (pending is not null)
+ {
+ if (await pending.WaitAsync(token).ConfigureAwait(false) is { } error) throw error is OperationCanceledException ? new OperationCanceledException(error.Message, error, token) : error;
+ continue;
+ }
+ await _demand.WaitAsync(token).ConfigureAwait(false);
+ try
+ {
+ await LoadWithinBudgetAsync(index, token).ConfigureAwait(false);
+ }
+ finally
+ {
+ _demand.Release();
+ }
+ }
+ }
+
+ public void Dispose() => DisposeAsync().AsTask().GetAwaiter().GetResult();
+
+ /// Cancels background decodes, waits for them and for an eviction in progress, releases every frame and
+ /// deletes the spill file. The semaphore and token source are left undisposed on purpose: callers racing the disposal
+ /// may still release or observe them, and neither holds an unmanaged resource here.
+ public async ValueTask DisposeAsync()
+ {
+ lock (_gate)
+ {
+ if (_disposed) return;
+ _disposed = true;
+ }
+ _cts.Cancel();
+ await _demand.WaitAsync().ConfigureAwait(false);
+ Task[] pending;
+ lock (_gate) pending = [.. _slots.Values.Select(s => s.Loading).OfType()];
+ await Task.WhenAll(pending).ConfigureAwait(false);
+ lock (_gate)
+ {
+ foreach (var slot in _slots.Values)
+ {
+ slot.Image?.Dispose();
+ slot.Image = null;
+ }
+ _slots.Clear();
+ _liveBytes = 0;
+ _spill?.Dispose();
+ }
+ }
+
+ internal void Release(int index)
+ {
+ lock (_gate)
+ {
+ if (_disposed || !_slots.TryGetValue(index, out var slot)) return;
+ slot.Leases--;
+ if (slot.Leases == 0 && !InWindow(index) && slot.Loading is null && !slot.Spilling) Drop(slot);
+ }
+ }
+
+ private bool InWindow(int index) => index >= _position - _options.Behind && index <= _position + _options.Ahead;
+
+ /// Starts the decode (or spill read) of once its size fits the budget: unleased frames
+ /// outside the window are dropped first, then in-window frames farthest from the position are spilled. The check and
+ /// the start happen under one lock so background read-ahead cannot take the room in between. The budget is exceeded
+ /// only when every resident frame is leased. Callers hold the demand semaphore (one eviction at a time).
+ private async Task LoadWithinBudgetAsync(int index, CancellationToken cancellationToken)
+ {
+ while (true)
+ {
+ Slot victim;
+ ImageBuffer image;
+ lock (_gate)
+ {
+ ObjectDisposedException.ThrowIf(_disposed, this);
+ if (!_slots.TryGetValue(index, out var slot))
+ {
+ slot = new Slot(index);
+ _slots[index] = slot;
+ }
+ if (slot.Image is not null || slot.Loading is not null) return;
+ var required = slot.Spill?.Bytes ?? _estimate;
+ Slot? best = null;
+ if (_liveBytes + required > _options.MemoryBudget)
+ {
+ foreach (var s in _slots.Values)
+ {
+ if (s.Index == index || s.Image is null || s.Leases > 0 || s.Spilling) continue;
+ if (best is null || Priority(s) > Priority(best)) best = s;
+ }
+ }
+ if (best is null)
+ {
+ StartLoad(slot, background: false);
+ return;
+ }
+ if (!InWindow(best.Index))
+ {
+ Drop(best);
+ continue;
+ }
+ if (best.Spill is not null)
+ {
+ Unload(best);
+ continue;
+ }
+ best.Spilling = true;
+ _spill ??= new SpillFile(_options.SpillDirectory);
+ (victim, image) = (best, best.Image!);
+ }
+ SpillExtent extent;
+ try
+ {
+ extent = await Task.Run(() => _spill!.Write(image), cancellationToken).ConfigureAwait(false);
+ }
+ catch
+ {
+ lock (_gate) victim.Spilling = false;
+ throw;
+ }
+ lock (_gate)
+ {
+ victim.Spilling = false;
+ victim.Spill = extent;
+ _spillWrites++;
+ if (victim.Leases == 0) Unload(victim);
+ }
+ }
+ }
+
+ /// Eviction order: outside the window first, then the farthest from the position (behind before ahead).
+ private double Priority(Slot s)
+ {
+ var distance = s.Index < _position ? (_position - s.Index) * 1.5 : s.Index - _position;
+ return InWindow(s.Index) ? distance : 1e9 + distance;
+ }
+
+ /// Starts a decode (or spill read) for the slot, reserving the estimated size. Caller holds the gate.
+ private void StartLoad(Slot slot, bool background)
+ {
+ var reserved = slot.Spill?.Bytes ?? _estimate;
+ slot.Reserved = reserved;
+ _liveBytes += reserved;
+ _peakLiveBytes = long.Max(_peakLiveBytes, _liveBytes);
+ if (background) _backgroundLoads++;
+ var spill = slot.Spill;
+ var token = _cts.Token;
+ slot.Loading = Task.Run(async () =>
+ {
+ ImageBuffer? image = null;
+ try
+ {
+ if (spill is not null) image = _spill!.Read(spill);
+ else image = await _loader(slot.Index, token).ConfigureAwait(false);
+ lock (_gate)
+ {
+ slot.Loading = null;
+ if (background) _backgroundLoads--;
+ _liveBytes -= slot.Reserved;
+ slot.Reserved = 0;
+ if (_disposed)
+ {
+ image.Dispose();
+ return new OperationCanceledException("The frame window was disposed.");
+ }
+ slot.Image = image;
+ _liveBytes += image.ByteSize;
+ _peakLiveBytes = long.Max(_peakLiveBytes, _liveBytes);
+ if (spill is null)
+ {
+ _loads++;
+ _estimate = image.ByteSize;
+ }
+ else
+ {
+ _spillReads++;
+ }
+ ScheduleReadAhead();
+ }
+ return null;
+ }
+ catch (Exception ex)
+ {
+ image?.Dispose();
+ lock (_gate)
+ {
+ if (slot.Loading is not null)
+ {
+ slot.Loading = null;
+ if (background) _backgroundLoads--;
+ _liveBytes -= slot.Reserved;
+ slot.Reserved = 0;
+ }
+ if (slot.Image is null && slot.Spill is null && slot.Leases == 0) _slots.Remove(slot.Index);
+ }
+ return (Exception?)ex;
+ }
+ }, CancellationToken.None);
+ }
+
+ /// Starts background decodes of missing frames ahead while the budget allows. Caller holds the gate.
+ private void ScheduleReadAhead()
+ {
+ if (_disposed) return;
+ var last = int.Min(Count - 1, _position + _options.Ahead);
+ for (var i = _position; i <= last && _backgroundLoads < _options.MaxConcurrentLoads; i++)
+ {
+ if (_slots.TryGetValue(i, out var existing) && (existing.Image is not null || existing.Loading is not null || existing.Spill is not null)) continue;
+ // The first frame's size is unknown: allow one decode to learn it.
+ if (_estimate == 0 ? _loads + _backgroundLoads > 0 : _liveBytes + _estimate > _options.MemoryBudget) return;
+ if (existing is null)
+ {
+ existing = new Slot(i);
+ _slots[i] = existing;
+ }
+ StartLoad(existing, background: true);
+ }
+ }
+
+ /// Releases the frame's memory (its spill copy, if any, stays). Caller holds the gate.
+ private void Unload(Slot slot)
+ {
+ if (slot.Image is null) return;
+ _liveBytes -= slot.Image.ByteSize;
+ slot.Image.Dispose();
+ slot.Image = null;
+ }
+
+ /// Forgets the frame entirely (memory and spill extent). Caller holds the gate.
+ private void Drop(Slot slot)
+ {
+ Unload(slot);
+ if (slot.Spill is { } extent) _spill?.Free(extent);
+ slot.Spill = null;
+ _slots.Remove(slot.Index);
+ }
+
+ private sealed class Slot(int index)
+ {
+ public int Index { get; } = index;
+ public ImageBuffer? Image { get; set; }
+ public Task? Loading { get; set; }
+ public SpillExtent? Spill { get; set; }
+ public bool Spilling { get; set; }
+ public int Leases { get; set; }
+ public long Reserved { get; set; }
+ }
+
+ private sealed record SpillExtent(long Offset, int Width, int Height, int Channels)
+ {
+ public long Bytes => (long)Width * Height * Channels * sizeof(float);
+ }
+
+ /// Temporary file of float32 planes; freed extents are reused by frames of the same size.
+ private sealed class SpillFile : IDisposable
+ {
+ private readonly SafeFileHandle _handle;
+ private readonly List _free = [];
+ private readonly Lock _gate = new();
+
+ public SpillFile(string? directory)
+ {
+ var dir = directory ?? System.IO.Path.GetTempPath();
+ Directory.CreateDirectory(dir);
+ Path = System.IO.Path.Combine(dir, $"titano-spill-{Guid.NewGuid():N}.tmp");
+ _handle = File.OpenHandle(Path, FileMode.CreateNew, FileAccess.ReadWrite, FileShare.None, FileOptions.DeleteOnClose | FileOptions.RandomAccess);
+ }
+
+ public string Path { get; }
+ public long Length { get; private set; }
+
+ public SpillExtent Write(ImageBuffer image)
+ {
+ SpillExtent extent;
+ lock (_gate)
+ {
+ var reuse = _free.FindIndex(e => e.Width == image.Width && e.Height == image.Height && e.Channels == image.Channels);
+ if (reuse >= 0)
+ {
+ extent = _free[reuse];
+ _free.RemoveAt(reuse);
+ }
+ else
+ {
+ extent = new SpillExtent(Length, image.Width, image.Height, image.Channels);
+ Length += extent.Bytes;
+ }
+ }
+ var planeBytes = (long)image.PlaneLength * sizeof(float);
+ for (var c = 0; c < image.Channels; c++) RandomAccess.Write(_handle, MemoryMarshal.AsBytes((ReadOnlySpan)image.Plane(c)), extent.Offset + c * planeBytes);
+ return extent;
+ }
+
+ public ImageBuffer Read(SpillExtent extent)
+ {
+ var image = new ImageBuffer(extent.Width, extent.Height, extent.Channels, clear: false);
+ try
+ {
+ var planeBytes = (long)image.PlaneLength * sizeof(float);
+ for (var c = 0; c < image.Channels; c++)
+ {
+ var bytes = MemoryMarshal.AsBytes(image.Plane(c));
+ var done = 0;
+ while (done < bytes.Length)
+ {
+ var n = RandomAccess.Read(_handle, bytes[done..], extent.Offset + c * planeBytes + done);
+ if (n == 0) throw new IOException("Spill file truncated");
+ done += n;
+ }
+ }
+ return image;
+ }
+ catch
+ {
+ image.Dispose();
+ throw;
+ }
+ }
+
+ public void Free(SpillExtent extent)
+ {
+ lock (_gate) _free.Add(extent);
+ }
+
+ public void Dispose()
+ {
+ _handle.Dispose();
+ try
+ {
+ if (File.Exists(Path)) File.Delete(Path);
+ }
+ catch (IOException)
+ {
+ }
+ catch (UnauthorizedAccessException)
+ {
+ }
+ }
+ }
+}
diff --git a/src/Titano.Core/Imaging/Thumbnails/ProxyBuilder.cs b/src/Titano.Core/Imaging/Thumbnails/ProxyBuilder.cs
new file mode 100644
index 00000000..3c9e403e
--- /dev/null
+++ b/src/Titano.Core/Imaging/Thumbnails/ProxyBuilder.cs
@@ -0,0 +1,64 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.IO;
+using Titano.Core.Metadata;
+
+namespace Titano.Core.Imaging.Thumbnails;
+
+/// Proxy long-edge policy (BRIEF §8.5).
+public enum ProxySize
+{
+ /// Source resolution.
+ Full = 0,
+ Edge1280 = 1280,
+ Edge1920 = 1920,
+ Edge2560 = 2560,
+}
+
+/// A built proxy and how its pixels were obtained.
+/// JPEG file bytes with an Exif block.
+/// Proxy width (oriented).
+/// Proxy height (oriented).
+/// Decode tier of the source (an embedded preview caps the proxy at the preview's size).
+public sealed record ProxyResult(byte[] Jpeg, int Width, int Height, DecodeTier Tier);
+
+///
+/// Builds proxies (BRIEF §8.5): the source decoded at the policy long edge (1280/1920/2560 or full) with its orientation
+/// applied, encoded as JPEG q92, carrying an Exif block written by from the
+/// source metadata (capture time, camera, exposure, GPS) with orientation reset to 1 because the pixels are upright.
+///
+public static class ProxyBuilder
+{
+ public const int Quality = 92;
+
+ /// Default policy.
+ public const ProxySize DefaultSize = ProxySize.Edge1920;
+
+ /// Decodes and encodes the proxy of ; null when no tier can decode it.
+ /// Source metadata; read from the file when null.
+ public static ProxyResult? Build(ImageDecoder decoder, string sourcePath, ProxySize size = DefaultSize, FrameMetadata? metadata = null, CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(decoder);
+ using var decoded = decoder.Decode(new DecodeRequest(sourcePath, (int)size, DecodePurpose.Proxy), cancellationToken);
+ if (decoded is null) return null;
+ metadata ??= MetadataReader.Read(sourcePath, cancellationToken);
+ return new ProxyResult(Encode(decoded.Pixels, metadata), decoded.Pixels.Width, decoded.Pixels.Height, decoded.Tier);
+ }
+
+ /// Builds the proxy and writes it crash-safely to .
+ public static ProxyResult? Write(ImageDecoder decoder, string sourcePath, string proxyPath, ProxySize size = DefaultSize, FrameMetadata? metadata = null, CancellationToken cancellationToken = default)
+ {
+ var result = Build(decoder, sourcePath, size, metadata, cancellationToken);
+ if (result is not null) AtomicFile.WriteAllBytes(proxyPath, result.Jpeg);
+ return result;
+ }
+
+ /// Encodes upright linear-light pixels as a proxy JPEG with the source's Exif (orientation 1).
+ public static byte[] Encode(ImageBuffer image, FrameMetadata metadata)
+ {
+ ArgumentNullException.ThrowIfNull(image);
+ ArgumentNullException.ThrowIfNull(metadata);
+ var segment = ExifWriter.BuildJpegApp1(metadata with { Orientation = 1, Width = image.Width, Height = image.Height });
+ // The encoder takes APP1 payloads: drop the marker and length that BuildJpegApp1 puts in front.
+ return JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = Quality, App1Segments = [segment[4..]], OptimizeHuffman = true });
+ }
+}
diff --git a/src/Titano.Core/Imaging/Thumbnails/ThumbnailCache.cs b/src/Titano.Core/Imaging/Thumbnails/ThumbnailCache.cs
new file mode 100644
index 00000000..863a4bba
--- /dev/null
+++ b/src/Titano.Core/Imaging/Thumbnails/ThumbnailCache.cs
@@ -0,0 +1,156 @@
+using Titano.Core.Codecs.Jpeg;
+
+namespace Titano.Core.Imaging.Thumbnails;
+
+/// A decoded thumbnail ready for display: interleaved 8-bit sRGB RGB.
+public sealed class Thumbnail(int width, int height, byte[] rgb)
+{
+ public int Width { get; } = width;
+ public int Height { get; } = height;
+
+ /// Width × height × 3 bytes, sRGB-encoded, top-down.
+ public byte[] Rgb { get; } = rgb;
+
+ /// Memory charged against a budget.
+ public long ByteSize => Rgb.Length + 64;
+
+ /// Decodes a thumbnail JPEG (gray is expanded to RGB).
+ /// The JPEG is malformed.
+ public static Thumbnail FromJpeg(ReadOnlySpan jpeg)
+ {
+ var image = JpegDecoder.Decode(jpeg);
+ var pixels = image.Pixels8 ?? throw new InvalidDataException("Thumbnail: not an 8-bit JPEG");
+ if (image.Components == 3) return new Thumbnail(image.Width, image.Height, pixels);
+ var rgb = new byte[pixels.Length * 3];
+ for (var i = 0; i < pixels.Length; i++) rgb[3 * i] = rgb[3 * i + 1] = rgb[3 * i + 2] = pixels[i];
+ return new Thumbnail(image.Width, image.Height, rgb);
+ }
+}
+
+///
+/// In-memory LRU of decoded thumbnails under a byte budget (BRIEF §8.5). Thread-safe; concurrent requests for the same
+/// key share one load (), so a scrolling UI never decodes a thumbnail twice.
+///
+public sealed class ThumbnailCache where TKey : notnull
+{
+ private readonly Lock _gate = new();
+ private readonly Dictionary> _map = [];
+ private readonly LinkedList<(TKey Key, Thumbnail Value)> _lru = new();
+ private readonly Dictionary> _loading = [];
+ private long _bytes;
+
+ /// Upper bound on the bytes held (a thumbnail larger than the budget is never cached).
+ public ThumbnailCache(long byteBudget)
+ {
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(byteBudget);
+ Budget = byteBudget;
+ }
+
+ public long Budget { get; }
+
+ public long Bytes
+ {
+ get
+ {
+ lock (_gate) return _bytes;
+ }
+ }
+
+ public int Count
+ {
+ get
+ {
+ lock (_gate) return _map.Count;
+ }
+ }
+
+ /// Returns a cached thumbnail and marks it most recently used.
+ public bool TryGet(TKey key, out Thumbnail thumbnail)
+ {
+ lock (_gate)
+ {
+ if (_map.TryGetValue(key, out var node))
+ {
+ _lru.Remove(node);
+ _lru.AddFirst(node);
+ thumbnail = node.Value.Value;
+ return true;
+ }
+ }
+ thumbnail = null!;
+ return false;
+ }
+
+ /// Adds or replaces a thumbnail, evicting least recently used ones to stay within the budget.
+ public void Set(TKey key, Thumbnail thumbnail)
+ {
+ ArgumentNullException.ThrowIfNull(thumbnail);
+ lock (_gate)
+ {
+ RemoveLocked(key);
+ if (thumbnail.ByteSize > Budget) return;
+ _map[key] = _lru.AddFirst((key, thumbnail));
+ _bytes += thumbnail.ByteSize;
+ while (_bytes > Budget && _lru.Last is { } last)
+ {
+ RemoveLocked(last.Value.Key);
+ }
+ }
+ }
+
+ public bool Remove(TKey key)
+ {
+ lock (_gate) return RemoveLocked(key);
+ }
+
+ public void Clear()
+ {
+ lock (_gate)
+ {
+ _map.Clear();
+ _lru.Clear();
+ _bytes = 0;
+ }
+ }
+
+ /// Cached thumbnail, or the result of (cached when not null). Concurrent calls for
+ /// the same key await the same load; each caller's only cancels its own wait.
+ public async Task GetOrLoadAsync(TKey key, Func> loader, CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(loader);
+ if (TryGet(key, out var hit)) return hit;
+ Task task;
+ lock (_gate)
+ {
+ if (!_loading.TryGetValue(key, out task!))
+ {
+ task = LoadAsync(key, loader);
+ _loading[key] = task;
+ }
+ }
+ return await task.WaitAsync(cancellationToken).ConfigureAwait(false);
+ }
+
+ private async Task LoadAsync(TKey key, Func> loader)
+ {
+ try
+ {
+ await Task.Yield();
+ var value = await loader(key, CancellationToken.None).ConfigureAwait(false);
+ if (value is not null) Set(key, value);
+ return value;
+ }
+ finally
+ {
+ lock (_gate) _loading.Remove(key);
+ }
+ }
+
+ private bool RemoveLocked(TKey key)
+ {
+ if (!_map.Remove(key, out var node)) return false;
+ _lru.Remove(node);
+ _bytes -= node.Value.Value.ByteSize;
+ return true;
+ }
+}
diff --git a/src/Titano.Core/Imaging/Thumbnails/ThumbnailPack.cs b/src/Titano.Core/Imaging/Thumbnails/ThumbnailPack.cs
new file mode 100644
index 00000000..3d6e104d
--- /dev/null
+++ b/src/Titano.Core/Imaging/Thumbnails/ThumbnailPack.cs
@@ -0,0 +1,497 @@
+using System.Buffers.Binary;
+using System.Collections.Concurrent;
+using Microsoft.Win32.SafeHandles;
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Hashing;
+using Titano.Core.IO;
+
+namespace Titano.Core.Imaging.Thumbnails;
+
+/// Index entry of one thumbnail in a .
+/// Frame the thumbnail belongs to.
+/// File offset of the entry record.
+/// JPEG length in bytes.
+/// Thumbnail width in pixels.
+/// Thumbnail height in pixels.
+/// CRC-32 of the JPEG bytes.
+public readonly record struct ThumbnailEntry(Guid FrameId, long Offset, int Length, int Width, int Height, uint Crc);
+
+///
+/// The per-sequence thumbnail file thumbs.pack (BRIEF §8.5): 320-pixel JPEG (q80) thumbnails appended to one file.
+/// Layout (little-endian): two 64-byte header slots at 0 and 64 (magic "TTPK", version, generation, offset/length/
+/// count of the current index record, the file length it covers, CRC-32); from 128, self-describing records — entries
+/// ("TENT": frame id, size, JPEG length and CRC, then the JPEG) and index tables ("TIDX": count, then frame id → offset,
+/// length, size, CRC per entry, then the record's CRC).
+/// Writes only append. Every appends (and on /)
+/// a new index record is appended and flushed, then the header slot not holding the newest generation is overwritten and
+/// flushed: a crash leaves the previous slot valid. Opening takes the newest valid slot, then recovers entries appended
+/// after its index by scanning forward until the first damaged record, so truncated or partially written files lose
+/// only their damaged tail. rewrites live entries into a fresh file committed with
+/// . Reads use positional I/O and run concurrently with one writer.
+///
+public sealed class ThumbnailPack : IDisposable
+{
+ public const int LongEdge = 320;
+ public const int Quality = 80;
+ public const int IndexInterval = 64;
+
+ private const uint HeaderMagic = 0x4B505454; // "TTPK"
+ private const uint EntryMagic = 0x544E4554; // "TENT"
+ private const uint IndexMagic = 0x58444954; // "TIDX"
+ private const ushort Version = 1;
+ private const int SlotSize = 64;
+ private const int DataStart = 2 * SlotSize;
+ private const int EntryHeaderSize = 32;
+ private const int IndexEntrySize = 36;
+ private const int MaxJpegBytes = 16 << 20;
+
+ private readonly ReaderWriterLockSlim _handleLock = new(LockRecursionPolicy.NoRecursion);
+ private readonly Lock _writeLock = new();
+ private readonly List _warnings = [];
+ private ConcurrentDictionary _index = new();
+ private SafeFileHandle _handle;
+ private long _tail;
+ private ulong _generation;
+ private int _activeSlot;
+ private int _unindexed;
+ private long _liveBytes;
+ private bool _disposed;
+
+ private ThumbnailPack(string path, bool writable, SafeFileHandle handle)
+ {
+ Path = path;
+ Writable = writable;
+ _handle = handle;
+ Load();
+ }
+
+ public string Path { get; }
+ public bool Writable { get; }
+
+ /// Problems met while opening or refreshing (damaged slots, records dropped from the tail).
+ public IReadOnlyList Warnings
+ {
+ get
+ {
+ lock (_warnings) return [.. _warnings];
+ }
+ }
+
+ public int Count => Volatile.Read(ref _index).Count;
+
+ /// Snapshot of the frames with a thumbnail.
+ public IReadOnlyCollection FrameIds => [.. Volatile.Read(ref _index).Keys];
+
+ /// Bytes held by superseded or removed entries (reclaimed by ).
+ public long WastedBytes => long.Max(0, _tail - DataStart - Volatile.Read(ref _liveBytes));
+
+ /// Opens (creating when writable and missing) a pack.
+ public static ThumbnailPack Open(string path, bool writable = true)
+ {
+ ArgumentException.ThrowIfNullOrEmpty(path);
+ if (writable && !File.Exists(path)) AtomicFile.WriteAllBytes(path, EmptyFile());
+ var handle = File.OpenHandle(path, FileMode.Open, writable ? FileAccess.ReadWrite : FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, FileOptions.RandomAccess);
+ return new ThumbnailPack(path, writable, handle);
+ }
+
+ /// Downscales a linear-light image to the thumbnail long edge and encodes it (JPEG q80).
+ public static (byte[] Jpeg, int Width, int Height) Encode(ImageBuffer image)
+ {
+ ArgumentNullException.ThrowIfNull(image);
+ using var small = Resampler.Thumbnail(image, LongEdge);
+ return (JpegEncoder.Encode(small, new JpegEncodeOptions { Quality = Quality }), small.Width, small.Height);
+ }
+
+ public bool TryGetEntry(Guid frameId, out ThumbnailEntry entry) => Volatile.Read(ref _index).TryGetValue(frameId, out entry);
+
+ /// The JPEG bytes of a frame's thumbnail; null when absent or damaged (CRC mismatch).
+ public byte[]? ReadJpeg(Guid frameId)
+ {
+ if (!TryGetEntry(frameId, out var e)) return null;
+ var data = new byte[e.Length];
+ _handleLock.EnterReadLock();
+ try
+ {
+ ObjectDisposedException.ThrowIf(_disposed, this);
+ if (RandomAccess.Read(_handle, data, e.Offset + EntryHeaderSize) != data.Length) return null;
+ }
+ finally
+ {
+ _handleLock.ExitReadLock();
+ }
+ return Crc32.Compute(data) == e.Crc ? data : null;
+ }
+
+ /// Encodes and appends the thumbnail of , replacing any previous one for the frame.
+ public ThumbnailEntry Add(Guid frameId, ImageBuffer image)
+ {
+ var (jpeg, w, h) = Encode(image);
+ return AddJpeg(frameId, jpeg, w, h);
+ }
+
+ /// Appends an encoded thumbnail, replacing any previous one for the frame.
+ public ThumbnailEntry AddJpeg(Guid frameId, ReadOnlySpan jpeg, int width, int height)
+ {
+ if (!Writable) throw new InvalidOperationException("The pack is open read-only.");
+ if (jpeg.Length is 0 or > MaxJpegBytes) throw new ArgumentOutOfRangeException(nameof(jpeg));
+ if (width is < 1 or > ushort.MaxValue || height is < 1 or > ushort.MaxValue) throw new ArgumentOutOfRangeException(nameof(width));
+ lock (_writeLock)
+ {
+ var record = new byte[EntryHeaderSize + jpeg.Length];
+ BinaryPrimitives.WriteUInt32LittleEndian(record, EntryMagic);
+ frameId.TryWriteBytes(record.AsSpan(4));
+ BinaryPrimitives.WriteUInt16LittleEndian(record.AsSpan(20), (ushort)width);
+ BinaryPrimitives.WriteUInt16LittleEndian(record.AsSpan(22), (ushort)height);
+ BinaryPrimitives.WriteInt32LittleEndian(record.AsSpan(24), jpeg.Length);
+ var crc = Crc32.Compute(jpeg);
+ BinaryPrimitives.WriteUInt32LittleEndian(record.AsSpan(28), crc);
+ jpeg.CopyTo(record.AsSpan(EntryHeaderSize));
+ var entry = new ThumbnailEntry(frameId, _tail, jpeg.Length, width, height, crc);
+ WriteAt(record, _tail);
+ _tail += record.Length;
+ if (_index.TryGetValue(frameId, out var old)) Interlocked.Add(ref _liveBytes, -(EntryHeaderSize + old.Length));
+ _index[frameId] = entry;
+ Interlocked.Add(ref _liveBytes, record.Length);
+ if (++_unindexed >= IndexInterval) WriteIndex();
+ return entry;
+ }
+ }
+
+ /// Drops a frame's thumbnail from the index (its bytes stay until ).
+ public bool Remove(Guid frameId)
+ {
+ if (!Writable) throw new InvalidOperationException("The pack is open read-only.");
+ lock (_writeLock)
+ {
+ if (!_index.TryRemove(frameId, out var old)) return false;
+ Interlocked.Add(ref _liveBytes, -(EntryHeaderSize + old.Length));
+ _unindexed++;
+ return true;
+ }
+ }
+
+ /// Writes the index now (appended record, then the alternate header slot).
+ public void Flush()
+ {
+ if (!Writable) return;
+ lock (_writeLock)
+ {
+ if (_unindexed > 0) WriteIndex();
+ }
+ }
+
+ /// Rewrites the live entries into a new file and atomically replaces this one.
+ public void Compact()
+ {
+ if (!Writable) throw new InvalidOperationException("The pack is open read-only.");
+ lock (_writeLock)
+ {
+ var temp = AtomicFile.TempPathFor(Path);
+ var entries = Volatile.Read(ref _index).Values.OrderBy(e => e.Offset).ToList();
+ var moved = new ConcurrentDictionary();
+ using (var output = new FileStream(temp, FileMode.CreateNew, FileAccess.Write, FileShare.None, 1 << 16))
+ {
+ output.Write(new byte[DataStart]);
+ var buffer = new byte[EntryHeaderSize + MaxJpegBytes / 16];
+ foreach (var e in entries)
+ {
+ var size = EntryHeaderSize + e.Length;
+ if (buffer.Length < size) buffer = new byte[size];
+ _handleLock.EnterReadLock();
+ int read;
+ try
+ {
+ read = RandomAccess.Read(_handle, buffer.AsSpan(0, size), e.Offset);
+ }
+ finally
+ {
+ _handleLock.ExitReadLock();
+ }
+ if (read != size || Crc32.Compute(buffer.AsSpan(EntryHeaderSize, e.Length)) != e.Crc)
+ {
+ Warn($"Thumbnail of {e.FrameId} damaged; dropped during compaction");
+ continue;
+ }
+ moved[e.FrameId] = e with { Offset = output.Position };
+ output.Write(buffer, 0, size);
+ }
+ var indexOffset = output.Position;
+ var index = IndexRecord(moved.Values);
+ output.Write(index);
+ output.Position = 0;
+ output.Write(HeaderSlot(_generation + 1, indexOffset, index.Length, moved.Count, indexOffset + index.Length));
+ }
+ _handleLock.EnterWriteLock();
+ try
+ {
+ _handle.Dispose();
+ AtomicFile.Commit(temp, Path);
+ _handle = File.OpenHandle(Path, FileMode.Open, FileAccess.ReadWrite, FileShare.ReadWrite | FileShare.Delete, FileOptions.RandomAccess);
+ _index = moved;
+ _generation++;
+ _activeSlot = 0;
+ _tail = RandomAccess.GetLength(_handle);
+ _liveBytes = moved.Values.Sum(e => (long)EntryHeaderSize + e.Length);
+ _unindexed = 0;
+ }
+ finally
+ {
+ _handleLock.ExitWriteLock();
+ }
+ }
+ }
+
+ /// Re-reads the file (read-only instances use it to see entries written by another instance).
+ public void Refresh()
+ {
+ if (Writable) return;
+ _handleLock.EnterWriteLock();
+ try
+ {
+ ObjectDisposedException.ThrowIf(_disposed, this);
+ _handle.Dispose();
+ _handle = File.OpenHandle(Path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, FileOptions.RandomAccess);
+ }
+ finally
+ {
+ _handleLock.ExitWriteLock();
+ }
+ Load();
+ }
+
+ public void Dispose()
+ {
+ if (_disposed) return;
+ if (Writable)
+ {
+ try
+ {
+ Flush();
+ }
+ catch (IOException ex)
+ {
+ Warn("Index not written on close: " + ex.Message);
+ }
+ }
+ _handleLock.EnterWriteLock();
+ try
+ {
+ _disposed = true;
+ _handle.Dispose();
+ }
+ finally
+ {
+ _handleLock.ExitWriteLock();
+ }
+ _handleLock.Dispose();
+ }
+
+ private static byte[] EmptyFile()
+ {
+ var file = new byte[DataStart];
+ HeaderSlot(1, 0, 0, 0, DataStart).CopyTo(file, 0);
+ return file;
+ }
+
+ private static byte[] HeaderSlot(ulong generation, long indexOffset, int indexLength, int count, long dataEnd)
+ {
+ var slot = new byte[SlotSize];
+ BinaryPrimitives.WriteUInt32LittleEndian(slot, HeaderMagic);
+ BinaryPrimitives.WriteUInt16LittleEndian(slot.AsSpan(4), Version);
+ BinaryPrimitives.WriteUInt64LittleEndian(slot.AsSpan(8), generation);
+ BinaryPrimitives.WriteInt64LittleEndian(slot.AsSpan(16), indexOffset);
+ BinaryPrimitives.WriteInt32LittleEndian(slot.AsSpan(24), indexLength);
+ BinaryPrimitives.WriteInt32LittleEndian(slot.AsSpan(28), count);
+ BinaryPrimitives.WriteInt64LittleEndian(slot.AsSpan(32), dataEnd);
+ BinaryPrimitives.WriteUInt32LittleEndian(slot.AsSpan(SlotSize - 4), Crc32.Compute(slot.AsSpan(0, SlotSize - 4)));
+ return slot;
+ }
+
+ private static byte[] IndexRecord(IEnumerable entries)
+ {
+ var list = entries.ToList();
+ var record = new byte[8 + list.Count * IndexEntrySize + 4];
+ BinaryPrimitives.WriteUInt32LittleEndian(record, IndexMagic);
+ BinaryPrimitives.WriteInt32LittleEndian(record.AsSpan(4), list.Count);
+ for (var i = 0; i < list.Count; i++)
+ {
+ var s = record.AsSpan(8 + i * IndexEntrySize, IndexEntrySize);
+ var e = list[i];
+ e.FrameId.TryWriteBytes(s);
+ BinaryPrimitives.WriteInt64LittleEndian(s[16..], e.Offset);
+ BinaryPrimitives.WriteInt32LittleEndian(s[24..], e.Length);
+ BinaryPrimitives.WriteUInt16LittleEndian(s[28..], (ushort)e.Width);
+ BinaryPrimitives.WriteUInt16LittleEndian(s[30..], (ushort)e.Height);
+ BinaryPrimitives.WriteUInt32LittleEndian(s[32..], e.Crc);
+ }
+ BinaryPrimitives.WriteUInt32LittleEndian(record.AsSpan(record.Length - 4), Crc32.Compute(record.AsSpan(0, record.Length - 4)));
+ return record;
+ }
+
+ /// Appends an index record, flushes, then commits it through the header slot not holding the newest generation.
+ private void WriteIndex()
+ {
+ var index = Volatile.Read(ref _index);
+ var record = IndexRecord(index.Values);
+ var offset = _tail;
+ WriteAt(record, offset);
+ _tail += record.Length;
+ RandomAccess.FlushToDisk(_handle);
+ var slot = 1 - _activeSlot;
+ WriteAt(HeaderSlot(_generation + 1, offset, record.Length, index.Count, _tail), slot * SlotSize);
+ RandomAccess.FlushToDisk(_handle);
+ _generation++;
+ _activeSlot = slot;
+ _unindexed = 0;
+ }
+
+ private void WriteAt(ReadOnlySpan data, long offset)
+ {
+ _handleLock.EnterReadLock();
+ try
+ {
+ ObjectDisposedException.ThrowIf(_disposed, this);
+ RandomAccess.Write(_handle, data, offset);
+ }
+ finally
+ {
+ _handleLock.ExitReadLock();
+ }
+ }
+
+ private void Warn(string message)
+ {
+ lock (_warnings)
+ {
+ if (_warnings.Count < 32) _warnings.Add(message);
+ }
+ }
+
+ /// Reads the newest valid header slot and its index, then recovers entries appended after it.
+ private void Load()
+ {
+ long length;
+ _handleLock.EnterReadLock();
+ try
+ {
+ length = RandomAccess.GetLength(_handle);
+ }
+ finally
+ {
+ _handleLock.ExitReadLock();
+ }
+ var index = new ConcurrentDictionary();
+ long scanFrom = DataStart;
+ (_generation, _activeSlot) = (0, 1);
+ var slots = new byte[DataStart];
+ var slotBytes = ReadAt(slots, 0);
+ for (var s = 0; s < 2; s++)
+ {
+ if (slotBytes < (s + 1) * SlotSize || ParseSlot(slots.AsSpan(s * SlotSize, SlotSize)) is not { } h)
+ {
+ if (slotBytes >= (s + 1) * SlotSize && slots.AsSpan(s * SlotSize, SlotSize).ContainsAnyExcept((byte)0)) Warn($"Header slot {s} damaged");
+ continue;
+ }
+ if (h.Generation <= _generation) continue;
+ var loaded = h.IndexLength > 0 ? ReadIndex(h.IndexOffset, h.IndexLength, length) : new ConcurrentDictionary();
+ if (loaded is null)
+ {
+ Warn($"Index of header slot {s} damaged");
+ continue;
+ }
+ (_generation, _activeSlot) = (h.Generation, s);
+ index = loaded;
+ scanFrom = h.DataEnd;
+ }
+ if (_generation == 0) Warn("No valid header; entries recovered by scanning");
+ _tail = length <= DataStart ? DataStart : Recover(index, long.Clamp(scanFrom, DataStart, length), length);
+ _index = index;
+ _liveBytes = index.Values.Sum(e => (long)EntryHeaderSize + e.Length);
+ _unindexed = 0;
+ }
+
+ private readonly record struct Slot(ulong Generation, long IndexOffset, int IndexLength, long DataEnd);
+
+ private static Slot? ParseSlot(ReadOnlySpan s)
+ {
+ if (BinaryPrimitives.ReadUInt32LittleEndian(s) != HeaderMagic || BinaryPrimitives.ReadUInt16LittleEndian(s[4..]) != Version) return null;
+ if (Crc32.Compute(s[..(SlotSize - 4)]) != BinaryPrimitives.ReadUInt32LittleEndian(s[(SlotSize - 4)..])) return null;
+ return new Slot(BinaryPrimitives.ReadUInt64LittleEndian(s[8..]), BinaryPrimitives.ReadInt64LittleEndian(s[16..]),
+ BinaryPrimitives.ReadInt32LittleEndian(s[24..]), BinaryPrimitives.ReadInt64LittleEndian(s[32..]));
+ }
+
+ private ConcurrentDictionary? ReadIndex(long offset, int length, long fileLength)
+ {
+ if (offset < DataStart || length < 12 || offset > fileLength - length || (length - 12) % IndexEntrySize != 0) return null;
+ var record = new byte[length];
+ if (ReadAt(record, offset) != length) return null;
+ if (BinaryPrimitives.ReadUInt32LittleEndian(record) != IndexMagic
+ || Crc32.Compute(record.AsSpan(0, length - 4)) != BinaryPrimitives.ReadUInt32LittleEndian(record.AsSpan(length - 4))) return null;
+ var count = BinaryPrimitives.ReadInt32LittleEndian(record.AsSpan(4));
+ if (count != (length - 12) / IndexEntrySize) return null;
+ var index = new ConcurrentDictionary();
+ for (var i = 0; i < count; i++)
+ {
+ var s = record.AsSpan(8 + i * IndexEntrySize, IndexEntrySize);
+ var e = new ThumbnailEntry(new Guid(s[..16]), BinaryPrimitives.ReadInt64LittleEndian(s[16..]), BinaryPrimitives.ReadInt32LittleEndian(s[24..]),
+ BinaryPrimitives.ReadUInt16LittleEndian(s[28..]), BinaryPrimitives.ReadUInt16LittleEndian(s[30..]), BinaryPrimitives.ReadUInt32LittleEndian(s[32..]));
+ if (e.Offset >= DataStart && e.Length is > 0 and <= MaxJpegBytes && e.Offset <= fileLength - EntryHeaderSize - e.Length) index[e.FrameId] = e;
+ }
+ return index;
+ }
+
+ /// Walks records from , adding valid entries (later ones win) and skipping index
+ /// records; stops at the first damaged or truncated record. Returns the end of the last good record.
+ private long Recover(ConcurrentDictionary index, long position, long length)
+ {
+ var head = new byte[EntryHeaderSize];
+ var recovered = 0;
+ while (position + 12 <= length)
+ {
+ var n = ReadAt(head.AsSpan(0, (int)long.Min(EntryHeaderSize, length - position)), position);
+ var magic = BinaryPrimitives.ReadUInt32LittleEndian(head);
+ if (magic == IndexMagic && n >= 8)
+ {
+ var count = BinaryPrimitives.ReadInt32LittleEndian(head.AsSpan(4));
+ var size = 12L + (long)count * IndexEntrySize;
+ if (count < 0 || position + size > length || ReadIndex(position, (int)long.Min(size, int.MaxValue), length) is null) break;
+ position += size;
+ continue;
+ }
+ if (magic != EntryMagic || n < EntryHeaderSize) break;
+ var jpegLength = BinaryPrimitives.ReadInt32LittleEndian(head.AsSpan(24));
+ if (jpegLength is <= 0 or > MaxJpegBytes || position + EntryHeaderSize + jpegLength > length) break;
+ var jpeg = new byte[jpegLength];
+ if (ReadAt(jpeg, position + EntryHeaderSize) != jpegLength) break;
+ var crc = BinaryPrimitives.ReadUInt32LittleEndian(head.AsSpan(28));
+ if (Crc32.Compute(jpeg) != crc) break;
+ var id = new Guid(head.AsSpan(4, 16));
+ index[id] = new ThumbnailEntry(id, position, jpegLength, BinaryPrimitives.ReadUInt16LittleEndian(head.AsSpan(20)), BinaryPrimitives.ReadUInt16LittleEndian(head.AsSpan(22)), crc);
+ position += EntryHeaderSize + jpegLength;
+ recovered++;
+ }
+ if (position < length) Warn($"Ignored {length - position} damaged bytes at the end of the pack");
+ if (recovered > 0) Warn($"Recovered {recovered} thumbnail(s) appended after the last index");
+ return position;
+ }
+
+ private int ReadAt(Span buffer, long offset)
+ {
+ _handleLock.EnterReadLock();
+ try
+ {
+ var total = 0;
+ while (total < buffer.Length)
+ {
+ var n = RandomAccess.Read(_handle, buffer[total..], offset + total);
+ if (n == 0) break;
+ total += n;
+ }
+ return total;
+ }
+ finally
+ {
+ _handleLock.ExitReadLock();
+ }
+ }
+}
diff --git a/src/Titano.Tools/Commands/DiagnoseCommand.cs b/src/Titano.Tools/Commands/DiagnoseCommand.cs
new file mode 100644
index 00000000..d6c1d958
--- /dev/null
+++ b/src/Titano.Tools/Commands/DiagnoseCommand.cs
@@ -0,0 +1,100 @@
+using System.Globalization;
+using Titano.Core.Imaging;
+using Titano.Core.Imaging.Decoders;
+using Titano.Core.Metadata;
+
+namespace Titano.Tools.Commands;
+
+///
+/// Per-file decode report for a folder of photos: format, the tier the managed decoders reach (the server's view — WIC
+/// does not exist in this tool), dimensions, camera, capture time and its source, warnings; then a summary per format.
+///
+internal sealed class DiagnoseCommand : ICommand
+{
+ public string Name => "diagnose";
+ public string Summary => "Decode tiers and metadata of the photos in a folder (--recursive, --formats)";
+
+ public Task RunAsync(string[] args)
+ {
+ var a = new Args(args, "recursive", "formats");
+ if (a.Has("formats")) PrintFormats();
+ if (a.Positional.Count == 0)
+ {
+ if (a.Has("formats")) return Task.FromResult(0);
+ throw new ToolException("Usage: diagnose [--recursive] [--formats]");
+ }
+ var folder = Path.GetFullPath(a.Positional[0]);
+ if (!Directory.Exists(folder)) throw new ToolException($"Folder not found: {folder}");
+ var files = Directory.EnumerateFiles(folder, "*", a.Has("recursive") ? SearchOption.AllDirectories : SearchOption.TopDirectoryOnly)
+ .Where(ImageFormatInfo.IsSupportedExtension)
+ .Order(StringComparer.OrdinalIgnoreCase)
+ .ToList();
+ Console.WriteLine($"{files.Count} photo(s) in {folder}. Tiers are the managed (server) view; WIC is not available in Titano.Tools.");
+ var provider = new ManagedDecoderProvider();
+ var summary = new SortedDictionary(StringComparer.Ordinal);
+ foreach (var file in files)
+ {
+ var line = Describe(provider, folder, file, out var format, out var tier);
+ Console.WriteLine(line);
+ if (!summary.TryGetValue(format, out var counts)) summary[format] = counts = new int[3];
+ counts[(int)tier - 1]++;
+ }
+ if (summary.Count > 0)
+ {
+ Console.WriteLine();
+ Console.WriteLine($"{"Format",-8} {"Files",6} {"Native",7} {"Preview",8} {"None",5}");
+ foreach (var (format, c) in summary) Console.WriteLine($"{format,-8} {c.Sum(),6} {c[0],7} {c[1],8} {c[2],5}");
+ }
+ return Task.FromResult(0);
+ }
+
+ private static string Describe(ManagedDecoderProvider provider, string folder, string file, out string format, out DecodeTier tier)
+ {
+ var name = Path.GetRelativePath(folder, file);
+ FrameMetadata metadata;
+ FileTier fileTier;
+ try
+ {
+ metadata = MetadataReader.Read(file);
+ fileTier = provider.Probe(file);
+ }
+ catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+ {
+ format = ImageFormatInfo.FromPath(file).Format.ToString();
+ tier = DecodeTier.Unavailable;
+ return $"{name}\n unreadable: {ex.Message}";
+ }
+ format = fileTier.Format.ToString();
+ tier = fileTier.Tier;
+ var (w, h) = fileTier.Width > 0 ? (fileTier.Width, fileTier.Height) : metadata.OrientedSize;
+ var camera = string.Join(' ', new[] { metadata.Make, metadata.Model }.Where(s => !string.IsNullOrEmpty(s)));
+ var captured = metadata.CapturedAt is { } t
+ ? $"{t.ToString("yyyy-MM-dd HH:mm:ss.fff", CultureInfo.InvariantCulture)} ({metadata.TimestampSource})"
+ : "unknown";
+ var tierText = fileTier.Tier switch
+ {
+ DecodeTier.Native => $"native ({fileTier.Decoder})",
+ DecodeTier.EmbeddedPreview => "embedded preview",
+ _ => "unavailable",
+ };
+ var lines = new List { $"{name}\n {format,-5} {tierText,-24} {$"{w}x{h}",-11} {(camera.Length > 0 ? camera : "camera unknown")}; captured {captured}" };
+ if (fileTier.Reason is { } reason) lines.Add($" reason: {reason}");
+ lines.AddRange(metadata.Warnings.Select(warning => $" warning: {warning}"));
+ return string.Join('\n', lines);
+ }
+
+ private static void PrintFormats()
+ {
+ Console.WriteLine("Format tiers (managed decoders):");
+ foreach (var row in DecoderFactory.DescribeFormats(DecoderFactory.CreateServer()))
+ {
+ var tier = row.Tier switch
+ {
+ DecodeTier.Native => "native",
+ DecodeTier.EmbeddedPreview => "embedded preview",
+ _ => "unavailable",
+ };
+ Console.WriteLine($" {row.Format.Format,-8} {string.Join(' ', row.Format.Extensions),-18} {tier}");
+ }
+ }
+}
diff --git a/src/Titano.Tools/Commands/FixturesCommand.cs b/src/Titano.Tools/Commands/FixturesCommand.cs
new file mode 100644
index 00000000..65d823af
--- /dev/null
+++ b/src/Titano.Tools/Commands/FixturesCommand.cs
@@ -0,0 +1,147 @@
+using System.Net;
+using System.Net.Http.Headers;
+using System.Security.Cryptography;
+using System.Text.Json;
+
+namespace Titano.Tools.Commands;
+
+///
+/// Fetches the CC0 RAW samples listed in tests/fixtures/manifest.json into tests/fixtures/external (BRIEF
+/// §20.2): interrupted downloads resume from their .part file with an HTTP range request, every file is verified
+/// against its SHA-256, and verified files are skipped. An entry whose sha256 is null gets the hash of its first
+/// download recorded in external/recorded-hashes.json (later runs verify against it) and printed so it can be
+/// copied into the manifest.
+///
+internal sealed class FixturesCommand : ICommand
+{
+ private const string RecordedHashesFile = "recorded-hashes.json";
+
+ public string Name => "fixtures";
+ public string Summary => "Download and verify the CC0 RAW samples in tests/fixtures/manifest.json (--manifest, --out)";
+
+ public async Task RunAsync(string[] args)
+ {
+ var a = new Args(args);
+ var root = Args.RepoRoot();
+ var manifestPath = a.Get("manifest") ?? Path.Combine(root, "tests", "fixtures", "manifest.json");
+ var outDir = a.Get("out") ?? Path.Combine(root, "tests", "fixtures", "external");
+ if (!File.Exists(manifestPath)) throw new ToolException($"Manifest not found: {manifestPath}");
+ var entries = ReadManifest(manifestPath);
+ Directory.CreateDirectory(outDir);
+ var recordedPath = Path.Combine(outDir, RecordedHashesFile);
+ var recorded = File.Exists(recordedPath)
+ ? JsonSerializer.Deserialize>(await File.ReadAllTextAsync(recordedPath)) ?? []
+ : [];
+ var newlyRecorded = new List();
+ var failures = 0;
+ using var http = new HttpClient { Timeout = TimeSpan.FromMinutes(10) };
+ http.DefaultRequestHeaders.UserAgent.ParseAdd("Titano.Tools/1.0 (+fixtures)");
+ foreach (var entry in entries)
+ {
+ var target = Path.Combine(outDir, entry.Name);
+ var expected = entry.Sha256 ?? recorded.GetValueOrDefault(entry.Name);
+ try
+ {
+ if (File.Exists(target))
+ {
+ var hash = await HashAsync(target);
+ if (expected is null || hash.Equals(expected, StringComparison.OrdinalIgnoreCase))
+ {
+ if (expected is null) Record(entry.Name, hash);
+ Console.WriteLine($"ok {entry.Name} (verified)");
+ continue;
+ }
+ Console.WriteLine($"mismatch {entry.Name}: downloading again");
+ File.Delete(target);
+ }
+ var actual = await DownloadAsync(http, entry, target);
+ if (expected is not null && !actual.Equals(expected, StringComparison.OrdinalIgnoreCase))
+ {
+ File.Delete(target);
+ throw new InvalidDataException($"SHA-256 {actual} does not match {expected}");
+ }
+ if (expected is null) Record(entry.Name, actual);
+ Console.WriteLine($"fetched {entry.Name} ({new FileInfo(target).Length / 1e6:F1} MB)");
+ }
+ catch (Exception ex) when (ex is HttpRequestException or IOException or InvalidDataException or TaskCanceledException or UnauthorizedAccessException)
+ {
+ failures++;
+ Console.Error.WriteLine($"failed {entry.Name}: {ex.Message}");
+ }
+ }
+ await File.WriteAllTextAsync(recordedPath, JsonSerializer.Serialize(recorded, new JsonSerializerOptions { WriteIndented = true }));
+ if (newlyRecorded.Count > 0)
+ {
+ Console.WriteLine("Recorded SHA-256 of first downloads (copy into the manifest to pin them):");
+ foreach (var line in newlyRecorded) Console.WriteLine(" " + line);
+ }
+ Console.WriteLine(failures == 0 ? $"{entries.Count} fixture(s) ready in {outDir}" : $"{failures} of {entries.Count} fixture(s) failed");
+ return failures == 0 ? 0 : 1;
+
+ void Record(string name, string hash)
+ {
+ if (recorded.GetValueOrDefault(name) == hash) return;
+ recorded[name] = hash;
+ newlyRecorded.Add($"{name}: {hash}");
+ }
+ }
+
+ internal sealed record Entry(string Name, Uri Url, string? Sha256, long? Size);
+
+ internal static List ReadManifest(string path)
+ {
+ using var doc = JsonDocument.Parse(File.ReadAllText(path));
+ if (!doc.RootElement.TryGetProperty("files", out var files) || files.ValueKind != JsonValueKind.Array) throw new ToolException("Manifest has no 'files' array");
+ var entries = new List();
+ foreach (var f in files.EnumerateArray())
+ {
+ var name = f.GetProperty("name").GetString() ?? throw new ToolException("Fixture without a name");
+ if (name != Path.GetFileName(name) || name.StartsWith('.')) throw new ToolException($"Fixture name must be a plain file name: {name}");
+ if (!Uri.TryCreate(f.GetProperty("url").GetString(), UriKind.Absolute, out var url) || url.Scheme != Uri.UriSchemeHttps)
+ throw new ToolException($"Fixture {name} needs an https URL");
+ var sha = f.TryGetProperty("sha256", out var s) && s.ValueKind == JsonValueKind.String ? s.GetString() : null;
+ long? size = f.TryGetProperty("size", out var z) && z.ValueKind == JsonValueKind.Number ? z.GetInt64() : null;
+ entries.Add(new Entry(name, url, sha, size));
+ }
+ return entries;
+ }
+
+ /// Downloads into target.part, resuming from its length with a range request, then renames it.
+ private static async Task DownloadAsync(HttpClient http, Entry entry, string target)
+ {
+ var part = target + ".part";
+ var existing = File.Exists(part) ? new FileInfo(part).Length : 0;
+ if (entry.Size is not { } size || existing < size)
+ {
+ using var request = new HttpRequestMessage(HttpMethod.Get, entry.Url);
+ if (existing > 0) request.Headers.Range = new RangeHeaderValue(existing, null);
+ using var response = await http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
+ if (response.StatusCode == HttpStatusCode.RequestedRangeNotSatisfiable && existing > 0)
+ {
+ // The partial file is already complete (or the server lost it): verified below.
+ }
+ else
+ {
+ response.EnsureSuccessStatusCode();
+ var resume = response.StatusCode == HttpStatusCode.PartialContent;
+ await using var output = new FileStream(part, resume ? FileMode.Append : FileMode.Create, FileAccess.Write, FileShare.None, 1 << 16, FileOptions.Asynchronous);
+ await using var input = await response.Content.ReadAsStreamAsync();
+ await input.CopyToAsync(output);
+ }
+ }
+ if (entry.Size is { } expected && new FileInfo(part).Length is var length && length != expected)
+ {
+ File.Delete(part);
+ throw new InvalidDataException($"size {length} differs from {expected}");
+ }
+ var hash = await HashAsync(part);
+ File.Move(part, target, overwrite: true);
+ return hash;
+ }
+
+ private static async Task HashAsync(string path)
+ {
+ await using var stream = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, 1 << 16, FileOptions.Asynchronous | FileOptions.SequentialScan);
+ return Convert.ToHexStringLower(await SHA256.HashDataAsync(stream));
+ }
+}
diff --git a/src/Titano.Tools/Program.cs b/src/Titano.Tools/Program.cs
index 6bf7af38..1e573c1f 100644
--- a/src/Titano.Tools/Program.cs
+++ b/src/Titano.Tools/Program.cs
@@ -10,6 +10,8 @@ var commands = new ICommand[]
new ChangelogCommand(),
new PackInstallerCommand(),
new SelfTestCommand(),
+ new DiagnoseCommand(),
+ new FixturesCommand(),
};
if (args.Length == 0 || args[0] is "-h" or "--help" or "help")
diff --git a/tests/Titano.Core.Tests/Decoding/ExternalFixtureTests.cs b/tests/Titano.Core.Tests/Decoding/ExternalFixtureTests.cs
new file mode 100644
index 00000000..f641ff7c
--- /dev/null
+++ b/tests/Titano.Core.Tests/Decoding/ExternalFixtureTests.cs
@@ -0,0 +1,84 @@
+using System.Text.Json;
+using Titano.Core.Imaging;
+using Titano.Core.Imaging.Decoders;
+using Titano.Core.Metadata;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Decoding;
+
+/// Real camera files from tests/fixtures/manifest.json (fetched by Titano.Tools fixtures); each test is
+/// skipped when its file is absent. A native decode must reach the expected size and look like the camera's own
+/// embedded preview (luminance correlation), which catches wrong byte orders, CFA phases or colour matrices.
+public sealed class ExternalFixtureTests(TestContext context)
+{
+ private const int Edge = 256;
+
+ private static JsonElement Entry(string name)
+ {
+ var manifest = JsonDocument.Parse(File.ReadAllText(Path.Combine(TestContext.FixturesDirectory, "manifest.json")));
+ foreach (var f in manifest.RootElement.GetProperty("files").EnumerateArray())
+ {
+ if (f.GetProperty("name").GetString() == name) return f.Clone();
+ }
+ throw new InvalidOperationException("No manifest entry " + name);
+ }
+
+ [Theory]
+ [Case("google-pixel-4a.dng")]
+ [Case("canon-eos-5d-mark-iii.cr2")]
+ [Case("nikon-d850.nef")]
+ [Case("sony-ilce-7m3.arw")]
+ [Case("fujifilm-x-t2.raf")]
+ [Case("pentax-k-1.pef")]
+ [Timeout(20_000)]
+ public void DecodesNativelyAndMatchesThePreview(string name)
+ {
+ var path = Path.Combine(TestContext.FixturesDirectory, "external", name);
+ if (!File.Exists(path)) TestContext.Skip($"{name} not fetched (run Titano.Tools fixtures)");
+ var entry = Entry(name);
+ var metadata = MetadataReader.Read(path);
+ Assert.Equal(entry.GetProperty("format").GetString(), metadata.Format.ToString());
+ var probe = new ManagedDecoderProvider().Probe(path);
+ context.Log($"{name}: {probe}; {metadata.Make} {metadata.Model}, {metadata.Width}x{metadata.Height}, orientation {metadata.Orientation}");
+ Assert.Equal(DecodeTier.Native, probe.Tier);
+
+ var decoder = DecoderFactory.CreateServer();
+ using var native = decoder.Decode(new DecodeRequest(path, Edge, DecodePurpose.Render, ApplyOrientation: false));
+ Assert.Equal(DecodeTier.Native, native!.Tier);
+ var (w, h) = (entry.GetProperty("width").GetInt32(), entry.GetProperty("height").GetInt32());
+ Assert.InRange(native.SourceWidth, w * 0.98, w * 1.02);
+ Assert.InRange(native.SourceHeight, h * 0.98, h * 1.02);
+ foreach (var v in native.Pixels.Data)
+ {
+ if (!float.IsFinite(v)) Assert.Fail("non-finite pixel");
+ }
+
+ using var preview = decoder.Decode(new DecodeRequest(path, Edge, DecodePurpose.Render, ApplyOrientation: false, ForcePreview: true));
+ if (preview is null || preview.Tier != DecodeTier.EmbeddedPreview) TestContext.Skip("no embedded preview to compare with");
+ var correlation = Correlation(native.Pixels, preview.Pixels);
+ context.Log($"luminance correlation with the embedded preview: {correlation:F3}");
+ Assert.Greater(correlation, 0.8);
+ }
+
+ /// Pearson correlation of sRGB-encoded luminance after resizing both to a common 64-pixel-wide grid.
+ private static double Correlation(ImageBuffer a, ImageBuffer b)
+ {
+ var height = int.Max(1, (int)double.Round(64.0 * a.Height / a.Width));
+ using var ra = Resampler.Resize(a, 64, height, ResampleFilter.Box);
+ using var rb = Resampler.Resize(b, 64, height, ResampleFilter.Box);
+ var n = ra.PlaneLength;
+ double sa = 0, sb = 0, saa = 0, sbb = 0, sab = 0;
+ for (var i = 0; i < n; i++)
+ {
+ double la = ColorSpace.EncodeFast(ColorSpace.Luminance(ra.Plane(0)[i], ra.Plane(1)[i], ra.Plane(2)[i]));
+ double lb = ColorSpace.EncodeFast(ColorSpace.Luminance(rb.Plane(0)[i], rb.Plane(1)[i], rb.Plane(2)[i]));
+ sa += la;
+ sb += lb;
+ saa += la * la;
+ sbb += lb * lb;
+ sab += la * lb;
+ }
+ var cov = sab / n - sa / n * (sb / n);
+ return cov / double.Sqrt(double.Max(saa / n - sa / n * (sa / n), 1e-12) * double.Max(sbb / n - sb / n * (sb / n), 1e-12));
+ }
+}
diff --git a/tests/Titano.Core.Tests/Decoding/FrameWindowTests.cs b/tests/Titano.Core.Tests/Decoding/FrameWindowTests.cs
new file mode 100644
index 00000000..06edd17b
--- /dev/null
+++ b/tests/Titano.Core.Tests/Decoding/FrameWindowTests.cs
@@ -0,0 +1,197 @@
+using Titano.Core.Imaging;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Decoding;
+
+/// : memory bound independent of sequence length, spill round trip, read-ahead,
+/// cancellation and deterministic disposal (BRIEF §8.4, §20.4 memory and cancellation gates).
+public sealed class FrameWindowTests(TestContext context)
+{
+ private const int Size = 64;
+ private const long FrameBytes = Size * Size * 3 * sizeof(float);
+
+ /// Synthetic loader whose frames encode their index; records every buffer it hands out.
+ private sealed class Source
+ {
+ private readonly List _made = [];
+ public int Loads;
+ public TimeSpan Delay;
+
+ public async ValueTask Load(int index, CancellationToken cancellationToken)
+ {
+ Interlocked.Increment(ref Loads);
+ if (Delay > TimeSpan.Zero) await Task.Delay(Delay, cancellationToken);
+ var image = new ImageBuffer(Size, Size, 3, clear: false);
+ image.Data.Fill(index);
+ image[1, 5, 7] = index + 0.25f;
+ lock (_made) _made.Add(image);
+ return image;
+ }
+
+ /// Loader-made buffers not yet disposed (independent of the window's own counters).
+ public int Live()
+ {
+ lock (_made)
+ {
+ var live = 0;
+ foreach (var b in _made)
+ {
+ try
+ {
+ _ = b.Storage;
+ live++;
+ }
+ catch (ObjectDisposedException)
+ {
+ }
+ }
+ return live;
+ }
+ }
+ }
+
+ private static void AssertFrame(FrameLease lease)
+ {
+ Assert.Equal((float)lease.Index, lease.Image[0, 10, 10]);
+ Assert.Equal(lease.Index + 0.25f, lease.Image[1, 5, 7]);
+ }
+
+ /// Render loop: each step moves the window and reads the frame plus its three predecessors — four frames
+ /// needed per step against a three-frame budget, so in-window frames must be spilled and read back.
+ private async Task<(FrameWindowStatistics Stats, int PeakLive, string? Spill)> Render(int frames, string spillDirectory)
+ {
+ var source = new Source();
+ var options = new FrameWindowOptions { Behind = 3, Ahead = 4, MemoryBudget = 3 * FrameBytes, SpillDirectory = spillDirectory };
+ var peakLive = 0;
+ FrameWindowStatistics stats;
+ string? spill;
+ await using (var window = new FrameWindow(frames, source.Load, options))
+ {
+ for (var i = 0; i < frames; i++)
+ {
+ window.MoveTo(i);
+ using (var current = await window.GetAsync(i)) AssertFrame(current);
+ for (var back = 1; back <= 3 && i - back >= 0; back++)
+ {
+ using var previous = await window.GetAsync(i - back);
+ AssertFrame(previous);
+ }
+ peakLive = int.Max(peakLive, source.Live());
+ Assert.LessOrEqual(window.Statistics.LiveBytes, options.MemoryBudget);
+ }
+ stats = window.Statistics;
+ spill = window.SpillPath;
+ Assert.FileExists(spill!);
+ }
+ Assert.Equal(0, source.Live());
+ return (stats, peakLive, spill);
+ }
+
+ [Test]
+ [Timeout(30_000)]
+ public async Task PeakMemoryIsBoundedAndIndependentOfSequenceLength()
+ {
+ var dir = context.CreateTempDirectory();
+ var shortRun = await Render(40, dir);
+ var longRun = await Render(400, dir);
+ context.Log($"40 frames: {shortRun.Stats}, peak live {shortRun.PeakLive}; 400 frames: {longRun.Stats}, peak live {longRun.PeakLive}");
+ foreach (var run in new[] { shortRun, longRun })
+ {
+ Assert.LessOrEqual(run.Stats.PeakLiveBytes, 3 * FrameBytes);
+ Assert.LessOrEqual(run.PeakLive, 3);
+ Assert.Greater(run.Stats.SpillWrites, 0);
+ Assert.Greater(run.Stats.SpillReads, 0);
+ // Spill extents are reused: only frames inside the window (3 behind + current + 4 ahead) are ever on disk.
+ Assert.LessOrEqual(run.Stats.SpillFileBytes, 8 * FrameBytes);
+ Assert.FileMissing(run.Spill!);
+ }
+ Assert.Equal(shortRun.Stats.PeakLiveBytes, longRun.Stats.PeakLiveBytes);
+ Assert.Equal(shortRun.PeakLive, longRun.PeakLive);
+ Assert.LessOrEqual(longRun.Stats.SpillFileBytes, shortRun.Stats.SpillFileBytes);
+ }
+
+ [Test]
+ [Timeout(10_000)]
+ public async Task ReadAheadDecodesInTheBackground()
+ {
+ var source = new Source();
+ await using var window = new FrameWindow(100, source.Load, new FrameWindowOptions { Ahead = 3, MemoryBudget = 10 * FrameBytes });
+ window.MoveTo(0);
+ using (var first = await window.GetAsync(0)) AssertFrame(first);
+ var deadline = DateTime.UtcNow.AddSeconds(5);
+ while (source.Loads < 4 && DateTime.UtcNow < deadline) await Task.Delay(5);
+ Assert.Equal(4, source.Loads);
+ using var ahead = await window.GetAsync(3);
+ AssertFrame(ahead);
+ Assert.Equal(4, source.Loads);
+ }
+
+ [Test]
+ [Timeout(10_000)]
+ public async Task CancellationLeavesNoSpillFileAndNoUnobservedErrors()
+ {
+ var unobserved = 0;
+ void OnUnobserved(object? sender, UnobservedTaskExceptionEventArgs e) => Interlocked.Increment(ref unobserved);
+ TaskScheduler.UnobservedTaskException += OnUnobserved;
+ try
+ {
+ var dir = context.CreateTempDirectory();
+ var source = new Source();
+ string? spill;
+ using var cts = new CancellationTokenSource();
+ var window = new FrameWindow(50, source.Load, new FrameWindowOptions { Behind = 3, Ahead = 2, MemoryBudget = 2 * FrameBytes, SpillDirectory = dir });
+ try
+ {
+ for (var i = 0; i < 6; i++)
+ {
+ window.MoveTo(i);
+ using var a = await window.GetAsync(i);
+ if (i > 0)
+ {
+ using var b = await window.GetAsync(i - 1);
+ }
+ }
+ spill = window.SpillPath;
+ Assert.NotNull(spill);
+ Assert.FileExists(spill!);
+ source.Delay = TimeSpan.FromSeconds(30);
+ window.MoveTo(20);
+ var pending = window.GetAsync(20, cts.Token);
+ cts.CancelAfter(50);
+ await Assert.ThrowsAsync(async () => await pending);
+ }
+ finally
+ {
+ await window.DisposeAsync();
+ }
+ Assert.FileMissing(spill!);
+ Assert.Equal(0, source.Live());
+ await Assert.ThrowsAsync(async () => await window.GetAsync(1));
+ }
+ finally
+ {
+ GC.Collect();
+ GC.WaitForPendingFinalizers();
+ TaskScheduler.UnobservedTaskException -= OnUnobserved;
+ }
+ Assert.Equal(0, unobserved);
+ }
+
+ [Test]
+ public async Task LoaderFailuresSurfaceAndCanBeRetried()
+ {
+ var attempts = 0;
+ async ValueTask Flaky(int index, CancellationToken ct)
+ {
+ await Task.Yield();
+ if (index == 2 && Interlocked.Increment(ref attempts) == 1) throw new InvalidDataException("bad frame");
+ var image = new ImageBuffer(8, 8, 3);
+ image.Data.Fill(index);
+ return image;
+ }
+ await using var window = new FrameWindow(5, Flaky, new FrameWindowOptions { Ahead = 0 });
+ await Assert.ThrowsAsync(async () => await window.GetAsync(2));
+ using var retried = await window.GetAsync(2);
+ Assert.Equal(2f, retried.Image[0, 0, 0]);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Decoding/ManagedDecoderProviderTests.cs b/tests/Titano.Core.Tests/Decoding/ManagedDecoderProviderTests.cs
new file mode 100644
index 00000000..bcbc861e
--- /dev/null
+++ b/tests/Titano.Core.Tests/Decoding/ManagedDecoderProviderTests.cs
@@ -0,0 +1,217 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Codecs.Png;
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Codecs.Tiff;
+using Titano.Core.Imaging;
+using Titano.Core.Imaging.Decoders;
+using Titano.Core.Metadata;
+using Titano.Core.Tests.Raw;
+using Titano.Testing;
+using static Titano.Core.Tests.Raw.NativeRawWriters;
+
+namespace Titano.Core.Tests.Decoding;
+
+/// Tier selection (native → embedded preview → unavailable), decoder chains and fast paths.
+public sealed class ManagedDecoderProviderTests(TestContext context)
+{
+ private const int W = 96, H = 64;
+ private readonly string _dir = context.CreateTempDirectory();
+
+ private string Write(string name, byte[] data)
+ {
+ var path = Path.Combine(_dir, name);
+ File.WriteAllBytes(path, data);
+ return path;
+ }
+
+ private static byte[] Cr2File(string model, int orientation = 1)
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var active = new RawRect(24, 4, 24 + W, 4 + H);
+ return Cr2(Sensor(scene, "Canon EOS 5D Mark III", CfaPattern.Bayer("RGGB"), 128, 72, active.Left, active.Top, 2048, 16383), active, orientation, model);
+ }
+
+ private static byte[] JpegFile(int width, int height, int orientation)
+ {
+ using var image = SyntheticRaw.Smooth(width, height);
+ var exif = ExifWriter.BuildTiff(new FrameMetadata { Make = "TestCam", Model = "T1", Orientation = orientation });
+ return JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = 90, App1Segments = [[.. "Exif\0\0"u8, .. exif]] });
+ }
+
+ [Test]
+ public void ServerFormatTableReportsTiers()
+ {
+ var rows = DecoderFactory.DescribeFormats(DecoderFactory.CreateServer()).ToDictionary(r => r.Format.Format);
+ foreach (var f in new[] { ImageFileFormat.Jpeg, ImageFileFormat.Png, ImageFileFormat.Tiff, ImageFileFormat.Dng, ImageFileFormat.Cr2, ImageFileFormat.Nef, ImageFileFormat.Arw, ImageFileFormat.Pef, ImageFileFormat.Raf })
+ {
+ Assert.Equal(DecodeTier.Native, rows[f].Tier);
+ Assert.Equal("managed", rows[f].Provider);
+ }
+ foreach (var f in new[] { ImageFileFormat.Cr3, ImageFileFormat.Orf, ImageFileFormat.Rw2, ImageFileFormat.Heif }) Assert.Equal(DecodeTier.EmbeddedPreview, rows[f].Tier);
+ foreach (var f in new[] { ImageFileFormat.WebP, ImageFileFormat.JpegXl, ImageFileFormat.Gif })
+ {
+ Assert.Equal(DecodeTier.Unavailable, rows[f].Tier);
+ Assert.Null(rows[f].Provider);
+ }
+ }
+
+ [Test]
+ public void ClientChainPrefersTheWindowsProvider()
+ {
+ var wic = new FakeProvider();
+ var decoder = DecoderFactory.CreateClient(wic);
+ Assert.Equal(2, decoder.Providers.Count);
+ var rows = DecoderFactory.DescribeFormats(decoder).ToDictionary(r => r.Format.Format);
+ Assert.Equal("fake", rows[ImageFileFormat.Cr3].Provider);
+ Assert.Equal(DecodeTier.Native, rows[ImageFileFormat.Cr3].Tier);
+ Assert.Equal("fake", rows[ImageFileFormat.Jpeg].Provider);
+ Assert.Equal("managed", rows[ImageFileFormat.Dng].Provider);
+
+ // The Windows provider declines this file: the managed provider decodes it.
+ var path = Write("a.jpg", JpegFile(64, 48, 1));
+ using var image = decoder.Decode(new DecodeRequest(path));
+ Assert.Equal(1, wic.Calls);
+ Assert.Equal("managed-jpeg", image!.Decoder);
+ Assert.Count(1, DecoderFactory.CreateClient(null).Providers);
+ }
+
+ [Test]
+ public void SupportedRawDecodesNatively()
+ {
+ var path = Write("IMG_1.CR2", Cr2File("Canon EOS 5D Mark III"));
+ var provider = new ManagedDecoderProvider();
+ Assert.Equal(DecodeTier.Native, provider.Probe(path).Tier);
+ using var image = DecoderFactory.CreateServer().Decode(new DecodeRequest(path));
+ Assert.Equal(DecodeTier.Native, image!.Tier);
+ Assert.Equal("managed-cr2", image.Decoder);
+ Assert.Equal(W, image.Pixels.Width);
+ Assert.Equal(W, image.SourceWidth);
+ }
+
+ [Test]
+ public void UnsupportedBodyFallsBackToTheOrientedPreview()
+ {
+ var path = Write("IMG_2.CR2", Cr2File("Canon EOS R99", orientation: 6));
+ var probe = new ManagedDecoderProvider().Probe(path);
+ Assert.Equal(DecodeTier.EmbeddedPreview, probe.Tier);
+ Assert.Contains("no colour matrix", probe.Reason);
+ using var image = DecoderFactory.CreateServer().Decode(new DecodeRequest(path));
+ Assert.Equal(DecodeTier.EmbeddedPreview, image!.Tier);
+ Assert.Equal("managed-preview", image.Decoder);
+ // The 64×48 preview is rotated by the RAW's orientation (6).
+ Assert.Equal(48, image.Pixels.Width);
+ Assert.Equal(64, image.Pixels.Height);
+ Assert.Equal(48, image.SourceWidth);
+ Assert.Null(DecoderFactory.CreateServer().Decode(new DecodeRequest(path, AllowPreview: false)));
+ }
+
+ [Test]
+ public void ForcePreviewSkipsNativeDevelopment()
+ {
+ var path = Write("IMG_3.CR2", Cr2File("Canon EOS 5D Mark III"));
+ using var image = DecoderFactory.CreateServer().Decode(new DecodeRequest(path, ForcePreview: true));
+ Assert.Equal(DecodeTier.EmbeddedPreview, image!.Tier);
+ Assert.Equal(64, image.Pixels.Width);
+ }
+
+ [Test]
+ public void FilesWithoutDecoderOrPreviewAreUnavailable()
+ {
+ // A NEF whose body has no matrix and no preview, and a WebP.
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var nef = Nef(Sensor(scene, "Nikon D850", CfaPattern.Bayer("RGGB"), W, H, 0, 0, 600, 16383), 14, NefEncoding.Lossless);
+ var text = System.Text.Encoding.Latin1.GetString(nef).Replace("NIKON D850", "NIKON Z99X");
+ var path = Write("DSC_9.NEF", System.Text.Encoding.Latin1.GetBytes(text));
+ Assert.Equal(DecodeTier.Unavailable, new ManagedDecoderProvider().Probe(path).Tier);
+ Assert.Null(DecoderFactory.CreateServer().Decode(new DecodeRequest(path)));
+ var webp = Write("x.webp", Metadata.Builders.Fixtures.WebP());
+ Assert.Null(DecoderFactory.CreateServer().Decode(new DecodeRequest(webp)));
+ Assert.Equal(DecodeTier.Unavailable, new ManagedDecoderProvider().Probe(webp).Tier);
+ }
+
+ [Test]
+ public void JpegUsesDctScalingAndOrientation()
+ {
+ var path = Write("big.jpg", JpegFile(1600, 1200, 6));
+ using var small = DecoderFactory.CreateServer().Decode(new DecodeRequest(path, MaxLongEdge: 300));
+ Assert.Equal(225, small!.Pixels.Width);
+ Assert.Equal(300, small.Pixels.Height);
+ Assert.Equal(1200, small.SourceWidth);
+ Assert.Equal(1600, small.SourceHeight);
+ using var stored = DecoderFactory.CreateServer().Decode(new DecodeRequest(path, MaxLongEdge: 300, ApplyOrientation: false));
+ Assert.Equal(300, stored!.Pixels.Width);
+ Assert.Equal(3, stored.Pixels.Channels);
+ }
+
+ [Test]
+ public void RawFastPathsBinAndFit()
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var path = Write("f.dng", SyntheticDng.Write(scene, new DngSpec()));
+ using var thumb = DecoderFactory.CreateServer().Decode(new DecodeRequest(path, MaxLongEdge: 40, Purpose: DecodePurpose.Thumbnail));
+ Assert.Equal(40, thumb!.Pixels.Width);
+ Assert.Equal(27, thumb.Pixels.Height);
+ Assert.Equal(W, thumb.SourceWidth);
+ using var expected = Resampler.Resize(scene, 40, 27, ResampleFilter.Box);
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(expected, thumb.Pixels, 1), 35);
+ }
+
+ [Test]
+ public void PngAndTiffDecodeToRgb()
+ {
+ using var gray = new ImageBuffer(20, 10, 1);
+ gray.Plane(0).Fill(0.25f);
+ var png = Write("g.png", PngEncoder.Encode(gray));
+ using var p = DecoderFactory.CreateServer().Decode(new DecodeRequest(png));
+ Assert.Equal(3, p!.Pixels.Channels);
+ Assert.Approximately(0.25, p.Pixels[2, 5, 5], 0.01);
+ var tif = Write("g.tif", TiffWriter.Write(gray));
+ using var t = DecoderFactory.CreateServer().Decode(new DecodeRequest(tif, MaxLongEdge: 10));
+ Assert.Equal(3, t!.Pixels.Channels);
+ Assert.Equal(10, t.Pixels.Width);
+ Assert.Equal("managed-tiff", t.Decoder);
+ }
+
+ [Test]
+ public void CorruptedRawFilesOnlyRaiseInvalidDataOrReturnNull()
+ {
+ var file = Cr2File("Canon EOS 5D Mark III");
+ var provider = new ManagedDecoderProvider();
+ var random = new Random(17);
+ for (var i = 0; i < 60; i++)
+ {
+ var variant = i < 20 ? file[..(file.Length * i / 20)] : (byte[])file.Clone();
+ if (i >= 20)
+ {
+ for (var k = 0; k < 3; k++) variant[random.Next(variant.Length)] = (byte)random.Next(256);
+ }
+ var path = Write($"fuzz{i}.cr2", variant);
+ try
+ {
+ provider.Probe(path);
+ using var image = provider.Decode(new DecodeRequest(path, MaxLongEdge: i % 2 == 0 ? 0 : 32, Purpose: DecodePurpose.Thumbnail));
+ }
+ catch (InvalidDataException)
+ {
+ }
+ catch (Exception ex)
+ {
+ Assert.Fail($"variant {i}: {ex.GetType().Name}: {ex.Message}\n{ex.StackTrace}");
+ }
+ }
+ }
+
+ /// A Windows-like provider claiming native support for everything but declining every file.
+ private sealed class FakeProvider : IImageDecoderProvider
+ {
+ public int Calls { get; private set; }
+ public string Name => "fake";
+ public DecodeTier? TierFor(ImageFileFormat format) => format is ImageFileFormat.Jpeg or ImageFileFormat.Cr3 ? DecodeTier.Native : null;
+
+ public DecodedImage? Decode(DecodeRequest request, CancellationToken cancellationToken = default)
+ {
+ Calls++;
+ return null;
+ }
+ }
+}
diff --git a/tests/Titano.Core.Tests/Decoding/ThumbnailTests.cs b/tests/Titano.Core.Tests/Decoding/ThumbnailTests.cs
new file mode 100644
index 00000000..7690ef7c
--- /dev/null
+++ b/tests/Titano.Core.Tests/Decoding/ThumbnailTests.cs
@@ -0,0 +1,277 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Imaging;
+using Titano.Core.Imaging.Decoders;
+using Titano.Core.Imaging.Thumbnails;
+using Titano.Core.Metadata;
+using Titano.Core.Model;
+using Titano.Core.Tests.Raw;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Decoding;
+
+/// format behaviour, and .
+public sealed class ThumbnailTests(TestContext context)
+{
+ private readonly string _dir = context.CreateTempDirectory();
+
+ private static ImageBuffer Frame(int seed, int width = 400, int height = 300)
+ {
+ var image = new ImageBuffer(width, height);
+ for (var y = 0; y < height; y++)
+ {
+ for (var x = 0; x < width; x++)
+ {
+ image[0, x, y] = (x + seed * 13) % 97 / 96f;
+ image[1, x, y] = (y + seed * 7) % 89 / 88f;
+ image[2, x, y] = seed % 5 / 5f;
+ }
+ }
+ return image;
+ }
+
+ /// Small distinct JPEGs (cheap to make in bulk).
+ private static byte[] Jpeg(int seed)
+ {
+ using var image = Frame(seed, 40, 30);
+ return JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = 80 });
+ }
+
+ private static Guid Id(int i) => new(i, 0, 0, [0, 0, 0, 0, 0, 0, 0, 1]);
+
+ [Test]
+ public void RoundTripAppendAndReplace()
+ {
+ var path = Path.Combine(_dir, "thumbs.pack");
+ using (var pack = ThumbnailPack.Open(path))
+ {
+ for (var i = 0; i < 20; i++)
+ {
+ using var frame = Frame(i);
+ var e = pack.Add(Id(i), frame);
+ Assert.Equal(320, e.Width);
+ Assert.Equal(240, e.Height);
+ }
+ }
+ using (var pack = ThumbnailPack.Open(path))
+ {
+ Assert.Equal(20, pack.Count);
+ Assert.Empty(pack.Warnings);
+ for (var i = 20; i < 25; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30);
+ pack.AddJpeg(Id(3), Jpeg(1000), 40, 30);
+ }
+ using var reader = ThumbnailPack.Open(path, writable: false);
+ Assert.Equal(25, reader.Count);
+ Assert.BytesEqual(Jpeg(1000), reader.ReadJpeg(Id(3)));
+ Assert.BytesEqual(Jpeg(22), reader.ReadJpeg(Id(22)));
+ var thumb = Thumbnail.FromJpeg(reader.ReadJpeg(Id(7))!);
+ Assert.Equal(320, thumb.Width);
+ Assert.Null(reader.ReadJpeg(Id(99)));
+ Assert.Greater(reader.WastedBytes, 0);
+ }
+
+ [Test]
+ public void EntriesAfterTheLastIndexAreRecovered()
+ {
+ var path = Path.Combine(_dir, "crash.pack");
+ var copy = Path.Combine(_dir, "crash-copy.pack");
+ var count = ThumbnailPack.IndexInterval + 6;
+ using (var pack = ThumbnailPack.Open(path))
+ {
+ for (var i = 0; i < count; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30);
+ // Simulated crash: the file as it is before the closing index write.
+ File.Copy(path, copy);
+ }
+ using var recovered = ThumbnailPack.Open(copy, writable: false);
+ Assert.Equal(count, recovered.Count);
+ Assert.Contains(recovered.Warnings, w => w.Contains("Recovered 6"));
+ Assert.BytesEqual(Jpeg(count - 1), recovered.ReadJpeg(Id(count - 1)));
+ }
+
+ [Test]
+ public void TruncatedAndDamagedFilesOpen()
+ {
+ var path = Path.Combine(_dir, "full.pack");
+ using (var pack = ThumbnailPack.Open(path))
+ {
+ for (var i = 0; i < 40; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30);
+ }
+ var bytes = File.ReadAllBytes(path);
+ for (var cut = 0; cut <= 40; cut++)
+ {
+ var file = Path.Combine(_dir, $"cut{cut}.pack");
+ File.WriteAllBytes(file, bytes[..(int)((long)bytes.Length * cut / 40)]);
+ using var pack = ThumbnailPack.Open(file, writable: false);
+ foreach (var id in pack.FrameIds) Assert.NotNull(pack.ReadJpeg(id));
+ Assert.LessOrEqual(pack.Count, 40);
+ }
+ // A damaged newest header slot falls back to the other one (or a scan).
+ var damaged = (byte[])bytes.Clone();
+ for (var i = 0; i < 128; i++) damaged[i] ^= 0x5A;
+ var damagedPath = Path.Combine(_dir, "damaged.pack");
+ File.WriteAllBytes(damagedPath, damaged);
+ using (var pack = ThumbnailPack.Open(damagedPath, writable: false))
+ {
+ Assert.Equal(40, pack.Count);
+ Assert.Contains(pack.Warnings, w => w.Contains("No valid header"));
+ }
+ // A flipped JPEG byte is caught by its CRC on read.
+ var flipped = (byte[])bytes.Clone();
+ flipped[128 + 40] ^= 0xFF;
+ var flippedPath = Path.Combine(_dir, "flipped.pack");
+ File.WriteAllBytes(flippedPath, flipped);
+ using var f = ThumbnailPack.Open(flippedPath, writable: false);
+ Assert.Null(f.ReadJpeg(Id(0)));
+ Assert.NotNull(f.ReadJpeg(Id(1)));
+ }
+
+ [Test]
+ public void CompactionDropsDeadEntries()
+ {
+ var path = Path.Combine(_dir, "compact.pack");
+ using var pack = ThumbnailPack.Open(path);
+ for (var i = 0; i < 30; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30);
+ for (var i = 0; i < 10; i++) pack.AddJpeg(Id(i), Jpeg(i + 500), 40, 30);
+ for (var i = 25; i < 30; i++) Assert.True(pack.Remove(Id(i)));
+ pack.Flush();
+ var before = new FileInfo(path).Length;
+ var wasted = pack.WastedBytes;
+ pack.Compact();
+ var after = new FileInfo(path).Length;
+ context.Log($"compaction {before} → {after} bytes (wasted {wasted})");
+ Assert.Less(after, before - wasted / 2);
+ Assert.Equal(25, pack.Count);
+ Assert.Null(pack.ReadJpeg(Id(27)));
+ Assert.BytesEqual(Jpeg(503), pack.ReadJpeg(Id(3)));
+ pack.AddJpeg(Id(100), Jpeg(100), 40, 30);
+ pack.Flush();
+ using var reopened = ThumbnailPack.Open(path, writable: false);
+ Assert.Equal(26, reopened.Count);
+ Assert.Empty(reopened.Warnings);
+ Assert.BytesEqual(Jpeg(15), reopened.ReadJpeg(Id(15)));
+ }
+
+ [Test]
+ [Timeout(20_000)]
+ public async Task ConcurrentReadsWhileWriting()
+ {
+ var path = Path.Combine(_dir, "concurrent.pack");
+ var jpegs = Enumerable.Range(0, 200).Select(Jpeg).ToArray();
+ using var pack = ThumbnailPack.Open(path);
+ for (var i = 0; i < 10; i++) pack.AddJpeg(Id(i), jpegs[i], 40, 30);
+ pack.Flush();
+ using var done = new CancellationTokenSource();
+ var writer = Task.Run(() =>
+ {
+ for (var i = 10; i < 200; i++) pack.AddJpeg(Id(i), jpegs[i], 40, 30);
+ pack.Flush();
+ done.Cancel();
+ });
+ var readers = Enumerable.Range(0, 4).Select(r => Task.Run(() =>
+ {
+ var random = new Random(r);
+ var reads = 0;
+ while (!done.IsCancellationRequested || reads < 50)
+ {
+ var ids = pack.FrameIds.ToArray();
+ var id = ids[random.Next(ids.Length)];
+ var data = pack.ReadJpeg(id);
+ Assert.NotNull(data);
+ Assert.BytesEqual(jpegs[id.ToByteArray()[0] | id.ToByteArray()[1] << 8], data);
+ reads++;
+ }
+ return reads;
+ })).ToArray();
+ var other = Task.Run(() =>
+ {
+ using var view = ThumbnailPack.Open(path, writable: false);
+ while (!done.IsCancellationRequested)
+ {
+ view.Refresh();
+ foreach (var id in view.FrameIds) Assert.NotNull(view.ReadJpeg(id));
+ }
+ });
+ await Task.WhenAll([writer, other, .. readers]);
+ Assert.Equal(200, pack.Count);
+ context.Log($"reads: {string.Join(", ", readers.Select(r => r.Result))}");
+ }
+
+ [Test]
+ public async Task CacheEvictsLeastRecentlyUsedAndCoalescesLoads()
+ {
+ var cache = new ThumbnailCache(3 * (300 + 64));
+ Thumbnail T() => new(10, 10, new byte[300]);
+ cache.Set(1, T());
+ cache.Set(2, T());
+ cache.Set(3, T());
+ Assert.True(cache.TryGet(1, out _));
+ cache.Set(4, T());
+ Assert.False(cache.TryGet(2, out _));
+ Assert.True(cache.TryGet(1, out _));
+ Assert.Equal(3, cache.Count);
+ Assert.LessOrEqual(cache.Bytes, cache.Budget);
+ cache.Set(5, new Thumbnail(100, 100, new byte[30000]));
+ Assert.False(cache.TryGet(5, out _));
+
+ var loads = 0;
+ var gate = new TaskCompletionSource();
+ async Task Loader(int key, CancellationToken ct)
+ {
+ Interlocked.Increment(ref loads);
+ await gate.Task;
+ return Thumbnail.FromJpeg(Jpeg(key));
+ }
+ var large = new ThumbnailCache(1 << 20);
+ var requests = Enumerable.Range(0, 10).Select(_ => large.GetOrLoadAsync(42, Loader)).ToArray();
+ gate.SetResult();
+ var results = await Task.WhenAll(requests);
+ Assert.Equal(1, loads);
+ Assert.True(results.All(r => ReferenceEquals(r, results[0])));
+ Assert.Equal(40, results[0]!.Width);
+ Assert.True(large.TryGet(42, out _));
+ }
+
+ [Test]
+ public void ProxyCarriesUprightPixelsAndCaptureExif()
+ {
+ var captured = new DateTime(2025, 7, 14, 21, 3, 9, DateTimeKind.Unspecified).AddTicks(4_500_000);
+ var metadata = new FrameMetadata { Make = "TestCam", Model = "T1", Orientation = 6, CapturedAt = captured, UtcOffsetMinutes = 120, Iso = 800, ExposureTime = 1 / 250.0 };
+ using var image = Frame(1, 2000, 1500);
+ var exif = ExifWriter.BuildTiff(metadata);
+ var source = Path.Combine(_dir, "src.jpg");
+ File.WriteAllBytes(source, JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = 90, App1Segments = [[.. "Exif\0\0"u8, .. exif]] }));
+
+ var proxy = ProxyBuilder.Write(DecoderFactory.CreateServer(), source, Path.Combine(_dir, "proxy.jpg"), ProxySize.Edge1280);
+ Assert.NotNull(proxy);
+ Assert.Equal(960, proxy!.Width);
+ Assert.Equal(1280, proxy.Height);
+ Assert.Equal(DecodeTier.Native, proxy.Tier);
+ var back = MetadataReader.Read(Path.Combine(_dir, "proxy.jpg"));
+ Assert.Equal(captured, back.CapturedAt);
+ Assert.Equal(120, back.UtcOffsetMinutes);
+ Assert.Equal(TimestampSource.ExifOriginal, back.TimestampSource);
+ Assert.Equal(1, back.Orientation);
+ Assert.Equal("TestCam", back.Make);
+ Assert.Equal(800, back.Iso);
+ Assert.Equal(960, back.Width);
+ Assert.Equal(1280, back.Height);
+ var info = JpegDecoder.ReadInfo(proxy.Jpeg);
+ Assert.Equal(960, info.Width);
+
+ var full = ProxyBuilder.Build(DecoderFactory.CreateServer(), source, ProxySize.Full);
+ Assert.Equal(1500, full!.Width);
+ }
+
+ [Test]
+ public void ProxyOfAnUnsupportedRawUsesThePreviewTier()
+ {
+ using var scene = SyntheticRaw.Smooth(96, 64);
+ var active = new RawRect(24, 4, 120, 68);
+ var cr2 = NativeRawWriters.Cr2(NativeRawWriters.Sensor(scene, "Canon EOS 5D Mark III", CfaPattern.Bayer("RGGB"), 128, 72, 24, 4, 2048, 16383), active, 1, "Canon EOS R99");
+ var path = Path.Combine(_dir, "x.cr2");
+ File.WriteAllBytes(path, cr2);
+ var proxy = ProxyBuilder.Build(DecoderFactory.CreateServer(), path);
+ Assert.Equal(DecodeTier.EmbeddedPreview, proxy!.Tier);
+ Assert.Equal(64, proxy.Width);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Raw/DemosaicTests.cs b/tests/Titano.Core.Tests/Raw/DemosaicTests.cs
new file mode 100644
index 00000000..fda81076
--- /dev/null
+++ b/tests/Titano.Core.Tests/Raw/DemosaicTests.cs
@@ -0,0 +1,139 @@
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Imaging;
+using Titano.Core.Mathematics;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Raw;
+
+/// Demosaic accuracy against the full-colour scene a mosaic was sampled from.
+public sealed class DemosaicTests(TestContext context)
+{
+ /// Fujifilm X-Trans layout (6×6).
+ internal static readonly CfaPattern XTrans = new(6, 6,
+ [
+ 1, 1, 0, 1, 1, 2,
+ 1, 1, 2, 1, 1, 0,
+ 2, 0, 1, 0, 2, 1,
+ 1, 1, 2, 1, 1, 0,
+ 1, 1, 0, 1, 1, 2,
+ 0, 2, 1, 2, 0, 1,
+ ]);
+
+ /// Smooth colour scene modelled like a photograph: luminance texture at 10–30 px periods multiplied by a
+ /// slowly varying chroma field (high frequencies correlate across channels, as in natural images).
+ private static ImageBuffer Scene(int w, int h)
+ {
+ var image = new ImageBuffer(w, h);
+ for (var y = 0; y < h; y++)
+ {
+ for (var x = 0; x < w; x++)
+ {
+ var l = 0.3 + 0.1 * double.Sin(x * 0.31 + y * 0.12) + 0.06 * double.Sin(y * 0.45 - x * 0.2) + 0.04 * double.Cos((x - y) * 0.6);
+ image[0, x, y] = (float)(l * (1 + 0.35 * double.Sin(x * 0.02 + 0.5)));
+ image[1, x, y] = (float)(l * (1 + 0.15 * double.Cos(y * 0.03)));
+ image[2, x, y] = (float)(l * (1 + 0.35 * double.Cos(x * 0.015 - y * 0.02)));
+ }
+ }
+ return image;
+ }
+
+ internal static ImageBuffer Mosaic(ImageBuffer scene, CfaPattern cfa)
+ {
+ var m = new ImageBuffer(scene.Width, scene.Height, 1);
+ for (var y = 0; y < scene.Height; y++)
+ {
+ for (var x = 0; x < scene.Width; x++) m[0, x, y] = scene[cfa.ColorAt(x, y), x, y];
+ }
+ return m;
+ }
+
+ [Theory]
+ [Case("RGGB")]
+ [Case("GBRG")]
+ public void AhdAndBilinearMeetTheirAccuracyGates(string layout)
+ {
+ var cfa = CfaPattern.Bayer(layout);
+ using var scene = Scene(256, 192);
+ using var mosaic = Mosaic(scene, cfa);
+ using var ahd = AhdDemosaic.Run(mosaic, cfa, Matrix3.Rec709ToXyz, -1, default);
+ using var bilinear = Demosaic.Bilinear(mosaic, cfa, -1, default);
+ var pAhd = SyntheticRaw.Psnr(scene, ahd, 2);
+ var pBilinear = SyntheticRaw.Psnr(scene, bilinear, 2);
+ context.Log($"{layout}: AHD {pAhd:F1} dB, bilinear {pBilinear:F1} dB");
+ Assert.GreaterOrEqual(pAhd, 38);
+ Assert.GreaterOrEqual(pBilinear, 32);
+ Assert.Greater(pAhd, pBilinear);
+ }
+
+ [Test]
+ public void AhdDoesNotZipperAlongEdges()
+ {
+ var cfa = CfaPattern.Bayer("RGGB");
+ using var scene = SyntheticRaw.Edges(128, 128);
+ using var mosaic = Mosaic(scene, cfa);
+ using var ahd = AhdDemosaic.Run(mosaic, cfa, Matrix3.Rec709ToXyz, -1, default);
+ using var bilinear = Demosaic.Bilinear(mosaic, cfa, -1, default);
+ var (zipAhd, fringeAhd) = EdgeArtefacts(ahd);
+ var (zipBilinear, fringeBilinear) = EdgeArtefacts(bilinear);
+ context.Log($"zipper AHD {zipAhd:F5} bilinear {zipBilinear:F5}; fringe AHD {fringeAhd:F5} bilinear {fringeBilinear:F5}");
+ Assert.Less(zipAhd, 0.002);
+ Assert.Less(fringeAhd, 0.002);
+ Assert.Less(fringeAhd, fringeBilinear);
+ }
+
+ [Test]
+ public void XTransNeighbourhoodInterpolationAndBinning()
+ {
+ using var scene = Scene(240, 180);
+ using var mosaic = Mosaic(scene, XTrans);
+ Assert.Equal(3, XTrans.BinSize);
+ Assert.False(XTrans.IsBayer);
+ using var full = Demosaic.Neighbourhood(mosaic, XTrans, -1, default);
+ var psnr = SyntheticRaw.Psnr(scene, full, 2);
+ using var third = Demosaic.Bin(mosaic, XTrans, 3, -1, default);
+ using var expected = Resampler.Resize(scene, 80, 60, ResampleFilter.Box);
+ var binned = SyntheticRaw.Psnr(expected, third, 1);
+ context.Log($"X-Trans neighbourhood {psnr:F1} dB, binned {binned:F1} dB");
+ Assert.GreaterOrEqual(psnr, 34);
+ Assert.GreaterOrEqual(binned, 34);
+ }
+
+ [Test]
+ public void PatternReductionAndShift()
+ {
+ var bayer = new CfaPattern(4, 4, [0, 1, 0, 1, 1, 2, 1, 2, 0, 1, 0, 1, 1, 2, 1, 2]);
+ Assert.Equal(2, bayer.Width);
+ Assert.True(bayer.IsBayer);
+ Assert.Equal("RGGB", bayer.ToString());
+ Assert.Equal("GRBG", bayer.Shift(1, 0).ToString());
+ Assert.Equal("BGGR", bayer.Shift(-1, -1).ToString());
+ Assert.Throws(() => new CfaPattern(2, 2, [0, 1, 1, 1]));
+ Assert.Throws(() => new CfaPattern(2, 2, [0, 1, 3, 2]));
+ }
+
+ /// Zipper: second difference along each edge; fringe: chroma |R−G| + |B−G| next to the edges of a gray scene.
+ private static (double Zipper, double Fringe) EdgeArtefacts(ImageBuffer image)
+ {
+ double zipper = 0, fringe = 0;
+ var n = 0;
+ int w = image.Width, h = image.Height;
+ for (var d = -2; d <= 1; d++)
+ {
+ for (var k = 8; k < h - 8; k++)
+ {
+ if (k is > 56 and < 72) continue;
+ // Vertical edge at x = w/2 (columns w/2-2 .. w/2+1), and horizontal edge at y = h/2.
+ int vx = w / 2 + d, hy = h / 2 + d;
+ for (var c = 0; c < 3; c++)
+ {
+ zipper += double.Abs(image[c, vx, k] - (image[c, vx, k - 1] + image[c, vx, k + 1]) / 2);
+ zipper += double.Abs(image[c, k, hy] - (image[c, k - 1, hy] + image[c, k + 1, hy]) / 2);
+ }
+ fringe += double.Abs(image[0, vx, k] - image[1, vx, k]) + double.Abs(image[2, vx, k] - image[1, vx, k]);
+ fringe += double.Abs(image[0, k, hy] - image[1, k, hy]) + double.Abs(image[2, k, hy] - image[1, k, hy]);
+ n += 2;
+ }
+ }
+ return (zipper / (3 * n), fringe / n);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Raw/DngDecoderTests.cs b/tests/Titano.Core.Tests/Raw/DngDecoderTests.cs
new file mode 100644
index 00000000..9fd8f8e0
--- /dev/null
+++ b/tests/Titano.Core.Tests/Raw/DngDecoderTests.cs
@@ -0,0 +1,277 @@
+using Titano.Core.Codecs.Dng;
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Imaging;
+using Titano.Core.Mathematics;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Raw;
+
+/// Synthetic DNG round trips: a known linear scene is mosaicked through a known camera model, written with the
+/// DNG feature under test, decoded, and compared with the scene.
+public sealed class DngDecoderTests(TestContext context)
+{
+ private const int W = 96, H = 72;
+
+ private static RawDecodeResult Decode(byte[] dng, RawDecodeOptions? options = null) =>
+ RawDecoder.Decode(new MemoryStream(dng), "test.dng", options);
+
+ [Theory]
+ [Case("RGGB")]
+ [Case("BGGR")]
+ [Case("GRBG")]
+ [Case("GBRG")]
+ public void BayerPatternsRoundTrip(string layout)
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var dng = SyntheticDng.Write(scene, new DngSpec { Cfa = CfaPattern.Bayer(layout) });
+ using var result = Decode(dng);
+ Assert.Equal(W, result.Image.Width);
+ Assert.Equal(H, result.Image.Height);
+ Assert.Equal(layout, result.Info.Layout);
+ var psnr = SyntheticRaw.Psnr(scene, result.Image, 4);
+ var de = SyntheticRaw.MeanDeltaE(scene, result.Image, 4);
+ context.Log($"{layout}: PSNR {psnr:F1} dB, mean ΔE {de:F2}");
+ Assert.GreaterOrEqual(psnr, 40);
+ Assert.Less(de, 1.0);
+ }
+
+ [Theory]
+ [Case(1, false)]
+ [Case(7, false)]
+ [Case(7, true)]
+ [Case(8, false)]
+ public void CompressionsDecodeIdentically(int compression, bool twoComponents)
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ using var reference = Decode(SyntheticDng.Write(scene, new DngSpec { Compression = 1 }));
+ using var result = Decode(SyntheticDng.Write(scene, new DngSpec { Compression = compression, TwoComponentTiles = twoComponents, RawInSubIfd = true }));
+ Assert.Empty(result.Warnings);
+ Assert.SequenceEqual(reference.Image.Data.ToArray(), result.Image.Data.ToArray());
+ }
+
+ [Test]
+ public void LossyJpegTilesWithLinearizationTable()
+ {
+ // Compression 34892: 8-bit JPEG tiles of sRGB-shaped codes, mapped back to linear by a 256-entry table.
+ var table = Enumerable.Range(0, 256).Select(i => (ushort)double.Round(ColorSpace.SrgbToLinear(i / 255.0) * 16383)).ToArray();
+ using var scene = SyntheticRaw.Smooth(W, H);
+ using var result = Decode(SyntheticDng.Write(scene, new DngSpec { Cfa = null, Compression = 34892, Linearization = table, Black = [0], TileSize = 32 }));
+ var psnr = SyntheticRaw.Psnr(scene, result.Image, 0);
+ context.Log($"lossy JPEG DNG: PSNR {psnr:F1} dB");
+ Assert.GreaterOrEqual(psnr, 36);
+ }
+
+ [Theory]
+ [Case(false)]
+ [Case(true)]
+ public void FloatingPointPredictorWithDeflate(bool mosaic)
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ using var result = Decode(SyntheticDng.Write(scene, new DngSpec { Cfa = mosaic ? CfaPattern.Bayer("RGGB") : null, FloatingPoint = true }));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 4), mosaic ? 40 : 60);
+ }
+
+ [Test]
+ public void CameraCalibrationAndAnalogBalanceEnterTheColourTransform()
+ {
+ var cc = Matrix3.Diagonal(1.08, 1.0, 0.93);
+ var ab = new Vector3D(1.05, 1.0, 0.97);
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var spec = new DngSpec
+ {
+ Cfa = null,
+ CameraCalibration1 = cc,
+ AnalogBalance = ab,
+ CaptureMatrix = Matrix3.Diagonal(ab.X, ab.Y, ab.Z) * cc * SyntheticRaw.CameraMatrix,
+ };
+ using var result = Decode(SyntheticDng.Write(scene, spec));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 0), 55);
+ }
+
+ [Test]
+ public void ValueMappingOpcodesInListThreeSeeUnbalancedValues()
+ {
+ // Stored halved; MapPolynomial ×2 in OpcodeList3 restores the scene only if applied before white balance.
+ var ops = new OpcodeListBuilder().Add(8, 0, p =>
+ {
+ OpcodeListBuilder.Area(p, 0, 0, H, W, planes: 3);
+ p.U32(1).F64(0).F64(2);
+ }).Build();
+ using var scene = SyntheticRaw.Smooth(W, H);
+ using var result = Decode(SyntheticDng.Write(scene, new DngSpec { Cfa = null, OpcodeList3 = ops, RawTransform = (_, _, v) => v / 2 }));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 0), 55);
+ }
+
+ [Test]
+ public void LinearRawRoundTripsExactly()
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ using var result = Decode(SyntheticDng.Write(scene, new DngSpec { Cfa = null }));
+ Assert.Equal("linear", result.Info.Layout);
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 0), 60);
+ }
+
+ [Test]
+ public void BlackLevelPatternAndDeltasAreSubtracted()
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var deltaH = Enumerable.Range(0, W).Select(x => (double)(x % 7)).ToArray();
+ var deltaV = Enumerable.Range(0, H).Select(y => y * 0.5).ToArray();
+ var spec = new DngSpec { BlackRows = 2, BlackColumns = 2, Black = [500, 520, 530, 510], BlackDeltaH = deltaH, BlackDeltaV = deltaV, MarginLeft = 4, MarginTop = 2 };
+ using var result = Decode(SyntheticDng.Write(scene, spec));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 4), 40);
+ }
+
+ [Test]
+ public void LinearizationTableIsApplied()
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ // 4096 codes covering 0..16383 with a square law: dense in the shadows, sparse in the highlights.
+ var table = Enumerable.Range(0, 4096).Select(i => (ushort)double.Round(16383.0 * i * i / (4095.0 * 4095.0))).ToArray();
+ using var result = Decode(SyntheticDng.Write(scene, new DngSpec { Linearization = table, Black = [0] }));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 4), 38);
+ }
+
+ [Test]
+ public void ActiveAreaAndDefaultCropSelectTheImage()
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var spec = new DngSpec { MarginLeft = 6, MarginTop = 4, MarginRight = 2, MarginBottom = 3, Crop = new RawRect(8, 6, 8 + 64, 6 + 48) };
+ using var result = Decode(SyntheticDng.Write(scene, spec));
+ Assert.Equal(64, result.Image.Width);
+ Assert.Equal(48, result.Image.Height);
+ Assert.Equal(64, result.Info.Width);
+ using var expected = Crop(scene, 8, 6, 64, 48);
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(expected, result.Image, 2), 40);
+ }
+
+ [Theory]
+ [Case(false)]
+ [Case(true)]
+ public void WhiteBalanceFromAsShotNeutralOrWhiteXy(bool whiteXy)
+ {
+ // Scene lit by tungsten (2850 K): decoding must adapt it back to the D65 scene.
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var tungsten = new Chromaticity(0.44757, 0.40745);
+ using var result = Decode(SyntheticDng.Write(scene, new DngSpec { SceneWhite = tungsten, WriteWhiteXy = whiteXy }));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 4), 38);
+ Assert.Less(SyntheticRaw.MeanDeltaE(scene, result.Image, 4), 1.5);
+ }
+
+ [Test]
+ public void DualIlluminantMatricesInterpolateByTemperature()
+ {
+ var profile = new DngColorProfile
+ {
+ ColorMatrix1 = SyntheticRaw.TungstenMatrix,
+ CalibrationIlluminant1 = 17,
+ ColorMatrix2 = SyntheticRaw.CameraMatrix,
+ CalibrationIlluminant2 = 21,
+ };
+ var warm = new Chromaticity(0.44757, 0.40745);
+ var mid = ColorTemperatureXy(4200);
+ Assert.Approximately(2850, DngColorProfile.Temperature(warm), 15);
+ Assert.Approximately(6504, DngColorProfile.Temperature(Chromaticity.D65), 30);
+ AssertMatrix(SyntheticRaw.TungstenMatrix, profile.XyzToCamera(warm), 1e-3);
+ AssertMatrix(SyntheticRaw.CameraMatrix, profile.XyzToCamera(Chromaticity.D65), 1e-9);
+ // Between the calibrations the weight is linear in inverse temperature.
+ var t = DngColorProfile.Temperature(mid);
+ var g = (1 / t - 1 / 6500.0) / (1 / 2850.0 - 1 / 6500.0);
+ Assert.Approximately(g * SyntheticRaw.TungstenMatrix.M11 + (1 - g) * SyntheticRaw.CameraMatrix.M11, profile.XyzToCamera(mid).M11, 1e-9);
+
+ // A DNG with both matrices, shot at 4200 K, decodes back to the scene.
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var spec = new DngSpec
+ {
+ ColorMatrix1 = SyntheticRaw.TungstenMatrix,
+ Illuminant1 = 17,
+ ColorMatrix2 = SyntheticRaw.CameraMatrix,
+ Illuminant2 = 21,
+ CaptureMatrix = profile.XyzToCamera(mid),
+ SceneWhite = mid,
+ };
+ using var result = Decode(SyntheticDng.Write(scene, spec));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 4), 38);
+ }
+
+ [Test]
+ public void ForwardMatrixMapsNeutralToWhite()
+ {
+ // ForwardMatrix = Rec.709 → XYZ(D50) with camera = linear Rec.709: a gray scene must stay gray.
+ var fm = Matrix3.BradfordAdaptation(Chromaticity.D65.ToXyz(), Chromaticity.D50.ToXyz()) * Matrix3.Rec709ToXyz;
+ using var scene = new ImageBuffer(32, 32);
+ scene.Data.Fill(0.4f);
+ var spec = new DngSpec { Cfa = null, ColorMatrix1 = Matrix3.XyzToRec709, ForwardMatrix1 = fm };
+ using var result = Decode(SyntheticDng.Write(scene, spec));
+ for (var c = 0; c < 3; c++) Assert.Approximately(0.4, result.Image[c, 16, 16], 2e-3);
+ }
+
+ [Test]
+ public void BaselineExposureScalesOutput()
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ using var plain = Decode(SyntheticDng.Write(scene, new DngSpec { Cfa = null }));
+ using var bright = Decode(SyntheticDng.Write(scene, new DngSpec { Cfa = null, BaselineExposure = 1 }));
+ Assert.Approximately(2 * plain.Image[1, 40, 30], bright.Image[1, 40, 30], 1e-4);
+ }
+
+ [Theory]
+ [Case((ushort)6)]
+ [Case((ushort)3)]
+ public void OrientationIsApplied(ushort orientation)
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var dng = SyntheticDng.Write(scene, new DngSpec { Cfa = null, Orientation = orientation });
+ using var oriented = Decode(dng);
+ using var stored = Decode(dng, new RawDecodeOptions { ApplyOrientation = false });
+ using var expected = PixelConvert.ApplyOrientation(stored.Image, orientation);
+ Assert.Equal(expected.Width, oriented.Image.Width);
+ Assert.Equal(expected.Width, oriented.Info.Width);
+ Assert.SequenceEqual(expected.Data.ToArray(), oriented.Image.Data.ToArray());
+ }
+
+ [Theory]
+ [Case(DemosaicQuality.Best)]
+ [Case(DemosaicQuality.Draft)]
+ public void BinningHalvesTheSize(DemosaicQuality quality)
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ using var result = Decode(SyntheticDng.Write(scene, new DngSpec()), new RawDecodeOptions { MaxLongEdge = W / 2, Quality = quality });
+ Assert.Equal(W / 2, result.Image.Width);
+ Assert.Equal(H / 2, result.Image.Height);
+ using var expected = Resampler.Resize(scene, W / 2, H / 2, ResampleFilter.Box);
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(expected, result.Image, 1), 34);
+ }
+
+ [Test]
+ public void ProbeDescribesWithoutDecoding()
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var dng = SyntheticDng.Write(scene, new DngSpec { Orientation = 6, Crop = new RawRect(2, 2, 66, 50) });
+ var probe = RawDecoder.Probe(new MemoryStream(dng), "x.dng");
+ Assert.True(probe.IsSupported);
+ Assert.Equal(48, probe.Info!.Width);
+ Assert.Equal(64, probe.Info.Height);
+ Assert.Equal("managed-dng", probe.Info.Decoder);
+ Assert.Equal("Synthetic", probe.Info.Model);
+ }
+
+ internal static ImageBuffer Crop(ImageBuffer source, int x0, int y0, int w, int h)
+ {
+ var result = new ImageBuffer(w, h, source.Channels);
+ for (var c = 0; c < source.Channels; c++)
+ {
+ for (var y = 0; y < h; y++) source.Row(c, y0 + y).Slice(x0, w).CopyTo(result.Row(c, y));
+ }
+ return result;
+ }
+
+ private static Chromaticity ColorTemperatureXy(double kelvin) => Titano.Core.Analysis.ColorTemperature.PlanckianChromaticity(kelvin);
+
+ private static void AssertMatrix(Matrix3 expected, Matrix3 actual, double tolerance)
+ {
+ double[] e = [expected.M11, expected.M12, expected.M13, expected.M21, expected.M22, expected.M23, expected.M31, expected.M32, expected.M33];
+ double[] a = [actual.M11, actual.M12, actual.M13, actual.M21, actual.M22, actual.M23, actual.M31, actual.M32, actual.M33];
+ for (var i = 0; i < 9; i++) Assert.Approximately(e[i], a[i], tolerance);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Raw/DngOpcodeTests.cs b/tests/Titano.Core.Tests/Raw/DngOpcodeTests.cs
new file mode 100644
index 00000000..07d242c2
--- /dev/null
+++ b/tests/Titano.Core.Tests/Raw/DngOpcodeTests.cs
@@ -0,0 +1,221 @@
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Imaging;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Raw;
+
+/// DNG opcode lists: raw data is distorted by the inverse of an opcode, the decoder must undo it.
+public sealed class DngOpcodeTests(TestContext context)
+{
+ private const int W = 96, H = 72;
+
+ private static RawDecodeResult Decode(byte[] dng) => RawDecoder.Decode(new MemoryStream(dng), "op.dng");
+
+ /// Bilinear grid interpolation as DNG §7 GainMap defines it (independent of the decoder's implementation).
+ private static double GainAt(double[,] grid, double spacingV, double spacingH, int x, int y)
+ {
+ int rows = grid.GetLength(0), cols = grid.GetLength(1);
+ double fr = double.Clamp(y / (double)H / spacingV, 0, rows - 1), fc = double.Clamp(x / (double)W / spacingH, 0, cols - 1);
+ int r0 = (int)fr, c0 = (int)fc, r1 = int.Min(r0 + 1, rows - 1), c1 = int.Min(c0 + 1, cols - 1);
+ double a = fr - r0, b = fc - c0;
+ return (grid[r0, c0] * (1 - b) + grid[r0, c1] * b) * (1 - a) + (grid[r1, c0] * (1 - b) + grid[r1, c1] * b) * a;
+ }
+
+ [Test]
+ public void GainMapRestoresShading()
+ {
+ double[,] grid = { { 1.6, 1.3, 1.6 }, { 1.2, 1.0, 1.25 }, { 1.7, 1.35, 1.5 } };
+ var ops = new OpcodeListBuilder().Add(9, 0, p =>
+ {
+ OpcodeListBuilder.Area(p, 0, 0, H, W);
+ p.U32(3).U32(3).F64(0.5).F64(0.5).F64(0).F64(0).U32(1);
+ for (var r = 0; r < 3; r++)
+ {
+ for (var c = 0; c < 3; c++) p.F32((float)grid[r, c]);
+ }
+ }).Build();
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var spec = new DngSpec { OpcodeList2 = ops, RawTransform = (x, y, v) => (float)(v / GainAt(grid, 0.5, 0.5, x, y)) };
+ using var result = Decode(SyntheticDng.Write(scene, spec));
+ Assert.Empty(result.Warnings);
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 4), 38);
+ }
+
+ [Test]
+ public void GainMapWithPitchTargetsOneCfaColour()
+ {
+ // Red sites of RGGB (even rows and columns) were attenuated by 1/1.5.
+ var ops = new OpcodeListBuilder().Add(9, 0, p =>
+ {
+ OpcodeListBuilder.Area(p, 0, 0, H, W, rowPitch: 2, colPitch: 2);
+ p.U32(1).U32(1).F64(1).F64(1).F64(0).F64(0).U32(1).F32(1.5f);
+ }).Build();
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var spec = new DngSpec { OpcodeList2 = ops, RawTransform = (x, y, v) => x % 2 == 0 && y % 2 == 0 ? v / 1.5f : v };
+ using var result = Decode(SyntheticDng.Write(scene, spec));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 4), 38);
+ }
+
+ [Test]
+ public void FixVignetteRadialRestoresFalloff()
+ {
+ double k0 = 0.4, k1 = 0.2;
+ var ops = new OpcodeListBuilder().Add(3, 0, p => p.F64(k0).F64(k1).F64(0).F64(0).F64(0).F64(0.5).F64(0.5)).Build();
+ var m = double.Hypot(W / 2.0, H / 2.0);
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var spec = new DngSpec
+ {
+ OpcodeList2 = ops,
+ RawTransform = (x, y, v) =>
+ {
+ var r2 = ((x - W / 2.0) * (x - W / 2.0) + (y - H / 2.0) * (y - H / 2.0)) / (m * m);
+ return (float)(v / (1 + k0 * r2 + k1 * r2 * r2));
+ },
+ };
+ using var result = Decode(SyntheticDng.Write(scene, spec));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 4), 38);
+ }
+
+ [Theory]
+ [Case(false)]
+ [Case(true)]
+ public void WarpRectilinearMovesPointsToTheirCorrectedPositions(bool mosaic)
+ {
+ // Corrected position p maps to source position f(p) (radial + tangential model, DNG §7 WarpRectilinear).
+ const int w = 160, h = 120;
+ double[] k = [1.0, 0.06, -0.01, 0.0, 0.002, -0.0015];
+ double cx = 0.48, cy = 0.53;
+ var ops = new OpcodeListBuilder().Add(1, 0, p =>
+ {
+ p.U32(1);
+ foreach (var v in k) p.F64(v);
+ p.F64(cx).F64(cy);
+ }).Build();
+ double ox = cx * w, oy = cy * h;
+ var m = new[] { (0.0, 0.0), (w, 0.0), (0.0, h), (w, h) }.Max(c => double.Hypot(c.Item1 - ox, c.Item2 - oy));
+ (double X, double Y) Source(double x, double y)
+ {
+ double dx = (x - ox) / m, dy = (y - oy) / m, r2 = dx * dx + dy * dy;
+ var f = k[0] + r2 * (k[1] + r2 * (k[2] + r2 * k[3]));
+ return (ox + m * (f * dx + k[4] * 2 * dx * dy + k[5] * (r2 + 2 * dx * dx)), oy + m * (f * dy + k[5] * 2 * dx * dy + k[4] * (r2 + 2 * dy * dy)));
+ }
+ (double X, double Y)[] targets = [(20, 18), (130, 25), (80, 60), (30, 100), (140, 104), (60, 40)];
+ using var distorted = new ImageBuffer(w, h);
+ foreach (var (tx, ty) in targets)
+ {
+ var (sx, sy) = Source(tx, ty);
+ for (var y = 0; y < h; y++)
+ {
+ for (var x = 0; x < w; x++)
+ {
+ var g = (float)(0.6 * double.Exp(-((x - sx) * (x - sx) + (y - sy) * (y - sy)) / (2 * 2.0 * 2.0)));
+ for (var c = 0; c < 3; c++) distorted[c, x, y] += g;
+ }
+ }
+ }
+ for (var i = 0; i < distorted.Data.Length; i++) distorted.Data[i] += 0.02f;
+ var spec = new DngSpec { Cfa = mosaic ? CfaPattern.Bayer("RGGB") : null, OpcodeList3 = ops };
+ using var result = Decode(SyntheticDng.Write(distorted, spec));
+ Assert.Empty(result.Warnings);
+ foreach (var (tx, ty) in targets)
+ {
+ var (x, y) = Centroid(result.Image, (int)tx, (int)ty, 6);
+ context.Log($"target ({tx}, {ty}) → ({x:F3}, {y:F3})");
+ Assert.Within(tx, ty, x, y, mosaic ? 0.2 : 0.1);
+ }
+ }
+
+ [Test]
+ public void TrimBoundsAndDefaultCropCompose()
+ {
+ var ops = new OpcodeListBuilder().Add(6, 0, p => p.U32(4).U32(10).U32(60).U32(90)).Build();
+ using var scene = SyntheticRaw.Smooth(W, H);
+ using var result = Decode(SyntheticDng.Write(scene, new DngSpec { OpcodeList3 = ops, Crop = new RawRect(0, 0, 80, 64) }));
+ Assert.Equal(70, result.Image.Width);
+ Assert.Equal(56, result.Image.Height);
+ using var expected = DngDecoderTests.Crop(scene, 10, 4, 70, 56);
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(expected, result.Image, 2), 38);
+ }
+
+ [Test]
+ public void FixBadPixelsConstantAndListRepairMosaic()
+ {
+ (int X, int Y)[] dead = [(10, 10), (41, 20), (70, 33)];
+ (int X, int Y)[] hot = [(30, 50), (55, 12)];
+ var list1 = new OpcodeListBuilder().Add(4, 0, p => p.U32(0).U32(0)).Build();
+ var list2 = new OpcodeListBuilder().Add(5, 0, p =>
+ {
+ p.U32(0).U32((uint)hot.Length).U32(1);
+ foreach (var (x, y) in hot) p.U32((uint)y).U32((uint)x);
+ p.U32(60).U32(80).U32(62).U32(83);
+ }).Build();
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var spec = new DngSpec
+ {
+ OpcodeList1 = list1,
+ OpcodeList2 = list2,
+ RawTransform = (x, y, v) => dead.Contains((x, y)) ? -1f : hot.Contains((x, y)) || (y is >= 60 and < 62 && x is >= 80 and < 83) ? 1f : v,
+ };
+ using var result = Decode(SyntheticDng.Write(scene, spec));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 4), 38);
+ }
+
+ [Test]
+ public void MapTableAndMapPolynomialInvertEncodings()
+ {
+ // Raw stored as v² is mapped back by a square-root table; then halved values are doubled by a polynomial.
+ var table = Enumerable.Range(0, 65536).Select(i => (ushort)double.Round(double.Sqrt(i / 65535.0) * 65535)).ToArray();
+ var ops = new OpcodeListBuilder()
+ .Add(7, 0, p =>
+ {
+ OpcodeListBuilder.Area(p, 0, 0, H, W);
+ p.U32((uint)table.Length);
+ foreach (var t in table) p.U16(t);
+ })
+ .Add(8, 0, p =>
+ {
+ OpcodeListBuilder.Area(p, 0, 0, H, W);
+ p.U32(1).F64(0).F64(2);
+ })
+ .Build();
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var spec = new DngSpec { Black = [0], OpcodeList2 = ops, RawTransform = (_, _, v) => float.Max(0, v / 2) * float.Max(0, v / 2) };
+ using var result = Decode(SyntheticDng.Write(scene, spec));
+ var psnr = SyntheticRaw.Psnr(scene, result.Image, 4);
+ context.Log($"MapTable+MapPolynomial PSNR {psnr:F1} dB");
+ Assert.GreaterOrEqual(psnr, 36);
+ }
+
+ [Test]
+ public void UnknownAndMalformedOpcodesWarnAndContinue()
+ {
+ var ops = new OpcodeListBuilder()
+ .Add(99, 1, p => p.U32(1))
+ .Add(98, 0, p => p.U32(1))
+ .Add(9, 0, p => p.U32(1))
+ .Build();
+ using var scene = SyntheticRaw.Smooth(W, H);
+ using var result = Decode(SyntheticDng.Write(scene, new DngSpec { OpcodeList3 = ops }));
+ Assert.Contains(result.Warnings, w => w.Contains("optional opcode 99"));
+ Assert.Contains(result.Warnings, w => w.Contains("required opcode 98"));
+ Assert.Contains(result.Warnings, w => w.Contains("GainMap") && w.Contains("malformed"));
+ Assert.GreaterOrEqual(SyntheticRaw.Psnr(scene, result.Image, 4), 40);
+ }
+
+ /// Intensity-weighted centroid above the background in a window around (x, y).
+ private static (double X, double Y) Centroid(ImageBuffer image, int cx, int cy, int radius)
+ {
+ double sum = 0, sx = 0, sy = 0;
+ for (var y = cy - radius; y <= cy + radius; y++)
+ {
+ for (var x = cx - radius; x <= cx + radius; x++)
+ {
+ var v = double.Max(0, image[1, x, y] - 0.05);
+ sum += v;
+ sx += v * x;
+ sy += v * y;
+ }
+ }
+ return (sx / sum, sy / sum);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Raw/HighlightTests.cs b/tests/Titano.Core.Tests/Raw/HighlightTests.cs
new file mode 100644
index 00000000..1f10dbfd
--- /dev/null
+++ b/tests/Titano.Core.Tests/Raw/HighlightTests.cs
@@ -0,0 +1,75 @@
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Imaging;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Raw;
+
+/// Clip-aware highlight reconstruction on decoded DNGs.
+public sealed class HighlightTests(TestContext context)
+{
+ private const int W = 96, H = 64;
+
+ /// Scene with three gray patches: unclipped (0.4), green clipped only (1.3) and fully clipped (3.0).
+ private static ImageBuffer Patches()
+ {
+ var scene = new ImageBuffer(W, H);
+ for (var y = 0; y < H; y++)
+ {
+ for (var x = 0; x < W; x++)
+ {
+ var v = x < 32 ? 0.4f : x < 64 ? 1.3f : 3.0f;
+ for (var c = 0; c < 3; c++) scene[c, x, y] = v;
+ }
+ }
+ return scene;
+ }
+
+ [Theory]
+ [Case(DemosaicQuality.Best, false)]
+ [Case(DemosaicQuality.Draft, true)]
+ public void ClippedGrayStaysNeutral(DemosaicQuality quality, bool binning)
+ {
+ using var scene = Patches();
+ var dng = SyntheticDng.Write(scene, new DngSpec());
+ using var result = RawDecoder.Decode(new MemoryStream(dng), "h.dng", new RawDecodeOptions { Quality = quality, MaxLongEdge = binning ? 1 : 0 });
+ var s = binning ? 2 : 1;
+ var (r0, g0, b0) = Pixel(result.Image, 16 / s, 32 / s);
+ var (r1, g1, b1) = Pixel(result.Image, 48 / s, 32 / s);
+ var (r2, g2, b2) = Pixel(result.Image, 80 / s, 32 / s);
+ context.Log($"0.4 → ({r0:F3}, {g0:F3}, {b0:F3}); 1.3 → ({r1:F3}, {g1:F3}, {b1:F3}); 3.0 → ({r2:F3}, {g2:F3}, {b2:F3})");
+
+ // Unclipped: exact.
+ Assert.Approximately(0.4, g0, 0.01);
+ Assert.Approximately(r0, b0, 0.01);
+
+ // Only green clipped: rebuilt from red and blue, neutral and at its true level (no magenta cast).
+ Assert.Approximately(1.3, g1, 0.03);
+ Assert.Approximately(1.3, r1, 0.03);
+ Assert.Approximately(1.3, b1, 0.03);
+
+ // Everything clipped: neutral, at least as bright as the partially clipped patch.
+ Assert.Approximately(r2, g2, 1e-3);
+ Assert.Approximately(b2, g2, 1e-3);
+ Assert.GreaterOrEqual(g2, g1);
+ }
+
+ [Test]
+ public void SaturatedColourKeepsItsHue()
+ {
+ // A red highlight clips the red channel while green and blue stay low: it must stay red, not turn white.
+ using var scene = new ImageBuffer(W, H);
+ for (var i = 0; i < scene.PlaneLength; i++)
+ {
+ scene.Plane(0)[i] = 5f;
+ scene.Plane(1)[i] = 0.15f;
+ scene.Plane(2)[i] = 0.1f;
+ }
+ using var result = RawDecoder.Decode(new MemoryStream(SyntheticDng.Write(scene, new DngSpec())), "red.dng");
+ var (r, g, b) = Pixel(result.Image, W / 2, H / 2);
+ context.Log($"red highlight → ({r:F3}, {g:F3}, {b:F3})");
+ Assert.Greater(r, 4 * g);
+ Assert.Greater(r, 4 * b);
+ }
+
+ private static (float R, float G, float B) Pixel(ImageBuffer image, int x, int y) => (image[0, x, y], image[1, x, y], image[2, x, y]);
+}
diff --git a/tests/Titano.Core.Tests/Raw/NativeRawTests.cs b/tests/Titano.Core.Tests/Raw/NativeRawTests.cs
new file mode 100644
index 00000000..f2ecac84
--- /dev/null
+++ b/tests/Titano.Core.Tests/Raw/NativeRawTests.cs
@@ -0,0 +1,183 @@
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Imaging;
+using Titano.Testing;
+using static Titano.Core.Tests.Raw.NativeRawWriters;
+
+namespace Titano.Core.Tests.Raw;
+
+/// Native RAW decoders on synthetic files written in each container's layout: the decoded image must match the
+/// scene the sensor data was generated from (camera matrix, as-shot white balance, black/white levels, crop).
+public sealed class NativeRawTests(TestContext context)
+{
+ private const int W = 96, H = 64;
+
+ private RawDecodeResult Decode(byte[] file, string name, RawDecodeOptions? options = null)
+ {
+ var result = RawDecoder.Decode(new MemoryStream(file), name, options);
+ context.Log($"{name}: {result.Info} warnings: {string.Join("; ", result.Warnings)}");
+ return result;
+ }
+
+ private static void AssertScene(ImageBuffer scene, ImageBuffer image, double minimum, TestContext context)
+ {
+ Assert.Equal(scene.Width, image.Width);
+ Assert.Equal(scene.Height, image.Height);
+ var psnr = SyntheticRaw.Psnr(scene, image, 4);
+ context.Log($"PSNR {psnr:F1} dB");
+ Assert.GreaterOrEqual(psnr, minimum);
+ }
+
+ [Test]
+ public void Cr2SlicedLosslessJpegWithMaskedBlack()
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ // 24 masked columns left and 4 rows on top; Canon's CFA is RGGB at the raster origin.
+ var active = new RawRect(24, 4, 24 + W, 4 + H);
+ var sensor = Sensor(scene, "Canon EOS 5D Mark III", CfaPattern.Bayer("RGGB"), 128, 72, active.Left, active.Top, 2048, 16383);
+ using var result = Decode(Cr2(sensor, active), "IMG_0001.CR2");
+ Assert.Equal("managed-cr2", result.Info.Decoder);
+ Assert.Equal("RGGB", result.Info.Layout);
+ AssertScene(scene, result.Image, 38, context);
+ }
+
+ [Theory]
+ [Case(NefEncoding.Lossless, 14)]
+ [Case(NefEncoding.Lossless, 12)]
+ [Case(NefEncoding.Unpacked, 12)]
+ [Case(NefEncoding.Packed, 12)]
+ public void NefEncodings(NefEncoding encoding, int bits)
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var sensor = Sensor(scene, "Nikon D850", CfaPattern.Bayer("RGGB"), W, H, 0, 0, 600 >> (14 - bits), (1 << bits) - 1);
+ using var result = Decode(Nef(sensor, bits, encoding), "DSC_0001.NEF");
+ Assert.Equal("managed-nef", result.Info.Decoder);
+ AssertScene(scene, result.Image, 38, context);
+ }
+
+ [Theory]
+ [Case(NefEncoding.LossyType1, 12, 0)]
+ [Case(NefEncoding.LossyType2, 14, 0)]
+ [Case(NefEncoding.LossyType2, 14, 40)]
+ public void NefLossyCurves(NefEncoding encoding, int bits, int split)
+ {
+ // A square-law curve: dense codes in the shadows, coarse in the highlights.
+ var size = encoding == NefEncoding.LossyType1 ? 683 : 1 << bits;
+ var curve = Enumerable.Range(0, size).Select(i => (ushort)double.Round(((1 << bits) - 1) * (i / (double)(size - 1)) * (i / (double)(size - 1)))).ToArray();
+ var white = encoding == NefEncoding.LossyType1 ? curve[^1] : InterpolatedCurve(curve, bits).Max();
+ // After the split row the tree has no unshifted codes for 9–12-bit differences: keep that scene gentle.
+ using var scene = split > 0 ? Gentle() : SyntheticRaw.Smooth(W, H);
+ var sensor = Sensor(scene, "Nikon D850", CfaPattern.Bayer("RGGB"), W, H, 0, 0, 600 >> (14 - bits), white);
+ using var result = Decode(Nef(sensor, bits, encoding, curve: curve, split: split), "DSC_0002.NEF");
+ AssertScene(scene, result.Image, 36, context);
+ }
+
+ [Theory]
+ [Case(true)]
+ [Case(false)]
+ public void ArwCompressedAndUncompressed(bool compressed)
+ {
+ ushort[] knots = [8000, 10400, 12900, 14100];
+ var curve = ToneCurve(knots);
+ double white = compressed ? curve[0x7FF << 1] : 16383;
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var sensor = Sensor(scene, "Sony ILCE-7M3", CfaPattern.Bayer("RGGB"), W, H, 0, 0, 512, white);
+ using var result = Decode(Arw(sensor, knots, compressed), "DSC00001.ARW");
+ Assert.Equal("managed-arw", result.Info.Decoder);
+ Assert.Contains(result.Warnings, w => w.Contains("daylight"));
+ AssertScene(scene, result.Image, compressed ? 36 : 38, context);
+ }
+
+ [Theory]
+ [Case(true)]
+ [Case(false)]
+ public void PefHuffmanAndUncompressed(bool compressed)
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var sensor = Sensor(scene, "Pentax K-1", CfaPattern.Bayer("BGGR"), W, H, 0, 0, 512, 16383);
+ using var result = Decode(Pef(sensor, 14, compressed), "IMGP0001.PEF");
+ Assert.Equal("managed-pef", result.Info.Decoder);
+ Assert.Equal("BGGR", result.Info.Layout);
+ AssertScene(scene, result.Image, 38, context);
+ }
+
+ [Theory]
+ [Case(true)]
+ [Case(false)]
+ public void RafXTransAndBayerLayouts(bool xtrans)
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var rasterCfa = xtrans ? DemosaicTests.XTrans : CfaPattern.Bayer("GRBG");
+ // Crop starts at an odd offset so the pattern must be re-anchored.
+ var crop = new RawRect(5, 3, 5 + W, 3 + H);
+ var sensor = Sensor(scene, "Fujifilm X-T2", rasterCfa, W + 8, H + 6, crop.Left, crop.Top, 1024, 16383);
+ using var result = Decode(Raf(sensor, Expand(rasterCfa), crop, orientation: 1), "DSCF0001.RAF");
+ Assert.Equal("managed-raf", result.Info.Decoder);
+ Assert.Equal("X-T2", result.Info.Model);
+ AssertScene(scene, result.Image, xtrans ? 34 : 38, context);
+ using var binned = Decode(Raf(sensor, Expand(rasterCfa), crop), "DSCF0001.RAF", new RawDecodeOptions { MaxLongEdge = 1 });
+ Assert.Equal(W / (xtrans ? 3 : 2), binned.Image.Width);
+ }
+
+ [Test]
+ public void OrientationComesFromTheContainer()
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var sensor = Sensor(scene, "Nikon D850", CfaPattern.Bayer("RGGB"), W, H, 0, 0, 600, 16383);
+ using var result = Decode(Nef(sensor, 14, NefEncoding.Lossless, orientation: 8), "DSC_0003.NEF");
+ Assert.Equal(H, result.Image.Width);
+ Assert.Equal(W, result.Image.Height);
+ Assert.Equal(H, result.Info.Width);
+ }
+
+ [Test]
+ public void UnknownBodyIsUnsupported()
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ var active = new RawRect(24, 4, 24 + W, 4 + H);
+ var sensor = Sensor(scene, "Canon EOS 5D Mark III", CfaPattern.Bayer("RGGB"), 128, 72, active.Left, active.Top, 2048, 16383);
+ var probe = RawDecoder.Probe(new MemoryStream(Cr2(sensor, active, model: "Canon EOS R99")), "x.cr2");
+ Assert.False(probe.IsSupported);
+ Assert.Contains("no colour matrix", probe.Reason);
+ Assert.Throws(() => RawDecoder.Decode(new MemoryStream(Cr2(sensor, active, model: "Canon EOS R99")), "x.cr2"));
+ }
+
+ [Test]
+ public void CameraNamesNormalise()
+ {
+ Assert.Equal("Nikon D850", NativeRaw.CameraName("NIKON CORPORATION", "NIKON D850"));
+ Assert.Equal("Canon EOS 5D Mark III", NativeRaw.CameraName("Canon", "Canon EOS 5D Mark III"));
+ Assert.Equal("Sony ILCE-7M3", NativeRaw.CameraName("SONY", "ILCE-7M3"));
+ Assert.Equal("Pentax K-1", NativeRaw.CameraName("RICOH IMAGING COMPANY, LTD.", "PENTAX K-1"));
+ Assert.Equal("Fujifilm X-T2", NativeRaw.CameraName("FUJIFILM", "X-T2"));
+ // Every tabulated matrix maps D65 to a positive camera neutral with green the strongest channel.
+ foreach (var name in CameraMatrices.Names)
+ {
+ var m = CameraMatrices.Find(name)!.Value;
+ var n = m * Titano.Core.Mathematics.Chromaticity.D65.ToXyz();
+ Assert.True(n.X > 0 && n.Z > 0 && n.Y > n.X && n.Y > n.Z, name);
+ }
+ }
+
+ private static ImageBuffer Gentle()
+ {
+ var scene = new ImageBuffer(W, H);
+ for (var y = 0; y < H; y++)
+ {
+ for (var x = 0; x < W; x++)
+ {
+ scene[0, x, y] = 0.3f + 0.03f * x / W;
+ scene[1, x, y] = 0.32f + 0.02f * y / H;
+ scene[2, x, y] = 0.25f + 0.01f * (x + y) / (W + H);
+ }
+ }
+ return scene;
+ }
+
+ /// The pattern written into the RAF layout record, expanded to 6×6.
+ private static CfaPattern Expand(CfaPattern cfa)
+ {
+ var colors = new byte[36];
+ for (var i = 0; i < 36; i++) colors[i] = (byte)cfa.ColorAt(i % 6, i / 6);
+ return new CfaPattern(6, 6, colors);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Raw/NativeRawWriters.cs b/tests/Titano.Core.Tests/Raw/NativeRawWriters.cs
new file mode 100644
index 00000000..4c566598
--- /dev/null
+++ b/tests/Titano.Core.Tests/Raw/NativeRawWriters.cs
@@ -0,0 +1,485 @@
+using System.Buffers.Binary;
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Imaging;
+using Titano.Core.Mathematics;
+using Titano.Core.Metadata;
+using Titano.Core.Metadata.Tiff;
+using Titano.Core.Tests.Metadata.Builders;
+
+namespace Titano.Core.Tests.Raw;
+
+/// Payload encodings of the synthetic NEF writer.
+public enum NefEncoding
+{
+ Lossless,
+ LossyType1,
+ LossyType2,
+ Unpacked,
+ Packed,
+}
+
+/// A synthetic sensor readout: stored samples of a scene through a camera model, plus the as-shot neutral.
+internal sealed record SensorData(ushort[] Samples, int Width, int Height, Vector3D Neutral);
+
+///
+/// Test-side writers for native RAW containers. Each follows the layout its reader documents (and dcraw/LibRaw decode):
+/// CR2 sliced lossless JPEG with Canon MakerNote, NEF Nikon Huffman with type-3 MakerNote, ARW2 cRAW blocks with tone
+/// curve, PEF Pentax Huffman with AOC MakerNote, RAF with FujiIFD and RAF directory.
+///
+internal static class NativeRawWriters
+{
+ /// Stored sensor values of placed at (left, top) of a raster, CFA anchored at the raster
+ /// origin, outside pixels at black.
+ public static SensorData Sensor(ImageBuffer scene, string camera, CfaPattern cfa, int width, int height, int left, int top, double black, double white)
+ {
+ var matrix = CameraMatrices.Find(camera) ?? throw new ArgumentException("No matrix for " + camera);
+ var (rgb, neutral) = SyntheticRaw.ToCamera(scene, matrix, Chromaticity.D65);
+ var samples = new ushort[width * height];
+ for (var y = 0; y < height; y++)
+ {
+ for (var x = 0; x < width; x++)
+ {
+ int sx = x - left, sy = y - top;
+ var v = black;
+ if (sx >= 0 && sy >= 0 && sx < scene.Width && sy < scene.Height) v += rgb[cfa.ColorAt(x, y)][sy * scene.Width + sx] * (white - black);
+ samples[y * width + x] = (ushort)double.Clamp(double.Round(v), 0, white);
+ }
+ }
+ return new SensorData(samples, width, height, neutral);
+ }
+
+ /// Real JPEG preview with an Exif block (make, model, orientation).
+ public static byte[] Preview(string make, string model, int orientation, int width = 64, int height = 48)
+ {
+ using var image = new ImageBuffer(width, height);
+ for (var i = 0; i < image.PlaneLength; i++)
+ {
+ image.Plane(0)[i] = 0.5f;
+ image.Plane(1)[i] = 0.3f;
+ image.Plane(2)[i] = 0.2f;
+ }
+ var exif = ExifWriter.BuildTiff(new FrameMetadata { Make = make, Model = model, Orientation = orientation });
+ return JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = 85, App1Segments = [[.. "Exif\0\0"u8, .. exif]] });
+ }
+
+ /// Canon CR2: "CR" header, IFD0 JPEG preview, two dummy IFDs, IFD3 lossless raw in two slices.
+ public static byte[] Cr2(SensorData s, RawRect active, int orientation = 1, string model = "Canon EOS 5D Mark III")
+ {
+ const int components = 2;
+ var sliceWidth = s.Width / 2;
+ var stream = new ushort[s.Samples.Length];
+ var k = 0;
+ foreach (var x0 in new[] { 0, sliceWidth })
+ {
+ for (var y = 0; y < s.Height; y++)
+ {
+ for (var x = 0; x < sliceWidth; x++) stream[k++] = s.Samples[y * s.Width + x0 + x];
+ }
+ }
+ var jpeg = JpegLosslessEncoder.Encode(stream, s.Width / components, s.Height, components, 14);
+ var sensor = new ushort[17];
+ sensor[1] = (ushort)s.Width;
+ sensor[2] = (ushort)s.Height;
+ sensor[5] = (ushort)active.Left;
+ sensor[6] = (ushort)active.Top;
+ sensor[7] = (ushort)(active.Right - 1);
+ sensor[8] = (ushort)(active.Bottom - 1);
+ var colorData = new ushort[1338];
+ colorData[63] = (ushort)double.Round(1024 * s.Neutral.Y / s.Neutral.X);
+ colorData[64] = colorData[65] = 1024;
+ colorData[66] = (ushort)double.Round(1024 * s.Neutral.Y / s.Neutral.Z);
+ var makerNote = new IfdSpec().Short(0x00E0, sensor).Short(0x4001, colorData);
+ var exif = new IfdSpec().Ascii(TiffTags.DateTimeOriginal, "2024:05:01 12:00:00").Embedded(TiffTags.MakerNote, [], makerNote, relativeToTiff: true, littleEndian: true);
+ var preview = Preview("Canon", model, orientation);
+ var ifd0 = new IfdSpec().Ascii(TiffTags.Make, "Canon").Ascii(TiffTags.Model, model).Short(TiffTags.Orientation, (ushort)orientation)
+ .Short(TiffTags.Compression, 6).Strip(preview).Child(TiffTags.ExifIfd, exif);
+ var ifd1 = new IfdSpec().Short(TiffTags.Compression, 6);
+ var ifd2 = new IfdSpec().Short(TiffTags.Compression, 1);
+ var ifd3 = new IfdSpec().Short(TiffTags.Compression, 6).Strip(jpeg).Short(0xC640, 1, (ushort)sliceWidth, (ushort)(s.Width - sliceWidth));
+ ifd0.Next = ifd1;
+ ifd1.Next = ifd2;
+ ifd2.Next = ifd3;
+ return TiffFile.Build(ifd0, true, headerExtra: [(byte)'C', (byte)'R', 2, 0, 0, 0, 0, 0]);
+ }
+
+ /// Canonical codes of a dcraw-layout Huffman specification: symbol → (code, length).
+ public static Dictionary Codes(byte[] spec)
+ {
+ var max = 16;
+ while (spec[max - 1] == 0) max--;
+ var codes = new Dictionary();
+ var h = 0;
+ var symbol = 16;
+ for (var len = 1; len <= max; len++)
+ {
+ for (var i = 0; i < spec[len - 1]; i++, symbol++)
+ {
+ codes.TryAdd(spec[symbol], (h >> (max - len), len));
+ h += 1 << (max - len);
+ }
+ }
+ return codes;
+ }
+
+ /// JPEG difference category and its bits (negative values one's-complement style).
+ public static (int Length, int Bits) Category(int diff)
+ {
+ if (diff == 0) return (0, 0);
+ var len = 32 - int.LeadingZeroCount(int.Abs(diff));
+ return (len, diff > 0 ? diff : diff + (1 << len) - 1);
+ }
+
+ /// Two-column horizontal prediction seeded by per-row-parity vertical predictors (Nikon and Pentax).
+ public static byte[] PredictiveHuffman(ushort[] values, int width, int height, Func> codesForRow, ushort[] initial)
+ {
+ var w = new BitWriter();
+ var vpred = (int[])[initial[0], initial[1], initial[2], initial[3]];
+ var hpred = new int[2];
+ for (var row = 0; row < height; row++)
+ {
+ var codes = codesForRow(row);
+ for (var col = 0; col < width; col++)
+ {
+ int v = values[row * width + col], predicted;
+ if (col < 2)
+ {
+ predicted = vpred[(row & 1) * 2 + col];
+ vpred[(row & 1) * 2 + col] = v;
+ hpred[col] = v;
+ }
+ else
+ {
+ predicted = hpred[col & 1];
+ hpred[col & 1] = v;
+ }
+ var (len, bits) = Category(v - predicted);
+ var (code, codeLength) = codes[len];
+ w.Write(code, codeLength);
+ w.Write(bits, len);
+ }
+ }
+ return w.ToArray();
+ }
+
+ /// Big-endian Nikon NEF: IFD0 thumbnail, SubIFD CFA raw, Exif with a type-3 MakerNote.
+ public static byte[] Nef(SensorData s, int bits, NefEncoding encoding, int orientation = 1, ushort[]? curve = null, int split = 0)
+ {
+ byte[] data;
+ uint compression = 34713;
+ var meta = new List { 0x46, 0x30 };
+ ushort[] vpred = [100, 200, 300, 400];
+ switch (encoding)
+ {
+ case NefEncoding.Lossless:
+ data = PredictiveHuffman(s.Samples, s.Width, s.Height, _ => Codes(NefTrees(bits == 14 ? 5 : 2)), vpred);
+ break;
+ case NefEncoding.LossyType1:
+ {
+ meta = [0x44, 0x10];
+ var indices = Indices(s.Samples, curve!);
+ data = PredictiveHuffman(indices, s.Width, s.Height, _ => Codes(NefTrees(bits == 14 ? 3 : 0)), vpred);
+ break;
+ }
+ case NefEncoding.LossyType2:
+ {
+ meta = [0x44, 0x20];
+ var indices = Indices(s.Samples, InterpolatedCurve(curve!, bits));
+ var tree = bits == 14 ? 3 : 0;
+ data = PredictiveHuffman(indices, s.Width, s.Height, row => Codes(NefTrees(split > 0 && row >= split ? tree + 1 : tree)), vpred);
+ break;
+ }
+ case NefEncoding.Unpacked:
+ data = new byte[s.Samples.Length * 2];
+ for (var i = 0; i < s.Samples.Length; i++) BinaryPrimitives.WriteUInt16BigEndian(data.AsSpan(2 * i), (ushort)(s.Samples[i] << 4));
+ break;
+ default:
+ compression = 1;
+ data = Packed(s.Samples, s.Width, s.Height, bits);
+ break;
+ }
+ foreach (var v in vpred) meta.AddRange([(byte)(v >> 8), (byte)v]);
+ if (encoding == NefEncoding.LossyType1)
+ {
+ meta.AddRange([(byte)(curve!.Length >> 8), (byte)curve.Length]);
+ foreach (var v in curve) meta.AddRange([(byte)(v >> 8), (byte)v]);
+ }
+ else if (encoding == NefEncoding.LossyType2)
+ {
+ // Curve sampled every 'step' codes; split row at byte 562.
+ meta.AddRange([(byte)(CurvePoints >> 8), unchecked((byte)CurvePoints)]);
+ foreach (var v in CurveSamples(curve!, bits)) meta.AddRange([(byte)(v >> 8), (byte)v]);
+ while (meta.Count < 562) meta.Add(0);
+ meta.AddRange([(byte)(split >> 8), (byte)split]);
+ }
+ else
+ {
+ meta.AddRange([0, 0]);
+ }
+ var nikon = new IfdSpec()
+ .Rational(0x000C, ((uint)double.Round(1e5 * s.Neutral.Y / s.Neutral.X), 100000u), ((uint)double.Round(1e5 * s.Neutral.Y / s.Neutral.Z), 100000u), (1u, 1u), (1u, 1u))
+ .Short(0x003D, 600, 600, 600, 600)
+ .Short(0x0093, (ushort)(encoding == NefEncoding.Lossless ? 3 : encoding == NefEncoding.LossyType1 ? 1 : encoding == NefEncoding.LossyType2 ? 4 : 2))
+ .Undefined(0x0096, [.. meta]);
+ var exif = new IfdSpec().Undefined(TiffTags.MakerNote, [.. "Nikon\0"u8, 2, 0x11, 0, 0, .. TiffFile.Build(nikon, littleEndian: false)]);
+ var raw = new IfdSpec().Long(TiffTags.NewSubfileType, 0)
+ .Long(TiffTags.ImageWidth, (uint)s.Width).Long(TiffTags.ImageLength, (uint)s.Height)
+ .Short(TiffTags.BitsPerSample, (ushort)bits).Short(TiffTags.Compression, (ushort)compression)
+ .Short(TiffTags.PhotometricInterpretation, 32803)
+ .Short(TiffTags.CfaRepeatPatternDim, 2, 2).Bytes(TiffTags.CfaPattern, 0, 1, 1, 2)
+ .Strip(data);
+ var ifd0 = new IfdSpec().Ascii(TiffTags.Make, "NIKON CORPORATION").Ascii(TiffTags.Model, "NIKON D850")
+ .Short(TiffTags.Orientation, (ushort)orientation).Long(TiffTags.NewSubfileType, 1)
+ .Child(TiffTags.SubIfds, raw).Child(TiffTags.ExifIfd, exif);
+ return TiffFile.Build(ifd0, littleEndian: false);
+ }
+
+ private static byte[] NefTrees(int index) => NefReader.Trees[index];
+
+ private const int CurvePoints = 257;
+
+ private static ushort[] CurveSamples(ushort[] curve, int bits)
+ {
+ var step = (1 << bits & 0x7FFF) / (CurvePoints - 1);
+ return [.. Enumerable.Range(0, CurvePoints).Select(i => curve[int.Min(i * step, curve.Length - 1)])];
+ }
+
+ /// The curve a lossy type-2 decoder rebuilds: samples every step codes, linearly interpolated.
+ public static ushort[] InterpolatedCurve(ushort[] curve, int bits)
+ {
+ var max = 1 << bits & 0x7FFF;
+ var step = max / (CurvePoints - 1);
+ var samples = CurveSamples(curve, bits);
+ var result = new ushort[max];
+ for (var i = 0; i < max; i++)
+ {
+ int k = i % step, a = i / step;
+ result[i] = (ushort)((samples[a] * (step - k) + samples[int.Min(a + 1, samples.Length - 1)] * k) / step);
+ }
+ return result;
+ }
+
+ /// Curve indices whose values are nearest to the samples (monotonic curve).
+ public static ushort[] Indices(ushort[] samples, ushort[] curve)
+ {
+ var result = new ushort[samples.Length];
+ for (var i = 0; i < samples.Length; i++)
+ {
+ var target = samples[i];
+ int lo = 0, hi = curve.Length - 1;
+ while (lo < hi)
+ {
+ var mid = (lo + hi) / 2;
+ if (curve[mid] < target) lo = mid + 1;
+ else hi = mid;
+ }
+ if (lo > 0 && target - curve[lo - 1] < curve[lo] - target) lo--;
+ result[i] = (ushort)lo;
+ }
+ return result;
+ }
+
+ /// MSB-first packed samples (TIFF convention), rows padded to whole bytes.
+ public static byte[] Packed(ushort[] samples, int width, int height, int bits)
+ {
+ var w = new BitWriter();
+ for (var y = 0; y < height; y++)
+ {
+ for (var x = 0; x < width; x++) w.Write(samples[y * width + x], bits);
+ w.Align();
+ }
+ return w.ToArray();
+ }
+
+ /// Sony ARW2 (cRAW): 16-pixel blocks of one colour in 32-column groups, values through the inverse tone curve.
+ public static byte[] Arw(SensorData s, ushort[] knots, bool compressed, int orientation = 1)
+ {
+ byte[] data;
+ uint compression = 32767;
+ if (compressed)
+ {
+ var curve = ToneCurve(knots);
+ var even = new ushort[2048];
+ for (var i = 0; i < even.Length; i++) even[i] = curve[i << 1];
+ var codes = Indices(s.Samples, even);
+ data = new byte[s.Width * s.Height];
+ for (var y = 0; y < s.Height; y++)
+ {
+ for (var group = 0; group < s.Width; group += 32)
+ {
+ for (var parity = 0; parity < 2; parity++)
+ {
+ var block = data.AsSpan(y * s.Width + group + parity * 16, 16);
+ var pix = new int[16];
+ for (var i = 0; i < 16; i++) pix[i] = codes[y * s.Width + group + parity + 2 * i];
+ EncodeBlock(pix, block);
+ }
+ }
+ }
+ }
+ else
+ {
+ data = new byte[s.Samples.Length * 2];
+ for (var i = 0; i < s.Samples.Length; i++) BinaryPrimitives.WriteUInt16LittleEndian(data.AsSpan(2 * i), s.Samples[i]);
+ }
+ var raw = new IfdSpec().Long(TiffTags.NewSubfileType, 0)
+ .Long(TiffTags.ImageWidth, (uint)s.Width).Long(TiffTags.ImageLength, (uint)s.Height)
+ .Short(TiffTags.BitsPerSample, (ushort)(compressed ? 8 : 14)).Short(TiffTags.Compression, (ushort)compression)
+ .Short(TiffTags.PhotometricInterpretation, 32803)
+ .Short(TiffTags.CfaRepeatPatternDim, 2, 2).Bytes(TiffTags.CfaPattern, 0, 1, 1, 2)
+ .Short(0x7010, knots).Short(0x7310, 512, 512, 512, 512)
+ .Strip(data);
+ var ifd0 = new IfdSpec().Ascii(TiffTags.Make, "SONY").Ascii(TiffTags.Model, "ILCE-7M3").Short(TiffTags.Orientation, (ushort)orientation)
+ .Long(TiffTags.NewSubfileType, 1).Child(TiffTags.SubIfds, raw);
+ return TiffFile.Build(ifd0);
+ }
+
+ /// The reader's tone curve (slopes 1, 2, 4, 8, 16 between the knots).
+ public static ushort[] ToneCurve(ushort[] knots)
+ {
+ int[] k = [0, knots[0] >> 2 & 0xFFF, knots[1] >> 2 & 0xFFF, knots[2] >> 2 & 0xFFF, knots[3] >> 2 & 0xFFF, 4095];
+ var curve = new ushort[4096];
+ for (var i = 0; i < curve.Length; i++) curve[i] = (ushort)i;
+ for (var i = 0; i < 5; i++)
+ {
+ for (var j = k[i] + 1; j <= k[i + 1]; j++) curve[j] = (ushort)(curve[j - 1] + (1 << i));
+ }
+ return curve;
+ }
+
+ private static void EncodeBlock(int[] pix, Span block)
+ {
+ int imax = 0, imin = 0;
+ for (var i = 1; i < 16; i++)
+ {
+ if (pix[i] > pix[imax]) imax = i;
+ if (pix[i] < pix[imin]) imin = i;
+ }
+ if (imax == imin) imin = imax == 0 ? 1 : 0;
+ int max = pix[imax], min = pix[imin];
+ var sh = 0;
+ while (sh < 4 && 0x80 << sh <= max - min) sh++;
+ var bits = new System.Collections.BitArray(130);
+ void Put(int value, int at, int count)
+ {
+ for (var b = 0; b < count; b++) bits[at + b] = (value >> b & 1) != 0;
+ }
+ Put(max, 0, 11);
+ Put(min, 11, 11);
+ Put(imax, 22, 4);
+ Put(imin, 26, 4);
+ var bit = 30;
+ for (var i = 0; i < 16; i++)
+ {
+ if (i == imax || i == imin) continue;
+ Put(int.Min((pix[i] - min) >> sh, 0x7F), bit, 7);
+ bit += 7;
+ }
+ for (var i = 0; i < 16; i++)
+ {
+ byte v = 0;
+ for (var b = 0; b < 8; b++) v |= (byte)(bits[i * 8 + b] ? 1 << b : 0);
+ block[i] = v;
+ }
+ }
+
+ /// Pentax PEF: big-endian, raw in IFD0, AOC MakerNote with black, WB and the Huffman table.
+ public static byte[] Pef(SensorData s, int bits, bool compressed, int orientation = 1)
+ {
+ // Prefix code over difference lengths 0..14 (Kraft sum below 1).
+ int[] lengths = [3, 3, 3, 3, 3, 4, 4, 5, 5, 6, 7, 8, 9, 10, 10];
+ var codes = new Dictionary();
+ var code = 0;
+ var previous = lengths[0];
+ for (var c = 0; c < lengths.Length; c++)
+ {
+ code <<= lengths[c] - previous;
+ previous = lengths[c];
+ codes[c] = (code, lengths[c]);
+ code++;
+ }
+ var table = new List { 0, (byte)((lengths.Length - 12) & 15) };
+ table.AddRange(new byte[12]);
+ for (var c = 0; c < lengths.Length; c++)
+ {
+ var aligned = codes[c].Code << (12 - codes[c].Length);
+ table.AddRange([(byte)(aligned >> 8), (byte)aligned]);
+ }
+ foreach (var len in lengths) table.Add((byte)len);
+ var data = compressed ? PredictiveHuffman(s.Samples, s.Width, s.Height, _ => codes, [0, 0, 0, 0]) : Packed(s.Samples, s.Width, s.Height, bits);
+ var levels = new ushort[] { (ushort)double.Round(1000 * s.Neutral.Y / s.Neutral.X), 1000, 1000, (ushort)double.Round(1000 * s.Neutral.Y / s.Neutral.Z) };
+ var pentax = new IfdSpec().Short(0x0200, 512, 512, 512, 512).Short(0x0201, levels).Undefined(0x0220, [.. table]);
+ var exif = new IfdSpec().Embedded(TiffTags.MakerNote, [.. "AOC\0MM"u8], pentax, relativeToTiff: true, littleEndian: false);
+ var ifd0 = new IfdSpec().Ascii(TiffTags.Make, "RICOH IMAGING COMPANY, LTD.").Ascii(TiffTags.Model, "PENTAX K-1")
+ .Short(TiffTags.Orientation, (ushort)orientation).Long(TiffTags.NewSubfileType, 0)
+ .Long(TiffTags.ImageWidth, (uint)s.Width).Long(TiffTags.ImageLength, (uint)s.Height)
+ .Short(TiffTags.BitsPerSample, (ushort)bits).Short(TiffTags.Compression, (ushort)(compressed ? 65535 : 1))
+ .Short(TiffTags.PhotometricInterpretation, 32803)
+ .Short(TiffTags.CfaRepeatPatternDim, 2, 2).Bytes(TiffTags.CfaPattern, 2, 1, 1, 0)
+ .Strip(data).Child(TiffTags.ExifIfd, exif);
+ return TiffFile.Build(ifd0, littleEndian: false);
+ }
+
+ /// Fujifilm RAF: header, JPEG with Exif, RAF directory (crop, layout, WB), FujiIFD block with 16-bit data.
+ public static byte[] Raf(SensorData s, CfaPattern rasterCfa, RawRect crop, int orientation = 1, string model = "X-T2")
+ {
+ var jpeg = Preview("FUJIFILM", model, orientation);
+ var pattern = new byte[36];
+ for (var i = 0; i < 36; i++) pattern[35 - i] = (byte)rasterCfa.ColorAt(i % 6, i / 6);
+ var records = new List();
+ void Record(ushort tag, byte[] payload) => records.AddRange([.. Box.U16(tag), .. Box.U16((ushort)payload.Length), .. payload]);
+ Record(0x0100, [.. Box.U16((ushort)s.Height), .. Box.U16((ushort)s.Width)]);
+ Record(0x0110, [.. Box.U16((ushort)crop.Top), .. Box.U16((ushort)crop.Left)]);
+ Record(0x0111, [.. Box.U16((ushort)crop.Height), .. Box.U16((ushort)crop.Width)]);
+ Record(0x0130, [0, 8, 0, 0]);
+ Record(0x0131, pattern);
+ Record(0x2FF0, [.. Box.U16(302), .. Box.U16((ushort)double.Round(302 * s.Neutral.Y / s.Neutral.X)), .. Box.U16(302), .. Box.U16((ushort)double.Round(302 * s.Neutral.Y / s.Neutral.Z))]);
+ byte[] directory = [.. Box.U32(6), .. records];
+ var data = new byte[s.Samples.Length * 2];
+ for (var i = 0; i < s.Samples.Length; i++) BinaryPrimitives.WriteUInt16LittleEndian(data.AsSpan(2 * i), s.Samples[i]);
+ var fuji = new IfdSpec().Long(0xF001, (uint)s.Width).Long(0xF002, (uint)s.Height).Long(0xF003, 14)
+ .Long(0xF00A, [.. Enumerable.Repeat(1024u, 36)]).Blob(0xF007, 0xF008, data);
+ var block = TiffFile.Build(new IfdSpec().Child(0xF000, fuji), littleEndian: false);
+ var jpegOffset = 0x6C;
+ var directoryOffset = jpegOffset + jpeg.Length;
+ var blockOffset = directoryOffset + directory.Length;
+ var header = new byte[0x6C];
+ "FUJIFILMCCD-RAW 0201FF129502"u8.CopyTo(header);
+ System.Text.Encoding.ASCII.GetBytes(model).CopyTo(header.AsSpan(0x1C));
+ uint[] fields = [(uint)jpegOffset, (uint)jpeg.Length, (uint)directoryOffset, (uint)directory.Length, (uint)blockOffset, (uint)block.Length];
+ for (var i = 0; i < fields.Length; i++) BinaryPrimitives.WriteUInt32BigEndian(header.AsSpan(0x54 + 4 * i), fields[i]);
+ return [.. header, .. jpeg, .. directory, .. block];
+ }
+
+ /// MSB-first bit writer.
+ internal sealed class BitWriter
+ {
+ private readonly List _bytes = [];
+ private int _accumulator;
+ private int _count;
+
+ public void Write(int value, int bits)
+ {
+ for (var b = bits - 1; b >= 0; b--)
+ {
+ _accumulator = _accumulator << 1 | (value >> b & 1);
+ if (++_count == 8)
+ {
+ _bytes.Add((byte)_accumulator);
+ _accumulator = _count = 0;
+ }
+ }
+ }
+
+ public void Align()
+ {
+ if (_count > 0) Write(0, 8 - _count);
+ }
+
+ public byte[] ToArray()
+ {
+ Align();
+ return [.. _bytes, 0, 0, 0, 0];
+ }
+ }
+}
diff --git a/tests/Titano.Core.Tests/Raw/RawFuzzTests.cs b/tests/Titano.Core.Tests/Raw/RawFuzzTests.cs
new file mode 100644
index 00000000..06818fdd
--- /dev/null
+++ b/tests/Titano.Core.Tests/Raw/RawFuzzTests.cs
@@ -0,0 +1,92 @@
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Imaging;
+using Titano.Testing;
+using static Titano.Core.Tests.Raw.NativeRawWriters;
+
+namespace Titano.Core.Tests.Raw;
+
+/// Truncated and corrupted RAW files may only raise (or decode).
+public sealed class RawFuzzTests(TestContext context)
+{
+ private const int W = 48, H = 32;
+
+ private static byte[] Sample(string format)
+ {
+ using var scene = SyntheticRaw.Smooth(W, H);
+ return format switch
+ {
+ "dng" => SyntheticDng.Write(scene, new DngSpec { TileSize = 16, OpcodeList2 = GainMapList(), OpcodeList3 = new OpcodeListBuilder().Add(3, 0, p => p.F64(0.1).F64(0).F64(0).F64(0).F64(0).F64(0.5).F64(0.5)).Build() }),
+ "linear.dng" => SyntheticDng.Write(scene, new DngSpec { Cfa = null, Compression = 8 }),
+ "cr2" => Cr2(Sensor(scene, "Canon EOS 5D Mark III", CfaPattern.Bayer("RGGB"), 80, 36, 24, 4, 2048, 16383), new RawRect(24, 4, 24 + W, 4 + H)),
+ "nef" => Nef(Sensor(scene, "Nikon D850", CfaPattern.Bayer("RGGB"), W, H, 0, 0, 600, 16383), 14, NefEncoding.Lossless),
+ "arw" => Arw(Sensor(scene, "Sony ILCE-7M3", CfaPattern.Bayer("RGGB"), 64, H, 0, 0, 512, 16000), [8000, 10400, 12900, 14100], compressed: true),
+ "pef" => Pef(Sensor(scene, "Pentax K-1", CfaPattern.Bayer("BGGR"), W, H, 0, 0, 512, 16383), 14, compressed: true),
+ _ => Raf(Sensor(scene, "Fujifilm X-T2", DemosaicTests.XTrans, W + 6, H + 6, 3, 3, 1024, 16383), DemosaicTests.XTrans, new RawRect(3, 3, 3 + W, 3 + H)),
+ };
+ }
+
+ private static byte[] GainMapList() => new OpcodeListBuilder().Add(9, 0, p =>
+ {
+ OpcodeListBuilder.Area(p, 0, 0, H, W);
+ p.U32(2).U32(2).F64(1).F64(1).F64(0).F64(0).U32(1).F32(1).F32(1.1f).F32(1.2f).F32(1.3f);
+ }).Build();
+
+ [Theory]
+ [Case("dng")]
+ [Case("linear.dng")]
+ [Case("cr2")]
+ [Case("nef")]
+ [Case("arw")]
+ [Case("pef")]
+ [Case("raf")]
+ public void TruncatedAndCorruptedFilesOnlyRaiseInvalidData(string format)
+ {
+ var file = Sample(format);
+ var name = "fuzz." + format.Split('.').Last();
+ var options = new RawDecodeOptions { Quality = DemosaicQuality.Draft, MaxDegreeOfParallelism = 1 };
+ using (var clean = RawDecoder.Decode(new MemoryStream(file), name, options)) Assert.Equal(format == "arw" ? 64 : W, clean.Image.Width);
+ var random = new Random(format.Length * 7919);
+ var outcomes = new Dictionary();
+ for (var i = 0; i < 120; i++)
+ {
+ byte[] variant;
+ if (i < 40)
+ {
+ variant = file[..(int)((long)file.Length * i / 40)];
+ }
+ else
+ {
+ variant = (byte[])file.Clone();
+ var flips = 1 + random.Next(4);
+ for (var k = 0; k < flips; k++)
+ {
+ // Bias corruption toward the headers, where structure lives.
+ var at = random.Next(2) == 0 ? random.Next(int.Min(variant.Length, 512)) : random.Next(variant.Length);
+ variant[at] = (byte)random.Next(256);
+ }
+ }
+ var outcome = Run(variant, name, options);
+ outcomes[outcome] = outcomes.GetValueOrDefault(outcome) + 1;
+ }
+ context.Log($"{format}: " + string.Join(", ", outcomes.Select(o => $"{o.Key} {o.Value}")));
+ }
+
+ private static string Run(byte[] data, string name, RawDecodeOptions options)
+ {
+ try
+ {
+ RawDecoder.Probe(new MemoryStream(data), name);
+ using var result = RawDecoder.Decode(new MemoryStream(data), name, options);
+ return "decoded";
+ }
+ catch (InvalidDataException)
+ {
+ return "invalid";
+ }
+ catch (Exception ex)
+ {
+ Assert.Fail($"{ex.GetType().Name}: {ex.Message}\n{ex.StackTrace}");
+ return "";
+ }
+ }
+}
diff --git a/tests/Titano.Core.Tests/Raw/RawPerformanceTests.cs b/tests/Titano.Core.Tests/Raw/RawPerformanceTests.cs
new file mode 100644
index 00000000..dee7cbda
--- /dev/null
+++ b/tests/Titano.Core.Tests/Raw/RawPerformanceTests.cs
@@ -0,0 +1,94 @@
+using System.Buffers.Binary;
+using System.Diagnostics;
+using System.Reflection;
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Codecs.Tiff;
+using Titano.Core.Metadata.Tiff;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Raw;
+
+/// 24-megapixel Bayer DNG development timing: AHD at full size and binned Draft at half size, all cores.
+[Serial]
+[Category("Performance")]
+public sealed class RawPerformanceTests(TestContext context)
+{
+ private const int W = 6000, H = 4000;
+
+ [Test]
+ [Timeout(60_000)]
+ public void Develops24MegapixelDngWithinBudget()
+ {
+ // A Debug build disables the JIT optimiser in Titano.Core: timings would measure the build, not the pipeline.
+ if (typeof(RawDecoder).Assembly.GetCustomAttribute()?.IsJITOptimizerDisabled == true)
+ TestContext.Skip("timing gate needs an optimised build (dotnet run -c Release)");
+ var dng = Mosaic();
+ var ahd = Best(dng, RawDecodeOptions.Default, out var size);
+ Assert.Equal(W, size.Width);
+ var half = Best(dng, new RawDecodeOptions { Quality = DemosaicQuality.Draft, MaxLongEdge = W / 2 }, out var halfSize);
+ Assert.Equal(W / 2, halfSize.Width);
+ context.Log($"24 MP DNG: AHD full size {ahd.TotalMilliseconds:F0} ms, binned half size {half.TotalMilliseconds:F0} ms ({Environment.ProcessorCount} cores)");
+ Console.WriteLine($"[perf] {context.LogText.Trim()}");
+ Assert.Less(ahd.TotalSeconds, 4.0);
+ Assert.Less(half.TotalSeconds, 1.0);
+ }
+
+ /// Best of two runs (the machine is shared; the first run also pays JIT warm-up).
+ private static TimeSpan Best(byte[] dng, RawDecodeOptions options, out (int Width, int Height) size)
+ {
+ var best = TimeSpan.MaxValue;
+ size = default;
+ for (var run = 0; run < 2; run++)
+ {
+ var sw = Stopwatch.StartNew();
+ using var result = RawDecoder.Decode(new MemoryStream(dng, writable: false), "perf.dng", options);
+ best = sw.Elapsed < best ? sw.Elapsed : best;
+ size = (result.Image.Width, result.Image.Height);
+ }
+ return best;
+ }
+
+ /// Uncompressed 14-bit RGGB DNG with photo-like texture (smooth illumination plus detail and noise).
+ private static byte[] Mosaic()
+ {
+ var data = new byte[W * H * 2];
+ Parallel.For(0, H, y =>
+ {
+ var state = (uint)(y * 2654435761u + 7);
+ for (var x = 0; x < W; x++)
+ {
+ state ^= state << 13;
+ state ^= state >> 17;
+ state ^= state << 5;
+ var colour = (y & 1) * 2 + (x & 1);
+ var level = 1500 + 5000 * (0.5 + 0.5 * double.Sin(x * 0.01) * double.Cos(y * 0.013)) * (colour is 1 or 2 ? 1.0 : 0.6)
+ + 800 * double.Sin(x * 0.4 + y * 0.3) + (state & 127);
+ BinaryPrimitives.WriteUInt16LittleEndian(data.AsSpan((y * W + x) * 2), (ushort)double.Clamp(level, 0, 16383));
+ }
+ });
+ using var output = new MemoryStream();
+ output.Write("II*\0\0\0\0\0"u8);
+ var ifd = new TiffDirectory();
+ ifd.Long(TiffTags.NewSubfileType, 0);
+ ifd.Long(TiffTags.ImageWidth, W);
+ ifd.Long(TiffTags.ImageLength, H);
+ ifd.Short(TiffTags.BitsPerSample, 16);
+ ifd.Short(TiffTags.Compression, 1);
+ ifd.Short(TiffTags.PhotometricInterpretation, 32803);
+ ifd.Short(TiffTags.SamplesPerPixel, 1);
+ ifd.Long(TiffTags.StripOffsets, 8);
+ ifd.Long(TiffTags.StripByteCounts, (uint)data.Length);
+ ifd.Long(TiffTags.RowsPerStrip, H);
+ ifd.Short(TiffTags.CfaRepeatPatternDim, 2, 2);
+ ifd.Bytes(TiffTags.CfaPattern, 0, 1, 1, 2);
+ ifd.Bytes(TiffTags.DngVersion, 1, 4, 0, 0);
+ ifd.Short(TiffTags.BlackLevel, 1024);
+ ifd.Short(TiffTags.WhiteLevel, 16383);
+ ifd.SRational(TiffTags.ColorMatrix1, (6722, 10000), (-635, 10000), (-963, 10000), (-4287, 10000), (12460, 10000), (2028, 10000), (-908, 10000), (2162, 10000), (5668, 10000));
+ ifd.Short(TiffTags.CalibrationIlluminant1, 21);
+ ifd.Rational(TiffTags.AsShotNeutral, (500u, 1000u), (1000u, 1000u), (700u, 1000u));
+ output.Write(data);
+ TiffWriter.WriteDirectory(output, 0, ifd);
+ return output.ToArray();
+ }
+}
diff --git a/tests/Titano.Core.Tests/Raw/SyntheticRaw.cs b/tests/Titano.Core.Tests/Raw/SyntheticRaw.cs
new file mode 100644
index 00000000..b8c16155
--- /dev/null
+++ b/tests/Titano.Core.Tests/Raw/SyntheticRaw.cs
@@ -0,0 +1,503 @@
+using System.Buffers.Binary;
+using System.IO.Compression;
+using Titano.Core.Codecs.Dng;
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Codecs.Raw;
+using Titano.Core.Codecs.Tiff;
+using Titano.Core.Imaging;
+using Titano.Core.Mathematics;
+using Titano.Core.Metadata.Tiff;
+
+namespace Titano.Core.Tests.Raw;
+
+/// Synthetic scenes and the camera model used to turn them into raw data with known answers.
+internal static class SyntheticRaw
+{
+ /// Canon EOS 5D Mark III ColorMatrix (XYZ → camera, D65), the adobe_coeff values divided by 10 000.
+ public static Matrix3 CameraMatrix { get; } = new(0.6722, -0.0635, -0.0963, -0.4287, 1.2460, 0.2028, -0.0908, 0.2162, 0.5668);
+
+ /// A second (tungsten) matrix for interpolation tests: the D65 one with a warmer bias.
+ public static Matrix3 TungstenMatrix { get; } = new(0.7300, -0.1100, -0.0800, -0.4000, 1.2000, 0.2400, -0.0500, 0.1500, 0.7400);
+
+ /// Smooth colourful linear Rec.709 scene with values in roughly 0.03–0.7.
+ public static ImageBuffer Smooth(int width, int height)
+ {
+ var image = new ImageBuffer(width, height);
+ for (var y = 0; y < height; y++)
+ {
+ for (var x = 0; x < width; x++)
+ {
+ double u = x / (double)width, v = y / (double)height;
+ image[0, x, y] = (float)(0.25 + 0.2 * double.Sin(2 * double.Pi * (u * 1.3 + 0.1)) * double.Cos(2 * double.Pi * v * 0.7));
+ image[1, x, y] = (float)(0.3 + 0.2 * double.Cos(2 * double.Pi * (u * 0.8 - v * 0.9)));
+ image[2, x, y] = (float)(0.2 + 0.15 * double.Sin(2 * double.Pi * (v * 1.1 + u * 0.4 + 0.3)));
+ }
+ }
+ return image;
+ }
+
+ /// Gray scene with a sharp vertical edge (dark left, bright right) and a sharp horizontal one.
+ public static ImageBuffer Edges(int width, int height)
+ {
+ var image = new ImageBuffer(width, height);
+ for (var y = 0; y < height; y++)
+ {
+ for (var x = 0; x < width; x++)
+ {
+ var v = (x >= width / 2 ? 0.6f : 0.08f) * (y >= height / 2 ? 0.5f : 1f);
+ for (var c = 0; c < 3; c++) image[c, x, y] = v;
+ }
+ }
+ return image;
+ }
+
+ /// Camera response of a scene lit by : Bradford(D65 → white) · Rec.709 → XYZ, then
+ /// XYZ → camera, scaled so the white's camera neutral peaks at 1. Returns per-pixel camera RGB and that neutral.
+ public static (float[][] Camera, Vector3D Neutral) ToCamera(ImageBuffer scene, Matrix3 xyzToCamera, Chromaticity white)
+ {
+ var whiteXyz = white.ToXyz();
+ var neutral = xyzToCamera * whiteXyz;
+ var s = double.Max(neutral.X, double.Max(neutral.Y, neutral.Z));
+ var m = xyzToCamera * Matrix3.BradfordAdaptation(Chromaticity.D65.ToXyz(), whiteXyz) * Matrix3.Rec709ToXyz;
+ var camera = new float[3][];
+ for (var c = 0; c < 3; c++) camera[c] = new float[scene.PlaneLength];
+ for (var i = 0; i < scene.PlaneLength; i++)
+ {
+ var v = m * new Vector3D(scene.Plane(0)[i], scene.Plane(1)[i], scene.Plane(2)[i]);
+ camera[0][i] = (float)(v.X / s);
+ camera[1][i] = (float)(v.Y / s);
+ camera[2][i] = (float)(v.Z / s);
+ }
+ return (camera, new Vector3D(neutral.X / s, neutral.Y / s, neutral.Z / s));
+ }
+
+ /// PSNR in dB between two RGB buffers on sRGB-encoded values, ignoring pixels.
+ public static double Psnr(ImageBuffer expected, ImageBuffer actual, int border)
+ {
+ double sum = 0;
+ long n = 0;
+ for (var c = 0; c < 3; c++)
+ {
+ for (var y = border; y < expected.Height - border; y++)
+ {
+ for (var x = border; x < expected.Width - border; x++)
+ {
+ var d = ColorSpace.EncodeFast(expected[c, x, y]) - ColorSpace.EncodeFast(actual[c, x, y]);
+ sum += d * d;
+ n++;
+ }
+ }
+ }
+ return 10 * double.Log10(1 / double.Max(sum / n, 1e-12));
+ }
+
+ /// Mean CIE76 ΔE between two linear Rec.709 buffers (D65 white), ignoring pixels.
+ public static double MeanDeltaE(ImageBuffer expected, ImageBuffer actual, int border)
+ {
+ double sum = 0;
+ long n = 0;
+ for (var y = border; y < expected.Height - border; y++)
+ {
+ for (var x = border; x < expected.Width - border; x++)
+ {
+ var a = Lab(expected, x, y);
+ var b = Lab(actual, x, y);
+ sum += double.Sqrt((a.L - b.L) * (a.L - b.L) + (a.A - b.A) * (a.A - b.A) + (a.B - b.B) * (a.B - b.B));
+ n++;
+ }
+ }
+ return sum / n;
+ }
+
+ private static (double L, double A, double B) Lab(ImageBuffer image, int x, int y)
+ {
+ var xyz = Matrix3.Rec709ToXyz * new Vector3D(image[0, x, y], image[1, x, y], image[2, x, y]);
+ var w = Chromaticity.D65.ToXyz();
+ static double F(double t) => t > 216.0 / 24389 ? double.Cbrt(t) : (24389.0 / 27 * t + 16) / 116;
+ double fx = F(xyz.X / w.X), fy = F(xyz.Y / w.Y), fz = F(xyz.Z / w.Z);
+ return (116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz));
+ }
+}
+
+/// Description of a synthetic DNG written by .
+internal sealed record DngSpec
+{
+ /// CFA pattern anchored at the active area; null writes a 3-sample LinearRaw image.
+ public CfaPattern? Cfa { get; init; } = CfaPattern.Bayer("RGGB");
+
+ /// Masked border around the scene (active area offset); the crop is relative to the active area.
+ public int MarginLeft { get; init; }
+
+ public int MarginTop { get; init; }
+ public int MarginRight { get; init; }
+ public int MarginBottom { get; init; }
+
+ /// DefaultCrop relative to the active area (null: none).
+ public RawRect? Crop { get; init; }
+
+ public int White { get; init; } = 16383;
+
+ /// Black pattern (rows × columns) or a single value.
+ public int BlackRows { get; init; } = 1;
+
+ public int BlackColumns { get; init; } = 1;
+ public double[] Black { get; init; } = [512];
+ public double[]? BlackDeltaH { get; init; }
+ public double[]? BlackDeltaV { get; init; }
+
+ /// Forward linearisation table (stored code → linear value).
+ public ushort[]? Linearization { get; init; }
+
+ /// 1 (uncompressed), 7 (lossless JPEG), 8 (Deflate with horizontal predictor) or 34892 (lossy JPEG tiles of
+ /// 8-bit codes; pair it with a 256-entry ).
+ public int Compression { get; init; } = 7;
+
+ /// Store 32-bit floats (raw camera values, white 1.0) with Deflate and the floating-point predictor.
+ public bool FloatingPoint { get; init; }
+
+ public Matrix3? CameraCalibration1 { get; init; }
+ public Vector3D? AnalogBalance { get; init; }
+
+ /// Lossless JPEG tiles encode CFA rows as two interleaved components at half width (as the DNG SDK does).
+ public bool TwoComponentTiles { get; init; } = true;
+
+ public int TileSize { get; init; } = 64;
+
+ public Matrix3 ColorMatrix1 { get; init; } = SyntheticRaw.CameraMatrix;
+
+ /// XYZ → camera used to synthesise the raw values (default: ).
+ public Matrix3? CaptureMatrix { get; init; }
+
+ public int Illuminant1 { get; init; } = 21;
+ public Matrix3? ColorMatrix2 { get; init; }
+ public int Illuminant2 { get; init; }
+ public Matrix3? ForwardMatrix1 { get; init; }
+
+ /// Scene illuminant; the file records it as AsShotNeutral or, with , AsShotWhiteXY.
+ public Chromaticity SceneWhite { get; init; } = Chromaticity.D65;
+
+ public bool WriteWhiteXy { get; init; }
+ public double BaselineExposure { get; init; }
+ public byte[]? OpcodeList1 { get; init; }
+ public byte[]? OpcodeList2 { get; init; }
+ public byte[]? OpcodeList3 { get; init; }
+ public ushort Orientation { get; init; } = 1;
+
+ /// Put the raw image in a SubIFD behind an IFD0 thumbnail, like camera DNGs.
+ public bool RawInSubIfd { get; init; }
+
+ /// Raw-value transform applied after mosaicking (e.g. the inverse of a gain map), stored-unit domain.
+ public Func? RawTransform { get; init; }
+}
+
+/// Writes synthetic DNGs from a linear scene with a known camera model (test-side writer).
+internal static class SyntheticDng
+{
+ public static byte[] Write(ImageBuffer scene, DngSpec spec)
+ {
+ var (camera, neutral) = SyntheticRaw.ToCamera(scene, spec.CaptureMatrix ?? spec.ColorMatrix1, spec.SceneWhite);
+ int sw = scene.Width, sh = scene.Height;
+ int w = sw + spec.MarginLeft + spec.MarginRight, h = sh + spec.MarginTop + spec.MarginBottom;
+ var spp = spec.Cfa is null ? 3 : 1;
+ var samples = new ushort[w * h * spp];
+ var floats = spec.FloatingPoint ? new float[w * h * spp] : null;
+ for (var y = 0; y < h; y++)
+ {
+ for (var x = 0; x < w; x++)
+ {
+ int ax = x - spec.MarginLeft, ay = y - spec.MarginTop;
+ var inside = ax >= 0 && ay >= 0 && ax < sw && ay < sh;
+ for (var s = 0; s < spp; s++)
+ {
+ var black = BlackAt(spec, ax, ay, s, spp);
+ double linear = black;
+ if (inside)
+ {
+ var c = spec.Cfa?.ColorAt(ax, ay) ?? s;
+ var raw = camera[c][ay * sw + ax];
+ if (spec.RawTransform is { } t) raw = t(ax, ay, raw);
+ if (floats is not null) floats[(y * w + x) * spp + s] = raw;
+ linear = black + raw * (spec.White - black);
+ }
+ linear = double.Clamp(linear, 0, spec.White);
+ samples[(y * w + x) * spp + s] = spec.Linearization is { } table ? Inverse(table, linear) : (ushort)double.Round(linear);
+ }
+ }
+ }
+ return Assemble(spec, samples, floats, w, h, spp, neutral);
+ }
+
+ /// Black level of the spec at active-area coordinates (outside the area: the pattern without deltas).
+ public static double BlackAt(DngSpec spec, int ax, int ay, int s, int spp)
+ {
+ var row = ((ay % spec.BlackRows) + spec.BlackRows) % spec.BlackRows;
+ var col = ((ax % spec.BlackColumns) + spec.BlackColumns) % spec.BlackColumns;
+ var b = spec.Black.Length == 1 ? spec.Black[0] : spec.Black[(row * spec.BlackColumns + col) * spp + s];
+ if (spec.BlackDeltaH is { } dh && ax >= 0 && ax < dh.Length) b += dh[ax];
+ if (spec.BlackDeltaV is { } dv && ay >= 0 && ay < dv.Length) b += dv[ay];
+ return b;
+ }
+
+ private static ushort Inverse(ushort[] table, double value)
+ {
+ var best = 0;
+ for (var i = 1; i < table.Length; i++)
+ {
+ if (double.Abs(table[i] - value) < double.Abs(table[best] - value)) best = i;
+ }
+ return (ushort)best;
+ }
+
+ private static byte[] Assemble(DngSpec spec, ushort[] samples, float[]? floats, int w, int h, int spp, Vector3D neutral)
+ {
+ using var output = new MemoryStream();
+ output.Write("II*\0\0\0\0\0"u8);
+ var raw = new TiffDirectory();
+ raw.Long(TiffTags.NewSubfileType, 0);
+ raw.Long(TiffTags.ImageWidth, (uint)w);
+ raw.Long(TiffTags.ImageLength, (uint)h);
+ var bits = floats is not null ? 32 : spec.Compression == 34892 ? 8 : 16;
+ raw.Short(TiffTags.BitsPerSample, [.. Enumerable.Repeat((ushort)bits, spp)]);
+ if (floats is not null) raw.Short(TiffTags.SampleFormat, [.. Enumerable.Repeat((ushort)3, spp)]);
+ raw.Short(TiffTags.Compression, (ushort)spec.Compression);
+ raw.Short(TiffTags.PhotometricInterpretation, (ushort)(spec.Cfa is null ? 34892 : 32803));
+ raw.Short(TiffTags.SamplesPerPixel, (ushort)spp);
+ raw.Short(TiffTags.PlanarConfiguration, 1);
+ if (floats is not null)
+ {
+ raw.Short(TiffTags.Compression, 8);
+ raw.Short(TiffTags.Predictor, 3);
+ WriteFloats(raw, output, floats, w, h, spp);
+ }
+ else
+ {
+ if (spec.Compression == 8) raw.Short(TiffTags.Predictor, 2);
+ WriteData(spec, raw, output, samples, w, h, spp);
+ }
+ if (spec.Cfa is { } cfa)
+ {
+ raw.Short(TiffTags.CfaRepeatPatternDim, (ushort)cfa.Height, (ushort)cfa.Width);
+ var pattern = new byte[cfa.Width * cfa.Height];
+ for (var i = 0; i < pattern.Length; i++) pattern[i] = (byte)cfa.ColorAt(i % cfa.Width, i / cfa.Width);
+ raw.Bytes(TiffTags.CfaPattern, pattern);
+ raw.Bytes(TiffTags.CfaPlaneColor, 0, 1, 2);
+ raw.Short(TiffTags.CfaLayout, 1);
+ }
+ if (spec.MarginLeft + spec.MarginTop + spec.MarginRight + spec.MarginBottom > 0)
+ raw.Long(TiffTags.ActiveArea, (uint)spec.MarginTop, (uint)spec.MarginLeft, (uint)(h - spec.MarginBottom), (uint)(w - spec.MarginRight));
+ if (spec.Crop is { } crop)
+ {
+ raw.Long(TiffTags.DefaultCropOrigin, (uint)crop.Left, (uint)crop.Top);
+ raw.Long(TiffTags.DefaultCropSize, (uint)crop.Width, (uint)crop.Height);
+ }
+ if (spec.Linearization is { } table) raw.Short(TiffTags.LinearizationTable, table);
+ if (spec.BlackRows * spec.BlackColumns > 1) raw.Short(TiffTags.BlackLevelRepeatDim, (ushort)spec.BlackRows, (ushort)spec.BlackColumns);
+ if (floats is null) raw.Rational(TiffTags.BlackLevel, [.. spec.Black.Select(b => ((uint)double.Round(b * 100), 100u))]);
+ if (spec.BlackDeltaH is { } dh) raw.SRational(TiffTags.BlackLevelDeltaH, [.. dh.Select(d => ((int)double.Round(d * 100), 100))]);
+ if (spec.BlackDeltaV is { } dv) raw.SRational(TiffTags.BlackLevelDeltaV, [.. dv.Select(d => ((int)double.Round(d * 100), 100))]);
+ if (floats is null) raw.Long(TiffTags.WhiteLevel, [.. Enumerable.Repeat((uint)spec.White, spp)]);
+ if (spec.OpcodeList1 is { } o1) raw.Add(TiffTags.OpcodeList1, TiffType.Undefined, o1.Length, o1);
+ if (spec.OpcodeList2 is { } o2) raw.Add(TiffTags.OpcodeList2, TiffType.Undefined, o2.Length, o2);
+ if (spec.OpcodeList3 is { } o3) raw.Add(TiffTags.OpcodeList3, TiffType.Undefined, o3.Length, o3);
+
+ var ifd0 = raw;
+ if (spec.RawInSubIfd)
+ {
+ ifd0 = new TiffDirectory();
+ ifd0.Long(TiffTags.NewSubfileType, 1);
+ ifd0.Long(TiffTags.ImageWidth, 4);
+ ifd0.Long(TiffTags.ImageLength, 4);
+ ifd0.Short(TiffTags.BitsPerSample, 8, 8, 8);
+ ifd0.Short(TiffTags.Compression, 1);
+ ifd0.Short(TiffTags.PhotometricInterpretation, 2);
+ ifd0.Short(TiffTags.SamplesPerPixel, 3);
+ ifd0.Long(TiffTags.StripOffsets, 8);
+ ifd0.Long(TiffTags.StripByteCounts, 48);
+ ifd0.Child(TiffTags.SubIfds, raw);
+ }
+ ifd0.Ascii(TiffTags.Make, "Titano");
+ ifd0.Ascii(TiffTags.Model, "Synthetic");
+ ifd0.Short(TiffTags.Orientation, spec.Orientation);
+ ifd0.Bytes(TiffTags.DngVersion, 1, 6, 0, 0);
+ ifd0.Bytes(TiffTags.DngBackwardVersion, 1, 1, 0, 0);
+ ifd0.Ascii(TiffTags.UniqueCameraModel, "Titano Synthetic");
+ ifd0.SRational(TiffTags.ColorMatrix1, Rationals(spec.ColorMatrix1));
+ ifd0.Short(TiffTags.CalibrationIlluminant1, (ushort)spec.Illuminant1);
+ if (spec.ColorMatrix2 is { } cm2)
+ {
+ ifd0.SRational(TiffTags.ColorMatrix2, Rationals(cm2));
+ ifd0.Short(TiffTags.CalibrationIlluminant2, (ushort)spec.Illuminant2);
+ }
+ if (spec.ForwardMatrix1 is { } fm) ifd0.SRational(TiffTags.ForwardMatrix1, Rationals(fm));
+ if (spec.CameraCalibration1 is { } cc) ifd0.SRational(TiffTags.CameraCalibration1, Rationals(cc));
+ if (spec.AnalogBalance is { } ab) ifd0.Rational(TiffTags.AnalogBalance, R(ab.X), R(ab.Y), R(ab.Z));
+ if (spec.WriteWhiteXy)
+ {
+ ifd0.Rational(TiffTags.AsShotWhiteXy, ((uint)double.Round(spec.SceneWhite.X * 1e6), 1_000_000u), ((uint)double.Round(spec.SceneWhite.Y * 1e6), 1_000_000u));
+ }
+ else
+ {
+ ifd0.Rational(TiffTags.AsShotNeutral, R(neutral.X), R(neutral.Y), R(neutral.Z));
+ }
+ ifd0.SRational(TiffTags.BaselineExposure, ((int)double.Round(spec.BaselineExposure * 1000), 1000));
+ TiffWriter.WriteDirectory(output, 0, ifd0);
+ return output.ToArray();
+ }
+
+ private static (uint, uint) R(double v) => ((uint)double.Round(v * 1_000_000), 1_000_000u);
+
+ private static (int, int)[] Rationals(Matrix3 m) =>
+ [.. new[] { m.M11, m.M12, m.M13, m.M21, m.M22, m.M23, m.M31, m.M32, m.M33 }.Select(v => ((int)double.Round(v * 1_000_000), 1_000_000))];
+
+ /// 32-bit float rows with the TIFF floating-point predictor (bytes split into MSB-first planes, then
+ /// differenced with a stride of one pixel), Deflate-compressed in one strip.
+ private static void WriteFloats(TiffDirectory raw, Stream output, float[] floats, int w, int h, int spp)
+ {
+ var count = w * spp;
+ var rows = new byte[floats.Length * 4];
+ for (var y = 0; y < h; y++)
+ {
+ var row = rows.AsSpan(y * count * 4, count * 4);
+ for (var i = 0; i < count; i++)
+ {
+ var bitsValue = BitConverter.SingleToUInt32Bits(floats[y * count + i]);
+ for (var k = 0; k < 4; k++) row[k * count + i] = (byte)(bitsValue >> (24 - 8 * k));
+ }
+ for (var i = row.Length - 1; i >= spp; i--) row[i] -= row[i - spp];
+ }
+ using var ms = new MemoryStream();
+ using (var z = new ZLibStream(ms, CompressionLevel.Fastest, leaveOpen: true)) z.Write(rows);
+ var bytes = ms.ToArray();
+ raw.Long(TiffTags.StripOffsets, (uint)output.Position);
+ raw.Long(TiffTags.StripByteCounts, (uint)bytes.Length);
+ raw.Long(TiffTags.RowsPerStrip, (uint)h);
+ output.Write(bytes);
+ }
+
+ private static void WriteData(DngSpec spec, TiffDirectory raw, Stream output, ushort[] samples, int w, int h, int spp)
+ {
+ if (spec.Compression is 7 or 34892)
+ {
+ var t = spec.TileSize;
+ int across = (w + t - 1) / t, down = (h + t - 1) / t;
+ var offsets = new uint[across * down];
+ var counts = new uint[across * down];
+ for (var ty = 0; ty < down; ty++)
+ {
+ for (var tx = 0; tx < across; tx++)
+ {
+ var tile = new ushort[t * t * spp];
+ for (var y = 0; y < t; y++)
+ {
+ for (var x = 0; x < t; x++)
+ {
+ int sx = int.Min(tx * t + x, w - 1), sy = int.Min(ty * t + y, h - 1);
+ for (var s = 0; s < spp; s++) tile[(y * t + x) * spp + s] = samples[(sy * w + sx) * spp + s];
+ }
+ }
+ var twoComponents = spec.TwoComponentTiles && spp == 1;
+ var jpeg = spec.Compression == 34892
+ ? JpegEncoder.Encode([.. tile.Select(v => (byte)v)], t, t, spp, new JpegEncodeOptions { Quality = 95, Subsampling = JpegSubsampling.Yuv444 })
+ : twoComponents ? JpegLosslessEncoder.Encode(tile, t / 2, t, 2, 16) : JpegLosslessEncoder.Encode(tile, t, t, spp, 16);
+ offsets[ty * across + tx] = (uint)output.Position;
+ counts[ty * across + tx] = (uint)jpeg.Length;
+ output.Write(jpeg);
+ if (output.Position % 2 != 0) output.WriteByte(0);
+ }
+ }
+ raw.Long(TiffTags.TileWidth, (uint)t);
+ raw.Long(TiffTags.TileLength, (uint)t);
+ raw.Long(TiffTags.TileOffsets, offsets);
+ raw.Long(TiffTags.TileByteCounts, counts);
+ return;
+ }
+ var bytes = new byte[samples.Length * 2];
+ if (spec.Compression == 8)
+ {
+ // Horizontal differencing per row (Predictor 2), then zlib.
+ var rowSamples = w * spp;
+ var diff = new ushort[samples.Length];
+ for (var y = 0; y < h; y++)
+ {
+ for (var i = 0; i < rowSamples; i++)
+ {
+ var k = y * rowSamples + i;
+ diff[k] = i < spp ? samples[k] : (ushort)(samples[k] - samples[k - spp]);
+ }
+ }
+ for (var i = 0; i < diff.Length; i++) BinaryPrimitives.WriteUInt16LittleEndian(bytes.AsSpan(2 * i), diff[i]);
+ using var ms = new MemoryStream();
+ using (var z = new ZLibStream(ms, CompressionLevel.Fastest, leaveOpen: true)) z.Write(bytes);
+ bytes = ms.ToArray();
+ }
+ else
+ {
+ for (var i = 0; i < samples.Length; i++) BinaryPrimitives.WriteUInt16LittleEndian(bytes.AsSpan(2 * i), samples[i]);
+ }
+ raw.Long(TiffTags.StripOffsets, (uint)output.Position);
+ raw.Long(TiffTags.StripByteCounts, (uint)bytes.Length);
+ raw.Long(TiffTags.RowsPerStrip, (uint)h);
+ output.Write(bytes);
+ }
+}
+
+/// Big-endian opcode list builder for tests (DNG 1.6 chapter 7 layout).
+internal sealed class OpcodeListBuilder
+{
+ private readonly List _ops = [];
+
+ public OpcodeListBuilder Add(uint id, uint flags, Action parameters)
+ {
+ var p = new BigEndian();
+ parameters(p);
+ var body = p.ToArray();
+ var head = new BigEndian().U32(id).U32(0x01030000).U32(flags).U32((uint)body.Length).ToArray();
+ _ops.Add([.. head, .. body]);
+ return this;
+ }
+
+ public byte[] Build() => [.. new BigEndian().U32((uint)_ops.Count).ToArray(), .. _ops.SelectMany(o => o)];
+
+ /// Area spec (top, left, bottom, right, plane, planes, row pitch, column pitch).
+ public static void Area(BigEndian p, int top, int left, int bottom, int right, int plane = 0, int planes = 1, int rowPitch = 1, int colPitch = 1) =>
+ p.U32((uint)top).U32((uint)left).U32((uint)bottom).U32((uint)right).U32((uint)plane).U32((uint)planes).U32((uint)rowPitch).U32((uint)colPitch);
+
+ internal sealed class BigEndian
+ {
+ private readonly MemoryStream _ms = new();
+
+ public BigEndian U32(uint v)
+ {
+ Span b = stackalloc byte[4];
+ BinaryPrimitives.WriteUInt32BigEndian(b, v);
+ _ms.Write(b);
+ return this;
+ }
+
+ public BigEndian U16(ushort v)
+ {
+ Span b = stackalloc byte[2];
+ BinaryPrimitives.WriteUInt16BigEndian(b, v);
+ _ms.Write(b);
+ return this;
+ }
+
+ public BigEndian F32(float v)
+ {
+ Span b = stackalloc byte[4];
+ BinaryPrimitives.WriteSingleBigEndian(b, v);
+ _ms.Write(b);
+ return this;
+ }
+
+ public BigEndian F64(double v)
+ {
+ Span b = stackalloc byte[8];
+ BinaryPrimitives.WriteDoubleBigEndian(b, v);
+ _ms.Write(b);
+ return this;
+ }
+
+ public byte[] ToArray() => _ms.ToArray();
+ }
+}
diff --git a/tests/fixtures/manifest.json b/tests/fixtures/manifest.json
new file mode 100644
index 00000000..73815b4d
--- /dev/null
+++ b/tests/fixtures/manifest.json
@@ -0,0 +1,78 @@
+{
+ "description": "CC0 RAW samples from raw.pixls.us (one per managed RAW decoder), fetched by 'Titano.Tools fixtures' into tests/fixtures/external (git-ignored, CI-cached on this file). sha256 null: the first download records its hash in external/recorded-hashes.json and prints it for pinning here. width/height: size the managed decoder develops (before orientation). urlVerified false: the URL follows the site's data/// layout but was written without network access; replace it with the sample's download link if the fetch reports 404.",
+ "license": "CC0-1.0",
+ "files": [
+ {
+ "name": "google-pixel-4a.dng",
+ "url": "https://raw.pixls.us/data/Google/Pixel%204a/PXL_20201101_120000000.dng",
+ "sha256": null,
+ "size": null,
+ "format": "Dng",
+ "make": "Google",
+ "model": "Pixel 4a",
+ "width": 4032,
+ "height": 3024,
+ "urlVerified": false
+ },
+ {
+ "name": "canon-eos-5d-mark-iii.cr2",
+ "url": "https://raw.pixls.us/data/Canon/EOS%205D%20Mark%20III/IMG_0001.CR2",
+ "sha256": null,
+ "size": null,
+ "format": "Cr2",
+ "make": "Canon",
+ "model": "Canon EOS 5D Mark III",
+ "width": 5760,
+ "height": 3840,
+ "urlVerified": false
+ },
+ {
+ "name": "nikon-d850.nef",
+ "url": "https://raw.pixls.us/data/Nikon/D850/DSC_0001.NEF",
+ "sha256": null,
+ "size": null,
+ "format": "Nef",
+ "make": "NIKON CORPORATION",
+ "model": "NIKON D850",
+ "width": 8288,
+ "height": 5520,
+ "urlVerified": false
+ },
+ {
+ "name": "sony-ilce-7m3.arw",
+ "url": "https://raw.pixls.us/data/Sony/ILCE-7M3/DSC00001.ARW",
+ "sha256": null,
+ "size": null,
+ "format": "Arw",
+ "make": "SONY",
+ "model": "ILCE-7M3",
+ "width": 6048,
+ "height": 4024,
+ "urlVerified": false
+ },
+ {
+ "name": "fujifilm-x-t2.raf",
+ "url": "https://raw.pixls.us/data/Fujifilm/X-T2/DSCF0001.RAF",
+ "sha256": null,
+ "size": null,
+ "format": "Raf",
+ "make": "FUJIFILM",
+ "model": "X-T2",
+ "width": 6000,
+ "height": 4000,
+ "urlVerified": false
+ },
+ {
+ "name": "pentax-k-1.pef",
+ "url": "https://raw.pixls.us/data/Pentax/K-1/IMGP0001.PEF",
+ "sha256": null,
+ "size": null,
+ "format": "Pef",
+ "make": "RICOH IMAGING COMPANY, LTD.",
+ "model": "PENTAX K-1",
+ "width": 7392,
+ "height": 4950,
+ "urlVerified": false
+ }
+ ]
+}