feat(codecs): add baseline and lossless JPEG encoders

Baseline encoder: IJG quality scaling, 4:4:4/4:2:2/4:2:0, optional
optimised Huffman tables, restart intervals, caller APP1 segments,
ImageBuffer input with optional ordered dither; parallel colour
conversion and float FDCT per MCU row, sequential entropy coding.
Lossless (SOF3) encoder with predictors 1-7 and point transform for DNG.

Tests: round-trip PSNR gates, monotonic quality, lossless round trips
for every predictor and precision, seeded fuzzing, restart resync,
DCT scaling and a 24 MP single-core decode benchmark.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:44:20 +00:00
1 parent a1d8287faa
commit 990c515b3b
8 files changed
+1530

No files matched your search

+477
View File
@@ -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;
/// <summary>Chroma subsampling written by <see cref="JpegEncoder"/>.</summary>
public enum JpegSubsampling
{
Yuv444,
Yuv422,
Yuv420,
}
/// <summary>Options for <see cref="JpegEncoder"/>.</summary>
public sealed record JpegEncodeOptions
{
public static JpegEncodeOptions Default { get; } = new();
/// <summary>IJG quality 1–100 (scales the Annex K tables).</summary>
public int Quality { get; init; } = 90;
public JpegSubsampling Subsampling { get; init; } = JpegSubsampling.Yuv420;
/// <summary>Two-pass encoding with Huffman tables built from the image's statistics (smaller files).</summary>
public bool OptimizeHuffman { get; init; }
/// <summary>Restart interval in MCUs (0 = none).</summary>
public int RestartInterval { get; init; }
/// <summary>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).</summary>
public IReadOnlyList<byte[]>? App1Segments { get; init; }
/// <summary>Ordered dither when quantising linear float input to 8-bit sRGB.</summary>
public bool Dither { get; init; }
/// <summary>Worker limit for colour conversion and forward DCT (-1 = all cores).</summary>
public int MaxDegreeOfParallelism { get; init; } = -1;
}
/// <summary>
/// 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.
/// </summary>
public static class JpegEncoder
{
private static readonly float[] BasisT = Transpose(JpegTables.Basis);
/// <summary>Encodes a linear-light buffer (1 channel → gray JPEG, 3/4 → YCbCr; alpha is dropped).</summary>
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);
}
/// <summary>Encodes interleaved 8-bit sRGB pixels: 1 = gray, 3 = RGB, 4 = RGBA (alpha ignored).</summary>
public static byte[] Encode(ReadOnlySpan<byte> 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<byte> 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>((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);
}
}
/// <summary>IJG quality scaling of a base table (jcparam.c), clamped to baseline 1..255.</summary>
internal static int[] ScaleTable(ReadOnlySpan<byte> 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<byte> 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]);
}
/// <summary>Colour conversion, chroma downsampling (box average), forward DCT and quantisation per MCU row.</summary>
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<float> block = stackalloc float[64];
Span<float> 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));
}
}
});
}
/// <summary>F = B·f·Bᵀ with the orthonormal basis (DC = 8 × mean), Vector256 rows when available.</summary>
private static void ForwardDct(ReadOnlySpan<float> f, Span<float> output)
{
var basis = JpegTables.Basis;
if (Vector256.IsHardwareAccelerated)
{
ref var bt = ref MemoryMarshal.GetArrayDataReference(BasisT);
Span<Vector256<float>> t = stackalloc Vector256<float>[8];
for (var y = 0; y < 8; y++)
{
var acc = Vector256<float>.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<float>.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<float> 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<float> coef, float[] recip, Span<short> 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);
}
/// <summary>Walks every MCU in order: counts symbol frequencies (<paramref name="freq"/>) or emits codes.</summary>
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<short> 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<short> 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<byte> 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;
}
}
@@ -0,0 +1,151 @@
namespace Titano.Core.Codecs.Jpeg;
/// <summary>Huffman code table for encoding (code and length per symbol) plus its DHT representation.</summary>
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<byte> bits, ReadOnlySpan<byte> 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;
}
}
/// <summary>Optimal length-limited (16-bit) table for symbol frequencies (T.81 Annex K.2, as libjpeg).</summary>
public static JpegHuffmanCode Optimal(ReadOnlySpan<long> 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<byte>();
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());
}
}
/// <summary>MSB-first bit writer with 0xFF byte stuffing into a growable buffer.</summary>
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<byte> Written => _buffer.AsSpan(0, _length);
/// <summary>Guarantees room for <paramref name="bytes"/> more output bytes (stuffing included).</summary>
public void Reserve(int bytes)
{
if (_length + bytes <= _buffer.Length) return;
Array.Resize(ref _buffer, Math.Max(_buffer.Length * 2, _length + bytes));
}
/// <summary>Appends the low <paramref name="size"/> bits of <paramref name="value"/> (size ≤ 32).</summary>
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;
}
}
/// <summary>Pads the last byte with 1-bits (T.81 F.1.2.3).</summary>
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;
}
}
@@ -0,0 +1,169 @@
namespace Titano.Core.Codecs.Jpeg;
/// <summary>
/// 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).
/// </summary>
public static class JpegLosslessEncoder
{
/// <summary>Encodes interleaved samples (each &lt; 2^<paramref name="precision"/>).</summary>
/// <param name="restartInterval">Restart interval in samples per component (0 = none).</param>
public static byte[] Encode(ReadOnlySpan<ushort> 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);
}
/// <summary>Visits every residual in stream order with the decoder's prediction rules (T.81 H.1.2).</summary>
private static void Walk<TSink>(ReadOnlySpan<ushort> 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));
}
}
}
@@ -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;
/// <summary>Encoder → decoder round trips on synthetic content.</summary>
public sealed class JpegEncoderTests(TestContext context)
{
private const int W = 160, H = 120;
/// <summary>The four synthetic content classes: smooth gradients, colour bars, sensor-like noise, text-like edges.</summary>
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);
}
/// <summary>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′.</summary>
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<double>(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<double>();
var sizes = new List<double>();
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<x:xmpmeta/>"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<ArgumentException>(() => 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<ushort>(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);
}
/// <summary>Minimal SOF1 12-bit gray encoder (quantiser 1, optimal tables) for decoder tests.</summary>
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<bool, int> symbol, Action<int, int>? 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));
}
}
@@ -0,0 +1,107 @@
using Titano.Core.Codecs.Jpeg;
using Titano.Testing;
namespace Titano.Core.Tests.Codecs;
/// <summary>Lossless JPEG (SOF3) round trips: every predictor, precisions 2–16, components, restarts.</summary>
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<InvalidDataException>(() => JpegLosslessDecoder.Decode(JpegEncoder.Encode(new byte[48], 4, 4, 3)));
}
@@ -0,0 +1,66 @@
using System.Diagnostics;
using Titano.Core.Codecs.Jpeg;
using Titano.Testing;
namespace Titano.Core.Tests.Codecs;
/// <summary>24-megapixel baseline 4:2:0 encode/decode timing (decode measured single-threaded).</summary>
[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);
}
/// <summary>Photo-like content: smooth illumination, texture and mild noise (≈ q90 file size of a real photo).</summary>
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;
}
}
@@ -0,0 +1,157 @@
using Titano.Core.Codecs.Jpeg;
using Titano.Testing;
using static Titano.Core.Tests.Codecs.CodecTestData;
namespace Titano.Core.Tests.Codecs;
/// <summary>Corrupt, truncated and hostile JPEG input: only <see cref="InvalidDataException"/> may escape.</summary>
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<InvalidDataException>(() => JpegDecoder.Decode([]));
Assert.Throws<InvalidDataException>(() => JpegDecoder.Decode([0xFF, 0xD8, 0xFF, 0xD9]));
Assert.Throws<InvalidDataException>(() => 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<InvalidDataException>(() => JpegDecoder.Decode(arithmetic));
var huge = Fixture("jpeg/b420.jpg");
huge[sof + 5] = huge[sof + 6] = huge[sof + 7] = huge[sof + 8] = 0xFF;
Assert.Throws<InvalidDataException>(() => 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<InvalidDataException>(() => 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");
}
}
}
@@ -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;
/// <summary>DCT-domain scaling (1/2, 1/4, 1/8) and the linear-light decode path.</summary>
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());
}
}