From 56757f12d34d86afac2e7b8a64aa1c059e8a79d0 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 11:21:58 +0000 Subject: [PATCH] feat(imaging): thumbs.pack, thumbnail LRU cache and proxy builder ThumbnailPack appends self-describing CRC-checked JPEG entries (320 px, q80) and index records; a two-slot header flips to each new index, so crashes and truncation lose only the damaged tail, and compaction rewrites live entries through AtomicFile. Reads are positional and run concurrently with the writer. ThumbnailCache is a byte-budget LRU that coalesces concurrent loads. ProxyBuilder decodes at the policy long edge with orientation applied and writes JPEG q92 with the source Exif (capture time kept, orientation reset). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- .../Imaging/Thumbnails/ProxyBuilder.cs | 64 +++ .../Imaging/Thumbnails/ThumbnailCache.cs | 156 ++++++ .../Imaging/Thumbnails/ThumbnailPack.cs | 497 ++++++++++++++++++ .../Decoding/ThumbnailTests.cs | 277 ++++++++++ 4 files changed, 994 insertions(+) create mode 100644 src/Titano.Core/Imaging/Thumbnails/ProxyBuilder.cs create mode 100644 src/Titano.Core/Imaging/Thumbnails/ThumbnailCache.cs create mode 100644 src/Titano.Core/Imaging/Thumbnails/ThumbnailPack.cs create mode 100644 tests/Titano.Core.Tests/Decoding/ThumbnailTests.cs diff --git a/src/Titano.Core/Imaging/Thumbnails/ProxyBuilder.cs b/src/Titano.Core/Imaging/Thumbnails/ProxyBuilder.cs new file mode 100644 index 00000000..3c9e403e --- /dev/null +++ b/src/Titano.Core/Imaging/Thumbnails/ProxyBuilder.cs @@ -0,0 +1,64 @@ +using Titano.Core.Codecs.Jpeg; +using Titano.Core.IO; +using Titano.Core.Metadata; + +namespace Titano.Core.Imaging.Thumbnails; + +/// Proxy long-edge policy (BRIEF §8.5). +public enum ProxySize +{ + /// Source resolution. + Full = 0, + Edge1280 = 1280, + Edge1920 = 1920, + Edge2560 = 2560, +} + +/// A built proxy and how its pixels were obtained. +/// JPEG file bytes with an Exif block. +/// Proxy width (oriented). +/// Proxy height (oriented). +/// Decode tier of the source (an embedded preview caps the proxy at the preview's size). +public sealed record ProxyResult(byte[] Jpeg, int Width, int Height, DecodeTier Tier); + +/// +/// Builds proxies (BRIEF §8.5): the source decoded at the policy long edge (1280/1920/2560 or full) with its orientation +/// applied, encoded as JPEG q92, carrying an Exif block written by from the +/// source metadata (capture time, camera, exposure, GPS) with orientation reset to 1 because the pixels are upright. +/// +public static class ProxyBuilder +{ + public const int Quality = 92; + + /// Default policy. + public const ProxySize DefaultSize = ProxySize.Edge1920; + + /// Decodes and encodes the proxy of ; null when no tier can decode it. + /// Source metadata; read from the file when null. + public static ProxyResult? Build(ImageDecoder decoder, string sourcePath, ProxySize size = DefaultSize, FrameMetadata? metadata = null, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(decoder); + using var decoded = decoder.Decode(new DecodeRequest(sourcePath, (int)size, DecodePurpose.Proxy), cancellationToken); + if (decoded is null) return null; + metadata ??= MetadataReader.Read(sourcePath, cancellationToken); + return new ProxyResult(Encode(decoded.Pixels, metadata), decoded.Pixels.Width, decoded.Pixels.Height, decoded.Tier); + } + + /// Builds the proxy and writes it crash-safely to . + public static ProxyResult? Write(ImageDecoder decoder, string sourcePath, string proxyPath, ProxySize size = DefaultSize, FrameMetadata? metadata = null, CancellationToken cancellationToken = default) + { + var result = Build(decoder, sourcePath, size, metadata, cancellationToken); + if (result is not null) AtomicFile.WriteAllBytes(proxyPath, result.Jpeg); + return result; + } + + /// Encodes upright linear-light pixels as a proxy JPEG with the source's Exif (orientation 1). + public static byte[] Encode(ImageBuffer image, FrameMetadata metadata) + { + ArgumentNullException.ThrowIfNull(image); + ArgumentNullException.ThrowIfNull(metadata); + var segment = ExifWriter.BuildJpegApp1(metadata with { Orientation = 1, Width = image.Width, Height = image.Height }); + // The encoder takes APP1 payloads: drop the marker and length that BuildJpegApp1 puts in front. + return JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = Quality, App1Segments = [segment[4..]], OptimizeHuffman = true }); + } +} diff --git a/src/Titano.Core/Imaging/Thumbnails/ThumbnailCache.cs b/src/Titano.Core/Imaging/Thumbnails/ThumbnailCache.cs new file mode 100644 index 00000000..863a4bba --- /dev/null +++ b/src/Titano.Core/Imaging/Thumbnails/ThumbnailCache.cs @@ -0,0 +1,156 @@ +using Titano.Core.Codecs.Jpeg; + +namespace Titano.Core.Imaging.Thumbnails; + +/// A decoded thumbnail ready for display: interleaved 8-bit sRGB RGB. +public sealed class Thumbnail(int width, int height, byte[] rgb) +{ + public int Width { get; } = width; + public int Height { get; } = height; + + /// Width × height × 3 bytes, sRGB-encoded, top-down. + public byte[] Rgb { get; } = rgb; + + /// Memory charged against a budget. + public long ByteSize => Rgb.Length + 64; + + /// Decodes a thumbnail JPEG (gray is expanded to RGB). + /// The JPEG is malformed. + public static Thumbnail FromJpeg(ReadOnlySpan jpeg) + { + var image = JpegDecoder.Decode(jpeg); + var pixels = image.Pixels8 ?? throw new InvalidDataException("Thumbnail: not an 8-bit JPEG"); + if (image.Components == 3) return new Thumbnail(image.Width, image.Height, pixels); + var rgb = new byte[pixels.Length * 3]; + for (var i = 0; i < pixels.Length; i++) rgb[3 * i] = rgb[3 * i + 1] = rgb[3 * i + 2] = pixels[i]; + return new Thumbnail(image.Width, image.Height, rgb); + } +} + +/// +/// In-memory LRU of decoded thumbnails under a byte budget (BRIEF §8.5). Thread-safe; concurrent requests for the same +/// key share one load (), so a scrolling UI never decodes a thumbnail twice. +/// +public sealed class ThumbnailCache where TKey : notnull +{ + private readonly Lock _gate = new(); + private readonly Dictionary> _map = []; + private readonly LinkedList<(TKey Key, Thumbnail Value)> _lru = new(); + private readonly Dictionary> _loading = []; + private long _bytes; + + /// Upper bound on the bytes held (a thumbnail larger than the budget is never cached). + public ThumbnailCache(long byteBudget) + { + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(byteBudget); + Budget = byteBudget; + } + + public long Budget { get; } + + public long Bytes + { + get + { + lock (_gate) return _bytes; + } + } + + public int Count + { + get + { + lock (_gate) return _map.Count; + } + } + + /// Returns a cached thumbnail and marks it most recently used. + public bool TryGet(TKey key, out Thumbnail thumbnail) + { + lock (_gate) + { + if (_map.TryGetValue(key, out var node)) + { + _lru.Remove(node); + _lru.AddFirst(node); + thumbnail = node.Value.Value; + return true; + } + } + thumbnail = null!; + return false; + } + + /// Adds or replaces a thumbnail, evicting least recently used ones to stay within the budget. + public void Set(TKey key, Thumbnail thumbnail) + { + ArgumentNullException.ThrowIfNull(thumbnail); + lock (_gate) + { + RemoveLocked(key); + if (thumbnail.ByteSize > Budget) return; + _map[key] = _lru.AddFirst((key, thumbnail)); + _bytes += thumbnail.ByteSize; + while (_bytes > Budget && _lru.Last is { } last) + { + RemoveLocked(last.Value.Key); + } + } + } + + public bool Remove(TKey key) + { + lock (_gate) return RemoveLocked(key); + } + + public void Clear() + { + lock (_gate) + { + _map.Clear(); + _lru.Clear(); + _bytes = 0; + } + } + + /// Cached thumbnail, or the result of (cached when not null). Concurrent calls for + /// the same key await the same load; each caller's only cancels its own wait. + public async Task GetOrLoadAsync(TKey key, Func> loader, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(loader); + if (TryGet(key, out var hit)) return hit; + Task task; + lock (_gate) + { + if (!_loading.TryGetValue(key, out task!)) + { + task = LoadAsync(key, loader); + _loading[key] = task; + } + } + return await task.WaitAsync(cancellationToken).ConfigureAwait(false); + } + + private async Task LoadAsync(TKey key, Func> loader) + { + try + { + await Task.Yield(); + var value = await loader(key, CancellationToken.None).ConfigureAwait(false); + if (value is not null) Set(key, value); + return value; + } + finally + { + lock (_gate) _loading.Remove(key); + } + } + + private bool RemoveLocked(TKey key) + { + if (!_map.Remove(key, out var node)) return false; + _lru.Remove(node); + _bytes -= node.Value.Value.ByteSize; + return true; + } +} diff --git a/src/Titano.Core/Imaging/Thumbnails/ThumbnailPack.cs b/src/Titano.Core/Imaging/Thumbnails/ThumbnailPack.cs new file mode 100644 index 00000000..3d6e104d --- /dev/null +++ b/src/Titano.Core/Imaging/Thumbnails/ThumbnailPack.cs @@ -0,0 +1,497 @@ +using System.Buffers.Binary; +using System.Collections.Concurrent; +using Microsoft.Win32.SafeHandles; +using Titano.Core.Codecs.Jpeg; +using Titano.Core.Hashing; +using Titano.Core.IO; + +namespace Titano.Core.Imaging.Thumbnails; + +/// Index entry of one thumbnail in a . +/// Frame the thumbnail belongs to. +/// File offset of the entry record. +/// JPEG length in bytes. +/// Thumbnail width in pixels. +/// Thumbnail height in pixels. +/// CRC-32 of the JPEG bytes. +public readonly record struct ThumbnailEntry(Guid FrameId, long Offset, int Length, int Width, int Height, uint Crc); + +/// +/// The per-sequence thumbnail file thumbs.pack (BRIEF §8.5): 320-pixel JPEG (q80) thumbnails appended to one file. +/// Layout (little-endian): two 64-byte header slots at 0 and 64 (magic "TTPK", version, generation, offset/length/ +/// count of the current index record, the file length it covers, CRC-32); from 128, self-describing records — entries +/// ("TENT": frame id, size, JPEG length and CRC, then the JPEG) and index tables ("TIDX": count, then frame id → offset, +/// length, size, CRC per entry, then the record's CRC). +/// Writes only append. Every appends (and on /) +/// a new index record is appended and flushed, then the header slot not holding the newest generation is overwritten and +/// flushed: a crash leaves the previous slot valid. Opening takes the newest valid slot, then recovers entries appended +/// after its index by scanning forward until the first damaged record, so truncated or partially written files lose +/// only their damaged tail. rewrites live entries into a fresh file committed with +/// . Reads use positional I/O and run concurrently with one writer. +/// +public sealed class ThumbnailPack : IDisposable +{ + public const int LongEdge = 320; + public const int Quality = 80; + public const int IndexInterval = 64; + + private const uint HeaderMagic = 0x4B505454; // "TTPK" + private const uint EntryMagic = 0x544E4554; // "TENT" + private const uint IndexMagic = 0x58444954; // "TIDX" + private const ushort Version = 1; + private const int SlotSize = 64; + private const int DataStart = 2 * SlotSize; + private const int EntryHeaderSize = 32; + private const int IndexEntrySize = 36; + private const int MaxJpegBytes = 16 << 20; + + private readonly ReaderWriterLockSlim _handleLock = new(LockRecursionPolicy.NoRecursion); + private readonly Lock _writeLock = new(); + private readonly List _warnings = []; + private ConcurrentDictionary _index = new(); + private SafeFileHandle _handle; + private long _tail; + private ulong _generation; + private int _activeSlot; + private int _unindexed; + private long _liveBytes; + private bool _disposed; + + private ThumbnailPack(string path, bool writable, SafeFileHandle handle) + { + Path = path; + Writable = writable; + _handle = handle; + Load(); + } + + public string Path { get; } + public bool Writable { get; } + + /// Problems met while opening or refreshing (damaged slots, records dropped from the tail). + public IReadOnlyList Warnings + { + get + { + lock (_warnings) return [.. _warnings]; + } + } + + public int Count => Volatile.Read(ref _index).Count; + + /// Snapshot of the frames with a thumbnail. + public IReadOnlyCollection FrameIds => [.. Volatile.Read(ref _index).Keys]; + + /// Bytes held by superseded or removed entries (reclaimed by ). + public long WastedBytes => long.Max(0, _tail - DataStart - Volatile.Read(ref _liveBytes)); + + /// Opens (creating when writable and missing) a pack. + public static ThumbnailPack Open(string path, bool writable = true) + { + ArgumentException.ThrowIfNullOrEmpty(path); + if (writable && !File.Exists(path)) AtomicFile.WriteAllBytes(path, EmptyFile()); + var handle = File.OpenHandle(path, FileMode.Open, writable ? FileAccess.ReadWrite : FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, FileOptions.RandomAccess); + return new ThumbnailPack(path, writable, handle); + } + + /// Downscales a linear-light image to the thumbnail long edge and encodes it (JPEG q80). + public static (byte[] Jpeg, int Width, int Height) Encode(ImageBuffer image) + { + ArgumentNullException.ThrowIfNull(image); + using var small = Resampler.Thumbnail(image, LongEdge); + return (JpegEncoder.Encode(small, new JpegEncodeOptions { Quality = Quality }), small.Width, small.Height); + } + + public bool TryGetEntry(Guid frameId, out ThumbnailEntry entry) => Volatile.Read(ref _index).TryGetValue(frameId, out entry); + + /// The JPEG bytes of a frame's thumbnail; null when absent or damaged (CRC mismatch). + public byte[]? ReadJpeg(Guid frameId) + { + if (!TryGetEntry(frameId, out var e)) return null; + var data = new byte[e.Length]; + _handleLock.EnterReadLock(); + try + { + ObjectDisposedException.ThrowIf(_disposed, this); + if (RandomAccess.Read(_handle, data, e.Offset + EntryHeaderSize) != data.Length) return null; + } + finally + { + _handleLock.ExitReadLock(); + } + return Crc32.Compute(data) == e.Crc ? data : null; + } + + /// Encodes and appends the thumbnail of , replacing any previous one for the frame. + public ThumbnailEntry Add(Guid frameId, ImageBuffer image) + { + var (jpeg, w, h) = Encode(image); + return AddJpeg(frameId, jpeg, w, h); + } + + /// Appends an encoded thumbnail, replacing any previous one for the frame. + public ThumbnailEntry AddJpeg(Guid frameId, ReadOnlySpan jpeg, int width, int height) + { + if (!Writable) throw new InvalidOperationException("The pack is open read-only."); + if (jpeg.Length is 0 or > MaxJpegBytes) throw new ArgumentOutOfRangeException(nameof(jpeg)); + if (width is < 1 or > ushort.MaxValue || height is < 1 or > ushort.MaxValue) throw new ArgumentOutOfRangeException(nameof(width)); + lock (_writeLock) + { + var record = new byte[EntryHeaderSize + jpeg.Length]; + BinaryPrimitives.WriteUInt32LittleEndian(record, EntryMagic); + frameId.TryWriteBytes(record.AsSpan(4)); + BinaryPrimitives.WriteUInt16LittleEndian(record.AsSpan(20), (ushort)width); + BinaryPrimitives.WriteUInt16LittleEndian(record.AsSpan(22), (ushort)height); + BinaryPrimitives.WriteInt32LittleEndian(record.AsSpan(24), jpeg.Length); + var crc = Crc32.Compute(jpeg); + BinaryPrimitives.WriteUInt32LittleEndian(record.AsSpan(28), crc); + jpeg.CopyTo(record.AsSpan(EntryHeaderSize)); + var entry = new ThumbnailEntry(frameId, _tail, jpeg.Length, width, height, crc); + WriteAt(record, _tail); + _tail += record.Length; + if (_index.TryGetValue(frameId, out var old)) Interlocked.Add(ref _liveBytes, -(EntryHeaderSize + old.Length)); + _index[frameId] = entry; + Interlocked.Add(ref _liveBytes, record.Length); + if (++_unindexed >= IndexInterval) WriteIndex(); + return entry; + } + } + + /// Drops a frame's thumbnail from the index (its bytes stay until ). + public bool Remove(Guid frameId) + { + if (!Writable) throw new InvalidOperationException("The pack is open read-only."); + lock (_writeLock) + { + if (!_index.TryRemove(frameId, out var old)) return false; + Interlocked.Add(ref _liveBytes, -(EntryHeaderSize + old.Length)); + _unindexed++; + return true; + } + } + + /// Writes the index now (appended record, then the alternate header slot). + public void Flush() + { + if (!Writable) return; + lock (_writeLock) + { + if (_unindexed > 0) WriteIndex(); + } + } + + /// Rewrites the live entries into a new file and atomically replaces this one. + public void Compact() + { + if (!Writable) throw new InvalidOperationException("The pack is open read-only."); + lock (_writeLock) + { + var temp = AtomicFile.TempPathFor(Path); + var entries = Volatile.Read(ref _index).Values.OrderBy(e => e.Offset).ToList(); + var moved = new ConcurrentDictionary(); + using (var output = new FileStream(temp, FileMode.CreateNew, FileAccess.Write, FileShare.None, 1 << 16)) + { + output.Write(new byte[DataStart]); + var buffer = new byte[EntryHeaderSize + MaxJpegBytes / 16]; + foreach (var e in entries) + { + var size = EntryHeaderSize + e.Length; + if (buffer.Length < size) buffer = new byte[size]; + _handleLock.EnterReadLock(); + int read; + try + { + read = RandomAccess.Read(_handle, buffer.AsSpan(0, size), e.Offset); + } + finally + { + _handleLock.ExitReadLock(); + } + if (read != size || Crc32.Compute(buffer.AsSpan(EntryHeaderSize, e.Length)) != e.Crc) + { + Warn($"Thumbnail of {e.FrameId} damaged; dropped during compaction"); + continue; + } + moved[e.FrameId] = e with { Offset = output.Position }; + output.Write(buffer, 0, size); + } + var indexOffset = output.Position; + var index = IndexRecord(moved.Values); + output.Write(index); + output.Position = 0; + output.Write(HeaderSlot(_generation + 1, indexOffset, index.Length, moved.Count, indexOffset + index.Length)); + } + _handleLock.EnterWriteLock(); + try + { + _handle.Dispose(); + AtomicFile.Commit(temp, Path); + _handle = File.OpenHandle(Path, FileMode.Open, FileAccess.ReadWrite, FileShare.ReadWrite | FileShare.Delete, FileOptions.RandomAccess); + _index = moved; + _generation++; + _activeSlot = 0; + _tail = RandomAccess.GetLength(_handle); + _liveBytes = moved.Values.Sum(e => (long)EntryHeaderSize + e.Length); + _unindexed = 0; + } + finally + { + _handleLock.ExitWriteLock(); + } + } + } + + /// Re-reads the file (read-only instances use it to see entries written by another instance). + public void Refresh() + { + if (Writable) return; + _handleLock.EnterWriteLock(); + try + { + ObjectDisposedException.ThrowIf(_disposed, this); + _handle.Dispose(); + _handle = File.OpenHandle(Path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, FileOptions.RandomAccess); + } + finally + { + _handleLock.ExitWriteLock(); + } + Load(); + } + + public void Dispose() + { + if (_disposed) return; + if (Writable) + { + try + { + Flush(); + } + catch (IOException ex) + { + Warn("Index not written on close: " + ex.Message); + } + } + _handleLock.EnterWriteLock(); + try + { + _disposed = true; + _handle.Dispose(); + } + finally + { + _handleLock.ExitWriteLock(); + } + _handleLock.Dispose(); + } + + private static byte[] EmptyFile() + { + var file = new byte[DataStart]; + HeaderSlot(1, 0, 0, 0, DataStart).CopyTo(file, 0); + return file; + } + + private static byte[] HeaderSlot(ulong generation, long indexOffset, int indexLength, int count, long dataEnd) + { + var slot = new byte[SlotSize]; + BinaryPrimitives.WriteUInt32LittleEndian(slot, HeaderMagic); + BinaryPrimitives.WriteUInt16LittleEndian(slot.AsSpan(4), Version); + BinaryPrimitives.WriteUInt64LittleEndian(slot.AsSpan(8), generation); + BinaryPrimitives.WriteInt64LittleEndian(slot.AsSpan(16), indexOffset); + BinaryPrimitives.WriteInt32LittleEndian(slot.AsSpan(24), indexLength); + BinaryPrimitives.WriteInt32LittleEndian(slot.AsSpan(28), count); + BinaryPrimitives.WriteInt64LittleEndian(slot.AsSpan(32), dataEnd); + BinaryPrimitives.WriteUInt32LittleEndian(slot.AsSpan(SlotSize - 4), Crc32.Compute(slot.AsSpan(0, SlotSize - 4))); + return slot; + } + + private static byte[] IndexRecord(IEnumerable entries) + { + var list = entries.ToList(); + var record = new byte[8 + list.Count * IndexEntrySize + 4]; + BinaryPrimitives.WriteUInt32LittleEndian(record, IndexMagic); + BinaryPrimitives.WriteInt32LittleEndian(record.AsSpan(4), list.Count); + for (var i = 0; i < list.Count; i++) + { + var s = record.AsSpan(8 + i * IndexEntrySize, IndexEntrySize); + var e = list[i]; + e.FrameId.TryWriteBytes(s); + BinaryPrimitives.WriteInt64LittleEndian(s[16..], e.Offset); + BinaryPrimitives.WriteInt32LittleEndian(s[24..], e.Length); + BinaryPrimitives.WriteUInt16LittleEndian(s[28..], (ushort)e.Width); + BinaryPrimitives.WriteUInt16LittleEndian(s[30..], (ushort)e.Height); + BinaryPrimitives.WriteUInt32LittleEndian(s[32..], e.Crc); + } + BinaryPrimitives.WriteUInt32LittleEndian(record.AsSpan(record.Length - 4), Crc32.Compute(record.AsSpan(0, record.Length - 4))); + return record; + } + + /// Appends an index record, flushes, then commits it through the header slot not holding the newest generation. + private void WriteIndex() + { + var index = Volatile.Read(ref _index); + var record = IndexRecord(index.Values); + var offset = _tail; + WriteAt(record, offset); + _tail += record.Length; + RandomAccess.FlushToDisk(_handle); + var slot = 1 - _activeSlot; + WriteAt(HeaderSlot(_generation + 1, offset, record.Length, index.Count, _tail), slot * SlotSize); + RandomAccess.FlushToDisk(_handle); + _generation++; + _activeSlot = slot; + _unindexed = 0; + } + + private void WriteAt(ReadOnlySpan data, long offset) + { + _handleLock.EnterReadLock(); + try + { + ObjectDisposedException.ThrowIf(_disposed, this); + RandomAccess.Write(_handle, data, offset); + } + finally + { + _handleLock.ExitReadLock(); + } + } + + private void Warn(string message) + { + lock (_warnings) + { + if (_warnings.Count < 32) _warnings.Add(message); + } + } + + /// Reads the newest valid header slot and its index, then recovers entries appended after it. + private void Load() + { + long length; + _handleLock.EnterReadLock(); + try + { + length = RandomAccess.GetLength(_handle); + } + finally + { + _handleLock.ExitReadLock(); + } + var index = new ConcurrentDictionary(); + long scanFrom = DataStart; + (_generation, _activeSlot) = (0, 1); + var slots = new byte[DataStart]; + var slotBytes = ReadAt(slots, 0); + for (var s = 0; s < 2; s++) + { + if (slotBytes < (s + 1) * SlotSize || ParseSlot(slots.AsSpan(s * SlotSize, SlotSize)) is not { } h) + { + if (slotBytes >= (s + 1) * SlotSize && slots.AsSpan(s * SlotSize, SlotSize).ContainsAnyExcept((byte)0)) Warn($"Header slot {s} damaged"); + continue; + } + if (h.Generation <= _generation) continue; + var loaded = h.IndexLength > 0 ? ReadIndex(h.IndexOffset, h.IndexLength, length) : new ConcurrentDictionary(); + if (loaded is null) + { + Warn($"Index of header slot {s} damaged"); + continue; + } + (_generation, _activeSlot) = (h.Generation, s); + index = loaded; + scanFrom = h.DataEnd; + } + if (_generation == 0) Warn("No valid header; entries recovered by scanning"); + _tail = length <= DataStart ? DataStart : Recover(index, long.Clamp(scanFrom, DataStart, length), length); + _index = index; + _liveBytes = index.Values.Sum(e => (long)EntryHeaderSize + e.Length); + _unindexed = 0; + } + + private readonly record struct Slot(ulong Generation, long IndexOffset, int IndexLength, long DataEnd); + + private static Slot? ParseSlot(ReadOnlySpan s) + { + if (BinaryPrimitives.ReadUInt32LittleEndian(s) != HeaderMagic || BinaryPrimitives.ReadUInt16LittleEndian(s[4..]) != Version) return null; + if (Crc32.Compute(s[..(SlotSize - 4)]) != BinaryPrimitives.ReadUInt32LittleEndian(s[(SlotSize - 4)..])) return null; + return new Slot(BinaryPrimitives.ReadUInt64LittleEndian(s[8..]), BinaryPrimitives.ReadInt64LittleEndian(s[16..]), + BinaryPrimitives.ReadInt32LittleEndian(s[24..]), BinaryPrimitives.ReadInt64LittleEndian(s[32..])); + } + + private ConcurrentDictionary? ReadIndex(long offset, int length, long fileLength) + { + if (offset < DataStart || length < 12 || offset > fileLength - length || (length - 12) % IndexEntrySize != 0) return null; + var record = new byte[length]; + if (ReadAt(record, offset) != length) return null; + if (BinaryPrimitives.ReadUInt32LittleEndian(record) != IndexMagic + || Crc32.Compute(record.AsSpan(0, length - 4)) != BinaryPrimitives.ReadUInt32LittleEndian(record.AsSpan(length - 4))) return null; + var count = BinaryPrimitives.ReadInt32LittleEndian(record.AsSpan(4)); + if (count != (length - 12) / IndexEntrySize) return null; + var index = new ConcurrentDictionary(); + for (var i = 0; i < count; i++) + { + var s = record.AsSpan(8 + i * IndexEntrySize, IndexEntrySize); + var e = new ThumbnailEntry(new Guid(s[..16]), BinaryPrimitives.ReadInt64LittleEndian(s[16..]), BinaryPrimitives.ReadInt32LittleEndian(s[24..]), + BinaryPrimitives.ReadUInt16LittleEndian(s[28..]), BinaryPrimitives.ReadUInt16LittleEndian(s[30..]), BinaryPrimitives.ReadUInt32LittleEndian(s[32..])); + if (e.Offset >= DataStart && e.Length is > 0 and <= MaxJpegBytes && e.Offset <= fileLength - EntryHeaderSize - e.Length) index[e.FrameId] = e; + } + return index; + } + + /// Walks records from , adding valid entries (later ones win) and skipping index + /// records; stops at the first damaged or truncated record. Returns the end of the last good record. + private long Recover(ConcurrentDictionary index, long position, long length) + { + var head = new byte[EntryHeaderSize]; + var recovered = 0; + while (position + 12 <= length) + { + var n = ReadAt(head.AsSpan(0, (int)long.Min(EntryHeaderSize, length - position)), position); + var magic = BinaryPrimitives.ReadUInt32LittleEndian(head); + if (magic == IndexMagic && n >= 8) + { + var count = BinaryPrimitives.ReadInt32LittleEndian(head.AsSpan(4)); + var size = 12L + (long)count * IndexEntrySize; + if (count < 0 || position + size > length || ReadIndex(position, (int)long.Min(size, int.MaxValue), length) is null) break; + position += size; + continue; + } + if (magic != EntryMagic || n < EntryHeaderSize) break; + var jpegLength = BinaryPrimitives.ReadInt32LittleEndian(head.AsSpan(24)); + if (jpegLength is <= 0 or > MaxJpegBytes || position + EntryHeaderSize + jpegLength > length) break; + var jpeg = new byte[jpegLength]; + if (ReadAt(jpeg, position + EntryHeaderSize) != jpegLength) break; + var crc = BinaryPrimitives.ReadUInt32LittleEndian(head.AsSpan(28)); + if (Crc32.Compute(jpeg) != crc) break; + var id = new Guid(head.AsSpan(4, 16)); + index[id] = new ThumbnailEntry(id, position, jpegLength, BinaryPrimitives.ReadUInt16LittleEndian(head.AsSpan(20)), BinaryPrimitives.ReadUInt16LittleEndian(head.AsSpan(22)), crc); + position += EntryHeaderSize + jpegLength; + recovered++; + } + if (position < length) Warn($"Ignored {length - position} damaged bytes at the end of the pack"); + if (recovered > 0) Warn($"Recovered {recovered} thumbnail(s) appended after the last index"); + return position; + } + + private int ReadAt(Span buffer, long offset) + { + _handleLock.EnterReadLock(); + try + { + var total = 0; + while (total < buffer.Length) + { + var n = RandomAccess.Read(_handle, buffer[total..], offset + total); + if (n == 0) break; + total += n; + } + return total; + } + finally + { + _handleLock.ExitReadLock(); + } + } +} diff --git a/tests/Titano.Core.Tests/Decoding/ThumbnailTests.cs b/tests/Titano.Core.Tests/Decoding/ThumbnailTests.cs new file mode 100644 index 00000000..7690ef7c --- /dev/null +++ b/tests/Titano.Core.Tests/Decoding/ThumbnailTests.cs @@ -0,0 +1,277 @@ +using Titano.Core.Codecs.Jpeg; +using Titano.Core.Codecs.Raw; +using Titano.Core.Imaging; +using Titano.Core.Imaging.Decoders; +using Titano.Core.Imaging.Thumbnails; +using Titano.Core.Metadata; +using Titano.Core.Model; +using Titano.Core.Tests.Raw; +using Titano.Testing; + +namespace Titano.Core.Tests.Decoding; + +/// format behaviour, and . +public sealed class ThumbnailTests(TestContext context) +{ + private readonly string _dir = context.CreateTempDirectory(); + + private static ImageBuffer Frame(int seed, int width = 400, int height = 300) + { + var image = new ImageBuffer(width, height); + for (var y = 0; y < height; y++) + { + for (var x = 0; x < width; x++) + { + image[0, x, y] = (x + seed * 13) % 97 / 96f; + image[1, x, y] = (y + seed * 7) % 89 / 88f; + image[2, x, y] = seed % 5 / 5f; + } + } + return image; + } + + /// Small distinct JPEGs (cheap to make in bulk). + private static byte[] Jpeg(int seed) + { + using var image = Frame(seed, 40, 30); + return JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = 80 }); + } + + private static Guid Id(int i) => new(i, 0, 0, [0, 0, 0, 0, 0, 0, 0, 1]); + + [Test] + public void RoundTripAppendAndReplace() + { + var path = Path.Combine(_dir, "thumbs.pack"); + using (var pack = ThumbnailPack.Open(path)) + { + for (var i = 0; i < 20; i++) + { + using var frame = Frame(i); + var e = pack.Add(Id(i), frame); + Assert.Equal(320, e.Width); + Assert.Equal(240, e.Height); + } + } + using (var pack = ThumbnailPack.Open(path)) + { + Assert.Equal(20, pack.Count); + Assert.Empty(pack.Warnings); + for (var i = 20; i < 25; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30); + pack.AddJpeg(Id(3), Jpeg(1000), 40, 30); + } + using var reader = ThumbnailPack.Open(path, writable: false); + Assert.Equal(25, reader.Count); + Assert.BytesEqual(Jpeg(1000), reader.ReadJpeg(Id(3))); + Assert.BytesEqual(Jpeg(22), reader.ReadJpeg(Id(22))); + var thumb = Thumbnail.FromJpeg(reader.ReadJpeg(Id(7))!); + Assert.Equal(320, thumb.Width); + Assert.Null(reader.ReadJpeg(Id(99))); + Assert.Greater(reader.WastedBytes, 0); + } + + [Test] + public void EntriesAfterTheLastIndexAreRecovered() + { + var path = Path.Combine(_dir, "crash.pack"); + var copy = Path.Combine(_dir, "crash-copy.pack"); + var count = ThumbnailPack.IndexInterval + 6; + using (var pack = ThumbnailPack.Open(path)) + { + for (var i = 0; i < count; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30); + // Simulated crash: the file as it is before the closing index write. + File.Copy(path, copy); + } + using var recovered = ThumbnailPack.Open(copy, writable: false); + Assert.Equal(count, recovered.Count); + Assert.Contains(recovered.Warnings, w => w.Contains("Recovered 6")); + Assert.BytesEqual(Jpeg(count - 1), recovered.ReadJpeg(Id(count - 1))); + } + + [Test] + public void TruncatedAndDamagedFilesOpen() + { + var path = Path.Combine(_dir, "full.pack"); + using (var pack = ThumbnailPack.Open(path)) + { + for (var i = 0; i < 40; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30); + } + var bytes = File.ReadAllBytes(path); + for (var cut = 0; cut <= 40; cut++) + { + var file = Path.Combine(_dir, $"cut{cut}.pack"); + File.WriteAllBytes(file, bytes[..(int)((long)bytes.Length * cut / 40)]); + using var pack = ThumbnailPack.Open(file, writable: false); + foreach (var id in pack.FrameIds) Assert.NotNull(pack.ReadJpeg(id)); + Assert.LessOrEqual(pack.Count, 40); + } + // A damaged newest header slot falls back to the other one (or a scan). + var damaged = (byte[])bytes.Clone(); + for (var i = 0; i < 128; i++) damaged[i] ^= 0x5A; + var damagedPath = Path.Combine(_dir, "damaged.pack"); + File.WriteAllBytes(damagedPath, damaged); + using (var pack = ThumbnailPack.Open(damagedPath, writable: false)) + { + Assert.Equal(40, pack.Count); + Assert.Contains(pack.Warnings, w => w.Contains("No valid header")); + } + // A flipped JPEG byte is caught by its CRC on read. + var flipped = (byte[])bytes.Clone(); + flipped[128 + 40] ^= 0xFF; + var flippedPath = Path.Combine(_dir, "flipped.pack"); + File.WriteAllBytes(flippedPath, flipped); + using var f = ThumbnailPack.Open(flippedPath, writable: false); + Assert.Null(f.ReadJpeg(Id(0))); + Assert.NotNull(f.ReadJpeg(Id(1))); + } + + [Test] + public void CompactionDropsDeadEntries() + { + var path = Path.Combine(_dir, "compact.pack"); + using var pack = ThumbnailPack.Open(path); + for (var i = 0; i < 30; i++) pack.AddJpeg(Id(i), Jpeg(i), 40, 30); + for (var i = 0; i < 10; i++) pack.AddJpeg(Id(i), Jpeg(i + 500), 40, 30); + for (var i = 25; i < 30; i++) Assert.True(pack.Remove(Id(i))); + pack.Flush(); + var before = new FileInfo(path).Length; + var wasted = pack.WastedBytes; + pack.Compact(); + var after = new FileInfo(path).Length; + context.Log($"compaction {before} → {after} bytes (wasted {wasted})"); + Assert.Less(after, before - wasted / 2); + Assert.Equal(25, pack.Count); + Assert.Null(pack.ReadJpeg(Id(27))); + Assert.BytesEqual(Jpeg(503), pack.ReadJpeg(Id(3))); + pack.AddJpeg(Id(100), Jpeg(100), 40, 30); + pack.Flush(); + using var reopened = ThumbnailPack.Open(path, writable: false); + Assert.Equal(26, reopened.Count); + Assert.Empty(reopened.Warnings); + Assert.BytesEqual(Jpeg(15), reopened.ReadJpeg(Id(15))); + } + + [Test] + [Timeout(20_000)] + public async Task ConcurrentReadsWhileWriting() + { + var path = Path.Combine(_dir, "concurrent.pack"); + var jpegs = Enumerable.Range(0, 200).Select(Jpeg).ToArray(); + using var pack = ThumbnailPack.Open(path); + for (var i = 0; i < 10; i++) pack.AddJpeg(Id(i), jpegs[i], 40, 30); + pack.Flush(); + using var done = new CancellationTokenSource(); + var writer = Task.Run(() => + { + for (var i = 10; i < 200; i++) pack.AddJpeg(Id(i), jpegs[i], 40, 30); + pack.Flush(); + done.Cancel(); + }); + var readers = Enumerable.Range(0, 4).Select(r => Task.Run(() => + { + var random = new Random(r); + var reads = 0; + while (!done.IsCancellationRequested || reads < 50) + { + var ids = pack.FrameIds.ToArray(); + var id = ids[random.Next(ids.Length)]; + var data = pack.ReadJpeg(id); + Assert.NotNull(data); + Assert.BytesEqual(jpegs[id.ToByteArray()[0] | id.ToByteArray()[1] << 8], data); + reads++; + } + return reads; + })).ToArray(); + var other = Task.Run(() => + { + using var view = ThumbnailPack.Open(path, writable: false); + while (!done.IsCancellationRequested) + { + view.Refresh(); + foreach (var id in view.FrameIds) Assert.NotNull(view.ReadJpeg(id)); + } + }); + await Task.WhenAll([writer, other, .. readers]); + Assert.Equal(200, pack.Count); + context.Log($"reads: {string.Join(", ", readers.Select(r => r.Result))}"); + } + + [Test] + public async Task CacheEvictsLeastRecentlyUsedAndCoalescesLoads() + { + var cache = new ThumbnailCache(3 * (300 + 64)); + Thumbnail T() => new(10, 10, new byte[300]); + cache.Set(1, T()); + cache.Set(2, T()); + cache.Set(3, T()); + Assert.True(cache.TryGet(1, out _)); + cache.Set(4, T()); + Assert.False(cache.TryGet(2, out _)); + Assert.True(cache.TryGet(1, out _)); + Assert.Equal(3, cache.Count); + Assert.LessOrEqual(cache.Bytes, cache.Budget); + cache.Set(5, new Thumbnail(100, 100, new byte[30000])); + Assert.False(cache.TryGet(5, out _)); + + var loads = 0; + var gate = new TaskCompletionSource(); + async Task Loader(int key, CancellationToken ct) + { + Interlocked.Increment(ref loads); + await gate.Task; + return Thumbnail.FromJpeg(Jpeg(key)); + } + var large = new ThumbnailCache(1 << 20); + var requests = Enumerable.Range(0, 10).Select(_ => large.GetOrLoadAsync(42, Loader)).ToArray(); + gate.SetResult(); + var results = await Task.WhenAll(requests); + Assert.Equal(1, loads); + Assert.True(results.All(r => ReferenceEquals(r, results[0]))); + Assert.Equal(40, results[0]!.Width); + Assert.True(large.TryGet(42, out _)); + } + + [Test] + public void ProxyCarriesUprightPixelsAndCaptureExif() + { + var captured = new DateTime(2025, 7, 14, 21, 3, 9, DateTimeKind.Unspecified).AddTicks(4_500_000); + var metadata = new FrameMetadata { Make = "TestCam", Model = "T1", Orientation = 6, CapturedAt = captured, UtcOffsetMinutes = 120, Iso = 800, ExposureTime = 1 / 250.0 }; + using var image = Frame(1, 2000, 1500); + var exif = ExifWriter.BuildTiff(metadata); + var source = Path.Combine(_dir, "src.jpg"); + File.WriteAllBytes(source, JpegEncoder.Encode(image, new JpegEncodeOptions { Quality = 90, App1Segments = [[.. "Exif\0\0"u8, .. exif]] })); + + var proxy = ProxyBuilder.Write(DecoderFactory.CreateServer(), source, Path.Combine(_dir, "proxy.jpg"), ProxySize.Edge1280); + Assert.NotNull(proxy); + Assert.Equal(960, proxy!.Width); + Assert.Equal(1280, proxy.Height); + Assert.Equal(DecodeTier.Native, proxy.Tier); + var back = MetadataReader.Read(Path.Combine(_dir, "proxy.jpg")); + Assert.Equal(captured, back.CapturedAt); + Assert.Equal(120, back.UtcOffsetMinutes); + Assert.Equal(TimestampSource.ExifOriginal, back.TimestampSource); + Assert.Equal(1, back.Orientation); + Assert.Equal("TestCam", back.Make); + Assert.Equal(800, back.Iso); + Assert.Equal(960, back.Width); + Assert.Equal(1280, back.Height); + var info = JpegDecoder.ReadInfo(proxy.Jpeg); + Assert.Equal(960, info.Width); + + var full = ProxyBuilder.Build(DecoderFactory.CreateServer(), source, ProxySize.Full); + Assert.Equal(1500, full!.Width); + } + + [Test] + public void ProxyOfAnUnsupportedRawUsesThePreviewTier() + { + using var scene = SyntheticRaw.Smooth(96, 64); + var active = new RawRect(24, 4, 120, 68); + var cr2 = NativeRawWriters.Cr2(NativeRawWriters.Sensor(scene, "Canon EOS 5D Mark III", CfaPattern.Bayer("RGGB"), 128, 72, 24, 4, 2048, 16383), active, 1, "Canon EOS R99"); + var path = Path.Combine(_dir, "x.cr2"); + File.WriteAllBytes(path, cr2); + var proxy = ProxyBuilder.Build(DecoderFactory.CreateServer(), path); + Assert.Equal(DecodeTier.EmbeddedPreview, proxy!.Tier); + Assert.Equal(64, proxy.Width); + } +}