Meziantou.FrameworkGainMapMetadata Class
The parameters of a gain map (ISO 21496-1, the hdrgm XMP namespace of Adobe and Ultra HDR): an image stored next to a base image, which gives the gain that turns the base image into an alternate rendition, typically a standard dynamic range photo into its high dynamic range version.
public sealed class GainMapMetadata : IEquatable<GainMapMetadata>Remarks
The headrooms are in stops: the log2 of the ratio of the peak light of a rendition to the white of standard dynamic range. A display of headroom H shows the base image when H is at most GainMapMetadata.BaseHdrHeadroom, the alternate image when H is at least GainMapMetadata.AlternateHdrHeadroom, and an interpolation in the log domain between them (GainMapMetadata.GetWeight).
A file stores the values as fractions (ISO 21496-1) or decimal numbers (XMP): they are converted to Double, and an Ultra HDR description with a high dynamic range base rendition (BaseRenditionIsHDR) is expressed with the headrooms and the offsets of the base and alternate renditions swapped, which gives the same colors.
- Implements
Constructors
| Name | Description |
|---|---|
| GainMapMetadata(double, double, IEnumerable<GainMapChannel>, bool) | Initializes a new instance of the GainMapMetadata class. |
GainMapMetadata(double, double, IEnumerable<GainMapChannel>, bool)
GainMapMetadata.csInitializes a new instance of the GainMapMetadata class.
public GainMapMetadata(double baseHdrHeadroom, double alternateHdrHeadroom, IEnumerable<GainMapChannel> channels, bool useBaseColorSpace = true)Parameters
baseHdrHeadroomdouble- The headroom of the base rendition, in stops; 0 for a standard dynamic range base image.
alternateHdrHeadroomdouble- The headroom of the alternate rendition, in stops.
channelsIEnumerable<GainMapChannel>- The parameters of the channels: one, for the three color channels, or three (red, green and blue).
useBaseColorSpacebooltruewhen the gain applies to the linear colors of the base image,falsewhen it applies to their conversion to the color space of the alternate rendition.
Exceptions
ArgumentNullExceptionchannelsor one of its values isnull.ArgumentExceptionchannelsdoes not have one or three values.ArgumentOutOfRangeException- A headroom is negative or not finite.
Properties
| Name | Description |
|---|---|
| AlternateHdrHeadroom | Gets the headroom of the alternate rendition, in stops. |
| BaseHdrHeadroom | Gets the headroom of the base rendition, in stops; 0 for a standard dynamic range base image. |
| Channels | Gets the parameters of the channels: one, for the three color channels, or three (red, green and blue). |
| UseBaseColorSpace | Gets a value indicating whether the gain applies to the linear colors of the base image (true), or to their conversion to the color space of the alternate rendition. |
AlternateHdrHeadroom
GainMapMetadata.csBaseHdrHeadroom
GainMapMetadata.csChannels
GainMapMetadata.csGets the parameters of the channels: one, for the three color channels, or three (red, green and blue).
public IReadOnlyList<GainMapChannel> Channels { get; }Property value
UseBaseColorSpace
GainMapMetadata.csMethods
| Name | Description |
|---|---|
| Apply(Image, Image, double, CancellationToken) | Applies a gain map to a base image: computes the rendition of the image for a display of a given headroom, in linear light, with the values above 1 that high dynamic range colors have. |
| Equals(GainMapMetadata?) | Indicates whether the current object is equal to another object of the same type. |
| Equals(object?) | Determines whether the specified object is equal to the current object. |
| GetHashCode() | Serves as the default hash function. |
| GetWeight(double) | Gets how much of the gain a display of a given headroom applies: 0 shows the base rendition, 1 the alternate rendition. |
| ToString() | Returns a string that represents the current object. |
Apply(Image, Image, double, CancellationToken)
GainMapMetadata.csApplies a gain map to a base image: computes the rendition of the image for a display of a given headroom, in linear light, with the values above 1 that high dynamic range colors have.
public Image<RgbaFloat> Apply(Image baseImage, Image gainMap, double hdrHeadroom, CancellationToken cancellationToken = default)Parameters
baseImageImage- The base image: its first frame is used.
gainMapImage- The gain map image: its first frame is used. A grayscale image applies its gain to the three channels; it may be smaller than the base image, which it then covers with bilinear interpolation.
hdrHeadroomdouble- The headroom of the display, in stops (
GainMapMetadata.GetWeight). cancellationTokenCancellationToken- The token checked between rows.
Returns
Image<RgbaFloat> A new image of the size of the base image whose colors are linear light, 1 being the white of standard dynamic range, in the primaries of the base image. Nothing is clipped: colors may exceed 1, and an offset may make a channel slightly negative. Alpha is the one of the base image. The metadata is labeled accordingly: linear sRGB primaries are ColorTransferFunction.Linear, the other primaries a CICP description with the linear transfer characteristics (8); the orientation and the EXIF and XMP metadata of the base image are kept.
Exceptions
ArgumentNullExceptionbaseImageorgainMapisnull.ArgumentOutOfRangeExceptionhdrHeadroomis negative or not finite.UnsupportedImageFeatureException- The color description of the base image is not one of those above, or
GainMapMetadata.UseBaseColorSpaceisfalse: the color space of the alternate rendition is not known here (AuxiliaryImageCollection.DecodeHdrreads it from the file). ObjectDisposedException- An image is disposed.
ImageResourceLimitException- The result exceeds the allocation limit of the configuration of the base image.
OperationCanceledExceptioncancellationTokenis canceled.
Remarks
The base image is converted to linear light with its color description: an RGB ICC profile whose primaries are those of sRGB, Display P3, DCI-P3 or BT.2020, a CICP description whose transfer characteristics are not high dynamic range ones, the linear transfer function, or else sRGB. The samples of both images are read with 16-bit precision, and the samples of the gain map are its coded values, whatever its color description.
Equals overloads
Equals(GainMapMetadata?)
GainMapMetadata.csIndicates whether the current object is equal to another object of the same type.
public bool Equals(GainMapMetadata? other)Parameters
otherGainMapMetadata?- An object to compare with this object.
Returns
bool true if the current object is equal to the other parameter; otherwise, false.
Equals(object?)
GainMapMetadata.csGetHashCode()
GainMapMetadata.csGetWeight(double)
GainMapMetadata.csGets how much of the gain a display of a given headroom applies: 0 shows the base rendition, 1 the alternate rendition.
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 for a standard dynamic range display).
Returns
double (hdrHeadroom - BaseHdrHeadroom) / (AlternateHdrHeadroom - BaseHdrHeadroom) clamped to [0, 1]; when the two headrooms are equal, 1 from that headroom on and 0 below it.
Exceptions
ArgumentOutOfRangeExceptionhdrHeadroomis negative or not finite.