Files
Chronos/tests/Titano.Core.Tests/Archiving/DecodeTierTests.cs
T
Claude 4d321a84b0 fix(imaging): record decode tiers per frame and keep undecodable frames out of renders
BRIEF §8.2 tiers 2 and 3 had no writer: PreviewOnly and Undecodable were never set,
so the advisor could not cap the output at the preview size and one unreadable frame
failed a whole render.

- ImageDecoder.Probe names a file's tier without decoding it (JPEG, PNG and TIFF
  without opening the file); the light analysis probes frames whose tier is unknown,
  and the deep analysis, renders from originals and thumbnail/proxy passes record
  what decoding actually found (FrameTiers). Sidecar frames gain "tier", "previewW"
  and "previewH"; the index gains frames.preview_width/height and
  sequences.preview_only_count (migration 0005, SQLite and PostgreSQL).
- SequenceContext takes the preview size from preview-only frames, so the advisor's
  output cap applies; the light analysis reports format tiers (preview-only frames as
  information, undecodable ones as a warning under the deep analysis' key, listed
  once); a sequence that gains undecodable frames warns at once.
- Only a file in a format the host decodes natively is flagged undecodable; files
  beyond the host's decoders keep their tier without the flag, so render nodes and
  proxies can still supply them.
- A frame that stops decoding during a render is replaced by its nearest planned
  neighbour and logged instead of failing the job; the render fails only when no
  planned frame decodes.
- The Library card shows a preview-only chip with the count (local and server
  sequences: SequenceDto.PreviewOnlyCount, FrameDto preview size).
- GoPro GPR decodes through the JPEG the camera writes beside it when that is larger
  than the embedded preview (BRIEF §8.1).
- Thumbnails use a stored embedded preview only when it reaches 320 px; a smaller one
  sends the frame through the host's decoders instead (BRIEF §8.5).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
2026-10-12 09:58:36 +00:00

199 lines
10 KiB
C#

