diff --git a/src/Titano.Core/Codecs/Jpeg/JpegEncoder.cs b/src/Titano.Core/Codecs/Jpeg/JpegEncoder.cs
new file mode 100644
index 00000000..dfc85e28
--- /dev/null
+++ b/src/Titano.Core/Codecs/Jpeg/JpegEncoder.cs
@@ -0,0 +1,477 @@
+using System.Numerics;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+using System.Runtime.Intrinsics;
+using Titano.Core.Imaging;
+
+namespace Titano.Core.Codecs.Jpeg;
+
+/// Chroma subsampling written by .
+public enum JpegSubsampling
+{
+ Yuv444,
+ Yuv422,
+ Yuv420,
+}
+
+/// Options for .
+public sealed record JpegEncodeOptions
+{
+ public static JpegEncodeOptions Default { get; } = new();
+
+ /// IJG quality 1–100 (scales the Annex K tables).
+ public int Quality { get; init; } = 90;
+
+ public JpegSubsampling Subsampling { get; init; } = JpegSubsampling.Yuv420;
+
+ /// Two-pass encoding with Huffman tables built from the image's statistics (smaller files).
+ public bool OptimizeHuffman { get; init; }
+
+ /// Restart interval in MCUs (0 = none).
+ public int RestartInterval { get; init; }
+
+ /// APP1 payloads written after SOI, each including its identifier (e.g. "Exif\0\0" + TIFF, or the XMP
+ /// namespace + packet); at most 65533 bytes each. When present the JFIF APP0 segment is omitted (Exif layout).
+ public IReadOnlyList? App1Segments { get; init; }
+
+ /// Ordered dither when quantising linear float input to 8-bit sRGB.
+ public bool Dither { get; init; }
+
+ /// Worker limit for colour conversion and forward DCT (-1 = all cores).
+ public int MaxDegreeOfParallelism { get; init; } = -1;
+}
+
+///
+/// Baseline JPEG encoder (8-bit, Huffman, 1 or 3 components). Colour conversion and float forward DCT run in
+/// parallel per MCU row; entropy coding is sequential.
+///
+public static class JpegEncoder
+{
+ private static readonly float[] BasisT = Transpose(JpegTables.Basis);
+
+ /// Encodes a linear-light buffer (1 channel → gray JPEG, 3/4 → YCbCr; alpha is dropped).
+ public static byte[] Encode(ImageBuffer image, JpegEncodeOptions? options = null)
+ {
+ using var ms = new MemoryStream();
+ Encode(ms, image, options);
+ return ms.ToArray();
+ }
+
+ public static void Encode(Stream output, ImageBuffer image, JpegEncodeOptions? options = null)
+ {
+ var o = options ?? JpegEncodeOptions.Default;
+ var channels = image.Channels == 1 ? 1 : 3;
+ EncodeCore(output, image.Width, image.Height, channels, (y, row) => PixelConvert.EncodeRow8(image, y, row, channels, TransferFunction.Srgb, o.Dither), o);
+ }
+
+ /// Encodes interleaved 8-bit sRGB pixels: 1 = gray, 3 = RGB, 4 = RGBA (alpha ignored).
+ public static byte[] Encode(ReadOnlySpan pixels, int width, int height, int channels, JpegEncodeOptions? options = null)
+ {
+ using var ms = new MemoryStream();
+ Encode(ms, pixels, width, height, channels, options);
+ return ms.ToArray();
+ }
+
+ public static unsafe void Encode(Stream output, ReadOnlySpan pixels, int width, int height, int channels, JpegEncodeOptions? options = null)
+ {
+ if (channels is not (1 or 3 or 4)) throw new ArgumentOutOfRangeException(nameof(channels));
+ if (pixels.Length < (long)width * height * channels) throw new ArgumentException("Pixel buffer too small", nameof(pixels));
+ var outChannels = channels == 1 ? 1 : 3;
+ fixed (byte* p = pixels)
+ {
+ var ptr = (nint)p;
+ EncodeCore(output, width, height, outChannels, (y, row) =>
+ {
+ var src = new ReadOnlySpan((byte*)ptr + (long)y * width * channels, width * channels);
+ if (channels == outChannels)
+ {
+ src.CopyTo(row);
+ return;
+ }
+ for (var x = 0; x < width; x++)
+ {
+ row[3 * x] = src[4 * x];
+ row[3 * x + 1] = src[4 * x + 1];
+ row[3 * x + 2] = src[4 * x + 2];
+ }
+ }, options ?? JpegEncodeOptions.Default);
+ }
+ }
+
+ /// IJG quality scaling of a base table (jcparam.c), clamped to baseline 1..255.
+ internal static int[] ScaleTable(ReadOnlySpan table, int quality)
+ {
+ quality = Math.Clamp(quality, 1, 100);
+ var scale = quality < 50 ? 5000 / quality : 200 - quality * 2;
+ var result = new int[64];
+ for (var i = 0; i < 64; i++) result[i] = Math.Clamp((table[i] * scale + 50) / 100, 1, 255);
+ return result;
+ }
+
+ private delegate void RowReader(int y, Span row);
+
+ private sealed class Plan
+ {
+ public required int Width, Height, Components, HY, VY, McusX, McusY;
+ public required int[][] Quant;
+ public required short[][] Coefficients;
+
+ public int BlocksPerLine(int c) => c == 0 ? McusX * HY : McusX;
+ }
+
+ private static void EncodeCore(Stream output, int width, int height, int components, RowReader read, JpegEncodeOptions o)
+ {
+ if (width is < 1 or > 65535 || height is < 1 or > 65535) throw new ArgumentOutOfRangeException(nameof(width), "JPEG dimensions are 1..65535");
+ if (o.RestartInterval is < 0 or > 65535) throw new ArgumentOutOfRangeException(nameof(o), "Restart interval is 0..65535");
+ var (hy, vy) = components == 1 ? (1, 1) : o.Subsampling switch
+ {
+ JpegSubsampling.Yuv444 => (1, 1),
+ JpegSubsampling.Yuv422 => (2, 1),
+ _ => (2, 2),
+ };
+ var mcusX = JpegParser.DivUp(width, 8 * hy);
+ var mcusY = JpegParser.DivUp(height, 8 * vy);
+ var plan = new Plan
+ {
+ Width = width, Height = height, Components = components, HY = hy, VY = vy, McusX = mcusX, McusY = mcusY,
+ Quant = [ScaleTable(JpegTables.LumaQuant, o.Quality), ScaleTable(JpegTables.ChromaQuant, o.Quality)],
+ Coefficients = new short[components][],
+ };
+ plan.Coefficients[0] = new short[checked(mcusX * hy * mcusY * vy * 64)];
+ for (var c = 1; c < components; c++) plan.Coefficients[c] = new short[checked(mcusX * mcusY * 64)];
+
+ Transform(plan, read, o.MaxDegreeOfParallelism);
+
+ JpegHuffmanCode dcY, acY, dcC, acC;
+ if (o.OptimizeHuffman)
+ {
+ var freq = new long[4][];
+ for (var i = 0; i < 4; i++) freq[i] = new long[256];
+ Entropy(plan, o.RestartInterval, null, freq, null);
+ dcY = JpegHuffmanCode.Optimal(freq[0]);
+ acY = JpegHuffmanCode.Optimal(freq[1]);
+ dcC = components > 1 ? JpegHuffmanCode.Optimal(freq[2]) : dcY;
+ acC = components > 1 ? JpegHuffmanCode.Optimal(freq[3]) : acY;
+ }
+ else
+ {
+ dcY = new JpegHuffmanCode(JpegTables.DcLumaBits, JpegTables.DcLumaValues);
+ acY = new JpegHuffmanCode(JpegTables.AcLumaBits, JpegTables.AcLumaValues);
+ dcC = new JpegHuffmanCode(JpegTables.DcChromaBits, JpegTables.DcChromaValues);
+ acC = new JpegHuffmanCode(JpegTables.AcChromaBits, JpegTables.AcChromaValues);
+ }
+
+ var writer = new JpegBitWriter(width * height * components / 4);
+ Entropy(plan, o.RestartInterval, writer, null, [dcY, acY, dcC, acC]);
+ WriteHeaders(output, plan, o, dcY, acY, dcC, acC);
+ output.Write(writer.Written);
+ output.Write([0xFF, JpegTables.Eoi]);
+ }
+
+ /// Colour conversion, chroma downsampling (box average), forward DCT and quantisation per MCU row.
+ private static void Transform(Plan p, RowReader read, int parallelism)
+ {
+ int hy = p.HY, vy = p.VY, mcuH = 8 * vy, paddedW = p.McusX * 8 * hy, nc = p.Components;
+ var recip = new float[2][];
+ for (var t = 0; t < 2; t++)
+ {
+ recip[t] = new float[64];
+ for (var i = 0; i < 64; i++) recip[t][i] = 1f / p.Quant[t][i];
+ }
+ Parallel.For(0, p.McusY, new ParallelOptions { MaxDegreeOfParallelism = parallelism }, my =>
+ {
+ var rgb = new byte[p.Width * nc];
+ var planes = new float[nc][];
+ for (var c = 0; c < nc; c++) planes[c] = new float[paddedW * mcuH];
+ for (var r = 0; r < mcuH; r++)
+ {
+ var y = Math.Min(my * mcuH + r, p.Height - 1);
+ read(y, rgb);
+ var row = r * paddedW;
+ if (nc == 1)
+ {
+ var g = planes[0];
+ for (var x = 0; x < p.Width; x++) g[row + x] = rgb[x] - 128f;
+ }
+ else
+ {
+ float[] yp = planes[0], cb = planes[1], cr = planes[2];
+ for (var x = 0; x < p.Width; x++)
+ {
+ float rr = rgb[3 * x], gg = rgb[3 * x + 1], bb = rgb[3 * x + 2];
+ yp[row + x] = 0.299f * rr + 0.587f * gg + 0.114f * bb - 128f;
+ cb[row + x] = -0.168736f * rr - 0.331264f * gg + 0.5f * bb;
+ cr[row + x] = 0.5f * rr - 0.418688f * gg - 0.081312f * bb;
+ }
+ }
+ for (var c = 0; c < nc; c++)
+ {
+ var plane = planes[c];
+ plane.AsSpan(row + p.Width, paddedW - p.Width).Fill(plane[row + p.Width - 1]);
+ }
+ }
+
+ Span block = stackalloc float[64];
+ Span coef = stackalloc float[64];
+ var bpl = p.BlocksPerLine(0);
+ for (var by = 0; by < vy; by++)
+ {
+ for (var bx = 0; bx < bpl; bx++)
+ {
+ for (var r = 0; r < 8; r++) planes[0].AsSpan((by * 8 + r) * paddedW + bx * 8, 8).CopyTo(block.Slice(r * 8, 8));
+ ForwardDct(block, coef);
+ Quantize(coef, recip[0], p.Coefficients[0].AsSpan(((my * vy + by) * bpl + bx) * 64, 64));
+ }
+ }
+ var area = 1f / (hy * vy);
+ for (var c = 1; c < nc; c++)
+ {
+ var plane = planes[c];
+ for (var bx = 0; bx < p.McusX; bx++)
+ {
+ for (var r = 0; r < 8; r++)
+ {
+ for (var i = 0; i < 8; i++)
+ {
+ var sum = 0f;
+ var x0 = (bx * 8 + i) * hy;
+ for (var dy = 0; dy < vy; dy++)
+ {
+ var at = (r * vy + dy) * paddedW + x0;
+ for (var dx = 0; dx < hy; dx++) sum += plane[at + dx];
+ }
+ block[r * 8 + i] = sum * area;
+ }
+ }
+ ForwardDct(block, coef);
+ Quantize(coef, recip[1], p.Coefficients[c].AsSpan((my * p.McusX + bx) * 64, 64));
+ }
+ }
+ });
+ }
+
+ /// F = B·f·Bᵀ with the orthonormal basis (DC = 8 × mean), Vector256 rows when available.
+ private static void ForwardDct(ReadOnlySpan f, Span output)
+ {
+ var basis = JpegTables.Basis;
+ if (Vector256.IsHardwareAccelerated)
+ {
+ ref var bt = ref MemoryMarshal.GetArrayDataReference(BasisT);
+ Span> t = stackalloc Vector256[8];
+ for (var y = 0; y < 8; y++)
+ {
+ var acc = Vector256.Zero;
+ for (var x = 0; x < 8; x++) acc += Vector256.Create(f[y * 8 + x]) * Vector256.LoadUnsafe(ref bt, (nuint)(x * 8));
+ t[y] = acc;
+ }
+ for (var v = 0; v < 8; v++)
+ {
+ var acc = Vector256.Zero;
+ for (var y = 0; y < 8; y++) acc += Vector256.Create(basis[v * 8 + y]) * t[y];
+ acc.CopyTo(output.Slice(v * 8, 8));
+ }
+ return;
+ }
+ Span tmp = stackalloc float[64];
+ for (var y = 0; y < 8; y++)
+ {
+ for (var u = 0; u < 8; u++)
+ {
+ var s = 0f;
+ for (var x = 0; x < 8; x++) s += f[y * 8 + x] * basis[u * 8 + x];
+ tmp[y * 8 + u] = s;
+ }
+ }
+ for (var v = 0; v < 8; v++)
+ {
+ for (var u = 0; u < 8; u++)
+ {
+ var s = 0f;
+ for (var y = 0; y < 8; y++) s += basis[v * 8 + y] * tmp[y * 8 + u];
+ output[v * 8 + u] = s;
+ }
+ }
+ }
+
+ private static void Quantize(ReadOnlySpan coef, float[] recip, Span destination)
+ {
+ destination[0] = (short)Math.Clamp(MathF.Round(coef[0] * recip[0]), -1024f, 1023f);
+ for (var i = 1; i < 64; i++) destination[i] = (short)Math.Clamp(MathF.Round(coef[i] * recip[i]), -1023f, 1023f);
+ }
+
+ /// Walks every MCU in order: counts symbol frequencies () or emits codes.
+ private static void Entropy(Plan p, int restartInterval, JpegBitWriter? writer, long[][]? freq, JpegHuffmanCode[]? codes)
+ {
+ var preds = new int[p.Components];
+ var total = p.McusX * p.McusY;
+ var rst = 0;
+ for (var mcu = 0; mcu < total; mcu++)
+ {
+ if (restartInterval > 0 && mcu > 0 && mcu % restartInterval == 0)
+ {
+ Array.Clear(preds);
+ if (writer is not null)
+ {
+ writer.Flush();
+ writer.WriteMarker((byte)(JpegTables.Rst0 + rst));
+ }
+ rst = (rst + 1) & 7;
+ }
+ writer?.Reserve(4096);
+ int mx = mcu % p.McusX, my = mcu / p.McusX;
+ for (var c = 0; c < p.Components; c++)
+ {
+ int h = c == 0 ? p.HY : 1, v = c == 0 ? p.VY : 1, bpl = p.BlocksPerLine(c), table = c == 0 ? 0 : 2;
+ for (var by = 0; by < v; by++)
+ {
+ for (var bx = 0; bx < h; bx++)
+ {
+ var block = p.Coefficients[c].AsSpan(((my * v + by) * bpl + mx * h + bx) * 64, 64);
+ if (writer is null) CountBlock(block, ref preds[c], freq![table], freq[table + 1]);
+ else EncodeBlock(writer, block, ref preds[c], codes![table], codes[table + 1]);
+ }
+ }
+ }
+ }
+ writer?.Flush();
+ }
+
+ [MethodImpl(MethodImplOptions.AggressiveInlining)]
+ private static int Category(int v) => v == 0 ? 0 : 32 - BitOperations.LeadingZeroCount((uint)Math.Abs(v));
+
+ private static void CountBlock(ReadOnlySpan block, ref int pred, long[] dc, long[] ac)
+ {
+ dc[Category(block[0] - pred)]++;
+ pred = block[0];
+ var run = 0;
+ var order = JpegTables.NaturalOrder;
+ for (var k = 1; k < 64; k++)
+ {
+ int v = block[order[k]];
+ if (v == 0)
+ {
+ run++;
+ continue;
+ }
+ for (; run >= 16; run -= 16) ac[0xF0]++;
+ ac[run << 4 | Category(v)]++;
+ run = 0;
+ }
+ if (run > 0) ac[0]++;
+ }
+
+ private static void EncodeBlock(JpegBitWriter w, ReadOnlySpan block, ref int pred, JpegHuffmanCode dc, JpegHuffmanCode ac)
+ {
+ var diff = block[0] - pred;
+ pred = block[0];
+ var s = Category(diff);
+ w.Write((uint)(dc.Code[s] << s | ((diff < 0 ? diff - 1 : diff) & ((1 << s) - 1))), dc.Length[s] + s);
+ var run = 0;
+ var order = JpegTables.NaturalOrder;
+ for (var k = 1; k < 64; k++)
+ {
+ int v = block[order[k]];
+ if (v == 0)
+ {
+ run++;
+ continue;
+ }
+ for (; run >= 16; run -= 16) w.Write(ac.Code[0xF0], ac.Length[0xF0]);
+ s = Category(v);
+ var symbol = run << 4 | s;
+ w.Write((uint)(ac.Code[symbol] << s | ((v < 0 ? v - 1 : v) & ((1 << s) - 1))), ac.Length[symbol] + s);
+ run = 0;
+ }
+ if (run > 0) w.Write(ac.Code[0], ac.Length[0]);
+ }
+
+ private static void WriteHeaders(Stream output, Plan p, JpegEncodeOptions o, JpegHuffmanCode dcY, JpegHuffmanCode acY, JpegHuffmanCode dcC, JpegHuffmanCode acC)
+ {
+ var h = new MemoryStream();
+ h.Write([0xFF, JpegTables.Soi]);
+ if (o.App1Segments is { Count: > 0 } apps)
+ {
+ foreach (var app in apps)
+ {
+ if (app.Length > 65533) throw new ArgumentException("APP1 payload exceeds 65533 bytes", nameof(o));
+ Segment(h, JpegTables.App1, app);
+ }
+ }
+ else
+ {
+ Segment(h, JpegTables.App0, [(byte)'J', (byte)'F', (byte)'I', (byte)'F', 0, 1, 1, 0, 0, 1, 0, 1, 0, 0]);
+ }
+ var tables = p.Components == 1 ? 1 : 2;
+ var dqt = new byte[65 * tables];
+ for (var t = 0; t < tables; t++)
+ {
+ dqt[65 * t] = (byte)t;
+ for (var k = 0; k < 64; k++) dqt[65 * t + 1 + k] = (byte)p.Quant[t][JpegTables.NaturalOrder[k]];
+ }
+ Segment(h, JpegTables.Dqt, dqt);
+
+ var sof = new byte[6 + 3 * p.Components];
+ sof[0] = 8;
+ sof[1] = (byte)(p.Height >> 8);
+ sof[2] = (byte)p.Height;
+ sof[3] = (byte)(p.Width >> 8);
+ sof[4] = (byte)p.Width;
+ sof[5] = (byte)p.Components;
+ for (var c = 0; c < p.Components; c++)
+ {
+ sof[6 + 3 * c] = (byte)(c + 1);
+ sof[7 + 3 * c] = c == 0 ? (byte)(p.HY << 4 | p.VY) : (byte)0x11;
+ sof[8 + 3 * c] = (byte)(c == 0 ? 0 : 1);
+ }
+ Segment(h, JpegTables.Sof0, sof);
+
+ var dht = new MemoryStream();
+ Huffman(dht, 0x00, dcY);
+ Huffman(dht, 0x10, acY);
+ if (p.Components > 1)
+ {
+ Huffman(dht, 0x01, dcC);
+ Huffman(dht, 0x11, acC);
+ }
+ Segment(h, JpegTables.Dht, dht.ToArray());
+ if (o.RestartInterval > 0) Segment(h, JpegTables.Dri, [(byte)(o.RestartInterval >> 8), (byte)o.RestartInterval]);
+
+ var sos = new byte[4 + 2 * p.Components];
+ sos[0] = (byte)p.Components;
+ for (var c = 0; c < p.Components; c++)
+ {
+ sos[1 + 2 * c] = (byte)(c + 1);
+ sos[2 + 2 * c] = c == 0 ? (byte)0x00 : (byte)0x11;
+ }
+ sos[^3] = 0;
+ sos[^2] = 63;
+ sos[^1] = 0;
+ Segment(h, JpegTables.Sos, sos);
+ h.Position = 0;
+ h.CopyTo(output);
+ }
+
+ private static void Huffman(Stream s, byte classAndId, JpegHuffmanCode code)
+ {
+ s.WriteByte(classAndId);
+ s.Write(code.Bits);
+ s.Write(code.Values);
+ }
+
+ internal static void Segment(Stream s, byte marker, ReadOnlySpan payload)
+ {
+ var length = payload.Length + 2;
+ s.Write([0xFF, marker, (byte)(length >> 8), (byte)length]);
+ s.Write(payload);
+ }
+
+ private static float[] Transpose(float[] m)
+ {
+ var t = new float[64];
+ for (var i = 0; i < 8; i++)
+ {
+ for (var j = 0; j < 8; j++) t[j * 8 + i] = m[i * 8 + j];
+ }
+ return t;
+ }
+}
diff --git a/src/Titano.Core/Codecs/Jpeg/JpegHuffmanEncoding.cs b/src/Titano.Core/Codecs/Jpeg/JpegHuffmanEncoding.cs
new file mode 100644
index 00000000..071d76d1
--- /dev/null
+++ b/src/Titano.Core/Codecs/Jpeg/JpegHuffmanEncoding.cs
@@ -0,0 +1,151 @@
+namespace Titano.Core.Codecs.Jpeg;
+
+/// Huffman code table for encoding (code and length per symbol) plus its DHT representation.
+internal sealed class JpegHuffmanCode
+{
+ public readonly byte[] Bits;
+ public readonly byte[] Values;
+ public readonly ushort[] Code = new ushort[256];
+ public readonly byte[] Length = new byte[256];
+
+ public JpegHuffmanCode(ReadOnlySpan bits, ReadOnlySpan values)
+ {
+ Bits = bits.ToArray();
+ Values = values.ToArray();
+ int code = 0, k = 0;
+ for (var len = 1; len <= 16; len++)
+ {
+ for (var i = 0; i < bits[len - 1]; i++, k++, code++)
+ {
+ Code[values[k]] = (ushort)code;
+ Length[values[k]] = (byte)len;
+ }
+ code <<= 1;
+ }
+ }
+
+ /// Optimal length-limited (16-bit) table for symbol frequencies (T.81 Annex K.2, as libjpeg).
+ public static JpegHuffmanCode Optimal(ReadOnlySpan frequencies)
+ {
+ var freq = new long[257];
+ frequencies.CopyTo(freq);
+ freq[256] = 1; // reserved code point guarantees no all-ones code
+ var codeSize = new int[257];
+ var others = new int[257];
+ Array.Fill(others, -1);
+ while (true)
+ {
+ int c1 = -1, c2 = -1;
+ long v1 = long.MaxValue, v2 = long.MaxValue;
+ for (var i = 0; i <= 256; i++)
+ {
+ if (freq[i] != 0 && freq[i] <= v1)
+ {
+ v1 = freq[i];
+ c1 = i;
+ }
+ }
+ for (var i = 0; i <= 256; i++)
+ {
+ if (freq[i] != 0 && freq[i] <= v2 && i != c1)
+ {
+ v2 = freq[i];
+ c2 = i;
+ }
+ }
+ if (c2 < 0) break;
+ freq[c1] += freq[c2];
+ freq[c2] = 0;
+ codeSize[c1]++;
+ while (others[c1] >= 0)
+ {
+ c1 = others[c1];
+ codeSize[c1]++;
+ }
+ others[c1] = c2;
+ codeSize[c2]++;
+ while (others[c2] >= 0)
+ {
+ c2 = others[c2];
+ codeSize[c2]++;
+ }
+ }
+ var bits = new int[33];
+ for (var i = 0; i <= 256; i++)
+ {
+ if (codeSize[i] > 0) bits[codeSize[i]]++;
+ }
+ for (var i = 32; i > 16; i--)
+ {
+ while (bits[i] > 0)
+ {
+ var j = i - 2;
+ while (bits[j] == 0) j--;
+ bits[i] -= 2;
+ bits[i - 1]++;
+ bits[j + 1] += 2;
+ bits[j]--;
+ }
+ }
+ var top = 16;
+ while (bits[top] == 0) top--;
+ bits[top]--; // drop the reserved symbol
+ var counts = new byte[16];
+ for (var i = 1; i <= 16; i++) counts[i - 1] = (byte)bits[i];
+ var values = new List();
+ for (var len = 1; len <= 32; len++)
+ {
+ for (var s = 0; s < 256; s++)
+ {
+ if (codeSize[s] == len) values.Add((byte)s);
+ }
+ }
+ return new JpegHuffmanCode(counts, values.ToArray());
+ }
+}
+
+/// MSB-first bit writer with 0xFF byte stuffing into a growable buffer.
+internal sealed class JpegBitWriter(int initialCapacity)
+{
+ private byte[] _buffer = new byte[Math.Max(1024, initialCapacity)];
+ private int _length;
+ private ulong _acc;
+ private int _bits;
+
+ public ReadOnlySpan Written => _buffer.AsSpan(0, _length);
+
+ /// Guarantees room for more output bytes (stuffing included).
+ public void Reserve(int bytes)
+ {
+ if (_length + bytes <= _buffer.Length) return;
+ Array.Resize(ref _buffer, Math.Max(_buffer.Length * 2, _length + bytes));
+ }
+
+ /// Appends the low bits of (size ≤ 32).
+ public void Write(uint value, int size)
+ {
+ _acc = (_acc << size) | (value & (uint)((1UL << size) - 1));
+ _bits += size;
+ while (_bits >= 8)
+ {
+ _bits -= 8;
+ var b = (byte)(_acc >> _bits);
+ _buffer[_length++] = b;
+ if (b == 0xFF) _buffer[_length++] = 0;
+ }
+ }
+
+ /// Pads the last byte with 1-bits (T.81 F.1.2.3).
+ public void Flush()
+ {
+ if (_bits > 0) Write((1u << (8 - _bits)) - 1, 8 - _bits);
+ _acc = 0;
+ }
+
+ public void WriteMarker(byte marker)
+ {
+ Reserve(2);
+ _buffer[_length++] = 0xFF;
+ _buffer[_length++] = marker;
+ }
+}
diff --git a/src/Titano.Core/Codecs/Jpeg/JpegLosslessEncoder.cs b/src/Titano.Core/Codecs/Jpeg/JpegLosslessEncoder.cs
new file mode 100644
index 00000000..8bd6eb31
--- /dev/null
+++ b/src/Titano.Core/Codecs/Jpeg/JpegLosslessEncoder.cs
@@ -0,0 +1,169 @@
+namespace Titano.Core.Codecs.Jpeg;
+
+///
+/// Lossless JPEG (SOF3) encoder: one interleaved scan, optimal Huffman table per component, predictors 1–7,
+/// point transform and restart intervals. Used for DNG tiles (DNG Compression = 7).
+///
+public static class JpegLosslessEncoder
+{
+ /// Encodes interleaved samples (each < 2^).
+ /// Restart interval in samples per component (0 = none).
+ public static byte[] Encode(ReadOnlySpan samples, int width, int height, int components, int precision,
+ int predictor = 1, int pointTransform = 0, int restartInterval = 0)
+ {
+ if (width is < 1 or > 65535 || height is < 1 or > 65535) throw new ArgumentOutOfRangeException(nameof(width));
+ if (components is < 1 or > 4) throw new ArgumentOutOfRangeException(nameof(components));
+ if (precision is < 2 or > 16) throw new ArgumentOutOfRangeException(nameof(precision));
+ if (predictor is < 1 or > 7) throw new ArgumentOutOfRangeException(nameof(predictor));
+ if (pointTransform < 0 || pointTransform >= precision) throw new ArgumentOutOfRangeException(nameof(pointTransform));
+ if (restartInterval is < 0 or > 65535) throw new ArgumentOutOfRangeException(nameof(restartInterval));
+ if (samples.Length < (long)width * height * components) throw new ArgumentException("Sample buffer too small", nameof(samples));
+ var limit = 1 << precision;
+ foreach (var s in samples[..(width * height * components)])
+ {
+ if (s >= limit) throw new ArgumentException($"Sample {s} exceeds {precision}-bit precision", nameof(samples));
+ }
+
+ var layout = new Layout(width, height, components, predictor, pointTransform, restartInterval, precision);
+ var counter = new Counter { Frequencies = new long[components][] };
+ for (var c = 0; c < components; c++) counter.Frequencies[c] = new long[256];
+ Walk(samples, layout, ref counter);
+ var codes = new JpegHuffmanCode[components];
+ for (var c = 0; c < components; c++) codes[c] = JpegHuffmanCode.Optimal(counter.Frequencies[c]);
+
+ var emitter = new Emitter { Writer = new JpegBitWriter(width * height * components), Codes = codes };
+ Walk(samples, layout, ref emitter);
+ emitter.Writer.Flush();
+
+ using var output = new MemoryStream();
+ output.Write([0xFF, JpegTables.Soi]);
+ var sof = new byte[6 + 3 * components];
+ sof[0] = (byte)precision;
+ sof[1] = (byte)(height >> 8);
+ sof[2] = (byte)height;
+ sof[3] = (byte)(width >> 8);
+ sof[4] = (byte)width;
+ sof[5] = (byte)components;
+ for (var c = 0; c < components; c++)
+ {
+ sof[6 + 3 * c] = (byte)(c + 1);
+ sof[7 + 3 * c] = 0x11;
+ }
+ JpegEncoder.Segment(output, JpegTables.Sof3, sof);
+ var dht = new MemoryStream();
+ for (var c = 0; c < components; c++)
+ {
+ dht.WriteByte((byte)c);
+ dht.Write(codes[c].Bits);
+ dht.Write(codes[c].Values);
+ }
+ JpegEncoder.Segment(output, JpegTables.Dht, dht.ToArray());
+ if (restartInterval > 0) JpegEncoder.Segment(output, JpegTables.Dri, [(byte)(restartInterval >> 8), (byte)restartInterval]);
+ var sos = new byte[4 + 2 * components];
+ sos[0] = (byte)components;
+ for (var c = 0; c < components; c++)
+ {
+ sos[1 + 2 * c] = (byte)(c + 1);
+ sos[2 + 2 * c] = (byte)(c << 4);
+ }
+ sos[^3] = (byte)predictor;
+ sos[^2] = 0;
+ sos[^1] = (byte)pointTransform;
+ JpegEncoder.Segment(output, JpegTables.Sos, sos);
+ output.Write(emitter.Writer.Written);
+ output.Write([0xFF, JpegTables.Eoi]);
+ return output.ToArray();
+ }
+
+ private readonly record struct Layout(int Width, int Height, int Components, int Predictor, int PointTransform, int RestartInterval, int Precision);
+
+ private interface ISink
+ {
+ void Difference(int component, int diff);
+ void Restart(int index);
+ }
+
+ /// Visits every residual in stream order with the decoder's prediction rules (T.81 H.1.2).
+ private static void Walk(ReadOnlySpan samples, Layout l, ref TSink sink) where TSink : struct, ISink
+ {
+ int w = l.Width, nc = l.Components, stride = w * nc, pt = l.PointTransform;
+ var initial = 1 << (l.Precision - pt - 1);
+ var total = (long)w * l.Height;
+ int restartRow = 0, x = 0, y = 0, rst = 0;
+ var first = true;
+ for (long mcu = 0; mcu < total; mcu++)
+ {
+ if (l.RestartInterval > 0 && mcu > 0 && mcu % l.RestartInterval == 0)
+ {
+ sink.Restart(rst);
+ rst = (rst + 1) & 7;
+ first = true;
+ restartRow = y;
+ }
+ var at = y * stride + x * nc;
+ for (var c = 0; c < nc; c++)
+ {
+ var idx = at + c;
+ int pred;
+ if (first) pred = initial;
+ else if (y == restartRow) pred = samples[idx - nc] >> pt;
+ else if (x == 0) pred = samples[idx - stride] >> pt;
+ else
+ {
+ int ra = samples[idx - nc] >> pt, rb = samples[idx - stride] >> pt, rc = samples[idx - stride - nc] >> pt;
+ pred = l.Predictor switch
+ {
+ 1 => ra,
+ 2 => rb,
+ 3 => rc,
+ 4 => ra + rb - rc,
+ 5 => ra + ((rb - rc) >> 1),
+ 6 => rb + ((ra - rc) >> 1),
+ _ => (ra + rb) >> 1,
+ };
+ }
+ sink.Difference(c, (short)((samples[idx] >> pt) - pred));
+ }
+ first = false;
+ if (++x == w)
+ {
+ x = 0;
+ y++;
+ }
+ }
+ }
+
+ private static int Category(int diff) => diff == -32768 ? 16 : diff == 0 ? 0 : 32 - System.Numerics.BitOperations.LeadingZeroCount((uint)Math.Abs(diff));
+
+ private struct Counter : ISink
+ {
+ public long[][] Frequencies;
+
+ public readonly void Difference(int component, int diff) => Frequencies[component][Category(diff)]++;
+
+ public readonly void Restart(int index)
+ {
+ }
+ }
+
+ private struct Emitter : ISink
+ {
+ public JpegBitWriter Writer;
+ public JpegHuffmanCode[] Codes;
+
+ public readonly void Difference(int component, int diff)
+ {
+ var code = Codes[component];
+ var s = Category(diff);
+ Writer.Reserve(16);
+ Writer.Write(code.Code[s], code.Length[s]);
+ if (s is > 0 and < 16) Writer.Write((uint)((diff < 0 ? diff - 1 : diff) & ((1 << s) - 1)), s);
+ }
+
+ public readonly void Restart(int index)
+ {
+ Writer.Flush();
+ Writer.WriteMarker((byte)(JpegTables.Rst0 + index));
+ }
+ }
+}
diff --git a/tests/Titano.Core.Tests/Codecs/JpegEncoderTests.cs b/tests/Titano.Core.Tests/Codecs/JpegEncoderTests.cs
new file mode 100644
index 00000000..a0ffe104
--- /dev/null
+++ b/tests/Titano.Core.Tests/Codecs/JpegEncoderTests.cs
@@ -0,0 +1,309 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Imaging;
+using Titano.Testing;
+using static Titano.Core.Tests.Codecs.CodecTestData;
+
+namespace Titano.Core.Tests.Codecs;
+
+/// Encoder → decoder round trips on synthetic content.
+public sealed class JpegEncoderTests(TestContext context)
+{
+ private const int W = 160, H = 120;
+
+ /// The four synthetic content classes: smooth gradients, colour bars, sensor-like noise, text-like edges.
+ private static byte[] Content(string kind)
+ {
+ var rgb = new byte[W * H * 3];
+ var rng = new Random(11);
+ for (var y = 0; y < H; y++)
+ {
+ for (var x = 0; x < W; x++)
+ {
+ int r, g, b;
+ switch (kind)
+ {
+ case "gradients":
+ r = x * 255 / (W - 1);
+ g = y * 255 / (H - 1);
+ b = (x + y) * 255 / (W + H - 2);
+ break;
+ case "bars":
+ var bar = x / (W / 8);
+ r = (bar & 4) != 0 ? 235 : 16;
+ g = (bar & 2) != 0 ? 235 : 16;
+ b = (bar & 1) != 0 ? 235 : 16;
+ break;
+ case "noise":
+ // Sensor-like: mostly luma noise (σ ≈ 3.7 levels) plus weak chroma noise.
+ var n = rng.Next(-6, 7);
+ r = 120 + x / 4 + n + rng.Next(-2, 3);
+ g = 110 + y / 4 + n + rng.Next(-2, 3);
+ b = 100 + n + rng.Next(-2, 3);
+ break;
+ default:
+ var ink = (x % 11 is 2 or 3 && y % 16 < 12) || (y % 16 is 5 && x % 11 < 8);
+ r = g = b = ink ? 24 : 232;
+ break;
+ }
+ var i = (y * W + x) * 3;
+ rgb[i] = (byte)r;
+ rgb[i + 1] = (byte)g;
+ rgb[i + 2] = (byte)b;
+ }
+ }
+ return rgb;
+ }
+
+ private static double RoundTripPsnr(byte[] rgb, JpegEncodeOptions options, int channels = 3)
+ {
+ var jpeg = JpegEncoder.Encode(rgb, W, H, channels, options);
+ var decoded = JpegDecoder.Decode(jpeg);
+ return Psnr(decoded.Pixels8, rgb);
+ }
+
+ /// PSNR of Rec.601 luma (Y′). 4:2:0 halves chroma resolution by design, so saturated chroma edges
+ /// (colour bars) lose a quarter of the step under triangle upsampling in any codec (libjpeg: 26.7 dB RGB on
+ /// the same bars); the codec's own fidelity is measured on Y′.
+ private static double RoundTripLumaPsnr(byte[] rgb, JpegEncodeOptions options)
+ {
+ var decoded = JpegDecoder.Decode(JpegEncoder.Encode(rgb, W, H, 3, options)).Pixels8!;
+ static double[] Luma(byte[] p)
+ {
+ var y = new double[p.Length / 3];
+ for (var i = 0; i < y.Length; i++) y[i] = 0.299 * p[3 * i] + 0.587 * p[3 * i + 1] + 0.114 * p[3 * i + 2];
+ return y;
+ }
+ return Psnr(Luma(decoded), Luma(rgb), 255);
+ }
+
+ [Theory]
+ [Case("gradients")]
+ [Case("bars")]
+ [Case("noise")]
+ [Case("text")]
+ public void HighQuality444Above40Db(string kind)
+ {
+ var psnr = RoundTripPsnr(Content(kind), new JpegEncodeOptions { Quality = 95, Subsampling = JpegSubsampling.Yuv444 });
+ context.Log($"{kind} q95 4:4:4: {psnr:F2} dB");
+ Assert.GreaterOrEqual(psnr, 40);
+ }
+
+ [Theory]
+ [Case("gradients")]
+ [Case("bars")]
+ [Case("noise")]
+ [Case("text")]
+ public void Quality90Yuv420Above34Db(string kind)
+ {
+ var options = new JpegEncodeOptions { Quality = 90, Subsampling = JpegSubsampling.Yuv420 };
+ var psnr = RoundTripLumaPsnr(Content(kind), options);
+ context.Log($"{kind} q90 4:2:0: Y′ {psnr:F2} dB, RGB {RoundTripPsnr(Content(kind), options):F2} dB");
+ Assert.GreaterOrEqual(psnr, 34);
+ }
+
+ [Test]
+ public void PsnrAndSizeGrowWithQuality()
+ {
+ var rgb = TestCard(W, H);
+ var psnr = new List();
+ var sizes = new List();
+ foreach (var q in new[] { 5, 20, 40, 60, 75, 85, 95, 100 })
+ {
+ var jpeg = JpegEncoder.Encode(rgb, W, H, 3, new JpegEncodeOptions { Quality = q, Subsampling = JpegSubsampling.Yuv422 });
+ sizes.Add(jpeg.Length);
+ psnr.Add(Psnr(JpegDecoder.Decode(jpeg).Pixels8, rgb));
+ }
+ context.Log("PSNR: " + string.Join(", ", psnr.Select(p => p.ToString("F1"))));
+ Assert.Monotonic(psnr, strict: true);
+ Assert.Monotonic(sizes, strict: true);
+ }
+
+ [Test]
+ public void OptimizedHuffmanIsSmallerAndPixelIdentical()
+ {
+ var rgb = TestCard(W, H);
+ var standard = JpegEncoder.Encode(rgb, W, H, 3, new JpegEncodeOptions { Quality = 85 });
+ var optimized = JpegEncoder.Encode(rgb, W, H, 3, new JpegEncodeOptions { Quality = 85, OptimizeHuffman = true });
+ context.Log($"standard {standard.Length} B, optimized {optimized.Length} B");
+ Assert.Less(optimized.Length, standard.Length);
+ Assert.BytesEqual(JpegDecoder.Decode(standard).Pixels8, JpegDecoder.Decode(optimized).Pixels8);
+ }
+
+ [Theory]
+ [Case(1)]
+ [Case(7)]
+ [Case(40)]
+ public void RestartIntervalsDecodeIdentically(int interval)
+ {
+ var rgb = TestCard(W, H);
+ var plain = JpegEncoder.Encode(rgb, W, H, 3, new JpegEncodeOptions { Quality = 80 });
+ var restart = JpegEncoder.Encode(rgb, W, H, 3, new JpegEncodeOptions { Quality = 80, RestartInterval = interval, OptimizeHuffman = true });
+ Assert.Equal(interval, JpegDecoder.ReadInfo(restart).RestartInterval);
+ var decoded = JpegDecoder.Decode(restart);
+ Assert.Empty(decoded.Warnings);
+ Assert.BytesEqual(JpegDecoder.Decode(plain).Pixels8, decoded.Pixels8);
+ }
+
+ [Test]
+ public void App1SegmentsFollowSoiAndReplaceJfif()
+ {
+ var exif = "Exif\0\0II*\0\b\0\0\0\0\0\0\0"u8.ToArray();
+ var xmp = "http://ns.adobe.com/xap/1.0/\0"u8.ToArray();
+ var jpeg = JpegEncoder.Encode(TestCard(32, 16), 32, 16, 3, new JpegEncodeOptions { App1Segments = [exif, xmp] });
+ Assert.Equal(0xE1, jpeg[3]);
+ Assert.BytesEqual(exif, jpeg.AsSpan(6, exif.Length));
+ var second = 4 + (jpeg[4] << 8 | jpeg[5]);
+ Assert.Equal(0xE1, jpeg[second + 1]);
+ Assert.False(jpeg.AsSpan().IndexOf("JFIF"u8) >= 0, "JFIF must be omitted when APP1 is supplied");
+ Assert.Equal(32, JpegDecoder.Decode(jpeg).Width);
+ Assert.Throws(() => JpegEncoder.Encode(TestCard(8, 8), 8, 8, 3, new JpegEncodeOptions { App1Segments = [new byte[65534]] }));
+ }
+
+ [Test]
+ public void GrayBufferEncodesSingleComponent()
+ {
+ using var gray = new ImageBuffer(50, 30, 1);
+ for (var i = 0; i < gray.PlaneLength; i++) gray.Plane(0)[i] = (i % 50) / 49f;
+ var jpeg = JpegEncoder.Encode(gray, new JpegEncodeOptions { Quality = 95 });
+ var info = JpegDecoder.ReadInfo(jpeg);
+ Assert.Equal(1, info.Components);
+ using var back = JpegDecoder.DecodeToLinear(jpeg);
+ Assert.Equal(1, back.Channels);
+ for (var x = 0; x < 50; x += 7) Assert.Approximately(gray[0, x, 15], back[0, x, 15], 0.02);
+ }
+
+ [Test]
+ public void LinearBufferRoundTripWithDither()
+ {
+ using var image = new ImageBuffer(96, 64);
+ for (var y = 0; y < 64; y++)
+ {
+ for (var x = 0; x < 96; x++)
+ {
+ image[0, x, y] = x / 95f;
+ image[1, x, y] = y / 63f * 0.5f;
+ image[2, x, y] = 0.18f;
+ }
+ }
+ var jpeg = JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = 95, Subsampling = JpegSubsampling.Yuv444, Dither = true });
+ using var back = JpegDecoder.DecodeToLinear(jpeg);
+ var reference = PixelConvert.ToInterleaved8(image, 3);
+ var decoded = PixelConvert.ToInterleaved8(back, 3);
+ var psnr = Psnr(decoded, reference);
+ context.Log($"linear round trip {psnr:F1} dB");
+ Assert.Greater(psnr, 40);
+ }
+
+ [Test]
+ public void TwelveBitExtendedSequentialDecodes()
+ {
+ const int w = 40, h = 24;
+ var samples = new ushort[w * h];
+ for (var y = 0; y < h; y++)
+ {
+ for (var x = 0; x < w; x++) samples[y * w + x] = (ushort)(x * 4095 / (w - 1) ^ (y * 37 % 256));
+ }
+ var jpeg = TwelveBitEncoder.EncodeGray(samples, w, h);
+ var image = JpegDecoder.Decode(jpeg);
+ Assert.Equal(12, image.BitDepth);
+ Assert.Equal(JpegProcess.ExtendedSequential, image.Info.Process);
+ var psnr = Psnr(image.Pixels16, samples, 4095);
+ context.Log($"12-bit PSNR {psnr:F1} dB");
+ Assert.Greater(psnr, 50);
+ using var linear = JpegDecoder.DecodeToLinear(jpeg);
+ Assert.Approximately(ColorSpace.SrgbToLinear(image.Pixels16![5] / 4095.0), linear[0, 5, 0], 1e-4);
+ }
+
+ /// Minimal SOF1 12-bit gray encoder (quantiser 1, optimal tables) for decoder tests.
+ private static class TwelveBitEncoder
+ {
+ public static byte[] EncodeGray(ushort[] samples, int width, int height)
+ {
+ int bw = (width + 7) / 8, bh = (height + 7) / 8;
+ var blocks = new short[bw * bh][];
+ for (var by = 0; by < bh; by++)
+ {
+ for (var bx = 0; bx < bw; bx++)
+ {
+ var coef = new short[64];
+ for (var v = 0; v < 8; v++)
+ {
+ for (var u = 0; u < 8; u++)
+ {
+ double sum = 0;
+ for (var y = 0; y < 8; y++)
+ {
+ for (var x = 0; x < 8; x++)
+ {
+ var s = samples[Math.Min(by * 8 + y, height - 1) * width + Math.Min(bx * 8 + x, width - 1)] - 2048.0;
+ sum += s * JpegTables.Basis[u * 8 + x] * JpegTables.Basis[v * 8 + y];
+ }
+ }
+ coef[v * 8 + u] = (short)Math.Round(sum);
+ }
+ }
+ blocks[by * bw + bx] = coef;
+ }
+ }
+ var dcFreq = new long[256];
+ var acFreq = new long[256];
+ Walk(blocks, (dc, s) => (dc ? dcFreq : acFreq)[s]++, null);
+ var dcCode = JpegHuffmanCode.Optimal(dcFreq);
+ var acCode = JpegHuffmanCode.Optimal(acFreq);
+ var writer = new JpegBitWriter(1 << 16);
+ Walk(blocks, (dc, s) => { var c = dc ? dcCode : acCode; writer.Reserve(8); writer.Write(c.Code[s], c.Length[s]); }, (v, s) => writer.Write((uint)((v < 0 ? v - 1 : v) & ((1 << s) - 1)), s));
+ writer.Flush();
+
+ using var ms = new MemoryStream();
+ ms.Write([0xFF, 0xD8]);
+ var dqt = new byte[129];
+ dqt[0] = 0x10;
+ for (var k = 0; k < 64; k++) dqt[2 + 2 * k] = 1;
+ JpegEncoder.Segment(ms, 0xDB, dqt);
+ JpegEncoder.Segment(ms, 0xC1, [12, (byte)(height >> 8), (byte)height, (byte)(width >> 8), (byte)width, 1, 1, 0x11, 0]);
+ var dht = new MemoryStream();
+ dht.WriteByte(0x00);
+ dht.Write(dcCode.Bits);
+ dht.Write(dcCode.Values);
+ dht.WriteByte(0x10);
+ dht.Write(acCode.Bits);
+ dht.Write(acCode.Values);
+ JpegEncoder.Segment(ms, 0xC4, dht.ToArray());
+ JpegEncoder.Segment(ms, 0xDA, [1, 1, 0x00, 0, 63, 0]);
+ ms.Write(writer.Written);
+ ms.Write([0xFF, 0xD9]);
+ return ms.ToArray();
+ }
+
+ private static void Walk(short[][] blocks, Action symbol, Action? bits)
+ {
+ var pred = 0;
+ foreach (var b in blocks)
+ {
+ var diff = b[0] - pred;
+ pred = b[0];
+ var s = Size(diff);
+ symbol(true, s);
+ if (s > 0) bits?.Invoke(diff, s);
+ var run = 0;
+ for (var k = 1; k < 64; k++)
+ {
+ int v = b[JpegTables.NaturalOrder[k]];
+ if (v == 0)
+ {
+ run++;
+ continue;
+ }
+ for (; run >= 16; run -= 16) symbol(false, 0xF0);
+ s = Size(v);
+ symbol(false, run << 4 | s);
+ bits?.Invoke(v, s);
+ run = 0;
+ }
+ if (run > 0) symbol(false, 0);
+ }
+ }
+
+ private static int Size(int v) => v == 0 ? 0 : 32 - System.Numerics.BitOperations.LeadingZeroCount((uint)Math.Abs(v));
+ }
+}
diff --git a/tests/Titano.Core.Tests/Codecs/JpegLosslessTests.cs b/tests/Titano.Core.Tests/Codecs/JpegLosslessTests.cs
new file mode 100644
index 00000000..65ba7c54
--- /dev/null
+++ b/tests/Titano.Core.Tests/Codecs/JpegLosslessTests.cs
@@ -0,0 +1,107 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Codecs;
+
+/// Lossless JPEG (SOF3) round trips: every predictor, precisions 2–16, components, restarts.
+public sealed class JpegLosslessTests
+{
+ private static ushort[] Raw(int width, int height, int components, int precision, int seed)
+ {
+ var rng = new Random(seed);
+ var max = (1 << precision) - 1;
+ var samples = new ushort[width * height * components];
+ for (var y = 0; y < height; y++)
+ {
+ for (var x = 0; x < width; x++)
+ {
+ for (var c = 0; c < components; c++)
+ {
+ // Smooth ramp + sensor noise, with a few clipped highlights and black pixels.
+ var v = (x * 3 + y * 5 + c * 97) % (max + 1) * 0.7 + rng.Next(Math.Max(1, max / 64));
+ if (rng.Next(200) == 0) v = max;
+ if (rng.Next(300) == 0) v = 0;
+ samples[(y * width + x) * components + c] = (ushort)Math.Clamp((int)v, 0, max);
+ }
+ }
+ }
+ return samples;
+ }
+
+ [Theory]
+ [Case(1)]
+ [Case(2)]
+ [Case(3)]
+ [Case(4)]
+ [Case(5)]
+ [Case(6)]
+ [Case(7)]
+ public void EveryPredictorRoundTrips(int predictor)
+ {
+ var samples = Raw(37, 23, 3, 12, predictor);
+ var jpeg = JpegLosslessEncoder.Encode(samples, 37, 23, 3, 12, predictor);
+ var decoded = JpegLosslessDecoder.Decode(jpeg);
+ Assert.Equal(37, decoded.Width);
+ Assert.Equal(23, decoded.Height);
+ Assert.Equal(3, decoded.Components);
+ Assert.Equal(12, decoded.Precision);
+ Assert.SequenceEqual(samples, decoded.Samples);
+ }
+
+ [Theory]
+ [Case(2, 1)]
+ [Case(8, 1)]
+ [Case(14, 2)]
+ [Case(16, 1)]
+ [Case(16, 4)]
+ public void PrecisionsAndComponentCounts(int precision, int components)
+ {
+ var samples = Raw(19, 11, components, precision, precision);
+ foreach (var predictor in new[] { 1, 4, 7 })
+ {
+ var decoded = JpegLosslessDecoder.Decode(JpegLosslessEncoder.Encode(samples, 19, 11, components, precision, predictor));
+ Assert.SequenceEqual(samples, decoded.Samples);
+ }
+ }
+
+ [Theory]
+ [Case(1)]
+ [Case(19)]
+ [Case(25)]
+ [Case(64)]
+ public void RestartIntervalsRoundTrip(int interval)
+ {
+ var samples = Raw(19, 13, 2, 14, interval);
+ foreach (var predictor in new[] { 1, 6 })
+ {
+ var jpeg = JpegLosslessEncoder.Encode(samples, 19, 13, 2, 14, predictor, restartInterval: interval);
+ Assert.SequenceEqual(samples, JpegLosslessDecoder.Decode(jpeg).Samples);
+ }
+ }
+
+ [Test]
+ public void PointTransformRestoresScaledSamples()
+ {
+ var samples = Raw(16, 9, 1, 16, 3).Select(s => (ushort)(s & ~7)).ToArray();
+ var jpeg = JpegLosslessEncoder.Encode(samples, 16, 9, 1, 16, predictor: 5, pointTransform: 3);
+ Assert.SequenceEqual(samples, JpegLosslessDecoder.Decode(jpeg).Samples);
+ }
+
+ [Test]
+ public void GeneralDecoderExposesLosslessAsImage()
+ {
+ var samples = Raw(10, 6, 3, 8, 1);
+ var image = JpegDecoder.Decode(JpegLosslessEncoder.Encode(samples, 10, 6, 3, 8));
+ Assert.Equal(JpegProcess.Lossless, image.Info.Process);
+ Assert.Equal(3, image.Components);
+ Assert.SequenceEqual(samples.Select(s => (byte)s), image.Pixels8!);
+ var wide = Raw(10, 6, 1, 14, 2);
+ var gray = JpegDecoder.Decode(JpegLosslessEncoder.Encode(wide, 10, 6, 1, 14));
+ Assert.Equal(14, gray.BitDepth);
+ Assert.SequenceEqual(wide, gray.Pixels16!);
+ }
+
+ [Test]
+ public void DctStreamIsRejectedByLosslessDecoder() =>
+ Assert.Throws(() => JpegLosslessDecoder.Decode(JpegEncoder.Encode(new byte[48], 4, 4, 3)));
+}
diff --git a/tests/Titano.Core.Tests/Codecs/JpegPerformanceTests.cs b/tests/Titano.Core.Tests/Codecs/JpegPerformanceTests.cs
new file mode 100644
index 00000000..105e6d29
--- /dev/null
+++ b/tests/Titano.Core.Tests/Codecs/JpegPerformanceTests.cs
@@ -0,0 +1,66 @@
+using System.Diagnostics;
+using Titano.Core.Codecs.Jpeg;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Codecs;
+
+/// 24-megapixel baseline 4:2:0 encode/decode timing (decode measured single-threaded).
+[Serial]
+[Category("Performance")]
+public sealed class JpegPerformanceTests(TestContext context)
+{
+ private const int W = 6000, H = 4000;
+
+ [Test]
+ [Timeout(60_000)]
+ public void Decodes24MegapixelOnOneCoreUnderThreeSeconds()
+ {
+ var rgb = Photo();
+ var sw = Stopwatch.StartNew();
+ var jpeg = JpegEncoder.Encode(rgb, W, H, 3, new JpegEncodeOptions { Quality = 90, Subsampling = JpegSubsampling.Yuv420 });
+ var encode = sw.Elapsed;
+
+ // Best of two runs: the machine is shared, the first run also pays JIT warm-up.
+ var single = TimeSpan.MaxValue;
+ JpegImage? image = null;
+ for (var run = 0; run < 2; run++)
+ {
+ sw.Restart();
+ image = JpegDecoder.Decode(jpeg, new JpegDecodeOptions { MaxDegreeOfParallelism = 1 });
+ single = sw.Elapsed < single ? sw.Elapsed : single;
+ }
+ sw.Restart();
+ JpegDecoder.Decode(jpeg);
+ var parallel = sw.Elapsed;
+
+ context.Log($"encode {encode.TotalMilliseconds:F0} ms ({W * (double)H / 1e6 / encode.TotalSeconds:F1} MP/s, {jpeg.Length / 1e6:F2} MB); " +
+ $"decode 1 core {single.TotalMilliseconds:F0} ms ({W * (double)H / 1e6 / single.TotalSeconds:F1} MP/s); " +
+ $"decode all cores {parallel.TotalMilliseconds:F0} ms");
+ Console.WriteLine($"[perf] {context.LogText.Trim()}");
+ Assert.Equal(W, image!.Width);
+ Assert.Less(single.TotalSeconds, 3.0);
+ }
+
+ /// Photo-like content: smooth illumination, texture and mild noise (≈ q90 file size of a real photo).
+ private static byte[] Photo()
+ {
+ var rgb = new byte[W * H * 3];
+ Parallel.For(0, H, y =>
+ {
+ var state = (uint)(y * 2654435761u + 1);
+ for (var x = 0; x < W; x++)
+ {
+ state ^= state << 13;
+ state ^= state >> 17;
+ state ^= state << 5;
+ var noise = (int)(state & 7) - 4;
+ var texture = ((x >> 3) ^ (y >> 3)) & 15;
+ var i = (y * W + x) * 3;
+ rgb[i] = (byte)Math.Clamp(60 + x * 150 / W + texture + noise, 0, 255);
+ rgb[i + 1] = (byte)Math.Clamp(80 + y * 120 / H + texture + noise, 0, 255);
+ rgb[i + 2] = (byte)Math.Clamp(200 - (x + y) * 140 / (W + H) + noise, 0, 255);
+ }
+ });
+ return rgb;
+ }
+}
diff --git a/tests/Titano.Core.Tests/Codecs/JpegRobustnessTests.cs b/tests/Titano.Core.Tests/Codecs/JpegRobustnessTests.cs
new file mode 100644
index 00000000..1b1dd8f9
--- /dev/null
+++ b/tests/Titano.Core.Tests/Codecs/JpegRobustnessTests.cs
@@ -0,0 +1,157 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Testing;
+using static Titano.Core.Tests.Codecs.CodecTestData;
+
+namespace Titano.Core.Tests.Codecs;
+
+/// Corrupt, truncated and hostile JPEG input: only may escape.
+public sealed class JpegRobustnessTests(TestContext context)
+{
+ private static byte[] LosslessSample()
+ {
+ var samples = new ushort[24 * 10 * 2];
+ for (var i = 0; i < samples.Length; i++) samples[i] = (ushort)(i * 37 % 4096);
+ return JpegLosslessEncoder.Encode(samples, 24, 10, 2, 12, predictor: 6, restartInterval: 24);
+ }
+
+ [Theory]
+ [Case("jpeg/b420.jpg")]
+ [Case("jpeg/b411.jpg")]
+ [Case("jpeg/p420.jpg")]
+ [Case("jpeg/p444.jpg")]
+ [Case("jpeg/r420.jpg")]
+ [Case("jpeg/pgray.jpg")]
+ [Case("jpeg/cmyk.jpg")]
+ [Case("lossless")]
+ public void FuzzedInputOnlyThrowsInvalidData(string source)
+ {
+ var valid = source == "lossless" ? LosslessSample() : Fixture(source);
+ var options = new[] { JpegDecodeOptions.Default, new JpegDecodeOptions { MaxLongEdge = 16, FancyUpsampling = false } };
+ int decoded = 0, rejected = 0;
+ var i = 0;
+ foreach (var input in Corruptions(valid, 120, seed: source.Sum(c => c)))
+ {
+ try
+ {
+ JpegDecoder.ReadInfo(input);
+ if (source == "lossless")
+ {
+ var raw = JpegLosslessDecoder.Decode(input);
+ Assert.Equal(raw.Width * raw.Height * raw.Components, raw.Samples.Length);
+ }
+ else
+ {
+ var image = JpegDecoder.Decode(input, options[i++ % 2]);
+ Assert.True(image.Width > 0 && image.Height > 0);
+ }
+ decoded++;
+ }
+ catch (InvalidDataException)
+ {
+ rejected++;
+ }
+ }
+ context.Log($"{source}: {decoded} decoded (possibly partial), {rejected} rejected");
+ }
+
+ [Test]
+ public void CorruptRestartIntervalIsResynchronised()
+ {
+ var data = Fixture("jpeg/r420.jpg");
+ var reference = ReadPnm(Fixture("jpeg/r420.ppm")).Samples;
+ var rst0 = data.AsSpan().IndexOf([(byte)0xFF, (byte)0xD0]);
+ var rst1 = data.AsSpan().IndexOf([(byte)0xFF, (byte)0xD1]);
+ Assert.True(rst0 > 0 && rst1 > rst0, "fixture has restart markers");
+ var corrupt = (byte[])data.Clone();
+ var rng = new Random(5);
+ for (var p = rst0 + 6; p < rst1 - 4; p += 3)
+ {
+ if (corrupt[p - 1] != 0xFF) corrupt[p] = (byte)rng.Next(0xFF);
+ }
+ // A bogus marker inside the damaged interval must be skipped, as libjpeg's resync does.
+ corrupt[rst0 + 10] = 0xFF;
+ corrupt[rst0 + 11] = 0x3A;
+ var image = JpegDecoder.Decode(corrupt);
+ context.Log(string.Join("; ", image.Warnings));
+ Assert.NotEmpty(image.Warnings);
+ AssertRowsMatch(image.Pixels8!, reference, 0, 14);
+ AssertRowsMatch(image.Pixels8!, reference, 34, 45);
+ }
+
+ [Test]
+ public void MissingRestartMarkerSkipsTheLostInterval()
+ {
+ var data = Fixture("jpeg/r420.jpg");
+ var reference = ReadPnm(Fixture("jpeg/r420.ppm")).Samples;
+ var rst0 = data.AsSpan().IndexOf([(byte)0xFF, (byte)0xD0]);
+ var cut = data.AsSpan(0, rst0).ToArray().Concat(data.AsSpan(rst0 + 2).ToArray()).ToArray();
+ var image = JpegDecoder.Decode(cut);
+ Assert.NotEmpty(image.Warnings);
+ AssertRowsMatch(image.Pixels8!, reference, 0, 14);
+ AssertRowsMatch(image.Pixels8!, reference, 34, 45);
+ }
+
+ [Theory]
+ [Case("jpeg/p420.jpg")]
+ [Case("jpeg/b444.jpg")]
+ public void TruncatedScanDataYieldsPartialImage(string name)
+ {
+ var data = Fixture(name);
+ var image = JpegDecoder.Decode(data.AsSpan(0, data.Length * 2 / 3));
+ Assert.Equal(61, image.Width);
+ Assert.Equal(45, image.Height);
+ Assert.NotEmpty(image.Warnings);
+ }
+
+ [Test]
+ public void StructuralErrorsAreRejected()
+ {
+ Assert.Throws(() => JpegDecoder.Decode([]));
+ Assert.Throws(() => JpegDecoder.Decode([0xFF, 0xD8, 0xFF, 0xD9]));
+ Assert.Throws(() => JpegDecoder.ReadInfo([0x89, 0x50, 0x4E, 0x47]));
+ var arithmetic = Fixture("jpeg/b420.jpg");
+ var sof = arithmetic.AsSpan().IndexOf([(byte)0xFF, (byte)0xC0]);
+ arithmetic[sof + 1] = 0xC9;
+ Assert.Throws(() => JpegDecoder.Decode(arithmetic));
+ var huge = Fixture("jpeg/b420.jpg");
+ huge[sof + 5] = huge[sof + 6] = huge[sof + 7] = huge[sof + 8] = 0xFF;
+ Assert.Throws(() => JpegDecoder.Decode(huge));
+ }
+
+ [Test]
+ public void TablesStreamFeedsAbbreviatedImage()
+ {
+ // TIFF JPEGTables layout: tables in one SOI..EOI stream, the image without DQT/DHT.
+ var full = Fixture("jpeg/b420.jpg");
+ var tables = new MemoryStream();
+ var image = new MemoryStream();
+ tables.Write([0xFF, 0xD8]);
+ image.Write([0xFF, 0xD8]);
+ var pos = 2;
+ while (pos < full.Length)
+ {
+ var marker = full[pos + 1];
+ if (marker == 0xDA)
+ {
+ image.Write(full.AsSpan(pos));
+ break;
+ }
+ var length = full[pos + 2] << 8 | full[pos + 3];
+ (marker is 0xDB or 0xC4 ? tables : image).Write(full.AsSpan(pos, length + 2));
+ pos += length + 2;
+ }
+ tables.Write([0xFF, 0xD9]);
+ Assert.Throws(() => JpegDecoder.Decode(image.ToArray()));
+ var decoded = JpegDecoder.Decode(image.ToArray(), new JpegDecodeOptions { Tables = tables.ToArray() });
+ Assert.BytesEqual(JpegDecoder.Decode(full).Pixels8, decoded.Pixels8);
+ }
+
+ private static void AssertRowsMatch(byte[] actual, int[] reference, int fromRow, int toRow)
+ {
+ var rowBytes = 61 * 3;
+ for (var i = fromRow * rowBytes; i < toRow * rowBytes; i++)
+ {
+ if (Math.Abs(actual[i] - reference[i]) > 2) Assert.Fail($"row {i / rowBytes} differs from the reference");
+ }
+ }
+}
diff --git a/tests/Titano.Core.Tests/Codecs/JpegScalingTests.cs b/tests/Titano.Core.Tests/Codecs/JpegScalingTests.cs
new file mode 100644
index 00000000..ef970575
--- /dev/null
+++ b/tests/Titano.Core.Tests/Codecs/JpegScalingTests.cs
@@ -0,0 +1,94 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Imaging;
+using Titano.Testing;
+using static Titano.Core.Tests.Codecs.CodecTestData;
+
+namespace Titano.Core.Tests.Codecs;
+
+/// DCT-domain scaling (1/2, 1/4, 1/8) and the linear-light decode path.
+public sealed class JpegScalingTests(TestContext context)
+{
+ private const int W = 256, H = 192;
+
+ [Theory]
+ [Case(0, 256, 192)]
+ [Case(200, 256, 192)]
+ [Case(128, 128, 96)]
+ [Case(100, 128, 96)]
+ [Case(64, 64, 48)]
+ [Case(33, 64, 48)]
+ [Case(32, 32, 24)]
+ [Case(1, 32, 24)]
+ public void MaxLongEdgePicksSmallestSufficientScale(int maxLongEdge, int width, int height)
+ {
+ var jpeg = JpegEncoder.Encode(SmoothImage(W, H), W, H, 3);
+ var image = JpegDecoder.Decode(jpeg, new JpegDecodeOptions { MaxLongEdge = maxLongEdge });
+ Assert.Equal(width, image.Width);
+ Assert.Equal(height, image.Height);
+ Assert.Equal(W, image.Info.Width);
+ }
+
+ [Theory]
+ [Case(2, 38.0)]
+ [Case(4, 34.0)]
+ [Case(8, 30.0)]
+ public void ScaledDecodeApproximatesAreaAverage(int factor, double minPsnr)
+ {
+ var jpeg = JpegEncoder.Encode(SmoothImage(W, H), W, H, 3, new JpegEncodeOptions { Quality = 92 });
+ var full = JpegDecoder.Decode(jpeg).Pixels8!;
+ var scaled = JpegDecoder.Decode(jpeg, new JpegDecodeOptions { MaxLongEdge = W / factor });
+ Assert.Equal(W / factor, scaled.Width);
+ int sw = W / factor, sh = H / factor;
+ var expected = new byte[sw * sh * 3];
+ for (var y = 0; y < sh; y++)
+ {
+ for (var x = 0; x < sw; x++)
+ {
+ for (var c = 0; c < 3; c++)
+ {
+ var sum = 0;
+ for (var dy = 0; dy < factor; dy++)
+ {
+ for (var dx = 0; dx < factor; dx++) sum += full[((y * factor + dy) * W + x * factor + dx) * 3 + c];
+ }
+ expected[(y * sw + x) * 3 + c] = (byte)((sum + factor * factor / 2) / (factor * factor));
+ }
+ }
+ }
+ var psnr = Psnr(scaled.Pixels8, expected);
+ context.Log($"1/{factor}: {psnr:F1} dB vs area average");
+ Assert.Greater(psnr, minPsnr);
+ }
+
+ [Test]
+ public void ScaledOddSizeKeepsEdges()
+ {
+ var image = JpegDecoder.Decode(Fixture("jpeg/b420.jpg"), new JpegDecodeOptions { MaxLongEdge = 31 });
+ Assert.Equal(31, image.Width);
+ Assert.Equal(23, image.Height);
+ var reference = ReadPnm(Fixture("src.ppm"));
+ // Bottom-right pixel of the scaled image must still resemble the source corner (no padding garbage).
+ var pixels = image.Pixels8!;
+ var last = pixels.AsSpan(pixels.Length - 3);
+ var src = reference.Samples.AsSpan(reference.Samples.Length - 3);
+ for (var c = 0; c < 3; c++) Assert.InRange(last[c], src[c] - 70, src[c] + 70);
+ }
+
+ [Test]
+ public void LinearDecodeMatchesLookupOfEightBitDecode()
+ {
+ var data = Fixture("jpeg/b422.jpg");
+ var bytes = JpegDecoder.Decode(data).Pixels8!;
+ using var linear = JpegDecoder.DecodeToLinear(data);
+ Assert.Equal(3, linear.Channels);
+ for (var i = 0; i < 61 * 45; i += 17)
+ {
+ for (var c = 0; c < 3; c++) Assert.Equal(ColorSpace.Linear8(bytes[i * 3 + c]), linear.Plane(c)[i]);
+ }
+ using var gray = JpegDecoder.DecodeToLinear(Fixture("jpeg/gray.jpg"));
+ Assert.Equal(1, gray.Channels);
+ using var expanded = JpegDecoder.DecodeToLinear(Fixture("jpeg/gray.jpg"), expandGray: true);
+ Assert.Equal(3, expanded.Channels);
+ Assert.SequenceEqual(gray.Plane(0).ToArray(), expanded.Plane(2).ToArray());
+ }
+}