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;
+ }
+}