feat(gif): add animated GIF encoder with variance-split palettes, dithering and frame differencing

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:49:30 +00:00
1 parent e15bbb9974
commit 71c0113f5f
5 files changed
+1166

No files matched your search

+394
View File
@@ -0,0 +1,394 @@
using Titano.Core.Diagnostics;
using Titano.Core.Imaging;
namespace Titano.Core.Codecs.Gif;
/// <summary>Where GIF frames take their colours from.</summary>
public enum GifPaletteMode
{
/// <summary>One palette for the whole animation, built from the first frames (or supplied).</summary>
Global,
/// <summary>A palette per frame, built from that frame.</summary>
Local,
}
/// <summary>Options of <see cref="GifEncoder"/>.</summary>
public sealed record GifEncoderOptions
{
/// <summary>NETSCAPE2.0 loop count: 0 loops forever; null plays once (no loop extension).</summary>
public int? LoopCount { get; init; } = 0;
/// <summary>Serpentine Floyd–Steinberg error diffusion.</summary>
public bool Dither { get; init; } = true;
/// <summary>Unchanged pixels become transparent and frames are cropped to the changed area.</summary>
public bool FrameDifferencing { get; init; } = true;
/// <summary>Largest per-channel difference (8-bit) between a pixel and its value when last drawn that still counts as unchanged.</summary>
public int DifferenceThreshold { get; init; } = 2;
public GifPaletteMode PaletteMode { get; init; } = GifPaletteMode.Global;
/// <summary>Frames buffered to build the global palette when <see cref="Palette"/> is not supplied.</summary>
public int PaletteSampleFrames { get; init; } = 8;
/// <summary>Optional global palette as RGB triples (see <see cref="GifEncoder.BuildPalette"/>).</summary>
public byte[]? Palette { get; init; }
/// <summary>Colours per palette, 2–256 (one is reserved for transparency when differencing).</summary>
public int MaxColors { get; init; } = 256;
}
/// <summary>
/// Animated GIF89a encoder. Frames arrive one by one as linear-light <see cref="ImageBuffer"/>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.
/// </summary>
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);
}
/// <summary>Frames written to the file so far (identical consecutive frames count once).</summary>
public int FrameCount { get; private set; }
/// <summary>Builds a palette (RGB triples) from sample frames, e.g. spread across a sequence.</summary>
public static byte[] BuildPalette(IEnumerable<ImageBuffer> 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);
}
/// <summary>Adds a linear-light frame (alpha ignored) shown for <paramref name="duration90k"/> ticks.</summary>
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);
}
/// <summary>Adds an interleaved 8-bit sRGB frame.</summary>
public void AddFrame(ReadOnlySpan<byte> rgb24, long duration90k)
{
if (rgb24.Length != _width * _height * 3) throw new ArgumentException("Expected width × height × 3 bytes", nameof(rgb24));
AddRgb(rgb24.ToArray(), duration90k);
}
/// <summary>Writes the remaining frames and the trailer.</summary>
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;
}
/// <summary>
/// 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.
/// </summary>
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<byte> 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;
}
/// <summary>Writes the pending frame with the delay up to <paramref name="end"/> (cumulative rounding keeps the total exact).</summary>
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<byte> 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<byte> 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;
/// <summary>Colour table size exponent (1–8) holding <paramref name="entries"/> entries.</summary>
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;
}
/// <summary>Every n-th pixel so at most about <paramref name="budget"/> pixels feed the palette (deterministic).</summary>
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;
}
}
+104
View File
@@ -0,0 +1,104 @@
namespace Titano.Core.Codecs.Gif;
/// <summary>GIF variable-length LZW encoder (GIF89a appendix F): clear/end codes, 12-bit cap, 255-byte sub-blocks.</summary>
internal static class GifLzw
{
private const int MaxCode = 4096;
private const int TableSize = 8192; // power of two > MaxCode for open addressing
/// <summary>Writes the LZW minimum code size, the data sub-blocks and the block terminator.</summary>
public static void Encode(ReadOnlySpan<byte> 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();
}
/// <summary>Packs codes LSB-first into sub-blocks of at most 255 bytes.</summary>
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;
}
}
}
+216
View File
@@ -0,0 +1,216 @@
namespace Titano.Core.Codecs.Gif;
/// <summary>Palette construction (exact or median cut) and nearest-colour mapping for GIF frames.</summary>
internal static class GifPalette
{
private const int WeightR = 2, WeightG = 4, WeightB = 3;
/// <summary>
/// Builds at most <paramref name="maxColors"/> 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.
/// </summary>
public static byte[] Build(ReadOnlySpan<byte> rgb, int maxColors)
{
var distinct = new HashSet<int>();
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);
}
/// <summary>Population moments of a set of histogram bins.</summary>
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 };
/// <summary>Sum of squared distances to the mean colour.</summary>
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<byte> 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<int>();
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<Box> { 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;
}
/// <summary>Tries each axis; returns the cut (first index of the right half) with the least summed error.</summary>
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;
}
/// <summary>Nearest palette entry (weighted RGB distance) with a green-sorted pruned search and a colour cache.</summary>
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;
}
}
}
@@ -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");
}
}
/// <summary>Mean absolute difference of 4×4 tile averages.</summary>
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<byte[]> { 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<byte[]> 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;
}
/// <summary>4×4 blocks coloured from <paramref name="palette"/>, pattern varying with <paramref name="variant"/>.</summary>
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;
}
}
@@ -0,0 +1,197 @@
using System.Text;
using Titano.Testing;
namespace Titano.Core.Tests.Video;
/// <summary>Minimal GIF89a decoder used to verify <c>GifEncoder</c> output (composition with disposal 0–3).</summary>
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<Frame> 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<byte>(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;
}
}