Class GainMap

Namespace

Egami.Colors

Assembly

Egami.dll

An HDR gain map: a small image that, with GainMapInfo, turns an SDR base image into its HDR rendition (or the reverse). Read from Ultra HDR, ISO 21496-1 and Apple JPEG files into GainMap; written back by the JPEG writer. Immutable, so rasters can share it.

public sealed class GainMap

Inheritance

object

GainMap

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// As stored: the SDR base image, with the gain map in the metadata.
using Raster sdr = Raster.Load("ultrahdr.jpg");
GainMap? map = sdr.Metadata.GainMap;                                     // null for a plain JPEG

// The HDR rendition for a display 4x as bright as SDR white: linear half floats, 1.0 = SDR white.
using Raster<RgbaF16> hdr = Raster.Load<RgbaF16>("ultrahdr.jpg", options: new ReaderOptions { Hdr = new HdrDecode { Headroom = 4 } });

// The same from a raster in hand, at the map's full capacity.
using Raster<RgbaF16> full = map!.Apply(sdr);

Constructors

GainMap(GainMapInfo, Raster)

Initializes a gain map from its metadata and image, whose pixels are copied.

public GainMap(GainMapInfo info, Raster image)

Parameters

info GainMapInfo

How the map applies.

image Raster

The map: gray for one channel, anything else as three (red, green, blue), 8 bits a sample.

Exceptions

ArgumentNullException

An argument is null.

Properties

Channels

Gets 1 for a gray map that boosts red, green and blue alike, or 3 for one boost each.

public int Channels { get; }

Property Value

int

Height

Gets the map's height.

public int Height { get; }

Property Value

int

Info

Gets how the map applies.

public GainMapInfo Info { get; }

Property Value

GainMapInfo

Width

Gets the map's width, often a fraction of the base image's.

public int Width { get; }

Property Value

int

Methods

Apply(Raster, double?)

Returns the rendition of baseImage for a display with headroom (its peak over SDR white, linear; null for the map's full HDR capacity): linear RgbaF16 with 1.0 as SDR white (203 cd/m²), in the base image's primaries, with MaxContentLightLevel set from the map's largest boost. The map is upsampled bilinearly row by row, so no full-size copy of it is made.

public Raster<RgbaF16> Apply(Raster baseImage, double? headroom = null)

Parameters

baseImage Raster

The base image, in its own encoding (usually sRGB), the size the map was made for (it may differ by scale).

headroom double?

The display headroom, 1 or more, or null for full HDR.

Returns

Raster<RgbaF16>

The rendition. The caller disposes it.

Examples

// As stored: the SDR base image, with the gain map in the metadata.
using Raster sdr = Raster.Load("ultrahdr.jpg");
GainMap? map = sdr.Metadata.GainMap;                                     // null for a plain JPEG

// The HDR rendition for a display 4x as bright as SDR white: linear half floats, 1.0 = SDR white.
using Raster<RgbaF16> hdr = Raster.Load<RgbaF16>("ultrahdr.jpg", options: new ReaderOptions { Hdr = new HdrDecode { Headroom = 4 } });

// The same from a raster in hand, at the map's full capacity.
using Raster<RgbaF16> full = map!.Apply(sdr);

Exceptions

ArgumentNullException

baseImage is null.

ArgumentOutOfRangeException

headroom is below 1.

Create(Raster, Raster?, GainMapOptions?)

Computes the gain map that turns sdr into hdr: for each map pixel, the log2 ratio of the HDR light to the SDR light, averaged over the pixels it covers, stored in 8 bits between the smallest and largest gain.

public static GainMap Create(Raster hdr, Raster? sdr = null, GainMapOptions? options = null)

Parameters

hdr Raster

The HDR rendition: linear light with 1.0 as SDR white (as Radiance, OpenEXR and HDR decodes give), or PQ or HLG with its color profile.

sdr Raster

The SDR rendition to show on SDR displays, the same size; or null to make one with Bt2390, as GainMap does.

options GainMapOptions

How to make the map, or null for the defaults.

Returns

GainMap

The gain map, for GainMap of the SDR rendition.

Examples

// An HDR raster as Ultra HDR: the SDR base, tone mapped with BT.2390, and a gain map that brings the HDR raster back.
using Raster<RgbaF32> hdr = Raster.Load<RgbaF32>("render.exr");
hdr.Save("render.jpg", new JpegWriterOptions { Quality = 90, GainMap = new GainMapOptions() });

// Or choose the SDR rendition: the map goes in its metadata, and saving as JPEG writes both.
using Raster<Rgb8> sdr = hdr.Derive(ops => ops.ToneMap(ToneMapping.Reinhard)).As<Rgb8>();
sdr.Metadata.GainMap = GainMap.Create(hdr, sdr, new GainMapOptions { Scale = 4 });
sdr.Save("graded.jpg", new JpegWriterOptions { Quality = 90 });

Exceptions

ArgumentNullException

hdr is null.

ArgumentException

sdr is not the size of hdr.

ToRaster(EgamiContext?)

Returns the map as a new raster: Gray8 for one channel, Rgb8 for three. The caller disposes it.

public Raster ToRaster(EgamiContext? context = null)

Parameters

context EgamiContext

The context for the raster, or null for Default.

Returns

Raster

The map's image.

WithInfo(GainMapInfo)

Returns the same map with other metadata.

public GainMap WithInfo(GainMapInfo info)

Parameters

info GainMapInfo

The new metadata.

Returns

GainMap

The map.