Radiance HDR

edit

Radiance HDR files (.hdr, formerly .pic) store high dynamic range pictures with four bytes per pixel: an 8-bit mantissa for each color and an exponent the three colors share. Lighting simulations write them, and most HDRI environment maps are distributed in this format. Files load as RgbaFloat pixels in linear light, and RadianceEncoder writes them.

What is read and written

ReadingWriting
PixelsRGB samples (RGBE); XYZE files are identified but not loadedRGB samples (RGBE)
ScanlinesFlat, "old" and "new" run-length encoded, mixed in one fileNew run-length encoding (default) or flat
OrientationThe eight orientations of the resolution string; the image is always uprightThe standard orientation (rows from the top)
HeaderExposure, color correction, primaries, pixel aspect ratio, gamma, view and software, reportedThe primaries

A pixel of mantissas m and exponent e is the color (m + 0.5) × 2^(e - 136): the middle of the interval the writer truncated the color into, as Radiance reads it. A float holds these values exactly. FFmpeg and Apple ImageIO read the bottom of the interval, m × 2^(e - 136), so their values are half a unit lower.

Load and save a Radiance HDR file

public static (Image<Rgba32> Preview, double Exposure) ConvertRadiance(string hdrPath, string flatPath)
{
    // Radiance HDR files load as RgbaFloat, in linear light: the pixels are the values the file stores
    using var hdr = Image.Load<RgbaFloat>(hdrPath);

    // The header is reported, never applied: divide by the exposure to get the radiances before it was adjusted
    var exposure = hdr.Metadata.RadianceHeader?.Exposure ?? 1;

    // Run-length encoded scanlines by default; flat ones on request. Each color is stored with 8 bits of mantissa
    hdr.Save(flatPath, new RadianceEncoder { Compression = RadianceCompression.None });

    // Integer pixels cannot hold the highlights: a typed load compresses them with a tone mapping
    var preview = Image.Load<Rgba32>(hdrPath, new ImageDecodeOptions
    {
        Conversion = new PixelConversionOptions { ToneMapping = new HdrToneMappingOptions() },
    });
    return (preview, exposure);
}

The header is reported in ImageMetadata.RadianceHeader, and never applied: the pixels are the values the file stores. Exposure is the product of the EXPOSURE lines, the multiplier applied to the pixels since the picture was rendered; divide by it to get the original radiances. A value that cannot be read, such as the PIXASPECT=inf FFmpeg writes, is skipped.

Integer pixels cannot hold values above 1: loading a Radiance HDR file as Rgba32 rejects them, unless the conversion clips them or compresses the highlights with a tone mapping, as in the example. See Pixel formats.

Options

OptionWhat it doesDefault
CompressionRunLength or None (flat scanlines, four bytes per pixel)RunLength
BackgroundColorThe opaque color pixels that are not opaque are composited over, in linear lightnull: such pixels are rejected
MetadataHandlingWhat to do with metadata Radiance HDR cannot storeStrict

Each color is truncated to 8 bits of mantissa, relative to the largest color of its pixel: RGBE has about 1% of precision, over a range from 1E-38 to 1E38. Integer pixels are written as their value divided by the largest sample (v / max), and gray pixel formats as three equal colors. A scanline shorter than 8 pixels or longer than 32,767 pixels is always flat.

Pitfalls

  • Radiance HDR samples are linear light. An image labeled sRGB, which is the label of integer pixel formats, or with an ICC profile follows MetadataHandling, which rejects it by default. A CICP description with linear transfer characteristics and BT.709, BT.2020, DCI-P3 or Display P3 primaries is written as PRIMARIES.
  • Negative colors, infinities and samples that are not numbers cannot be stored, and are rejected before anything is written: clamp the colors first. A resampling filter such as Lanczos can make small negative colors.
  • XYZE files (CIE XYZ samples) are rejected by a load with an UnsupportedImageFeatureException: converting them to RGB is a color conversion, which the library never makes implicitly. Convert them with ra_xyze -r first.
  • The standard primaries of Radiance are read as those of BT.709 (sRGB), as other readers do: they differ by 0.01 in the x of green and by their white point. Other primaries label the image with a CICP description or an ICC profile.
  • The encoder writes no exposure: RadianceHeader is ignored when saving, so the pixels written are the values of the image.
  • A truncated file is rejected: there is no lenient decoding for Radiance HDR.