mirror of https://github.com/SixLabors/ImageSharp
James Jackson-South
1 week ago
7 changed files with 761 additions and 352 deletions
@ -0,0 +1,369 @@ |
|||||
|
// Copyright (c) Six Labors.
|
||||
|
// Licensed under the Six Labors Split License.
|
||||
|
|
||||
|
using System.Buffers.Binary; |
||||
|
using SixLabors.ImageSharp.ColorProfiles; |
||||
|
using SixLabors.ImageSharp.Metadata.Profiles.Cicp; |
||||
|
using SixLabors.ImageSharp.Metadata.Profiles.Icc; |
||||
|
|
||||
|
namespace SixLabors.ImageSharp.Formats.Heif; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses the image properties shared by HEIF items and image-sequence sample entries.
|
||||
|
/// </summary>
|
||||
|
internal static class HeifPropertyParser |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// Parses relative horizontal and vertical pixel spacing.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete pixel-aspect-ratio payload.</param>
|
||||
|
/// <returns>The validated relative pixel spacing.</returns>
|
||||
|
public static HeifPixelAspectRatio ParsePixelAspectRatio(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
EnsureExactLength(data, 8, "pixel aspect ratio"); |
||||
|
uint horizontalSpacing = BinaryPrimitives.ReadUInt32BigEndian(data); |
||||
|
uint verticalSpacing = BinaryPrimitives.ReadUInt32BigEndian(data[4..]); |
||||
|
if (horizontalSpacing == 0 || verticalSpacing == 0) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The pixel aspect ratio property has zero spacing."); |
||||
|
} |
||||
|
|
||||
|
return new HeifPixelAspectRatio(horizontalSpacing, verticalSpacing); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses and validates an embedded ICC profile.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete ICC profile bytes.</param>
|
||||
|
/// <returns>The validated ICC profile.</returns>
|
||||
|
public static IccProfile ParseIccProfile(byte[] data) |
||||
|
{ |
||||
|
if (data.Length == 0) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The HEIF ICC color property contains an empty profile."); |
||||
|
} |
||||
|
|
||||
|
IccProfile profile = new(data); |
||||
|
if (!profile.CheckIsValid()) |
||||
|
{ |
||||
|
throw new InvalidIccProfileException("Invalid HEIF ICC profile."); |
||||
|
} |
||||
|
|
||||
|
return profile; |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses a CICP color description from an <c>nclx</c> color-information payload.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete payload following the <c>nclx</c> color type.</param>
|
||||
|
/// <returns>The CICP color description.</returns>
|
||||
|
public static CicpProfile ParseCicpProfile(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
EnsureExactLength(data, 7, "CICP color information"); |
||||
|
ushort colorPrimaries = BinaryPrimitives.ReadUInt16BigEndian(data); |
||||
|
ushort transferCharacteristics = BinaryPrimitives.ReadUInt16BigEndian(data[2..]); |
||||
|
ushort matrixCoefficients = BinaryPrimitives.ReadUInt16BigEndian(data[4..]); |
||||
|
byte rangeAndReserved = data[6]; |
||||
|
if ((rangeAndReserved & 0x7F) != 0) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The HEIF CICP color property has nonzero reserved bits."); |
||||
|
} |
||||
|
|
||||
|
// The box fields are 16-bit so future registrations remain representable. ImageSharp's CICP profile exposes
|
||||
|
// the currently registered byte-sized H.273 values and maps larger future values to unspecified.
|
||||
|
byte colorPrimariesValue = colorPrimaries <= byte.MaxValue ? (byte)colorPrimaries : (byte)CicpColorPrimaries.Unspecified; |
||||
|
byte transferCharacteristicsValue = transferCharacteristics <= byte.MaxValue |
||||
|
? (byte)transferCharacteristics |
||||
|
: (byte)CicpTransferCharacteristics.Unspecified; |
||||
|
|
||||
|
byte matrixCoefficientsValue = matrixCoefficients <= byte.MaxValue |
||||
|
? (byte)matrixCoefficients |
||||
|
: (byte)CicpMatrixCoefficients.Unspecified; |
||||
|
|
||||
|
return new CicpProfile(colorPrimariesValue, transferCharacteristicsValue, matrixCoefficientsValue, (rangeAndReserved & 0x80) != 0); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses content light-level information.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete content-light-level payload.</param>
|
||||
|
/// <returns>The content light-level information.</returns>
|
||||
|
public static HeifContentLightLevel ParseContentLightLevel(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
EnsureExactLength(data, 4, "content light level"); |
||||
|
return new HeifContentLightLevel(BinaryPrimitives.ReadUInt16BigEndian(data), BinaryPrimitives.ReadUInt16BigEndian(data[2..])); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses mastering-display color-volume information.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete mastering-display color-volume payload.</param>
|
||||
|
/// <returns>The mastering-display color-volume information.</returns>
|
||||
|
public static HeifMasteringDisplayColorVolume ParseMasteringDisplayColorVolume(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
EnsureExactLength(data, 24, "mastering display color volume"); |
||||
|
const float chromaticityScale = 1F / 50000F; |
||||
|
const double luminanceScale = 1D / 10000D; |
||||
|
|
||||
|
// The registered payload inherits the G, B, R primary order used by its mastering-display source syntax.
|
||||
|
// Reorder it into ImageSharp's existing RGB coordinate type at the shared container boundary.
|
||||
|
CieXyChromaticityCoordinates greenPrimary = new( |
||||
|
BinaryPrimitives.ReadUInt16BigEndian(data) * chromaticityScale, |
||||
|
BinaryPrimitives.ReadUInt16BigEndian(data[2..]) * chromaticityScale); |
||||
|
|
||||
|
CieXyChromaticityCoordinates bluePrimary = new( |
||||
|
BinaryPrimitives.ReadUInt16BigEndian(data[4..]) * chromaticityScale, |
||||
|
BinaryPrimitives.ReadUInt16BigEndian(data[6..]) * chromaticityScale); |
||||
|
|
||||
|
CieXyChromaticityCoordinates redPrimary = new( |
||||
|
BinaryPrimitives.ReadUInt16BigEndian(data[8..]) * chromaticityScale, |
||||
|
BinaryPrimitives.ReadUInt16BigEndian(data[10..]) * chromaticityScale); |
||||
|
|
||||
|
return new HeifMasteringDisplayColorVolume( |
||||
|
new RgbPrimariesChromaticityCoordinates(redPrimary, greenPrimary, bluePrimary), |
||||
|
new CieXyChromaticityCoordinates( |
||||
|
BinaryPrimitives.ReadUInt16BigEndian(data[12..]) * chromaticityScale, |
||||
|
BinaryPrimitives.ReadUInt16BigEndian(data[14..]) * chromaticityScale), |
||||
|
BinaryPrimitives.ReadUInt32BigEndian(data[16..]) * luminanceScale, |
||||
|
BinaryPrimitives.ReadUInt32BigEndian(data[20..]) * luminanceScale); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses content color-volume information.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete content color-volume payload.</param>
|
||||
|
/// <returns>The content color-volume information.</returns>
|
||||
|
public static HeifContentColorVolume ParseContentColorVolume(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
if (data.IsEmpty) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The content color-volume property is truncated."); |
||||
|
} |
||||
|
|
||||
|
byte flags = data[0]; |
||||
|
if ((flags & 0xC3) != 0) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The content color-volume property has nonzero reserved flags."); |
||||
|
} |
||||
|
|
||||
|
bool primariesPresent = (flags & 0x20) != 0; |
||||
|
bool minimumLuminancePresent = (flags & 0x10) != 0; |
||||
|
bool maximumLuminancePresent = (flags & 0x08) != 0; |
||||
|
bool averageLuminancePresent = (flags & 0x04) != 0; |
||||
|
if (!primariesPresent && !minimumLuminancePresent && !maximumLuminancePresent && !averageLuminancePresent) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The content color-volume property does not describe any values."); |
||||
|
} |
||||
|
|
||||
|
int expectedLength = 1 |
||||
|
+ (primariesPresent ? 24 : 0) |
||||
|
+ (minimumLuminancePresent ? 4 : 0) |
||||
|
+ (maximumLuminancePresent ? 4 : 0) |
||||
|
+ (averageLuminancePresent ? 4 : 0); |
||||
|
|
||||
|
EnsureExactLength(data, expectedLength, "content color volume"); |
||||
|
int offset = 1; |
||||
|
RgbPrimariesChromaticityCoordinates? primaries = null; |
||||
|
if (primariesPresent) |
||||
|
{ |
||||
|
int greenX = BinaryPrimitives.ReadInt32BigEndian(data[offset..]); |
||||
|
int greenY = BinaryPrimitives.ReadInt32BigEndian(data[(offset + 4)..]); |
||||
|
int blueX = BinaryPrimitives.ReadInt32BigEndian(data[(offset + 8)..]); |
||||
|
int blueY = BinaryPrimitives.ReadInt32BigEndian(data[(offset + 12)..]); |
||||
|
int redX = BinaryPrimitives.ReadInt32BigEndian(data[(offset + 16)..]); |
||||
|
int redY = BinaryPrimitives.ReadInt32BigEndian(data[(offset + 20)..]); |
||||
|
const int maximumChromaticityValue = 5_000_000; |
||||
|
if (greenX is < -maximumChromaticityValue or > maximumChromaticityValue |
||||
|
|| greenY is < -maximumChromaticityValue or > maximumChromaticityValue |
||||
|
|| blueX is < -maximumChromaticityValue or > maximumChromaticityValue |
||||
|
|| blueY is < -maximumChromaticityValue or > maximumChromaticityValue |
||||
|
|| redX is < -maximumChromaticityValue or > maximumChromaticityValue |
||||
|
|| redY is < -maximumChromaticityValue or > maximumChromaticityValue) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The content color-volume property has an out-of-range primary coordinate."); |
||||
|
} |
||||
|
|
||||
|
const float chromaticityScale = 1F / 50000F; |
||||
|
|
||||
|
// Content-color-volume syntax also stores signed coordinates in G, B, R order.
|
||||
|
primaries = new RgbPrimariesChromaticityCoordinates( |
||||
|
new CieXyChromaticityCoordinates(redX * chromaticityScale, redY * chromaticityScale), |
||||
|
new CieXyChromaticityCoordinates(greenX * chromaticityScale, greenY * chromaticityScale), |
||||
|
new CieXyChromaticityCoordinates(blueX * chromaticityScale, blueY * chromaticityScale)); |
||||
|
|
||||
|
offset += 24; |
||||
|
} |
||||
|
|
||||
|
uint? minimumLuminance = minimumLuminancePresent ? BinaryPrimitives.ReadUInt32BigEndian(data[offset..]) : null; |
||||
|
offset += minimumLuminancePresent ? 4 : 0; |
||||
|
uint? maximumLuminance = maximumLuminancePresent ? BinaryPrimitives.ReadUInt32BigEndian(data[offset..]) : null; |
||||
|
offset += maximumLuminancePresent ? 4 : 0; |
||||
|
uint? averageLuminance = averageLuminancePresent ? BinaryPrimitives.ReadUInt32BigEndian(data[offset..]) : null; |
||||
|
if ((minimumLuminance is not null && averageLuminance is not null && minimumLuminance.Value > averageLuminance.Value) |
||||
|
|| (averageLuminance is not null && maximumLuminance is not null && averageLuminance.Value > maximumLuminance.Value) |
||||
|
|| (minimumLuminance is not null && maximumLuminance is not null && minimumLuminance.Value > maximumLuminance.Value)) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The content color-volume luminance values are not in ascending order."); |
||||
|
} |
||||
|
|
||||
|
const double luminanceScale = 1D / 10000000D; |
||||
|
|
||||
|
// These values are normalized according to the signaled transfer characteristics. Preserve that
|
||||
|
// unitless meaning instead of presenting them as physical display luminance.
|
||||
|
return new HeifContentColorVolume( |
||||
|
primaries, |
||||
|
minimumLuminance * luminanceScale, |
||||
|
maximumLuminance * luminanceScale, |
||||
|
averageLuminance * luminanceScale); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses an ambient viewing environment.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete ambient viewing-environment payload.</param>
|
||||
|
/// <returns>The ambient viewing environment.</returns>
|
||||
|
public static HeifAmbientViewingEnvironment ParseAmbientViewingEnvironment(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
EnsureExactLength(data, 8, "ambient viewing environment"); |
||||
|
uint illuminance = BinaryPrimitives.ReadUInt32BigEndian(data); |
||||
|
ushort lightX = BinaryPrimitives.ReadUInt16BigEndian(data[4..]); |
||||
|
ushort lightY = BinaryPrimitives.ReadUInt16BigEndian(data[6..]); |
||||
|
if (illuminance == 0) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The ambient viewing-environment property has zero illuminance."); |
||||
|
} |
||||
|
|
||||
|
if (lightX > 50000 || lightY > 50000) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The ambient viewing-environment property has an out-of-range chromaticity coordinate."); |
||||
|
} |
||||
|
|
||||
|
const double illuminanceScale = 1D / 10000D; |
||||
|
const float chromaticityScale = 1F / 50000F; |
||||
|
|
||||
|
// The property inherits H.274's fixed-point units: 0.0001 lux for illuminance and 0.00002 for each
|
||||
|
// normalized CIE chromaticity coordinate.
|
||||
|
return new HeifAmbientViewingEnvironment( |
||||
|
illuminance * illuminanceScale, |
||||
|
new CieXyChromaticityCoordinates(lightX * chromaticityScale, lightY * chromaticityScale)); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses a reference viewing environment.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete reference viewing-environment payload.</param>
|
||||
|
/// <returns>The reference viewing environment.</returns>
|
||||
|
public static HeifReferenceViewingEnvironment ParseReferenceViewingEnvironment(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
EnsureExactLength(data, 20, "reference viewing environment"); |
||||
|
if (BinaryPrimitives.ReadUInt32BigEndian(data) != 0) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The reference viewing-environment property has an unsupported version or flags."); |
||||
|
} |
||||
|
|
||||
|
ushort surroundX = BinaryPrimitives.ReadUInt16BigEndian(data[8..]); |
||||
|
ushort surroundY = BinaryPrimitives.ReadUInt16BigEndian(data[10..]); |
||||
|
ushort peripheryX = BinaryPrimitives.ReadUInt16BigEndian(data[16..]); |
||||
|
ushort peripheryY = BinaryPrimitives.ReadUInt16BigEndian(data[18..]); |
||||
|
if (surroundX > 10000 || surroundY > 10000 || peripheryX > 10000 || peripheryY > 10000) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The reference viewing-environment property has an out-of-range chromaticity coordinate."); |
||||
|
} |
||||
|
|
||||
|
const double luminanceScale = 1D / 10000D; |
||||
|
const float chromaticityScale = 1F / 10000F; |
||||
|
|
||||
|
// The full-box header is followed by display-surround and wider-periphery fields. Both groups use
|
||||
|
// 0.0001 increments, but luminance is physical cd/m2 while the CIE coordinates are normalized.
|
||||
|
return new HeifReferenceViewingEnvironment( |
||||
|
BinaryPrimitives.ReadUInt32BigEndian(data[4..]) * luminanceScale, |
||||
|
new CieXyChromaticityCoordinates(surroundX * chromaticityScale, surroundY * chromaticityScale), |
||||
|
BinaryPrimitives.ReadUInt32BigEndian(data[12..]) * luminanceScale, |
||||
|
new CieXyChromaticityCoordinates(peripheryX * chromaticityScale, peripheryY * chromaticityScale)); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses nominal diffuse-white information.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete nominal diffuse-white payload.</param>
|
||||
|
/// <returns>The nominal diffuse-white information.</returns>
|
||||
|
public static HeifNominalDiffuseWhite ParseNominalDiffuseWhite(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
EnsureExactLength(data, 8, "nominal diffuse white"); |
||||
|
if (BinaryPrimitives.ReadUInt32BigEndian(data) != 0) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The nominal diffuse-white property has an unsupported version or flags."); |
||||
|
} |
||||
|
|
||||
|
uint luminance = BinaryPrimitives.ReadUInt32BigEndian(data[4..]); |
||||
|
const double luminanceScale = 1D / 10000D; |
||||
|
|
||||
|
// A zero coded value requests the standard-defined default rather than describing black diffuse white.
|
||||
|
return new HeifNominalDiffuseWhite(luminance == 0 ? null : luminance * luminanceScale); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses a clean-aperture crop description.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete clean-aperture payload.</param>
|
||||
|
/// <returns>The clean-aperture crop description.</returns>
|
||||
|
public static HeifCleanAperture ParseCleanAperture(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
EnsureExactLength(data, 32, "clean aperture"); |
||||
|
return new HeifCleanAperture( |
||||
|
BinaryPrimitives.ReadInt32BigEndian(data), |
||||
|
BinaryPrimitives.ReadInt32BigEndian(data[4..]), |
||||
|
BinaryPrimitives.ReadInt32BigEndian(data[8..]), |
||||
|
BinaryPrimitives.ReadInt32BigEndian(data[12..]), |
||||
|
BinaryPrimitives.ReadInt32BigEndian(data[16..]), |
||||
|
BinaryPrimitives.ReadInt32BigEndian(data[20..]), |
||||
|
BinaryPrimitives.ReadInt32BigEndian(data[24..]), |
||||
|
BinaryPrimitives.ReadInt32BigEndian(data[28..])); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses the number of counter-clockwise quarter turns applied to an image.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete image-rotation payload.</param>
|
||||
|
/// <returns>The number of counter-clockwise quarter turns.</returns>
|
||||
|
public static byte ParseRotation(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
EnsureExactLength(data, 1, "image rotation"); |
||||
|
if ((data[0] & 0xFC) != 0) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The image rotation property has nonzero reserved bits."); |
||||
|
} |
||||
|
|
||||
|
return (byte)(data[0] & 3); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Parses the horizontal or vertical image-mirror axis.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete image-mirror payload.</param>
|
||||
|
/// <returns>Zero for the horizontal axis or one for the vertical axis.</returns>
|
||||
|
public static byte ParseMirrorAxis(ReadOnlySpan<byte> data) |
||||
|
{ |
||||
|
EnsureExactLength(data, 1, "image mirror"); |
||||
|
if ((data[0] & 0xFE) != 0) |
||||
|
{ |
||||
|
throw new InvalidImageContentException("The image mirror property has nonzero reserved bits."); |
||||
|
} |
||||
|
|
||||
|
return (byte)(data[0] & 1); |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Requires a fixed-size image property to contain exactly its registered payload length.
|
||||
|
/// </summary>
|
||||
|
/// <param name="data">The complete property payload.</param>
|
||||
|
/// <param name="length">The registered payload length.</param>
|
||||
|
/// <param name="name">The property name used in malformed-image diagnostics.</param>
|
||||
|
private static void EnsureExactLength(ReadOnlySpan<byte> data, int length, string name) |
||||
|
{ |
||||
|
if (data.Length != length) |
||||
|
{ |
||||
|
throw new InvalidImageContentException($"The {name} property has an invalid length."); |
||||
|
} |
||||
|
} |
||||
|
} |
||||
Loading…
Reference in new issue