feat(metadata): add signature detection and MetadataReader
ImageSignature.Detect identifies every BRIEF 8.1 format by magic bytes, refining TIFF-based RAWs by the CR2 marker, DNGVersion and Make, and ISO-BMFF files by ftyp brands; the extension only breaks ties. MetadataReader.Read (path or seekable stream) dispatches to the container parsers, opens files shared for read/write/delete with a small buffer, honours cancellation and turns any parser defect into a warning so malformed input never throws. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
2 files changed
+259
No files matched your search
@@ -0,0 +1,149 @@
|
||||
using System.Buffers.Binary;
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Metadata.Tiff;
|
||||
|
||||
namespace Titano.Core.Metadata;
|
||||
|
||||
/// <summary>
|
||||
/// Identifies a file's format from its leading bytes. TIFF-based files are refined by the CR2 marker, IFD0
|
||||
/// <c>DNGVersion</c> and <c>Make</c>; ISO-BMFF files by their <c>ftyp</c> brands. The file-name extension only breaks
|
||||
/// ties between formats that share a container (NEF/NRW, ARW/SRF/SR2, 3FR/FFF, RW2/RWL/RAW, TIFF vs camera RAW).
|
||||
/// </summary>
|
||||
public static class ImageSignature
|
||||
{
|
||||
private const int HeadBytes = 32;
|
||||
private const int MaxFtypBytes = 256;
|
||||
|
||||
private static ReadOnlySpan<byte> PngSignature => [0x89, (byte)'P', (byte)'N', (byte)'G', 0x0D, 0x0A, 0x1A, 0x0A];
|
||||
private static ReadOnlySpan<byte> JpegXrSignature => [(byte)'I', (byte)'I', 0xBC];
|
||||
private static ReadOnlySpan<byte> JpegXlBox => [0, 0, 0, 0x0C, (byte)'J', (byte)'X', (byte)'L', (byte)' ', 0x0D, 0x0A, 0x87, 0x0A];
|
||||
|
||||
private static readonly HashSet<ImageFileFormat> TiffBasedRaws =
|
||||
[
|
||||
ImageFileFormat.Dng, ImageFileFormat.Cr2, ImageFileFormat.Nef, ImageFileFormat.Nrw, ImageFileFormat.Arw,
|
||||
ImageFileFormat.Srf, ImageFileFormat.Sr2, ImageFileFormat.Orf, ImageFileFormat.Rw2, ImageFileFormat.Raw,
|
||||
ImageFileFormat.Rwl, ImageFileFormat.Pef, ImageFileFormat.Srw, ImageFileFormat.ThreeFr, ImageFileFormat.Fff,
|
||||
ImageFileFormat.Iiq, ImageFileFormat.Gpr,
|
||||
];
|
||||
|
||||
/// <summary>Detects the format of the bytes in <paramref name="stream"/> (read from offset 0; the position is restored).</summary>
|
||||
/// <param name="fileName">Optional name or path whose extension breaks ties; never overrides the signature.</param>
|
||||
/// <returns><see cref="ImageFileFormat.Unknown"/> when no known signature matches.</returns>
|
||||
public static ImageFileFormat Detect(Stream stream, string? fileName)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(stream);
|
||||
if (!stream.CanSeek || !stream.CanRead) throw new ArgumentException("The stream must be readable and seekable.", nameof(stream));
|
||||
var position = stream.Position;
|
||||
try
|
||||
{
|
||||
var extension = string.IsNullOrEmpty(fileName) ? ImageFileFormat.Unknown : ImageFormatInfo.FromPath(fileName).Format;
|
||||
return DetectCore(stream, extension);
|
||||
}
|
||||
catch (IOException)
|
||||
{
|
||||
return ImageFileFormat.Unknown;
|
||||
}
|
||||
finally
|
||||
{
|
||||
stream.Position = position;
|
||||
}
|
||||
}
|
||||
|
||||
private static ImageFileFormat DetectCore(Stream stream, ImageFileFormat extension)
|
||||
{
|
||||
Span<byte> buffer = stackalloc byte[HeadBytes];
|
||||
var h = buffer[..stream.ReadUpTo(0, buffer)];
|
||||
if (h.StartsWith((ReadOnlySpan<byte>)[0xFF, 0xD8, 0xFF])) return ImageFileFormat.Jpeg;
|
||||
if (h.StartsWith(PngSignature)) return ImageFileFormat.Png;
|
||||
if (h.StartsWith("GIF87a"u8) || h.StartsWith("GIF89a"u8)) return ImageFileFormat.Gif;
|
||||
if (h.StartsWith("FUJIFILMCCD-RAW "u8)) return ImageFileFormat.Raf;
|
||||
if (h.Length >= 12 && h.StartsWith("RIFF"u8) && h[8..12].SequenceEqual("WEBP"u8)) return ImageFileFormat.WebP;
|
||||
if (h.StartsWith((ReadOnlySpan<byte>)[0xFF, 0x0A]) || h.StartsWith(JpegXlBox)) return ImageFileFormat.JpegXl;
|
||||
if (h.Length >= 12 && h[4..8].SequenceEqual("ftyp"u8)) return FromBrands(stream, BinaryPrimitives.ReadUInt32BigEndian(h));
|
||||
if (h.Length >= 4 && h.StartsWith(JpegXrSignature) && h[3] <= 1) return ImageFileFormat.JpegXr;
|
||||
if (h.Length >= 14 && h[6..14].SequenceEqual("HEAPCCDR"u8)) return ImageFileFormat.Crw;
|
||||
if (h.StartsWith("IIRO"u8) || h.StartsWith("IIRS"u8) || h.StartsWith("MMOR"u8)) return ImageFileFormat.Orf;
|
||||
if (h.StartsWith("IIU\0"u8)) return Panasonic(stream, extension);
|
||||
if (h.StartsWith("II*\0"u8) || h.StartsWith("MM\0*"u8)) return Tiff(stream, h, extension);
|
||||
if (h.Length >= 18 && h.StartsWith("BM"u8) && BinaryPrimitives.ReadUInt32LittleEndian(h[14..]) is 12 or 16 or 40 or 52 or 56 or 64 or 108 or 124)
|
||||
return ImageFileFormat.Bmp;
|
||||
return ImageFileFormat.Unknown;
|
||||
}
|
||||
|
||||
/// <summary>CR3 (crx), AVIF (avif/avis) or HEIF (heic, heix, hevc, hevx, heim, heis, mif1, msf1); major brand first.</summary>
|
||||
private static ImageFileFormat FromBrands(Stream stream, uint ftypSize)
|
||||
{
|
||||
Span<byte> buffer = stackalloc byte[MaxFtypBytes];
|
||||
var n = stream.ReadUpTo(0, buffer[..(int)Math.Clamp(ftypSize, 16, MaxFtypBytes)]);
|
||||
if (n < 12) return ImageFileFormat.Unknown;
|
||||
var major = Brand(buffer[8..12]);
|
||||
if (major == BrandKind.Cr3) return ImageFileFormat.Cr3;
|
||||
if (major == BrandKind.Avif) return ImageFileFormat.Avif;
|
||||
if (major == BrandKind.Heif) return ImageFileFormat.Heif;
|
||||
var heif = major == BrandKind.Image;
|
||||
for (var i = 16; i + 4 <= n; i += 4)
|
||||
{
|
||||
var brand = Brand(buffer.Slice(i, 4));
|
||||
if (brand == BrandKind.Avif) return ImageFileFormat.Avif;
|
||||
heif |= brand is BrandKind.Heif or BrandKind.Image;
|
||||
}
|
||||
return heif ? ImageFileFormat.Heif : ImageFileFormat.Unknown;
|
||||
}
|
||||
|
||||
private enum BrandKind
|
||||
{
|
||||
Other,
|
||||
Cr3,
|
||||
Avif,
|
||||
Heif,
|
||||
Image,
|
||||
}
|
||||
|
||||
private static BrandKind Brand(ReadOnlySpan<byte> b) =>
|
||||
b.SequenceEqual("crx "u8) ? BrandKind.Cr3
|
||||
: b.SequenceEqual("avif"u8) || b.SequenceEqual("avis"u8) ? BrandKind.Avif
|
||||
: b.SequenceEqual("heic"u8) || b.SequenceEqual("heix"u8) || b.SequenceEqual("hevc"u8) || b.SequenceEqual("hevx"u8)
|
||||
|| b.SequenceEqual("heim"u8) || b.SequenceEqual("heis"u8) ? BrandKind.Heif
|
||||
: b.SequenceEqual("mif1"u8) || b.SequenceEqual("msf1"u8) ? BrandKind.Image
|
||||
: BrandKind.Other;
|
||||
|
||||
private static ImageFileFormat Panasonic(Stream stream, ImageFileFormat extension)
|
||||
{
|
||||
if (extension is ImageFileFormat.Rwl or ImageFileFormat.Raw) return extension;
|
||||
return Make(stream)?.StartsWith("LEICA", StringComparison.OrdinalIgnoreCase) == true ? ImageFileFormat.Rwl : ImageFileFormat.Rw2;
|
||||
}
|
||||
|
||||
private static ImageFileFormat Tiff(Stream stream, ReadOnlySpan<byte> h, ImageFileFormat extension)
|
||||
{
|
||||
if (h.Length >= 10 && h[8..10].SequenceEqual("CR"u8)) return ImageFileFormat.Cr2;
|
||||
var reader = TiffReader.Open(stream);
|
||||
var ifd0 = reader?.ReadIfd(reader.FirstIfdOffset);
|
||||
var make = reader is not null && ifd0 is not null ? IfdValue.String(reader, ifd0, TiffTags.Make) : null;
|
||||
if (ifd0?.Has(TiffTags.DngVersion) == true)
|
||||
return extension == ImageFileFormat.Gpr || make?.StartsWith("GoPro", StringComparison.OrdinalIgnoreCase) == true ? ImageFileFormat.Gpr : ImageFileFormat.Dng;
|
||||
if (extension == ImageFileFormat.Tiff) return ImageFileFormat.Tiff;
|
||||
var byMake = ByMake(make, extension);
|
||||
if (byMake != ImageFileFormat.Unknown) return byMake;
|
||||
return TiffBasedRaws.Contains(extension) ? extension : ImageFileFormat.Tiff;
|
||||
}
|
||||
|
||||
private static ImageFileFormat ByMake(string? make, ImageFileFormat extension)
|
||||
{
|
||||
if (make is null) return ImageFileFormat.Unknown;
|
||||
bool Is(string prefix) => make.StartsWith(prefix, StringComparison.OrdinalIgnoreCase);
|
||||
if (Is("NIKON")) return extension == ImageFileFormat.Nrw ? ImageFileFormat.Nrw : ImageFileFormat.Nef;
|
||||
if (Is("SONY")) return extension is ImageFileFormat.Srf or ImageFileFormat.Sr2 ? extension : ImageFileFormat.Arw;
|
||||
if (Is("PENTAX") || Is("RICOH")) return ImageFileFormat.Pef;
|
||||
if (Is("SAMSUNG")) return ImageFileFormat.Srw;
|
||||
if (Is("Hasselblad")) return extension == ImageFileFormat.Fff ? ImageFileFormat.Fff : ImageFileFormat.ThreeFr;
|
||||
if (Is("Imacon")) return ImageFileFormat.Fff;
|
||||
if (Is("Phase One") || Is("Leaf")) return ImageFileFormat.Iiq;
|
||||
return ImageFileFormat.Unknown;
|
||||
}
|
||||
|
||||
private static string? Make(Stream stream)
|
||||
{
|
||||
var reader = TiffReader.Open(stream);
|
||||
return reader?.ReadIfd(reader.FirstIfdOffset) is { } ifd ? IfdValue.String(reader, ifd, TiffTags.Make) : null;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,110 @@
|
||||
using Titano.Core.Diagnostics;
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Metadata.Bmff;
|
||||
using Titano.Core.Metadata.Jpeg;
|
||||
using Titano.Core.Metadata.Png;
|
||||
using Titano.Core.Metadata.Raf;
|
||||
using Titano.Core.Metadata.Riff;
|
||||
using Titano.Core.Metadata.Tiff;
|
||||
|
||||
namespace Titano.Core.Metadata;
|
||||
|
||||
/// <summary>
|
||||
/// Reads <see cref="FrameMetadata"/> from any supported photo (BRIEF §9). Detects the container by signature, then
|
||||
/// reads only the structures it needs through bounded seeks (a RAW's image data is never read). Malformed input never
|
||||
/// throws: the result carries whatever was readable plus <see cref="FrameMetadata.Warnings"/>.
|
||||
/// </summary>
|
||||
public static class MetadataReader
|
||||
{
|
||||
private const string LogCategory = "Metadata";
|
||||
private const int FileBufferSize = 4096;
|
||||
|
||||
/// <summary>Reads the file at <paramref name="path"/>; its modification time is the last-resort capture time.</summary>
|
||||
/// <exception cref="IOException">The file cannot be opened (missing or locked).</exception>
|
||||
/// <exception cref="UnauthorizedAccessException">Access to the file is denied.</exception>
|
||||
public static FrameMetadata Read(string path, CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(path);
|
||||
using var stream = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, FileBufferSize, FileOptions.RandomAccess);
|
||||
return Read(stream, Path.GetFileName(path), File.GetLastWriteTime(path), cancellationToken);
|
||||
}
|
||||
|
||||
/// <summary>Reads metadata from a readable, seekable stream (the position is left undefined).</summary>
|
||||
/// <param name="fileName">Name used only to break signature ties (see <see cref="ImageSignature"/>).</param>
|
||||
/// <param name="fileModifiedLocal">File time used when no capture time is recorded (<see cref="Model.TimestampSource.FileSystem"/>);
|
||||
/// its UTC offset is taken from the local zone for <see cref="DateTimeKind.Local"/> values.</param>
|
||||
/// <exception cref="OperationCanceledException">Cancelled through <paramref name="cancellationToken"/>.</exception>
|
||||
public static FrameMetadata Read(Stream stream, string? fileName, DateTime? fileModifiedLocal = null, CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(stream);
|
||||
if (!stream.CanSeek || !stream.CanRead) throw new ArgumentException("The stream must be readable and seekable.", nameof(stream));
|
||||
cancellationToken.ThrowIfCancellationRequested();
|
||||
var m = new MetadataBuilder(stream, cancellationToken);
|
||||
try
|
||||
{
|
||||
m.Format = ImageSignature.Detect(stream, fileName);
|
||||
Parse(m);
|
||||
}
|
||||
catch (OperationCanceledException)
|
||||
{
|
||||
throw;
|
||||
}
|
||||
catch (IOException ex)
|
||||
{
|
||||
m.Warn("I/O error: " + ex.Message);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
// Safety net: parsers are written not to throw, but a defect must cost one file's metadata, not the import.
|
||||
m.Warn($"Parser fault: {ex.GetType().Name}: {ex.Message}");
|
||||
Log.Warning(LogCategory, $"Metadata parser fault in {fileName ?? "stream"}", ex);
|
||||
}
|
||||
return m.Build(fileModifiedLocal);
|
||||
}
|
||||
|
||||
private static void Parse(MetadataBuilder m)
|
||||
{
|
||||
switch (m.Format)
|
||||
{
|
||||
case ImageFileFormat.Jpeg:
|
||||
JpegParser.Parse(m, 0, m.Length, primary: true);
|
||||
break;
|
||||
case ImageFileFormat.Png:
|
||||
PngParser.Parse(m);
|
||||
break;
|
||||
case ImageFileFormat.WebP:
|
||||
WebPParser.Parse(m);
|
||||
break;
|
||||
case ImageFileFormat.Heif or ImageFileFormat.Avif:
|
||||
HeifParser.Parse(m);
|
||||
break;
|
||||
case ImageFileFormat.Cr3:
|
||||
Cr3Parser.Parse(m);
|
||||
break;
|
||||
case ImageFileFormat.Raf:
|
||||
RafParser.Parse(m);
|
||||
break;
|
||||
case ImageFileFormat.Gif:
|
||||
MinimalFormatParser.ParseGif(m);
|
||||
break;
|
||||
case ImageFileFormat.Bmp:
|
||||
MinimalFormatParser.ParseBmp(m);
|
||||
break;
|
||||
case ImageFileFormat.JpegXr:
|
||||
MinimalFormatParser.ParseJpegXr(m);
|
||||
break;
|
||||
case ImageFileFormat.JpegXl:
|
||||
MinimalFormatParser.ParseJpegXl(m);
|
||||
break;
|
||||
case ImageFileFormat.Crw:
|
||||
m.Warn("CRW (CIFF) metadata is not supported");
|
||||
break;
|
||||
case ImageFileFormat.Unknown:
|
||||
m.Warn("Unrecognised file signature");
|
||||
break;
|
||||
default:
|
||||
ExifParser.ParseFile(m);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user