using System.Text; using Chronos.Core.Advice; using Chronos.Core.Analysis; using Chronos.Core.Analysis.Deep; using Chronos.Core.Archiving; using Chronos.Core.Codecs.Jpeg; using Chronos.Core.Diagnostics.Synthetic; using Chronos.Core.Imaging; using Chronos.Core.Imaging.Decoders; using Chronos.Core.Metadata; using Chronos.Core.Model; using Chronos.Core.Project; using Chronos.Core.Tests.Analysis.Deep; using Chronos.Core.Tests.Raw; using Chronos.Testing; namespace Chronos.Core.Tests.Archiving; /// Decode tiers of frames (BRIEF ยง8.2): sidecar fields, flags, thumbnails from previews, and what the advisor reads. [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 AFrameReadFromItsProxyKeepsItsPreviewTierButIsNotPreviewOnly() { // A HEIF on the server: its decoders find only the Exif thumbnail, but renders read the proxy a client sent. var heif = Sidecar() with { File = "originals/IMG_0001.HEIC", Format = ImageFileFormat.Heif, Flags = FrameFlags.Duplicate }; var thumbnail = new FileTier(ImageFileFormat.Heif, DecodeTier.EmbeddedPreview, "managed-preview", "no managed decoder for Heif", 160, 120); var proxied = SequenceFrames.WithTier(heif, thumbnail, damaged: false, proxied: true); Assert.Equal((DecodeTier.EmbeddedPreview, FrameFlags.Duplicate, (int?)160, (int?)120), (proxied.Tier, proxied.Flags, proxied.PreviewW, proxied.PreviewH)); // The flag follows the proxy, the tier and preview size stay the original's. var gone = SequenceFrames.WithProxy(proxied, proxied: false); Assert.Equal((DecodeTier.EmbeddedPreview, FrameFlags.Duplicate | FrameFlags.PreviewOnly, (int?)160), (gone.Tier, gone.Flags, gone.PreviewW)); Assert.Equal(FrameFlags.Duplicate, SequenceFrames.WithProxy(gone, proxied: true).Flags); // Other tiers have no preview-only flag to follow. var unavailable = SequenceFrames.WithTier(heif, new FileTier(ImageFileFormat.Heif, DecodeTier.Unavailable, null, "nothing", 0, 0), damaged: false); Assert.Same(unavailable, SequenceFrames.WithProxy(unavailable, proxied: false)); } [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, int? storedWidth = null) { // 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 stored = storedWidth ?? previewWidth; 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 ? stored : null, PreviewH = sizeKnown ? stored * 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)); // The stored size can be a GPR companion's, larger than the embedded preview: the JPEG's own header decides. var companionSized = Thumbnail("companion.dng", 200, sizeKnown: true, storedWidth: 4000); Assert.Equal((320, DecodeTier.Native), (companionSized.Width, companionSized.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() { // Frame 4 does not decode; frame 7 is not read either (missing, or beyond this host), which never flags it. var source = new SyntheticFrameSource(SyntheticSequence.Create(new SyntheticSequenceOptions { Width = 96, Height = 64, FrameCount = 12 })) { Undecodable = [4, 7], }; 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 them. var unflagged = Advisor.Recommend(LightAnalyzer.Analyze(metadata), deep, context).Findings.Where(f => f.Key == DeepFindingKeys.UnreadableFrames).ToList(); Assert.SequenceEqual([4, 7], unflagged.Single().Frames); // Once frame 4 is flagged both analyses report it: one finding over both lists, counted once. var flagged = metadata.Select(m => m.Index == 4 ? m with { Flags = FrameFlags.Undecodable } : m).ToList(); var light = LightAnalyzer.Analyze(flagged); Assert.SequenceEqual([4], light.Findings.Single(f => f.Key == DeepFindingKeys.UnreadableFrames).Frames); var merged = Advisor.Recommend(light, deep, context).Findings.Single(f => f.Key == DeepFindingKeys.UnreadableFrames); Assert.SequenceEqual([4, 7], merged.Frames); Assert.Equal((FindingSeverity.Warning, 2), (merged.Severity, Convert.ToInt32(merged.Arguments.Single()))); // A frame flagged since the deep pass (a render found it broken) joins the list too. var later = LightAnalyzer.Analyze(flagged.Select(m => m.Index == 9 ? m with { Flags = FrameFlags.Undecodable } : m).ToList()); var all = Advisor.Recommend(later, deep, context).Findings.Single(f => f.Key == DeepFindingKeys.UnreadableFrames); Assert.Equal((3, 3), (all.Frames.Count, Convert.ToInt32(all.Arguments.Single()))); } [Test] public void FramesTheCamerasIntervalometerShotTimeTheirGapsAdaptively() { var metadata = new FrameMetadata { Format = ImageFileFormat.Rw2, IntervalShooting = true }; Assert.Equal(FrameFlags.Intervalometer, SequenceFrames.FromMetadata(Guid.CreateVersion7(), "a.rw2", "a.rw2", 10, null, metadata).Flags); Assert.Equal(FrameFlags.None, SequenceFrames.FromMetadata(Guid.CreateVersion7(), "b.rw2", "b.rw2", 10, null, metadata with { IntervalShooting = false }).Flags); // 60 frames 10 s apart with one 40 s gap: a sparse gap alone keeps the timing constant (motion unmeasured). LightFrame Frame(int i, FrameFlags flags) => new() { Index = i, CapturedAt = Start.AddSeconds(10 * i + (i >= 30 ? 30 : 0)), Width = 6000, Height = 4000, Flags = flags, }; var context = new SequenceContext { FrameCount = 60, SourceWidth = 6000, SourceHeight = 4000 }; var plain = LightAnalyzer.Analyze([.. Enumerable.Range(0, 60).Select(i => Frame(i, FrameFlags.None))]); Assert.Equal(0, plain.IntervalometerFrames); var free = Advisor.Recommend(plain, null, context).Find(AdvisorParameters.TimingMode)!; Assert.Equal((AdvisorKeys.TimingSparseGaps, (object?)TimingMode.Constant), (free.ReasonKey, free.Value)); // The camera's own intervalometer shot them: its pause was deliberate, so adaptive timing keeps it short. var shot = LightAnalyzer.Analyze([.. Enumerable.Range(0, 60).Select(i => Frame(i, FrameFlags.Intervalometer))]); Assert.Equal(60, shot.IntervalometerFrames); var advice = Advisor.Recommend(shot, null, context).Find(AdvisorParameters.TimingMode)!; Assert.Equal((AdvisorKeys.TimingIntervalometer, (object?)TimingMode.Adaptive), (advice.ReasonKey, advice.Value)); Assert.Equal(1, Convert.ToInt32(advice.ReasonArgs.Single())); } }