From 71c0113f5fdce5c7045bb37ddb8195b8dea62463 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:49:30 +0000 Subject: [PATCH] feat(gif): add animated GIF encoder with variance-split palettes, dithering and frame differencing Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Core/Codecs/Gif/GifEncoder.cs | 394 ++++++++++++++++++ src/Titano.Core/Codecs/Gif/GifLzw.cs | 104 +++++ src/Titano.Core/Codecs/Gif/GifPalette.cs | 216 ++++++++++ .../Video/GifEncoderTests.cs | 255 ++++++++++++ .../Titano.Core.Tests/Video/GifTestDecoder.cs | 197 +++++++++ 5 files changed, 1166 insertions(+) create mode 100644 src/Titano.Core/Codecs/Gif/GifEncoder.cs create mode 100644 src/Titano.Core/Codecs/Gif/GifLzw.cs create mode 100644 src/Titano.Core/Codecs/Gif/GifPalette.cs create mode 100644 tests/Titano.Core.Tests/Video/GifEncoderTests.cs create mode 100644 tests/Titano.Core.Tests/Video/GifTestDecoder.cs diff --git a/src/Titano.Core/Codecs/Gif/GifEncoder.cs b/src/Titano.Core/Codecs/Gif/GifEncoder.cs new file mode 100644 index 00000000..fa754467 --- /dev/null +++ b/src/Titano.Core/Codecs/Gif/GifEncoder.cs @@ -0,0 +1,394 @@ +using Titano.Core.Diagnostics; +using Titano.Core.Imaging; + +namespace Titano.Core.Codecs.Gif; + +/// Where GIF frames take their colours from. +public enum GifPaletteMode +{ + /// One palette for the whole animation, built from the first frames (or supplied). + Global, + + /// A palette per frame, built from that frame. + Local, +} + +/// Options of . +public sealed record GifEncoderOptions +{ + /// NETSCAPE2.0 loop count: 0 loops forever; null plays once (no loop extension). + public int? LoopCount { get; init; } = 0; + + /// Serpentine Floyd–Steinberg error diffusion. + public bool Dither { get; init; } = true; + + /// Unchanged pixels become transparent and frames are cropped to the changed area. + public bool FrameDifferencing { get; init; } = true; + + /// Largest per-channel difference (8-bit) between a pixel and its value when last drawn that still counts as unchanged. + public int DifferenceThreshold { get; init; } = 2; + + public GifPaletteMode PaletteMode { get; init; } = GifPaletteMode.Global; + + /// Frames buffered to build the global palette when is not supplied. + public int PaletteSampleFrames { get; init; } = 8; + + /// Optional global palette as RGB triples (see ). + public byte[]? Palette { get; init; } + + /// Colours per palette, 2–256 (one is reserved for transparency when differencing). + public int MaxColors { get; init; } = 256; +} + +/// +/// Animated GIF89a encoder. Frames arrive one by one as linear-light s (converted to +/// 8-bit sRGB) or 8-bit sRGB RGB bytes, with durations in 90 kHz ticks. Delays are rounded on the cumulative +/// timeline so the total duration is exact to the centisecond; identical frames merge into one longer frame. +/// The output stream is not disposed. +/// +public sealed class GifEncoder +{ + private const string LogCategory = "GifEncoder"; + private const int PaletteSamples = 1 << 18; + + private readonly Stream _output; + private readonly int _width; + private readonly int _height; + private readonly GifEncoderOptions _options; + private readonly List<(byte[] Rgb, long Duration)> _sampling = []; + private byte[]? _globalPalette; + private GifPalette.Map? _globalMap; + private byte[]? _canvas; + private byte[]? _drawn; + private PendingFrame? _pending; + private long _time; + private bool _headerWritten; + private bool _warnedShortDelay; + private bool _completed; + + public GifEncoder(Stream output, int width, int height, GifEncoderOptions? options = null) + { + ArgumentNullException.ThrowIfNull(output); + if (width is <= 0 or > ushort.MaxValue || height is <= 0 or > ushort.MaxValue) throw new ArgumentOutOfRangeException(nameof(width), "GIF sizes are 1–65535"); + _options = options ?? new GifEncoderOptions(); + if (_options.MaxColors is < 2 or > 256) throw new ArgumentOutOfRangeException(nameof(options), "MaxColors must be 2–256"); + if (_options.Palette is { } p && (p.Length % 3 != 0 || p.Length / 3 > PaletteBudget || p.Length == 0)) + throw new ArgumentException("Palette must hold 1 to MaxColors (minus the transparent slot) RGB triples", nameof(options)); + _output = output; + _width = width; + _height = height; + if (_options.PaletteMode == GifPaletteMode.Global && _options.Palette is { } palette) SetGlobalPalette(palette); + } + + /// Frames written to the file so far (identical consecutive frames count once). + public int FrameCount { get; private set; } + + /// Builds a palette (RGB triples) from sample frames, e.g. spread across a sequence. + public static byte[] BuildPalette(IEnumerable frames, int maxColors = 255) + { + using var ms = new MemoryStream(); + foreach (var frame in frames) ms.Write(Subsample(ToRgb(frame), frame.Width * frame.Height, PaletteSamples / 8)); + return GifPalette.Build(ms.ToArray(), maxColors); + } + + /// Adds a linear-light frame (alpha ignored) shown for ticks. + public void AddFrame(ImageBuffer frame, long duration90k) + { + if (frame.Width != _width || frame.Height != _height) throw new ArgumentException("Frame size differs from the animation size", nameof(frame)); + AddRgb(ToRgb(frame), duration90k); + } + + /// Adds an interleaved 8-bit sRGB frame. + public void AddFrame(ReadOnlySpan rgb24, long duration90k) + { + if (rgb24.Length != _width * _height * 3) throw new ArgumentException("Expected width × height × 3 bytes", nameof(rgb24)); + AddRgb(rgb24.ToArray(), duration90k); + } + + /// Writes the remaining frames and the trailer. + public void Complete() + { + if (_completed) throw new InvalidOperationException("The encoder is already complete"); + if (_globalMap is null && _options.PaletteMode == GifPaletteMode.Global) FlushSampling(); + if (!_headerWritten) throw new InvalidOperationException("No frames were added"); + Emit(_time); + _output.WriteByte(0x3B); + _output.Flush(); + _completed = true; + } + + private int PaletteBudget => _options.FrameDifferencing ? _options.MaxColors - 1 : _options.MaxColors; + + private void AddRgb(byte[] rgb, long duration) + { + if (_completed) throw new InvalidOperationException("The encoder is complete"); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(duration); + if (_options.PaletteMode == GifPaletteMode.Global && _globalMap is null) + { + _sampling.Add((rgb, duration)); + if (_sampling.Count >= Math.Max(1, _options.PaletteSampleFrames)) FlushSampling(); + return; + } + EncodeFrame(rgb, duration); + } + + private void FlushSampling() + { + if (_sampling.Count == 0) return; + using var ms = new MemoryStream(); + foreach (var (rgb, _) in _sampling) ms.Write(Subsample(rgb, _width * _height, PaletteSamples / _sampling.Count)); + SetGlobalPalette(GifPalette.Build(ms.ToArray(), PaletteBudget)); + foreach (var (rgb, duration) in _sampling) EncodeFrame(rgb, duration); + _sampling.Clear(); + } + + private void SetGlobalPalette(byte[] palette) + { + _globalPalette = palette; + _globalMap = new GifPalette.Map(palette); + } + + private sealed record PendingFrame(long Start, int Left, int Top, int Width, int Height, byte[]? LocalPalette, int Transparent, byte[] Indices, int TableBits); + + private void EncodeFrame(byte[] rgb, long duration) + { + byte[] palette; + GifPalette.Map map; + if (_options.PaletteMode == GifPaletteMode.Local) + { + palette = GifPalette.Build(Subsample(rgb, _width * _height, PaletteSamples), PaletteBudget); + map = new GifPalette.Map(palette); + } + else + { + palette = _globalPalette!; + map = _globalMap!; + } + var colors = palette.Length / 3; + var differencing = _options.FrameDifferencing && _canvas is not null; + var transparent = _options.FrameDifferencing ? colors : -1; + + var indices = new byte[_width * _height]; + var changed = Quantize(rgb, palette, map, indices, differencing); + var (left, top, right, bottom) = differencing ? Bounds(changed) : (0, 0, _width - 1, _height - 1); + if (right < left) + { + // Nothing visible changed: the previous frame simply stays longer. + _time += duration; + return; + } + + _canvas ??= new byte[_width * _height * 3]; + var w = right - left + 1; + var h = bottom - top + 1; + var cropped = new byte[w * h]; + for (var y = 0; y < h; y++) + { + for (var x = 0; x < w; x++) + { + var i = (top + y) * _width + left + x; + if (differencing && !changed[i]) + { + cropped[y * w + x] = (byte)transparent; + continue; + } + var index = indices[i]; + cropped[y * w + x] = index; + _canvas[i * 3] = palette[index * 3]; + _canvas[i * 3 + 1] = palette[index * 3 + 1]; + _canvas[i * 3 + 2] = palette[index * 3 + 2]; + } + } + + if (!_headerWritten) WriteHeader(); + Emit(_time); + var tableBits = TableBits(colors + (transparent >= 0 ? 1 : 0)); + _pending = new PendingFrame(_time, left, top, w, h, _options.PaletteMode == GifPaletteMode.Local ? palette : null, + differencing ? transparent : -1, cropped, tableBits); + _time += duration; + } + + /// + /// Maps the frame to palette indices with optional serpentine Floyd–Steinberg diffusion. With a previous canvas, + /// pixels whose source stays within the threshold of the source they were last drawn from keep the displayed + /// colour and pass no error on, so static areas keep their dither pattern while other regions change. + /// + private bool[] Quantize(byte[] rgb, byte[] palette, GifPalette.Map map, byte[] indices, bool differencing) + { + var changed = new bool[_width * _height]; + _drawn ??= new byte[rgb.Length]; + var dither = _options.Dither; + var threshold = _options.DifferenceThreshold; + var current = new float[(_width + 2) * 3]; + var next = new float[(_width + 2) * 3]; + for (var y = 0; y < _height; y++) + { + var reverse = dither && (y & 1) == 1; + var step = reverse ? -1 : 1; + for (var n = 0; n < _width; n++) + { + var x = reverse ? _width - 1 - n : n; + var i = y * _width + x; + var p = i * 3; + if (differencing + && Math.Abs(rgb[p] - _drawn[p]) <= threshold && Math.Abs(rgb[p + 1] - _drawn[p + 1]) <= threshold && Math.Abs(rgb[p + 2] - _drawn[p + 2]) <= threshold) + { + continue; + } + var e = (x + 1) * 3; + var r = Math.Clamp(rgb[p] + current[e], 0f, 255f); + var g = Math.Clamp(rgb[p + 1] + current[e + 1], 0f, 255f); + var b = Math.Clamp(rgb[p + 2] + current[e + 2], 0f, 255f); + var index = map.Nearest((int)(r + 0.5f), (int)(g + 0.5f), (int)(b + 0.5f)); + int outR = palette[index * 3], outG = palette[index * 3 + 1], outB = palette[index * 3 + 2]; + indices[i] = (byte)index; + changed[i] = !differencing || outR != _canvas![p] || outG != _canvas[p + 1] || outB != _canvas[p + 2]; + _drawn[p] = rgb[p]; + _drawn[p + 1] = rgb[p + 1]; + _drawn[p + 2] = rgb[p + 2]; + if (!dither) continue; + var er = r - outR; + var eg = g - outG; + var eb = b - outB; + var ahead = e + step * 3; + var behind = e - step * 3; + current[ahead] += er * (7 / 16f); + current[ahead + 1] += eg * (7 / 16f); + current[ahead + 2] += eb * (7 / 16f); + next[behind] += er * (3 / 16f); + next[behind + 1] += eg * (3 / 16f); + next[behind + 2] += eb * (3 / 16f); + next[e] += er * (5 / 16f); + next[e + 1] += eg * (5 / 16f); + next[e + 2] += eb * (5 / 16f); + next[ahead] += er * (1 / 16f); + next[ahead + 1] += eg * (1 / 16f); + next[ahead + 2] += eb * (1 / 16f); + } + (current, next) = (next, current); + Array.Clear(next); + } + return changed; + } + + private (int Left, int Top, int Right, int Bottom) Bounds(bool[] changed) + { + int left = _width, top = _height, right = -1, bottom = -1; + for (var y = 0; y < _height; y++) + { + for (var x = 0; x < _width; x++) + { + if (!changed[y * _width + x]) continue; + left = Math.Min(left, x); + right = Math.Max(right, x); + top = Math.Min(top, y); + bottom = y; + } + } + return (left, top, right, bottom); + } + + private void WriteHeader() + { + _output.Write("GIF89a"u8); + Span screen = stackalloc byte[7]; + screen[0] = (byte)_width; + screen[1] = (byte)(_width >> 8); + screen[2] = (byte)_height; + screen[3] = (byte)(_height >> 8); + var globalBits = 0; + if (_globalPalette is not null) + { + globalBits = TableBits(_globalPalette.Length / 3 + (_options.FrameDifferencing ? 1 : 0)); + screen[4] = (byte)(0x80 | 0x70 | (globalBits - 1)); + } + _output.Write(screen); + if (_globalPalette is not null) WriteColorTable(_globalPalette, globalBits); + if (_options.LoopCount is { } loops) + { + _output.Write([0x21, 0xFF, 0x0B]); + _output.Write("NETSCAPE2.0"u8); + _output.Write([0x03, 0x01, (byte)loops, (byte)(loops >> 8), 0x00]); + } + _headerWritten = true; + } + + /// Writes the pending frame with the delay up to (cumulative rounding keeps the total exact). + private void Emit(long end) + { + if (_pending is not { } frame) return; + var delay = (int)(Centiseconds(end) - Centiseconds(frame.Start)); + if (delay > ushort.MaxValue) + { + Log.Warning(LogCategory, "Frame delay above 655 s clamped"); + delay = ushort.MaxValue; + } + if (delay < 2 && !_warnedShortDelay) + { + Log.Warning(LogCategory, "Frame delays below 2 cs are slowed down by most viewers"); + _warnedShortDelay = true; + } + + Span gce = [0x21, 0xF9, 0x04, (byte)(1 << 2 | (frame.Transparent >= 0 ? 1 : 0)), (byte)delay, (byte)(delay >> 8), (byte)Math.Max(frame.Transparent, 0), 0x00]; + _output.Write(gce); + Span descriptor = + [ + 0x2C, (byte)frame.Left, (byte)(frame.Left >> 8), (byte)frame.Top, (byte)(frame.Top >> 8), + (byte)frame.Width, (byte)(frame.Width >> 8), (byte)frame.Height, (byte)(frame.Height >> 8), + frame.LocalPalette is null ? (byte)0 : (byte)(0x80 | (frame.TableBits - 1)), + ]; + _output.Write(descriptor); + if (frame.LocalPalette is not null) WriteColorTable(frame.LocalPalette, frame.TableBits); + GifLzw.Encode(frame.Indices, Math.Max(2, frame.TableBits), _output); + FrameCount++; + _pending = null; + } + + private void WriteColorTable(byte[] palette, int bits) + { + var table = new byte[3 << bits]; + palette.CopyTo(table, 0); + _output.Write(table); + } + + private static long Centiseconds(long ticks90k) => (ticks90k + 450) / 900; + + /// Colour table size exponent (1–8) holding entries. + private static int TableBits(int entries) + { + var bits = 1; + while (1 << bits < entries) bits++; + return bits; + } + + private static byte[] ToRgb(ImageBuffer frame) + { + var n = frame.Width * frame.Height; + var rgb = new byte[n * 3]; + var r = frame.Plane(0); + var g = frame.Channels >= 3 ? frame.Plane(1) : r; + var b = frame.Channels >= 3 ? frame.Plane(2) : r; + for (var i = 0; i < n; i++) + { + rgb[i * 3] = ColorSpace.Encode8(r[i]); + rgb[i * 3 + 1] = ColorSpace.Encode8(g[i]); + rgb[i * 3 + 2] = ColorSpace.Encode8(b[i]); + } + return rgb; + } + + /// Every n-th pixel so at most about pixels feed the palette (deterministic). + private static byte[] Subsample(byte[] rgb, int pixels, int budget) + { + var stride = Math.Max(1, pixels / Math.Max(budget, 4096)); + if (stride == 1) return rgb; + var result = new byte[(pixels + stride - 1) / stride * 3]; + for (int i = 0, o = 0; i < pixels; i += stride, o += 3) + { + result[o] = rgb[i * 3]; + result[o + 1] = rgb[i * 3 + 1]; + result[o + 2] = rgb[i * 3 + 2]; + } + return result; + } +} diff --git a/src/Titano.Core/Codecs/Gif/GifLzw.cs b/src/Titano.Core/Codecs/Gif/GifLzw.cs new file mode 100644 index 00000000..38fba552 --- /dev/null +++ b/src/Titano.Core/Codecs/Gif/GifLzw.cs @@ -0,0 +1,104 @@ +namespace Titano.Core.Codecs.Gif; + +/// GIF variable-length LZW encoder (GIF89a appendix F): clear/end codes, 12-bit cap, 255-byte sub-blocks. +internal static class GifLzw +{ + private const int MaxCode = 4096; + private const int TableSize = 8192; // power of two > MaxCode for open addressing + + /// Writes the LZW minimum code size, the data sub-blocks and the block terminator. + public static void Encode(ReadOnlySpan indices, int minCodeSize, Stream output) + { + output.WriteByte((byte)minCodeSize); + var writer = new BlockWriter(output); + var clear = 1 << minCodeSize; + var end = clear + 1; + var keys = new int[TableSize]; + var codes = new short[TableSize]; + Array.Fill(keys, -1); + var next = end + 1; + var codeSize = minCodeSize + 1; + writer.Write(clear, codeSize); + if (indices.IsEmpty) + { + writer.Write(end, codeSize); + writer.Finish(); + return; + } + + int prefix = indices[0]; + for (var i = 1; i < indices.Length; i++) + { + int k = indices[i]; + var key = prefix << 8 | k; + var slot = (int)(((uint)key * 0x9E3779B1u) >> 19); // 13 bits: 0..TableSize-1 + while (keys[slot] != -1 && keys[slot] != key) slot = (slot + 1) & (TableSize - 1); + if (keys[slot] == key) + { + prefix = codes[slot]; + continue; + } + writer.Write(prefix, codeSize); + if (next == MaxCode) + { + // Table full: restart the dictionary (the clear code is still written at 12 bits). + writer.Write(clear, codeSize); + Array.Fill(keys, -1); + next = end + 1; + codeSize = minCodeSize + 1; + } + else + { + if (next >= 1 << codeSize) codeSize++; + keys[slot] = key; + codes[slot] = (short)next++; + } + prefix = k; + } + writer.Write(prefix, codeSize); + writer.Write(end, codeSize); + writer.Finish(); + } + + /// Packs codes LSB-first into sub-blocks of at most 255 bytes. + private sealed class BlockWriter(Stream output) + { + private readonly byte[] _block = new byte[256]; + private int _length; + private ulong _bits; + private int _count; + + public void Write(int code, int size) + { + _bits |= (ulong)code << _count; + _count += size; + while (_count >= 8) + { + Put((byte)_bits); + _bits >>= 8; + _count -= 8; + } + } + + public void Finish() + { + if (_count > 0) Put((byte)_bits); + Flush(); + output.WriteByte(0); + } + + private void Put(byte b) + { + _block[1 + _length++] = b; + if (_length == 255) Flush(); + } + + private void Flush() + { + if (_length == 0) return; + _block[0] = (byte)_length; + output.Write(_block, 0, _length + 1); + _length = 0; + } + } +} diff --git a/src/Titano.Core/Codecs/Gif/GifPalette.cs b/src/Titano.Core/Codecs/Gif/GifPalette.cs new file mode 100644 index 00000000..d6f29823 --- /dev/null +++ b/src/Titano.Core/Codecs/Gif/GifPalette.cs @@ -0,0 +1,216 @@ +namespace Titano.Core.Codecs.Gif; + +/// Palette construction (exact or median cut) and nearest-colour mapping for GIF frames. +internal static class GifPalette +{ + private const int WeightR = 2, WeightG = 4, WeightB = 3; + + /// + /// Builds at most colours (RGB triples) from interleaved RGB samples: the exact set when + /// it is small enough, otherwise median cut over a 5-bit-per-channel histogram where, as in Wu's quantiser, the box + /// with the largest squared error is split at the position that minimises the summed error of both halves. + /// + public static byte[] Build(ReadOnlySpan rgb, int maxColors) + { + var distinct = new HashSet(); + for (var i = 0; i + 2 < rgb.Length && distinct.Count <= maxColors; i += 3) distinct.Add(rgb[i] << 16 | rgb[i + 1] << 8 | rgb[i + 2]); + if (distinct.Count <= maxColors) + { + var exact = distinct.Order().ToArray(); + var palette = new byte[exact.Length * 3]; + for (var i = 0; i < exact.Length; i++) + { + palette[i * 3] = (byte)(exact[i] >> 16); + palette[i * 3 + 1] = (byte)(exact[i] >> 8); + palette[i * 3 + 2] = (byte)exact[i]; + } + return palette; + } + return MedianCut(rgb, maxColors); + } + + /// Population moments of a set of histogram bins. + private struct Moments + { + public long N, R, G, B, Squares; + + public void Add(in Moments m) + { + N += m.N; + R += m.R; + G += m.G; + B += m.B; + Squares += m.Squares; + } + + public readonly Moments Minus(in Moments m) => new() { N = N - m.N, R = R - m.R, G = G - m.G, B = B - m.B, Squares = Squares - m.Squares }; + + /// Sum of squared distances to the mean colour. + public readonly double Error => N == 0 ? 0 : Squares - ((double)R * R + (double)G * G + (double)B * B) / N; + } + + private readonly record struct Box(int Start, int End, Moments Moments); + + private static byte[] MedianCut(ReadOnlySpan rgb, int maxColors) + { + var bins = new Moments[1 << 15]; + for (var i = 0; i + 2 < rgb.Length; i += 3) + { + int r = rgb[i], g = rgb[i + 1], b = rgb[i + 2]; + ref var m = ref bins[(r >> 3) << 10 | (g >> 3) << 5 | (b >> 3)]; + m.N++; + m.R += r; + m.G += g; + m.B += b; + m.Squares += r * r + g * g + b * b; + } + var used = new List(); + var total = default(Moments); + for (var b = 0; b < bins.Length; b++) + { + if (bins[b].N == 0) continue; + used.Add(b); + total.Add(bins[b]); + } + var order = used.ToArray(); + var keys = new int[order.Length]; + var boxes = new List { new(0, order.Length, total) }; + + while (boxes.Count < maxColors) + { + var pick = -1; + double worst = 0; + for (var i = 0; i < boxes.Count; i++) + { + if (boxes[i].End - boxes[i].Start > 1 && boxes[i].Moments.Error > worst) + { + worst = boxes[i].Moments.Error; + pick = i; + } + } + if (pick < 0) break; + var box = boxes[pick]; + var (axis, split, left) = BestSplit(order, keys, bins, box); + var shift = 10 - axis * 5; + for (var i = box.Start; i < box.End; i++) keys[i] = (order[i] >> shift) & 31; + Array.Sort(keys, order, box.Start, box.End - box.Start); + boxes[pick] = new Box(box.Start, split, left); + boxes.Add(new Box(split, box.End, box.Moments.Minus(left))); + } + + var palette = new byte[boxes.Count * 3]; + for (var p = 0; p < boxes.Count; p++) + { + var m = boxes[p].Moments; + palette[p * 3] = (byte)((m.R + m.N / 2) / m.N); + palette[p * 3 + 1] = (byte)((m.G + m.N / 2) / m.N); + palette[p * 3 + 2] = (byte)((m.B + m.N / 2) / m.N); + } + return palette; + } + + /// Tries each axis; returns the cut (first index of the right half) with the least summed error. + private static (int Axis, int Split, Moments Left) BestSplit(int[] order, int[] keys, Moments[] bins, Box box) + { + (int Axis, int Split, Moments Left) best = (0, box.Start + 1, bins[order[box.Start]]); + var bestError = double.MaxValue; + for (var axis = 0; axis < 3; axis++) + { + var shift = 10 - axis * 5; + for (var i = box.Start; i < box.End; i++) keys[i] = (order[i] >> shift) & 31; + Array.Sort(keys, order, box.Start, box.End - box.Start); + var left = default(Moments); + for (var i = box.Start; i < box.End - 1; i++) + { + left.Add(bins[order[i]]); + if (keys[i] == keys[i + 1]) continue; // cut only between distinct coordinates + var error = left.Error + box.Moments.Minus(left).Error; + if (error < bestError) + { + bestError = error; + best = (axis, i + 1, left); + } + } + } + return best; + } + + /// Nearest palette entry (weighted RGB distance) with a green-sorted pruned search and a colour cache. + public sealed class Map + { + private readonly byte[] _palette; + private readonly int[] _order; + private readonly int[] _green; + private readonly int[] _cacheKey = new int[1 << 16]; + private readonly byte[] _cacheValue = new byte[1 << 16]; + + public Map(byte[] palette) + { + _palette = palette; + var n = palette.Length / 3; + _order = new int[n]; + _green = new int[n]; + for (var i = 0; i < n; i++) + { + _order[i] = i; + _green[i] = palette[i * 3 + 1]; + } + Array.Sort(_green, _order); + } + + public int Nearest(int r, int g, int b) + { + var color = r << 16 | g << 8 | b; + var slot = (int)(((uint)color * 0x9E3779B1u) >> 16); + if (_cacheKey[slot] == color + 1) return _cacheValue[slot]; + + var best = int.MaxValue; + var bestIndex = 0; + var up = LowerBound(g); + var down = up - 1; + while (up < _green.Length || down >= 0) + { + if (up < _green.Length) + { + var dg = _green[up] - g; + if (WeightG * dg * dg >= best) up = _green.Length; + else Consider(_order[up++], r, g, b, ref best, ref bestIndex); + } + if (down >= 0) + { + var dg = g - _green[down]; + if (WeightG * dg * dg >= best) down = -1; + else Consider(_order[down--], r, g, b, ref best, ref bestIndex); + } + } + _cacheKey[slot] = color + 1; + _cacheValue[slot] = (byte)bestIndex; + return bestIndex; + } + + private void Consider(int index, int r, int g, int b, ref int best, ref int bestIndex) + { + var dr = _palette[index * 3] - r; + var dg = _palette[index * 3 + 1] - g; + var db = _palette[index * 3 + 2] - b; + var d = WeightR * dr * dr + WeightG * dg * dg + WeightB * db * db; + if (d < best) + { + best = d; + bestIndex = index; + } + } + + private int LowerBound(int g) + { + int lo = 0, hi = _green.Length; + while (lo < hi) + { + var mid = (lo + hi) >> 1; + if (_green[mid] < g) lo = mid + 1; + else hi = mid; + } + return lo; + } + } +} diff --git a/tests/Titano.Core.Tests/Video/GifEncoderTests.cs b/tests/Titano.Core.Tests/Video/GifEncoderTests.cs new file mode 100644 index 00000000..4ac317cc --- /dev/null +++ b/tests/Titano.Core.Tests/Video/GifEncoderTests.cs @@ -0,0 +1,255 @@ +using Titano.Core.Codecs.Gif; +using Titano.Core.Imaging; +using Titano.Testing; + +namespace Titano.Core.Tests.Video; + +public sealed class GifEncoderTests(TestContext context) +{ + private const int W = 64, H = 48; + private const long Frame30 = 3000; // 1/30 s in 90 kHz ticks + + [Test] + public void SmoothFramesRoundTripWithinPaletteError() + { + var frames = Enumerable.Range(0, 4).Select(i => Smooth(i * 3)).ToList(); + var plain = Encode(frames, new GifEncoderOptions { Dither = false }); + var dithered = Encode(frames, new GifEncoderOptions()); + Assert.Equal(4, plain.Frames.Count); + Assert.True(plain.GlobalTable); + for (var f = 0; f < frames.Count; f++) + { + var (mean, max) = Error(frames[f], plain.Frames[f].Canvas); + Assert.Less(mean, 6.0, $"frame {f} mean error"); + Assert.Less(max, 40, $"frame {f} max error"); + context.Log($"frame {f}: plain {mean:0.00}/{max}, dithered tiles {TileError(frames[f], dithered.Frames[f].Canvas):0.00}"); + // Dithering trades per-pixel error for accurate local averages. + Assert.Less(TileError(frames[f], dithered.Frames[f].Canvas), 2.0, $"frame {f} 4×4 average error"); + } + } + + /// Mean absolute difference of 4×4 tile averages. + private static double TileError(byte[] rgb, byte[] rgba) + { + double sum = 0; + var tiles = 0; + for (var ty = 0; ty < H / 4; ty++) + { + for (var tx = 0; tx < W / 4; tx++) + { + for (var c = 0; c < 3; c++) + { + double a = 0, b = 0; + for (var y = 0; y < 4; y++) + { + for (var x = 0; x < 4; x++) + { + var i = (ty * 4 + y) * W + tx * 4 + x; + a += rgb[i * 3 + c]; + b += rgba[i * 4 + c]; + } + } + sum += Math.Abs(a - b) / 16; + tiles++; + } + } + } + return sum / tiles; + } + + [Test] + public void ExactColoursReproduceExactly() + { + var palette = RandomColours(120, 5); + var frames = Enumerable.Range(0, 3).Select(i => Blocks(palette, i)).ToList(); + var gif = Encode(frames, new GifEncoderOptions { Dither = false, DifferenceThreshold = 0 }); + for (var f = 0; f < frames.Count; f++) Assert.Equal((0.0, 0), Error(frames[f], gif.Frames[f].Canvas)); + } + + [Test] + public void DelaysFollowTheCumulativeTimelineAndLoopIsWritten() + { + var frames = Enumerable.Range(0, 10).Select(i => Blocks(RandomColours(8, i), i)).ToList(); + var gif = Encode(frames, new GifEncoderOptions()); + Assert.Equal(0, gif.LoopCount); + Assert.SequenceEqual([3, 4, 3, 3, 4, 3, 3, 4, 3, 3], gif.Frames.Select(f => f.DelayCs)); + Assert.Equal(33, gif.Frames.Sum(f => f.DelayCs)); + + Assert.Equal(5, Encode(frames, new GifEncoderOptions { LoopCount = 5 }).LoopCount); + Assert.Null(Encode(frames, new GifEncoderOptions { LoopCount = null }).LoopCount); + } + + [Test] + public void DifferencingCropsToTheChangedAreaAndKeepsTheRest() + { + var palette = RandomColours(64, 9); + var a = Blocks(palette, 0); + var b = (byte[])a.Clone(); + for (var y = 7; y < 11; y++) + { + for (var x = 10; x < 15; x++) + { + var i = (y * W + x) * 3; + b[i] = (byte)(255 - b[i]); + b[i + 1] = (byte)(255 - b[i + 1]); + } + } + var gif = Encode([a, b], new GifEncoderOptions { Dither = false, DifferenceThreshold = 0 }); + Assert.Equal(2, gif.Frames.Count); + var second = gif.Frames[1]; + Assert.Equal((10, 7, 5, 4), (second.Left, second.Top, second.Width, second.Height)); + Assert.True(second.Transparent); + Assert.Equal(1, second.Disposal); + Assert.Equal(1, gif.Frames[0].Disposal); + Assert.False(gif.Frames[0].Transparent); + Assert.Equal((0.0, 0), Error(b, second.Canvas)); + } + + [Test] + public void IdenticalFramesMergeIntoOneLongerFrame() + { + var palette = RandomColours(16, 2); + var a = Blocks(palette, 0); + var b = Blocks(palette, 1); + var gif = Encode([a, a, a, b], new GifEncoderOptions { Dither = false }); + Assert.Equal(2, gif.Frames.Count); + Assert.Equal(10, gif.Frames[0].DelayCs); + Assert.Equal(3, gif.Frames[1].DelayCs); + } + + [Test] + public void LocalPalettesFollowEachFrame() + { + var reds = Enumerable.Range(0, 200).SelectMany(i => new[] { (byte)(55 + i), (byte)(i / 4), (byte)0 }).ToArray(); + var blues = Enumerable.Range(0, 200).SelectMany(i => new[] { (byte)0, (byte)(i / 4), (byte)(55 + i) }).ToArray(); + var frames = new List { Blocks(reds, 0), Blocks(blues, 0) }; + var gif = Encode(frames, new GifEncoderOptions { PaletteMode = GifPaletteMode.Local, Dither = false, DifferenceThreshold = 0 }); + Assert.False(gif.GlobalTable); + Assert.True(gif.Frames.All(f => f.LocalTable)); + for (var f = 0; f < 2; f++) Assert.Equal((0.0, 0), Error(frames[f], gif.Frames[f].Canvas)); + } + + [Test] + public void LzwSurvivesDictionaryResets() + { + // 200×200 pixels of random indices fill the 4096-entry dictionary many times over. + const int size = 200; + var palette = RandomColours(200, 4); + var rng = new Random(8); + var rgb = new byte[size * size * 3]; + for (var i = 0; i < size * size; i++) + { + var c = rng.Next(200); + rgb[i * 3] = palette[c * 3]; + rgb[i * 3 + 1] = palette[c * 3 + 1]; + rgb[i * 3 + 2] = palette[c * 3 + 2]; + } + using var ms = new MemoryStream(); + var encoder = new GifEncoder(ms, size, size, new GifEncoderOptions { Dither = false, FrameDifferencing = false }); + encoder.AddFrame(rgb, Frame30); + encoder.Complete(); + var gif = GifTestDecoder.Decode(ms.ToArray()); + Assert.Equal((0.0, 0), Error(rgb, gif.Frames[0].Canvas)); + } + + [Test] + public void LinearImageBuffersAreEncodedAsSrgb() + { + var palette = RandomColours(30, 6); + var rgb = Blocks(palette, 3); + using var image = new ImageBuffer(W, H); + for (var i = 0; i < W * H; i++) + { + for (var c = 0; c < 3; c++) image.Plane(c)[i] = ColorSpace.Linear8(rgb[i * 3 + c]); + } + using var ms = new MemoryStream(); + var encoder = new GifEncoder(ms, W, H, new GifEncoderOptions { Dither = false }); + encoder.AddFrame(image, Frame30); + encoder.Complete(); + Assert.Equal(1, encoder.FrameCount); + Assert.Equal((0.0, 0), Error(rgb, GifTestDecoder.Decode(ms.ToArray()).Frames[0].Canvas)); + } + + [Test] + public void SuppliedPaletteIsUsedAsGlobalTable() + { + using var image = new ImageBuffer(W, H); + image.Plane(0).Fill(0.5f); + var palette = GifEncoder.BuildPalette([image], 4); + Assert.Equal(3, palette.Length); + using var ms = new MemoryStream(); + var encoder = new GifEncoder(ms, W, H, new GifEncoderOptions { Palette = palette }); + encoder.AddFrame(image, Frame30); + encoder.Complete(); + var gif = GifTestDecoder.Decode(ms.ToArray()); + Assert.True(gif.GlobalTable); + Assert.Equal(ColorSpace.Encode8(0.5f), gif.Frames[0].Canvas[0]); + } + + private static GifTestDecoder Encode(List frames, GifEncoderOptions options) + { + using var ms = new MemoryStream(); + var encoder = new GifEncoder(ms, W, H, options); + foreach (var f in frames) encoder.AddFrame(f, Frame30); + encoder.Complete(); + return GifTestDecoder.Decode(ms.ToArray()); + } + + private static (double Mean, int Max) Error(byte[] rgb, byte[] rgba) + { + long sum = 0; + var max = 0; + for (var i = 0; i < rgb.Length / 3; i++) + { + for (var c = 0; c < 3; c++) + { + var d = Math.Abs(rgb[i * 3 + c] - rgba[i * 4 + c]); + sum += d; + max = Math.Max(max, d); + } + } + return (sum / (double)rgb.Length, max); + } + + private static byte[] Smooth(int shift) + { + var rgb = new byte[W * H * 3]; + for (var y = 0; y < H; y++) + { + for (var x = 0; x < W; x++) + { + var i = (y * W + x) * 3; + rgb[i] = (byte)((x + shift) * 255 / (W + 12)); + rgb[i + 1] = (byte)(y * 255 / H); + rgb[i + 2] = (byte)(128 + 100 * Math.Sin((x + y + shift) * 0.1)); + } + } + return rgb; + } + + private static byte[] RandomColours(int count, int seed) + { + var bytes = new byte[count * 3]; + new Random(seed).NextBytes(bytes); + return bytes; + } + + /// 4×4 blocks coloured from , pattern varying with . + private static byte[] Blocks(byte[] palette, int variant) + { + var colours = palette.Length / 3; + var rgb = new byte[W * H * 3]; + for (var y = 0; y < H; y++) + { + for (var x = 0; x < W; x++) + { + var c = ((x / 4) * 7 + (y / 4) * 13 + variant * 5) % colours; + var i = (y * W + x) * 3; + rgb[i] = palette[c * 3]; + rgb[i + 1] = palette[c * 3 + 1]; + rgb[i + 2] = palette[c * 3 + 2]; + } + } + return rgb; + } +} diff --git a/tests/Titano.Core.Tests/Video/GifTestDecoder.cs b/tests/Titano.Core.Tests/Video/GifTestDecoder.cs new file mode 100644 index 00000000..1283fae6 --- /dev/null +++ b/tests/Titano.Core.Tests/Video/GifTestDecoder.cs @@ -0,0 +1,197 @@ +using System.Text; +using Titano.Testing; + +namespace Titano.Core.Tests.Video; + +/// Minimal GIF89a decoder used to verify GifEncoder output (composition with disposal 0–3). +internal sealed class GifTestDecoder +{ + public sealed record Frame(byte[] Canvas, int DelayCs, int Left, int Top, int Width, int Height, int Disposal, bool Transparent, bool LocalTable); + + public int Width { get; private set; } + public int Height { get; private set; } + public bool GlobalTable { get; private set; } + public int? LoopCount { get; private set; } + public List Frames { get; } = []; + + public static GifTestDecoder Decode(byte[] data) + { + var gif = new GifTestDecoder(); + Assert.Equal("GIF89a", Encoding.ASCII.GetString(data, 0, 6)); + gif.Width = data[6] | data[7] << 8; + gif.Height = data[8] | data[9] << 8; + var pos = 13; + byte[]? global = null; + if ((data[10] & 0x80) != 0) + { + gif.GlobalTable = true; + var size = 3 << ((data[10] & 7) + 1); + global = data.AsSpan(pos, size).ToArray(); + pos += size; + } + var canvas = new byte[gif.Width * gif.Height * 4]; + int delay = 0, disposal = 0, transparentIndex = -1; + while (true) + { + var block = data[pos++]; + if (block == 0x3B) break; + if (block == 0x21) + { + var label = data[pos++]; + if (label == 0xF9) + { + Assert.Equal((byte)4, data[pos]); + disposal = (data[pos + 1] >> 2) & 7; + transparentIndex = (data[pos + 1] & 1) != 0 ? data[pos + 4] : -1; + delay = data[pos + 2] | data[pos + 3] << 8; + pos += 6; + } + else if (label == 0xFF && Encoding.ASCII.GetString(data, pos + 1, 11) == "NETSCAPE2.0") + { + gif.LoopCount = data[pos + 14] | data[pos + 15] << 8; + pos += 12; + pos = SkipSubBlocks(data, pos); + } + else + { + pos = SkipSubBlocks(data, pos); + } + continue; + } + Assert.Equal((byte)0x2C, block); + var left = data[pos] | data[pos + 1] << 8; + var top = data[pos + 2] | data[pos + 3] << 8; + var w = data[pos + 4] | data[pos + 5] << 8; + var h = data[pos + 6] | data[pos + 7] << 8; + var packed = data[pos + 8]; + pos += 9; + var table = global; + var local = (packed & 0x80) != 0; + if (local) + { + var size = 3 << ((packed & 7) + 1); + table = data.AsSpan(pos, size).ToArray(); + pos += size; + } + Assert.False((packed & 0x40) != 0, "interlaced frames are not produced"); + Assert.True(left + w <= gif.Width && top + h <= gif.Height, "frame inside the logical screen"); + var minCode = data[pos++]; + using var lzw = new MemoryStream(); + while (data[pos] != 0) + { + lzw.Write(data, pos + 1, data[pos]); + pos += data[pos] + 1; + } + pos++; + var indices = DecodeLzw(lzw.ToArray(), minCode, w * h); + var saved = disposal == 3 ? (byte[])canvas.Clone() : null; + for (var y = 0; y < h; y++) + { + for (var x = 0; x < w; x++) + { + var index = indices[y * w + x]; + if (index == transparentIndex) continue; + var o = ((top + y) * gif.Width + left + x) * 4; + canvas[o] = table![index * 3]; + canvas[o + 1] = table[index * 3 + 1]; + canvas[o + 2] = table[index * 3 + 2]; + canvas[o + 3] = 255; + } + } + gif.Frames.Add(new Frame((byte[])canvas.Clone(), delay, left, top, w, h, disposal, transparentIndex >= 0, local)); + if (disposal == 2) + { + for (var y = 0; y < h; y++) canvas.AsSpan(((top + y) * gif.Width + left) * 4, w * 4).Clear(); + } + else if (disposal == 3) + { + canvas = saved!; + } + delay = 0; + disposal = 0; + transparentIndex = -1; + } + return gif; + } + + private static int SkipSubBlocks(byte[] data, int pos) + { + while (data[pos] != 0) pos += data[pos] + 1; + return pos + 1; + } + + private static byte[] DecodeLzw(byte[] data, int minCode, int pixels) + { + var output = new List(pixels); + var prefix = new short[4096]; + var suffix = new byte[4096]; + var stack = new byte[4097]; + var clear = 1 << minCode; + var end = clear + 1; + var codeSize = minCode + 1; + var next = end + 1; + var old = -1; + long bits = 0; + var count = 0; + var pos = 0; + while (true) + { + while (count < codeSize && pos < data.Length) + { + bits |= (long)data[pos++] << count; + count += 8; + } + Assert.True(count >= codeSize, "LZW data ended before the end code"); + var code = (int)(bits & ((1 << codeSize) - 1)); + bits >>= codeSize; + count -= codeSize; + if (code == clear) + { + codeSize = minCode + 1; + next = end + 1; + old = -1; + continue; + } + if (code == end) break; + if (old == -1) + { + Assert.True(code < clear, "first code after clear is a literal"); + output.Add((byte)code); + old = code; + continue; + } + Assert.True(code <= next, $"LZW code {code} beyond the table ({next})"); + var depth = 0; + var c = code; + if (code == next) + { + stack[depth++] = First(old, prefix, suffix, clear); + c = old; + } + while (c >= clear) + { + stack[depth++] = suffix[c]; + c = prefix[c]; + } + stack[depth++] = (byte)c; + var firstByte = (byte)c; + for (var i = depth - 1; i >= 0; i--) output.Add(stack[i]); + if (next < 4096) + { + prefix[next] = (short)old; + suffix[next] = firstByte; + next++; + if (next == 1 << codeSize && codeSize < 12) codeSize++; + } + old = code; + } + Assert.Equal(pixels, output.Count); + return [.. output]; + } + + private static byte First(int code, short[] prefix, byte[] suffix, int clear) + { + while (code >= clear) code = prefix[code]; + return (byte)code; + } +}