using System.Text;
using Titano.Core.Advice;
using Titano.Core.Analysis;
using Titano.Core.Analysis.Deep;
using Titano.Core.Archiving;
using Titano.Core.Codecs.Jpeg;
using Titano.Core.Diagnostics.Synthetic;
using Titano.Core.Imaging;
using Titano.Core.Imaging.Decoders;
using Titano.Core.Metadata;
using Titano.Core.Model;
using Titano.Core.Tests.Analysis.Deep;
using Titano.Core.Tests.Raw;
using Titano.Testing;
namespace Titano.Core.Tests.Archiving;
/// <summary>Decode tiers of frames (BRIEF §8.2): sidecar fields, flags, thumbnails from previews, and what the advisor reads.</summary>
[Category("archive")]
public sealed class DecodeTierTests(TestContext context)
{
private static readonly DateTime Start = new(2026, 9, 28, 18, 0, 0);
private static SidecarFrame Sidecar(int orientation = 1, int? previewW = null, int? previewH = null) => new()
{
Id = Guid.CreateVersion7(),
File = "originals/IMG_0001.CR2",
Format = ImageFileFormat.Cr2,
W = 6000,
H = 4000,
Orientation = orientation,
PreviewW = previewW,
PreviewH = previewH,
};
[Test]
public void TheTierSetsItsFlagsAndThePreviewSize()
{
var frame = Sidecar(orientation: 6) with { Flags = FrameFlags.Duplicate };
// FileTier sizes are oriented; the sidecar keeps them like W and H, before orientation.
var preview = SequenceFrames.WithTier(frame, new FileTier(ImageFileFormat.Cr2, DecodeTier.EmbeddedPreview, "managed-preview", "body", 1080, 1620));
Assert.Equal((DecodeTier.EmbeddedPreview, FrameFlags.Duplicate | FrameFlags.PreviewOnly, (int?)1620, (int?)1080),
(preview.Tier, preview.Flags, preview.PreviewW, preview.PreviewH));
var none = SequenceFrames.WithTier(preview, new FileTier(ImageFileFormat.Cr2, DecodeTier.Unavailable, null, "nothing", 0, 0));
Assert.Equal((FrameFlags.Duplicate | FrameFlags.Undecodable, (int?)1620), (none.Flags, none.PreviewW));
var native = SequenceFrames.WithTier(none, new FileTier(ImageFileFormat.Cr2, DecodeTier.Native, "wic", null, 4000, 6000));
Assert.Equal((DecodeTier.Native, FrameFlags.Duplicate, (int?)1620), (native.Tier, native.Flags, native.PreviewW));
// A host without a native decoder for the format proves nothing about the file: tier kept, flag left as it was.
var beyond = SequenceFrames.WithTier(native, new FileTier(ImageFileFormat.Cr2, DecodeTier.Unavailable, null, "nothing here", 0, 0), damaged: false);
Assert.Equal((DecodeTier.Unavailable, FrameFlags.Duplicate), (beyond.Tier, beyond.Flags));
Assert.Equal(FrameFlags.Duplicate | FrameFlags.Undecodable,
SequenceFrames.WithTier(none, new FileTier(ImageFileFormat.Cr2, DecodeTier.Unavailable, null, "nothing here", 0, 0), damaged: false).Flags);
}
[Test]
public void SidecarsKeepTheTierAndThePreviewSizeAndOlderOnesReadAsUnknown()
{
var path = Path.Combine(context.CreateTempDirectory(), "sequence.json");
var frame = SequenceFrames.WithTier(Sidecar(previewW: 1620, previewH: 1080),
new FileTier(ImageFileFormat.Cr2, DecodeTier.EmbeddedPreview, "managed-preview", null, 1620, 1080));
ManifestStore.WriteSequence(path, new SequenceManifest { Id = Guid.CreateVersion7(), Frames = [frame] });
var json = File.ReadAllText(path);
Assert.Contains("\"tier\":\"EmbeddedPreview\"", json);
Assert.Contains("\"previewW\":1620", json);
var read = ManifestStore.ReadSequence(path).Frames.Single();
Assert.Equal((DecodeTier.EmbeddedPreview, FrameFlags.PreviewOnly, (int?)1620, (int?)1080), (read.Tier, read.Flags, read.PreviewW, read.PreviewH));
// A frame never probed writes no tier, and a sidecar from before tiers reads as unknown.
ManifestStore.WriteSequence(path, new SequenceManifest { Id = Guid.CreateVersion7(), Frames = [Sidecar()] });
Assert.DoesNotContain("tier", File.ReadAllText(path).Split('"'));
var older = ManifestStore.ParseSequence(Encoding.UTF8.GetBytes(
"""{"id":"0192f7a0-0000-7000-8000-000000000001","frames":[{"id":"0192f7a0-0000-7000-8000-000000000002","file":"a.jpg","tier":"SomethingNew"}]}"""), "test");
Assert.Equal((DecodeTier)0, older.Frames.Single().Tier);
}
[Test]
public void IndexingKeepsTheSizeOfTheLargestPreview()
{
var metadata = new FrameMetadata
{
Format = ImageFileFormat.Cr2,
Width = 6000,
Height = 4000,
Previews = [new EmbeddedPreview(4096, 90_000, 1620, 1080, PreviewKind.Preview), new EmbeddedPreview(100, 4000, 160, 120, PreviewKind.Thumbnail)],
};
var frame = SequenceFrames.FromMetadata(Guid.CreateVersion7(), "a.cr2", "a.cr2", 10, null, metadata);
Assert.Equal((4096L, (int?)1620, (int?)1080, (DecodeTier)0), (frame.PreviewOffset!.Value, frame.PreviewW, frame.PreviewH, frame.Tier));
Assert.Null(SequenceFrames.FromMetadata(Guid.CreateVersion7(), "b.jpg", "b.jpg", 10, null, new FrameMetadata { Format = ImageFileFormat.Jpeg }).PreviewW);
}
[Test]
public void ThumbnailsUseAStoredPreviewOnlyWhenItReachesTheThumbnailSize()
{
var archive = new ArchivePaths(context.CreateTempDirectory("archive"));
var sequence = archive.Sequence("s");
Directory.CreateDirectory(sequence.Originals);
using var scene = SyntheticRaw.Smooth(640, 480);
var dng = SyntheticDng.Write(scene, new DngSpec());
var renderer = new FrameImageRenderer(DecoderFactory.CreateServer());
EncodedImage Thumbnail(string name, int previewWidth, bool sizeKnown)
{
// The preview is appended after the DNG, which the TIFF offsets never reach.
var preview = TestPhotos.Jpeg(Start, 3, width: previewWidth, height: previewWidth * 3 / 4);
File.WriteAllBytes(Path.Combine(sequence.Originals, name), [.. dng, .. preview]);
var frame = new SidecarFrame
{
Id = Guid.CreateVersion7(),
File = "originals/" + name,
Format = ImageFileFormat.Dng,
W = 640,
H = 480,
PreviewOffset = dng.Length,
PreviewLength = preview.Length,
PreviewW = sizeKnown ? previewWidth : null,
PreviewH = sizeKnown ? previewWidth * 3 / 4 : null,
};
return renderer.Thumbnail(sequence, frame)!;
}
// A 200 px preview would leave the thumbnail short of 320 px (ENG-10): the RAW is developed instead.
var small = Thumbnail("small.dng", 200, sizeKnown: true);
Assert.Equal((320, 240, DecodeTier.Native), (small.Width, small.Height, small.Tier));
var unknown = Thumbnail("unknown.dng", 200, sizeKnown: false);
Assert.Equal((320, DecodeTier.Native), (unknown.Width, unknown.Tier));
var large = Thumbnail("large.dng", 400, sizeKnown: true);
Assert.Equal((320, 240, DecodeTier.EmbeddedPreview), (large.Width, large.Height, large.Tier));
Assert.Equal(320, JpegDecoder.ReadInfo(large.Jpeg).Width);
}
[Test]
public void TheAdvisorCapsTheOutputAtThePreviewsOfPreviewOnlyFrames()
{
var sequence = Guid.CreateVersion7();
Frame Row(int index, FrameFlags flags, int previewW, int previewH) => new()
{
Id = Guid.CreateVersion7(),
SequenceId = sequence,
Index = index,
RelativePath = $"s/{index}.cr3",
FileName = $"{index}.cr3",
CapturedAt = Start.AddSeconds(5 * index),
ExposureTime = 1.0 / 250,
FNumber = 8,
Iso = 100,
Width = 6000,
Height = 4000,
Orientation = 6,
Flags = flags,
PreviewWidth = previewW,
PreviewHeight = previewH,
};
var rows = Enumerable.Range(0, 20)
.Select(i => Row(i, i == 19 ? FrameFlags.Undecodable : i < 15 ? FrameFlags.PreviewOnly : FrameFlags.None, i == 3 ? 1280 : 1620, i == 3 ? 960 : 1080))
.ToList();
var context = SequenceContext.FromFrames(rows);
// Portrait frames: the previews are oriented like the main image; the most common preview size wins.
Assert.Equal((4000, 6000, 15, 1080, 1620), (context.SourceWidth, context.SourceHeight, context.PreviewOnlyCount, context.PreviewWidth, context.PreviewHeight));
var light = LightAnalyzer.Analyze(rows);
Assert.SequenceEqual(Enumerable.Range(0, 15), light.PreviewOnlyFrames);
Assert.SequenceEqual([19], light.UndecodableFrames);
var preview = light.Findings.Single(f => f.Key == FindingKeys.PreviewOnly);
Assert.Equal((FindingSeverity.Info, (object)15), (preview.Severity, preview.Arguments[0]));
Assert.Equal(FindingSeverity.Warning, light.Findings.Single(f => f.Key == DeepFindingKeys.UnreadableFrames).Severity);
var result = Advisor.Recommend(light, null, context);
var resolution = result.Find(AdvisorParameters.Resolution)!;
Assert.Equal(AdvisorKeys.ResolutionPreview, resolution.ReasonKey);
Assert.SequenceEqual([15, 1080, 1620], resolution.ReasonArgs.Select(Convert.ToInt32));
}
[Test]
public async Task FramesBothAnalysesFoundUndecodableAreListedOnce()
{
var source = new SyntheticFrameSource(SyntheticSequence.Create(new SyntheticSequenceOptions { Width = 96, Height = 64, FrameCount = 12 }))
{
Undecodable = [4],
};
var deep = await DeepAnalyzer.AnalyzeAsync(source, DeepScenes.Options);
var metadata = Enumerable.Range(0, source.Count).Select(source.Metadata).ToList();
var context = new SequenceContext { FrameCount = source.Count, SourceWidth = 96, SourceHeight = 64 };
// Before the deep pass flagged the frame, only its own finding names it.
var unflagged = Advisor.Recommend(LightAnalyzer.Analyze(metadata), deep, context).Findings.Where(f => f.Key == DeepFindingKeys.UnreadableFrames).ToList();
Assert.SequenceEqual([4], unflagged.Single().Frames);
// Once flagged, the light analysis lists it and the deep finding is not repeated.
var flagged = metadata.Select(m => m.Index == 4 ? m with { Flags = FrameFlags.Undecodable } : m).ToList();
var light = LightAnalyzer.Analyze(flagged);
var findings = Advisor.Recommend(light, deep, context).Findings.Where(f => f.Key == DeepFindingKeys.UnreadableFrames).ToList();
Assert.Same(light.Findings.Single(f => f.Key == DeepFindingKeys.UnreadableFrames), findings.Single());
}
}