RadianceEncoder Class

Immutable settings for Radiance HDR encoding (RGBE: linear-light, high dynamic range still images).

public sealed class RadianceEncoder : ImageEncoder

Remarks

The output is an RGBE picture (#?RADIANCE, FORMAT=32-bit_rle_rgbe) in the standard orientation (-Y height +X width): the scanlines are the rows, from the top. Each pixel stores an 8-bit mantissa per color and an exponent shared by the three colors (Greg Ward, "Real Pixels", Graphics Gems II): the largest color keeps 8 significant bits, and the others keep what the shared exponent leaves them. This rounding is the format itself, like the quantization of a lossy format: the decoder reads a mantissa m as the middle of its interval, (m + 0.5) × 2^(e - 136), so a color comes back within half a unit of the last place of the largest color of its pixel. A pixel whose largest color is at most 1E-32 is written black.

Floating-point pixels may have any finite value from 0 to 2^127 (excluded). A negative color, an infinity or a sample that is not a number cannot be stored, and is rejected with UnsupportedImageFeatureException before anything is written (clamp the colors of the image first). Integer pixels are stored as the floating-point values of the conversion of Image.CloneAs to RgbaFloat (v / max); gray pixel formats are written with three equal colors. ImageEncoder.FloatingPointConversion does not apply.

Radiance HDR has no alpha channel: a pixel that is not fully opaque (alpha other than 1) requires RadianceEncoder.BackgroundColor, over which it is composited, and is rejected otherwise.

The samples are linear light: the image must be labeled ColorTransferFunction.Linear (the default of floating-point images), or have a CICP description with the linear transfer characteristics (8) and the primaries of BT.709, BT.2020, DCI-P3 or Display P3. The header records the primaries (PRIMARIES, those of BT.709 for an image labeled linear). Any other label (sRGB-encoded samples, an ICC profile), EXIF, XMP, an orientation other than ExifOrientation.TopLeft, a resolution or text entries follow ImageEncoder.MetadataHandling (rejected by default). ImageMetadata.RadianceHeader is ignored.

Radiance HDR stores exactly one frame: animated images and images with a poster frame are rejected with an UnsupportedImageFeatureException; use ImageFrame.Save to save one frame explicitly.

Inheritance
ImageEncoder RadianceEncoder

Constructors

NameDescription
RadianceEncoder()

RadianceEncoder()

RadianceEncoder.cs
public RadianceEncoder()

No documentation is available.

Properties

NameDescription
BackgroundColorGets the opaque background color non-opaque pixels are composited over, as linear-light fractions of one (v / 65535), or null to reject non-opaque pixels. Fully opaque images never need it.
CompressionGets the encoding of the scanlines. Defaults to RadianceCompression.RunLength.
FormatGets the format produced by this encoder.

BackgroundColor

RadianceEncoder.cs

Gets the opaque background color non-opaque pixels are composited over, as linear-light fractions of one (v / 65535), or null to reject non-opaque pixels. Fully opaque images never need it.

public Rgba64? BackgroundColor { get; init; }

Property value

Rgba64?

Exceptions

ArgumentException
The color is not fully opaque.

Remarks

A pixel of alpha a (clamped to [0, 1]) becomes a × color + (1 - a) × background, computed in double precision; its color is then checked like any other.

Gets the encoding of the scanlines. Defaults to RadianceCompression.RunLength.

public RadianceCompression Compression { get; init; }

Property value

RadianceCompression

Exceptions

ArgumentOutOfRangeException
The value is not a defined RadianceCompression.

Gets the format produced by this encoder.

public override ImageFormat Format { get; }

Property value

ImageFormat