Meziantou.FrameworkAuxiliaryImageCollection Class
The images that a file stores next to its primary image without presenting them: the thumbnails, depth maps, gain maps and mattes of HEIC and AVIF files, and the images that follow the primary image of a JPEG Multi-Picture Format file (the gain map of an Ultra HDR photo). Image.Load never reads them.
public sealed class AuxiliaryImageCollection : IEnumerable<AuxiliaryImage>, IReadOnlyCollection<AuxiliaryImage>, IReadOnlyList<AuxiliaryImage>, IEnumerableRemarks
Loading reads the whole input into memory (up to ImageResourceLimits.MaxEncodedBytes) and its structure only: each image is decoded on demand by AuxiliaryImage.Decode, with its own limits. The collection holds no resource that needs to be disposed, and its images can be decoded from several threads at once.
The images are listed in the order of the file. A file of another format, or a file without such images, gives an empty collection. The description of an image is optional data: an image whose description cannot be read (an index of a JPEG file that points outside the file, a HEIF item without size) is not listed, and gain map parameters that cannot be read leave AuxiliaryImage.GainMapMetadata null (AuxiliaryImageCollection.DecodeHdr then throws the error).
- Implements
Properties
| Name | Description |
|---|---|
| Configuration | Gets the configuration the collection was loaded with, which decodes its images unless other options are given. |
| Count | Gets the number of images. |
| Format | Gets the format of the file. |
| GainMapImage | Gets the gain map that AuxiliaryImageCollection.DecodeHdr applies: the first gain map whose parameters are known, or else the first gain map, or null when the file has none. |
Configuration
AuxiliaryImageCollection.csGets the configuration the collection was loaded with, which decodes its images unless other options are given.
public ImageConfiguration Configuration { get; }Property value
GainMapImage
AuxiliaryImageCollection.csGets the gain map that AuxiliaryImageCollection.DecodeHdr applies: the first gain map whose parameters are known, or else the first gain map, or null when the file has none.
public AuxiliaryImage? GainMapImage { get; }Property value
Indexers
| Name | Description |
|---|---|
| this[int] | Gets an image. |
this[int]
AuxiliaryImageCollection.csGets an image.
public AuxiliaryImage this[int index] { get; }Parameters
indexint- The index of the image.
Property value
Exceptions
ArgumentOutOfRangeExceptionindexis out of range.
Methods
| Name | Description |
|---|---|
| DecodeHdr(double, ImageDecodeOptions?, CancellationToken) | Decodes the primary image and its gain map (AuxiliaryImageCollection.GainMapImage), and applies the gain map for a display of a given headroom (GainMapMetadata.Apply). |
| GetEnumerator() | Returns an enumerator over the images. |
| Load(Stream, ImageConfiguration?) | Lists the images of a stream, read from its current position to its end. |
| Load(ReadOnlySpan<byte>, ImageConfiguration?) | Lists the images of encoded data, which is copied. |
| Load(string, ImageConfiguration?) | Lists the images of a file. |
| System.Collections.IEnumerable.GetEnumerator() |
DecodeHdr(double, ImageDecodeOptions?, CancellationToken)
AuxiliaryImageCollection.csDecodes the primary image and its gain map (AuxiliaryImageCollection.GainMapImage), and applies the gain map for a display of a given headroom (GainMapMetadata.Apply).
public Image<RgbaFloat> DecodeHdr(double hdrHeadroom, ImageDecodeOptions? options = null, CancellationToken cancellationToken = default)Parameters
hdrHeadroomdouble- The headroom of the display, in stops: the log2 of the ratio of its peak light to the white of standard dynamic range. 0 gives the base image in linear light; the
GainMapMetadata.AlternateHdrHeadroomof the gain map, or more, gives the full alternate rendition. optionsImageDecodeOptions?- The decoding options of both images, or
nullfor the configuration the collection was loaded with. cancellationTokenCancellationToken- The token checked while the gain map is applied.
Returns
Image<RgbaFloat> A new image, owned by the caller, of linear light where 1 is the white of standard dynamic range, in the primaries of the base image (or of the alternate rendition when the gain map applies in its color space). The primary image decodes exactly as with Image.Load.
Exceptions
ArgumentOutOfRangeExceptionhdrHeadroomis negative or not finite.InvalidOperationException- The file has no gain map.
InvalidImageContentException- An image or the parameters of the gain map are malformed.
UnsupportedImageFeatureException- The parameters of the gain map are not known (a gain map of Apple without ISO 21496-1 metadata, a newer version of the metadata), or an image uses a feature that is not supported.
ImageResourceLimitException- An image exceeds a resource limit.
OperationCanceledExceptioncancellationTokenis canceled.
GetEnumerator()
AuxiliaryImageCollection.csReturns an enumerator over the images.
public IEnumerator<AuxiliaryImage> GetEnumerator()Returns
IEnumerator<AuxiliaryImage> The enumerator.
Load overloads
Load(Stream, ImageConfiguration?)
AuxiliaryImageCollection.csLists the images of a stream, read from its current position to its end.
public static AuxiliaryImageCollection Load(Stream stream, ImageConfiguration? configuration = null)Parameters
streamStream- The stream; it is not closed.
configurationImageConfiguration?- The configuration, or
nullforImageConfiguration.Default.
Returns
AuxiliaryImageCollection The images.
Exceptions
ArgumentNullExceptionstreamisnull.ArgumentExceptionstreamis not readable.UnknownImageFormatException- The format of the data is not recognized.
InvalidImageContentException- The structure of a HEIC or AVIF file is malformed.
ImageResourceLimitException- The stream has more than
ImageResourceLimits.MaxEncodedBytesbytes.
Load(ReadOnlySpan<byte>, ImageConfiguration?)
AuxiliaryImageCollection.csLists the images of encoded data, which is copied.
public static AuxiliaryImageCollection Load(ReadOnlySpan<byte> data, ImageConfiguration? configuration = null)Parameters
dataReadOnlySpan<byte>- The encoded data.
configurationImageConfiguration?- The configuration, or
nullforImageConfiguration.Default.
Returns
AuxiliaryImageCollection The images.
Exceptions
UnknownImageFormatException- The format of the data is not recognized.
InvalidImageContentException- The structure of a HEIC or AVIF file is malformed.
ImageResourceLimitException- The data is larger than
ImageResourceLimits.MaxEncodedBytes.
Load(string, ImageConfiguration?)
AuxiliaryImageCollection.csLists the images of a file.
public static AuxiliaryImageCollection Load(string path, ImageConfiguration? configuration = null)Parameters
pathstring- The path of the file.
configurationImageConfiguration?- The configuration, or
nullforImageConfiguration.Default.
Returns
AuxiliaryImageCollection The images.
Exceptions
ArgumentExceptionpathisnullor empty.UnknownImageFormatException- The format of the file is not recognized.
InvalidImageContentException- The structure of a HEIC or AVIF file is malformed.
ImageResourceLimitException- The file is larger than
ImageResourceLimits.MaxEncodedBytes. IOException- The file cannot be read.