Files
Chronos/src/Titano.Data/Archiving/ArchiveImages.cs
T

374 lines
18 KiB
C#
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
using System.Diagnostics;
using Titano.Core.Archiving;
using Titano.Core.Codecs.Jpeg;
using Titano.Core.Imaging;
using Titano.Core.Imaging.Decoders;
using Titano.Core.IO;
using Titano.Core.Metadata;
using Titano.Core.Model;
namespace Titano.Data.Archiving;
/// <summary>Frames processed by one thumbnail or proxy pass over a sequence.</summary>
public sealed record ImagePassResult(int Built, int Reused, int Undecodable);
/// <summary>What became of a proxy sent by a client or render node (<see cref="ArchiveImages.StoreProxy"/>).</summary>
public enum ProxyStoreResult
{
Stored,
/// <summary>The archive's proxy policy makes no proxies.</summary>
Disabled,
/// <summary>Not a JPEG that decodes, or larger than <see cref="ArchiveImages.MaxProxyBytes"/>.</summary>
Invalid,
/// <summary>Its Exif capture time is not the frame's: it was made from another photo.</summary>
WrongFrame,
/// <summary>Smaller than the archive's proxies of that frame: made from an embedded preview, not the original.</summary>
TooSmall,
}
/// <summary>
/// Thumbnails (<c>thumbs.pack</c>) and proxies (<c>proxies/0001.jpg</c>) of sequences (BRIEF §8.5). Both are
/// regenerable and self-validating: a thumbnail carries its source fingerprint, a proxy its capture time, so after
/// frames were renumbered the stale ones are rebuilt and the rest reused. A frame whose original this host cannot
/// decode (<see cref="NeedsProxy(ImageDecoder, ImageFileFormat)"/>) gets its proxy from a client or render node that can
/// (<see cref="StoreProxy"/>, BRIEF §2.3) and its thumbnail from that proxy.
/// </summary>
public sealed class ArchiveImages
{
/// <summary>Largest proxy a client or render node may send: a full-size proxy of a large sensor at q92 fits.</summary>
public const long MaxProxyBytes = 64L << 20;
private const int CommitFrames = 200;
private const int ProbeLongEdge = 64;
private static readonly TimeSpan CommitInterval = TimeSpan.FromSeconds(10);
private static readonly ImageDecoder ServerDecoders = DecoderFactory.CreateServer();
private readonly TitanoDatabase _db;
private readonly SequenceWriter _writer;
private readonly ArchiveIndexer _indexer;
private readonly FrameImageRenderer _renderer;
internal ArchiveImages(TitanoDatabase db, SequenceWriter writer, ArchiveIndexer indexer)
{
_db = db;
_writer = writer;
_indexer = indexer;
_renderer = new FrameImageRenderer(writer.Options.Decoder);
}
/// <summary>
/// Whether a host with <paramref name="decoder"/> takes the pixels of a <paramref name="format"/> original from its
/// proxy: no decoder reads the format, or only previews of a HEIF, which embeds thumbnails at best (BRIEF §2.3,
/// §8.1: the server keeps HEIF originals and relies on proxies made by a Windows client or render node). Never for a
/// JPEG (proxies are JPEGs: a host that reads them reads it) or a file no format was recognised in.
/// </summary>
public static bool NeedsProxy(ImageDecoder decoder, ImageFileFormat format)
{
ArgumentNullException.ThrowIfNull(decoder);
if (format is ImageFileFormat.Unknown or ImageFileFormat.Jpeg) return false;
var tier = decoder.TierFor(format);
return tier == DecodeTier.Unavailable || (tier != DecodeTier.Native && ImageFormatInfo.Of(format).Family == ImageFamily.Heif);
}
/// <summary><see cref="NeedsProxy(ImageDecoder, ImageFileFormat)"/> with this archive engine's decoders.</summary>
public bool NeedsProxy(ImageFileFormat format) => NeedsProxy(_writer.Options.Decoder, format);
/// <summary>
/// <see cref="NeedsProxy(ImageDecoder, ImageFileFormat)"/> on a Titano Server, whose decoders are managed only (BRIEF
/// §4.2): it asks clients and render nodes for the proxies of those originals.
/// </summary>
public static bool ServerNeedsProxy(ImageFileFormat format) => NeedsProxy(ServerDecoders, format);
/// <summary>
/// A proxy of the original at <paramref name="path"/> for a server that cannot decode it (<see cref="StoreProxy"/>):
/// at <paramref name="longEdge"/> (0 = full size) and <paramref name="quality"/>, with <paramref name="frame"/>'s capture
/// data (the server's record, which it checks) and <paramref name="camera"/> in its Exif. Null when
/// <paramref name="decoder"/> cannot decode the original either.
/// </summary>
/// <exception cref="IOException">The original cannot be read.</exception>
public static byte[]? MakeProxy(ImageDecoder decoder, string path, Frame frame, SidecarCamera? camera, int longEdge, int quality,
CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(frame);
if (NeedsProxy(decoder, frame.Format)) return null;
// The original's folder stands in for a sequence folder: the renderer reads frames relative to one.
var folder = new ArchivePaths(Path.GetDirectoryName(Path.GetFullPath(path))!).Sequence(string.Empty);
var source = new SidecarFrame
{
Id = frame.Id,
I = frame.Index,
File = Path.GetFileName(path),
Size = frame.Size,
CapturedAt = frame.CapturedAt,
UtcOffset = frame.UtcOffsetMinutes,
Exposure = frame.ExposureTime,
FNumber = frame.FNumber,
Iso = frame.Iso,
Focal = frame.FocalLength,
Bias = frame.ExposureBias,
Orientation = frame.Orientation,
Format = frame.Format,
};
var policy = new ProxyPolicy { LongEdge = longEdge, Quality = quality };
return new FrameImageRenderer(decoder).Proxy(folder, source, camera, policy, cancellationToken)?.Jpeg;
}
/// <summary>
/// Files a proxy made elsewhere (a client or render node whose decoders read the original) as the frame's proxy,
/// replacing the one there: a JPEG of at most <see cref="MaxProxyBytes"/> that decodes, whose Exif capture time is the
/// frame's (proxies carry it, so the proxy counts as current and cannot belong to another photo) and whose size is
/// the policy's (<see cref="TooSmall"/>), written atomically.
/// </summary>
/// <exception cref="ArchiveOfflineException">The archive is offline or read-only.</exception>
public ProxyStoreResult StoreProxy(Archive archive, Sequence sequence, Frame frame, byte[] jpeg)
{
ArgumentNullException.ThrowIfNull(jpeg);
var paths = new ArchivePaths(archive.RootPath);
ArchiveVolume.EnsureWritable(paths);
var policy = ManifestStore.ReadArchive(paths.ManifestPath).ProxyPolicy;
if (policy.LongEdge == ProxyPolicy.Disabled) return ProxyStoreResult.Disabled;
if (jpeg.Length is 0 or > (int)MaxProxyBytes || !Decodes(jpeg)) return ProxyStoreResult.Invalid;
var info = JpegDecoder.ReadInfo(jpeg);
if (TooSmall(System.Math.Max(info.Width, info.Height), frame.Width, frame.Height, policy)) return ProxyStoreResult.TooSmall;
if (frame.CapturedAt is { } captured)
{
using var stream = new MemoryStream(jpeg, writable: false);
if (MetadataReader.Read(stream, "proxy.jpg").CapturedAt != captured) return ProxyStoreResult.WrongFrame;
}
var folder = paths.Sequence(sequence.Folder);
Directory.CreateDirectory(folder.Proxies);
AtomicFile.WriteAllBytes(folder.Proxy(frame.Index), jpeg);
return ProxyStoreResult.Stored;
}
/// <param name="startFrame">Resume point inside the sequence (frames before it were done by an earlier run).</param>
/// <param name="checkpoint">Called with the next frame index whenever the pack has been committed.</param>
public async Task<ImagePassResult> BuildThumbnailsAsync(Archive archive, Sequence sequence, bool force, int startFrame,
Func<int, int, ValueTask> checkpoint, CancellationToken cancellationToken = default)
{
var paths = new ArchivePaths(archive.RootPath);
ArchiveVolume.EnsureWritable(paths);
var policy = ManifestStore.ReadArchive(paths.ManifestPath).ThumbnailPolicy;
var folder = paths.Sequence(sequence.Folder);
var manifest = ManifestStore.ReadSequence(folder.ManifestPath);
int built = 0, reused = 0, undecodable = 0;
// Thumbnail writers exclude each other only; ingest keeps committing meanwhile.
using (await LeaseFile.AcquireAsync(paths.LocksDirectory, $"thumbs-{sequence.Id:N}", _writer.Options.Owner, _writer.Options.LeaseWait,
_writer.Options.LeaseDuration, cancellationToken).ConfigureAwait(false))
using (var pack = ThumbPackWriter.Open(folder.ThumbsPackPath))
{
var cadence = new Cadence();
for (var i = startFrame; i < manifest.Frames.Count; i++)
{
cancellationToken.ThrowIfCancellationRequested();
var frame = manifest.Frames[i];
var fingerprint = ThumbPack.Fingerprint(frame.Sha256, frame.File, frame.Size);
var entry = pack.Entries.GetValueOrDefault(frame.I);
var edge = entry is null ? 0 : System.Math.Max(entry.Width, entry.Height);
var current = !force && entry is not null && entry.SourceHash.AsSpan().SequenceEqual(fingerprint);
// A frame this host cannot decode shows its proxy once one arrived; until then its original's embedded
// preview, whose smaller thumbnail the proxy's replaces.
var fromProxy = false;
if (NeedsProxy(frame.Format) && !(current && edge >= FrameImageRenderer.ThumbnailLongEdge)
&& ReadProxy(folder.Proxy(frame.I), frame) is { Check: ProxyCheck.Current or ProxyCheck.Unverifiable } proxy)
fromProxy = !current || edge < System.Math.Min(FrameImageRenderer.ThumbnailLongEdge, proxy.LongEdge);
if (current && !fromProxy)
{
reused++;
continue;
}
var source = fromProxy ? ProxySource(frame) : frame;
if (Render(() => _renderer.Thumbnail(folder, source, policy, cancellationToken)) is { } image)
{
pack.Append(frame.I, image.Width, image.Height, fingerprint, image.Jpeg);
built++;
}
else
{
undecodable++;
}
if (cadence.Due())
{
pack.Commit();
await checkpoint(i + 1, manifest.Frames.Count).ConfigureAwait(false);
}
}
pack.Commit();
}
await MarkAsync(archive, paths, sequence, SequenceStatus.ThumbsBuilt, undecodable == 0, cancellationToken).ConfigureAwait(false);
return new ImagePassResult(built, reused, undecodable);
}
/// <inheritdoc cref="BuildThumbnailsAsync"/>
public async Task<ImagePassResult> BuildProxiesAsync(Archive archive, Sequence sequence, bool force, int startFrame,
Func<int, int, ValueTask> checkpoint, CancellationToken cancellationToken = default)
{
var paths = new ArchivePaths(archive.RootPath);
ArchiveVolume.EnsureWritable(paths);
var policy = ManifestStore.ReadArchive(paths.ManifestPath).ProxyPolicy;
if (policy.LongEdge == ProxyPolicy.Disabled) return new ImagePassResult(0, 0, 0);
var folder = paths.Sequence(sequence.Folder);
var manifest = ManifestStore.ReadSequence(folder.ManifestPath);
Directory.CreateDirectory(folder.Proxies);
int built = 0, reused = 0, undecodable = 0;
var cadence = new Cadence();
for (var i = startFrame; i < manifest.Frames.Count; i++)
{
cancellationToken.ThrowIfCancellationRequested();
var frame = manifest.Frames[i];
var path = folder.Proxy(frame.I);
if (NeedsProxy(frame.Format))
{
// Only a client or render node that decodes the original makes this proxy: a preview would make one the
// size of a thumbnail here. One left from a frame renumbered since goes, so it is asked for again, and so
// does one smaller than the policy's (made here from a preview by an earlier version).
var (check, longEdge) = ReadProxy(path, frame);
if (check is ProxyCheck.Current or ProxyCheck.Unverifiable && TooSmall(longEdge, frame.W, frame.H, policy)) check = ProxyCheck.Stale;
if (check is ProxyCheck.Current or ProxyCheck.Unverifiable)
{
reused++;
}
else
{
if (check == ProxyCheck.Stale) File.Delete(path);
undecodable++;
}
}
else if (!force && ReadProxy(path, frame).Check == ProxyCheck.Current)
{
reused++;
continue;
}
else if (Render(() => _renderer.Proxy(folder, frame, manifest.Camera, policy, cancellationToken)) is { } image)
{
AtomicFile.WriteAllBytes(path, image.Jpeg);
built++;
}
else
{
undecodable++;
}
if (cadence.Due()) await checkpoint(i + 1, manifest.Frames.Count).ConfigureAwait(false);
}
await MarkAsync(archive, paths, sequence, SequenceStatus.ProxiesBuilt, undecodable == 0, cancellationToken).ConfigureAwait(false);
return new ImagePassResult(built, reused, undecodable);
}
/// <summary>Where a frame's proxy stands; only a capture time tells whether it is the frame's.</summary>
private enum ProxyCheck
{
Missing,
/// <summary>Its Exif capture time is the frame's.</summary>
Current,
/// <summary>The frame has no capture time to compare with.</summary>
Unverifiable,
/// <summary>Made from another frame (frames were renumbered since).</summary>
Stale,
}
/// <summary>Where the proxy at <paramref name="proxy"/> stands for <paramref name="frame"/>, and its long edge.</summary>
private static (ProxyCheck Check, int LongEdge) ReadProxy(string proxy, SidecarFrame frame)
{
if (!File.Exists(proxy)) return (ProxyCheck.Missing, 0);
try
{
var metadata = MetadataReader.Read(proxy);
var (width, height) = metadata.OrientedSize;
var check = frame.CapturedAt is null ? ProxyCheck.Unverifiable : metadata.CapturedAt == frame.CapturedAt ? ProxyCheck.Current : ProxyCheck.Stale;
return (check, System.Math.Max(width, height));
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
return (ProxyCheck.Missing, 0);
}
}
/// <summary>
/// Whether a proxy whose long edge is <paramref name="longEdge"/> falls short of the policy's for a frame of
/// <paramref name="width"/> × <paramref name="height"/> (the policy's long edge, or the frame's own when smaller or
/// at full size): one made from an embedded preview. A frame of unknown size is never judged (a small original's
/// proxy would be refused again and again); a tenth of slack spares decoders that crop a few pixels.
/// </summary>
private static bool TooSmall(int longEdge, int width, int height, ProxyPolicy policy)
{
var own = System.Math.Max(width, height);
if (own <= 0) return false;
var expected = policy.LongEdge == ProxyPolicy.FullSize ? own : System.Math.Min(own, policy.LongEdge);
return longEdge * 10L < expected * 9L;
}
/// <summary>The frame's proxy as the frame to draw: a JPEG already oriented, under <c>proxies/</c>.</summary>
private static SidecarFrame ProxySource(SidecarFrame frame) => frame with
{
File = ArchiveLayout.ProxiesFolder + "/" + ArchiveLayout.ProxyFileName(frame.I),
Format = ImageFileFormat.Jpeg,
Orientation = 1,
PreviewOffset = null,
PreviewLength = null,
};
/// <summary>A colour or grey JPEG whose headers parse and whose scans decode (at a small DCT-scaled size).</summary>
private static bool Decodes(byte[] jpeg)
{
try
{
var info = JpegDecoder.ReadInfo(jpeg);
if (info.Process == JpegProcess.Lossless || info.Components is not (1 or 3) || info.Width < 1 || info.Height < 1) return false;
using var probe = JpegDecoder.DecodeToLinear(jpeg, new JpegDecodeOptions { MaxLongEdge = ProbeLongEdge });
return true;
}
catch (Exception ex) when (ex is InvalidDataException or NotSupportedException)
{
return false;
}
}
/// <summary>A frame no decoder can read is skipped and counted; it never stops the pass.</summary>
private static EncodedImage? Render(Func<EncodedImage?> render)
{
try
{
return render();
}
catch (Exception ex) when (ex is IOException or InvalidDataException or NotSupportedException)
{
Core.Diagnostics.Log.Warning("archive", "Frame image could not be rendered", ex);
return null;
}
}
/// <summary>Commit/checkpoint rhythm: every <see cref="CommitFrames"/> rendered frames or <see cref="CommitInterval"/>.</summary>
private sealed class Cadence
{
private readonly Stopwatch _clock = Stopwatch.StartNew();
private int _frames;
public bool Due()
{
if (++_frames < CommitFrames && _clock.Elapsed < CommitInterval) return false;
_frames = 0;
_clock.Restart();
return true;
}
}
private async Task MarkAsync(Archive archive, ArchivePaths paths, Sequence sequence, SequenceStatus flag, bool complete, CancellationToken cancellationToken)
{
await _writer.UpdateAsync(paths, sequence.Id, sequence.Folder, m =>
{
var status = complete ? m.Status | flag : m.Status & ~flag;
return status == m.Status ? null : m with { Status = status, UpdatedAt = DateTimeOffset.UtcNow };
}, cancellationToken).ConfigureAwait(false);
await _db.Sequences.UpdateStatusAsync(sequence.Id, complete ? flag : SequenceStatus.None, complete ? SequenceStatus.None : flag, cancellationToken)
.ConfigureAwait(false);
await _indexer.RecordStampsAsync(archive, paths.Sequence(sequence.Folder), sequence.Id, cancellationToken).ConfigureAwait(false);
}
}