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