using System.Security.Cryptography;
using System.Text;
using Titano.Core.Advice;
using Titano.Core.Analysis;
using Titano.Core.Analysis.Deep;
using Titano.Core.Archiving;
using Titano.Core.Imaging;
using Titano.Core.Model;
using Titano.Data.Archiving;
using Titano.Data.Repositories;
namespace Titano.Data.Processing;
/// What an analysis of one sequence found and changed.
/// Findings of warning severity or worse (light and, when current, deep).
/// The advisor changed Auto values of the project.
/// The project could not be read, so its Auto values were left alone.
/// Sequence presets that fit the content (deep analysis only).
/// How the frames it read were no longer the sequence's when it recorded: anything but
/// means nothing was recorded from them.
internal sealed record AnalysisOutcome(Sequence Sequence, int Frames, int Warnings, bool SettingsChanged, bool SettingsUnreadable,
IReadOnlyList Presets, FramesChange FramesChanged = FramesChange.None);
/// How the frames an analysis read had changed by the time it recorded, under the sequence lock.
internal enum FramesChange
{
/// Still the sequence's frames, or changed in this index with a light analysis queued to replace what it records.
None,
///
/// Added, removed or renumbered in this index (an upload, an import, a scan), with no light analysis queued: one must
/// run here for the frames as they are.
///
Indexed,
///
/// Changed in the sidecar by another process (a desktop sharing a server's archive, or that server), which analyses
/// them; this index holds them only after its next scan, which on a server queues their analysis here too.
///
NotIndexed,
}
///
/// Light (BRIEF §10.1) and deep (§10.2) analysis of archived sequences, followed by the advisor (§10.3–10.4) filling the
/// Auto values of the project. The light pass reads the index, probes the decode tier (§8.2) of frames whose tier is not
/// known yet (headers only, once per frame) and reads one file for the GPS fix; the deep pass decodes every frame,
/// checkpointing into .titano/analysis.partial so a cancelled, paused or crashed run resumes, records the tier
/// each frame decoded at (or that it did not decode) and saves analysis.json atomically under the sequence lock.
/// Results land in the sidecar (status, tiers), the index (status, warning count, compact summary, tier flags,
/// per-frame light statistics) and project.json.
///
internal sealed class SequenceAnalyser(TitanoDatabase db, ProcessingOptions options, SequenceWriter writer, ArchiveIndexer indexer, ProjectStore projects)
{
/// Long edge of the decode that confirms a frame an interrupted earlier run found undecodable.
private const int ConfirmLongEdge = 64;
private readonly FrameTiers _tiers = new(db, writer, indexer);
/// Analyses one sequence; null when it is no longer in the index.
/// The archive is offline or read-only.
public async Task AnalyseAsync(Guid sequenceId, bool deep, IProgress? progress, CancellationToken cancellationToken)
{
if (await db.Sequences.GetAsync(sequenceId, cancellationToken).ConfigureAwait(false) is not { } sequence
|| await db.Archives.GetAsync(sequence.ArchiveId, cancellationToken).ConfigureAwait(false) is not { } archive) return null;
var paths = new ArchivePaths(archive.RootPath);
ArchiveVolume.EnsureWritable(paths);
var folder = paths.Sequence(sequence.Folder);
var frames = await SequenceFrames.LoadAsync(db, archive, sequence, useProxies: false, options.Archive.Decoder, cancellationToken).ConfigureAwait(false);
// Format tiers (BRIEF §10.1): frames indexed since the last analysis are probed with this host's decoders. A frame
// read from its proxy is not preview-only whatever its original's tier, so it caps nothing (BRIEF §8.1, §8.2); the
// flags are taken as the sidecar has them once recorded, so ones another worker recorded meanwhile count too.
var probed = await _tiers.ProbeUnknownAsync(archive, folder, ManifestStore.ReadSequence(folder.ManifestPath), cancellationToken).ConfigureAwait(false);
frames = WithTiers(frames, await _tiers.RecordAsync(archive, sequence, probed, proxies: true, cancellationToken).ConfigureAwait(false));
var metadata = frames.LightFrames();
DeepAnalysisReport? report = null;
if (deep)
{
// Proxies may have arrived during the pass: the flags below follow the frames as they are at its end, and the
// report is checked against them under the lock.
(report, var decoded) = await AnalyseDeepAsync(archive, frames, metadata, folder, progress, cancellationToken).ConfigureAwait(false);
frames = WithTiers(frames, await _tiers.RecordAsync(archive, sequence, decoded, proxies: true, cancellationToken).ConfigureAwait(false));
metadata = [.. metadata.Select((m, i) => m with { Flags = frames.Frames[i].Flags })];
}
var light = LightAnalyzer.Analyze(metadata);
var context = SequenceContext.FromFrames(frames.Frames, options.AdvisorCodecs);
bool changed, unreadable = false;
int warnings;
// Under the sequence lock, which a deep pass of the same sequence also takes to record its report: a light pass
// then either sees that report or runs before it is recorded, and never clears what it recorded. The report counts
// only while it describes the frames as they are under the lock (ReadReport), so a deep pass loads them again: a
// proxy that arrived while it ran (for hours) makes its verdict on that frame's original stale. The light analysis
// the proxy queued then either ran before this, and the advice, status and warnings stay without the report as it
// left them, or runs after. A pass whose frames were added to, removed or renumbered since it read them records
// nothing (FramesChangeAsync), and a light analysis of the frames as they are runs instead, here or where they
// were changed; its report is saved only over none of the frames as they are (SaveReport). What a deep pass records
// then follows the report analysis.json holds: its own, or the one it left in place.
await using (await writer.LockAsync(paths, sequence.Id, cancellationToken).ConfigureAwait(false))
{
var manifest = SequenceWriter.ReadLocked(folder, sequence.Id);
var change = await FramesChangeAsync(sequence, manifest, cancellationToken).ConfigureAwait(false);
// The frames as this host reads them now: a proxy that arrived while the pass ran moves no frames version but
// makes the pass's verdict on that frame's original stale, so only a report that describes them is current.
var now = deep && change == FramesChange.None
? await SequenceFrames.LoadAsync(db, archive, sequence, useProxies: false, options.Archive.Decoder, cancellationToken).ConfigureAwait(false)
: null;
var saved = deep && SaveReport(folder, report!,
change == FramesChange.None && manifest.Versions.Frames == sequence.FramesVersion && Describes(report!, now!),
now, manifest.Frames.Count);
if (change != FramesChange.None)
return new AnalysisOutcome(sequence, frames.Count, 0, SettingsChanged: false, SettingsUnreadable: false, [], change);
if (deep)
{
// A report left in place is read as a light analysis reads it, so the deep status, summary, warnings and
// Auto values recorded here describe the file that readers and the report endpoint open.
if (!saved) report = ReadReport(folder, now!);
else if (!Describes(report!, now!)) report = null;
}
else
{
report = ReadReport(folder, frames);
}
try
{
// The frame rate follows the user's "fit to N seconds" when one is set (BRIEF §10.3).
changed = await projects.UpdateLockedAsync(paths, sequence,
settings => Advisor.Apply(settings, Advisor.Recommend(light, report, context with { TargetDurationSeconds = settings.Timing.FitToSeconds })),
cancellationToken).ConfigureAwait(false);
}
catch (InvalidDataException ex)
{
Core.Diagnostics.Log.Warning("processing", $"The project of {sequence.DisplayTitle} cannot be read", ex);
(changed, unreadable) = (false, true);
}
warnings = Advisor.Recommend(light, report, context).Findings.Count(f => f.Severity >= FindingSeverity.Warning);
var set = SequenceStatus.AnalyzedLight | (report is null ? SequenceStatus.None : SequenceStatus.AnalyzedDeep)
| (warnings > 0 ? SequenceStatus.HasWarnings : SequenceStatus.None);
// Without a current report (none, or made before frames were added) the deep status no longer holds.
var clear = (report is null ? SequenceStatus.AnalyzedDeep : SequenceStatus.None) | (warnings > 0 ? SequenceStatus.None : SequenceStatus.HasWarnings);
var inStep = await indexer.InStepAsync(archive, folder, manifest, cancellationToken).ConfigureAwait(false);
var status = (manifest.Status | set) & ~clear;
if (status != manifest.Status) ManifestStore.WriteSequence(folder.ManifestPath, manifest with { Status = status, UpdatedAt = DateTimeOffset.UtcNow });
var summary = deep && report is not null ? AnalysisSummary.From(report).ToJson() : null;
await db.Sequences.RecordAnalysisAsync(sequence.Id, set, clear, warnings, summary, cancellationToken).ConfigureAwait(false);
if (inStep) await indexer.RecordStampsAsync(archive, folder, sequence.Id, cancellationToken).ConfigureAwait(false);
}
if (changed) await options.NotifyAsync(sequence.Id, ProcessingOptions.SettingsChange, cancellationToken).ConfigureAwait(false);
var presets = deep ? SequencePresets.Generate(light, report, context) : [];
return new AnalysisOutcome(sequence, frames.Count, warnings, changed, unreadable, presets);
}
///
/// How the frames this pass read had changed by now, under the sequence lock. Every writer of this index's frames bumps
/// the row's frames version with them under the same lock (an upload or import, a scan reconciling photos copied in by
/// hand or indexing frames another process listed in the sidecar), and every writer of the sidecar's frames bumps its
/// version (, read under the lock). What the pass found then describes other frames:
/// recorded, it would mark the new ones analysed, with Auto values and warnings counted on the old ones, over what an
/// analysis of the frames as they are may have recorded already, in the shared sidecar and project.json too.
/// A sidecar at another version than the row lists frames another process changed and this index does not hold yet
/// (): nothing is queued here, since a light analysis would read this index as
/// it is and find it behind the sidecar again until the next scan indexes them. A row whose version moved since the
/// pass read it holds the frames as they are, and a light analysis here covers them ().
/// One already queued for the sequence runs after this on the frames as they are then, so the pass still records
/// meanwhile, as an image pass keeps its flag (): during an upload burst every pass is
/// overtaken, and a sequence being shot would otherwise show no analysis until uploads paused.
///
private async Task FramesChangeAsync(Sequence sequence, SequenceManifest manifest, CancellationToken cancellationToken)
{
if (await db.Sequences.GetAsync(sequence.Id, cancellationToken).ConfigureAwait(false) is not { } row) return FramesChange.None;
if (manifest.Versions.Frames != row.FramesVersion) return FramesChange.NotIndexed;
return row.FramesVersion == sequence.FramesVersion
|| await db.Jobs.IsQueuedAsync(JobKind.LightAnalyse, sequence.Id, cancellationToken).ConfigureAwait(false)
? FramesChange.None
: FramesChange.Indexed;
}
///
/// The saved deep report when it describes as this host reads them now: also stale when a
/// frame it found unreadable has been read from its proxy since (one sent for an original this host cannot decode,
/// BRIEF §2.3), so that verdict and the frame's missing measurements no longer hold.
///
public static DeepAnalysisReport? ReadReport(SequencePaths folder, SequenceFrames frames) =>
ReadReport(folder, frames.Count) is { } report && Describes(report, frames) ? report : null;
/// Whether describes as this host reads them now ().
private static bool Describes(DeepAnalysisReport report, SequenceFrames frames)
{
if (report.FrameCount != frames.Count) return false;
if (frames.Proxied is not { } proxied) return true;
HashSet measured = report.ProxyFrames is { } read ? [.. read] : [];
foreach (var index in report.Issues.Undecodable)
{
if (index < frames.Count && proxied[index] && !measured.Contains(index) && (frames.Frames[index].Flags & SequenceFrames.NotAnalysed) == 0)
return false;
}
return true;
}
/// The saved deep report when it covers frames; null when absent, stale or unreadable.
public static DeepAnalysisReport? ReadReport(SequencePaths folder, int frameCount)
{
if (!File.Exists(folder.AnalysisPath)) return null;
try
{
var report = DeepAnalysisReport.Load(folder.AnalysisPath);
return report.FrameCount == frameCount ? report : null;
}
catch (Exception ex) when (ex is IOException or InvalidDataException or System.Text.Json.JsonException)
{
Core.Diagnostics.Log.Warning("processing", $"{folder.AnalysisPath} cannot be read", ex);
return null;
}
}
/// The frame rows with the flags and preview sizes of the sidecar frames.
private static SequenceFrames WithTiers(SequenceFrames frames, IReadOnlyList current)
{
if (current.Count == 0) return frames;
var byId = current.ToDictionary(f => f.Id);
var rows = frames.Frames.Select(f => byId.TryGetValue(f.Id, out var s)
? f with { Flags = s.Flags, PreviewWidth = s.PreviewW ?? 0, PreviewHeight = s.PreviewH ?? 0 }
: f).ToList();
return frames with { Frames = rows };
}
///
/// What the deep pass learnt about each frame's tier, by frame id: the tier this run decoded it at. A frame this run
/// tried to read and recorded nothing for vanished or could not be read, which says nothing about its content. A frame
/// only an interrupted earlier run analysed and found undecodable is decoded again (small) to confirm it: that run's
/// failure may have been a read error too. Missing and corrupt frames are not decoded at all.
///
private Dictionary Decoded(SequenceFrames frames, DeepAnalysisReport report, SequenceFrameSource source,
IReadOnlyDictionary companions, CancellationToken cancellationToken)
{
var tiers = new Dictionary();
foreach (var (index, tier) in source.Observed) tiers[frames.Frames[index].Id] = tier;
var read = source.Read.ToHashSet();
foreach (var index in report.Issues.Undecodable)
{
// A frame read from its proxy says nothing about its original's tier.
if (index >= frames.Count || read.Contains(index) || frames.Files[index] is not { } path
|| (frames.Frames[index].Flags & SequenceFrames.NotAnalysed) != 0 || frames.Proxied is { } proxied && proxied[index]) continue;
var frame = frames.Frames[index];
try
{
using var decoded = options.Archive.Decoder.Decode(
new DecodeRequest(path, ConfirmLongEdge, DecodePurpose.Analysis, Companion: companions.GetValueOrDefault(frame.Id)), cancellationToken);
if (decoded is not null) tiers[frame.Id] = new FileTier(frame.Format, decoded.Tier, decoded.Decoder, null, 0, 0);
else if (File.Exists(path)) tiers[frame.Id] = new FileTier(frame.Format, DecodeTier.Unavailable, null, "no decoder produced pixels", 0, 0);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Core.Diagnostics.Log.Warning("processing", $"Frame {path} could not be read", ex);
}
}
return tiers;
}
///
/// Saves a deep pass's report as analysis.json, under the sequence lock, then drops its checkpoint; returns
/// whether it saved it. The report replaces the saved one when it describes the frames as they are
/// (), or when the saved one describes them no better: none, unreadable, or not describing
/// (the frames as this host reads them, proxies included), or, when they were not read, of
/// another frame count than , the sidecar's. A pass overtaken by an upload, by a proxy,
/// or by another process sharing the archive, would otherwise replace the report a later pass made of the frames as
/// they are, and the next light analysis would drop that one's deep status.
///
private static bool SaveReport(SequencePaths folder, DeepAnalysisReport report, bool current, SequenceFrames? now, int frameCount)
{
var save = current || (now is not null ? ReadReport(folder, now) : ReadReport(folder, frameCount)) is null;
if (save) report.Save(folder.AnalysisPath);
Checkpoint(folder).Delete();
return save;
}
/// The deep pass's checkpoint, .titano/analysis.partial: kept until the pass has saved its report.
private static DeepAnalysisCheckpointFile Checkpoint(SequencePaths folder) =>
new(Path.Combine(folder.MetaDirectory, DeepAnalysisCheckpointFile.FileName));
private async Task<(DeepAnalysisReport Report, Dictionary Decoded)> AnalyseDeepAsync(Archive archive, SequenceFrames frames,
IReadOnlyList metadata, SequencePaths folder, IProgress? progress, CancellationToken cancellationToken)
{
var file = Checkpoint(folder);
// The host's analysis parameters as they are now (Settings › Analysis on the desktop). Those that change per-frame
// results are part of the checkpoint's fingerprint, so a partial run made with other values starts again.
var analysis = options.Current.DeepAnalysis;
var companions = await GprCompanions.FindAsync(db, archive, frames.Frames, cancellationToken).ConfigureAwait(false);
DeepAnalysisReport report;
Dictionary decoded;
await using (var source = new SequenceFrameSource(frames, metadata, options.Archive.Decoder) { Originals = true, Companions = companions })
{
report = await DeepAnalyzer.AnalyzeAsync(source, analysis, new FramesCheckpoint(file, ContentKey(frames)), progress, cancellationToken)
.ConfigureAwait(false);
decoded = Decoded(frames, report, source, companions, cancellationToken);
}
// An unreadable verdict on a frame read from its original goes stale once the frame has a proxy (ReadReport). The
// report is saved under the sequence lock, once the frames it measured are known to be current (SaveReport).
int[] fromProxies = [.. Enumerable.Range(0, frames.Count).Where(i => frames.Proxied?[i] == true)];
report = report with { ProxyFrames = fromProxies.Length > 0 ? fromProxies : null };
var columns = report.Frames;
var stats = new FrameLightStats[frames.Count];
for (var i = 0; i < stats.Length; i++)
stats[i] = new FrameLightStats(frames.Frames[i].Id, columns.LogLuminance[i], columns.ClipLow[i], columns.ClipHigh[i]);
await db.Frames.UpdateLightStatsAsync(stats, cancellationToken).ConfigureAwait(false);
return (report, decoded);
}
/// Identity of the analysed content: frames replaced or renumbered since a checkpoint was written (with the
/// same count), or now read from their proxies where they were read from their originals (or the other way round),
/// make it stale, like changed options do. Only frames read from proxies are marked, so the key of a sequence read
/// from its originals is what it was before proxies counted, and checkpoints written then still resume.
internal static string ContentKey(SequenceFrames frames)
{
using var hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256);
for (var i = 0; i < frames.Count; i++)
{
var f = frames.Frames[i];
var source = frames.Proxied is { } proxied && proxied[i] ? "/proxy" : "";
hash.AppendData(Encoding.UTF8.GetBytes($"{f.Id:N}/{f.Sha256}/{f.Size}/{f.Flags & SequenceFrames.NotAnalysed}{source};"));
}
return Convert.ToHexStringLower(hash.GetHashAndReset())[..16];
}
private sealed class FramesCheckpoint(DeepAnalysisCheckpointFile file, string contentKey) : IDeepAnalysisCheckpoint
{
public ValueTask> LoadAsync(string fingerprint, CancellationToken cancellationToken) =>
file.LoadAsync($"{fingerprint};content={contentKey}", cancellationToken);
public ValueTask AppendAsync(IReadOnlyList frames, CancellationToken cancellationToken) => file.AppendAsync(frames, cancellationToken);
}
}