HDR Gain Maps

hdr

The hdr parameter preserves high dynamic range through a render. An HDR photo delivers its extra brightness through a gain map: a second, smaller image appended to an ordinary 8-bit file that tells an HDR display how far to brighten each pixel. Without hdr, any transformation drops that map and the output is the plain SDR image.

hdr accepts the following values:

Value	Description
`true`	Carries an existing gain map through the render, or generates one from a PQ or HLG source.
`false` (default)	Strips the gain map and its metadata, producing a plain SDR file.

The parameter is off by default, so a URL with no hdr behaves exactly as it always has.

A gain-mapped file is safe to serve to everyone: a client that does not understand the map shows the SDR base image and ignores it, so one URL works for every visitor.

Which clients render the map depends on the container:

Container	Rendered by
Ultra HDR JPEG	Chrome and Edge 116+, Brave 1.58+, Opera 102+, Safari 26+
AVIF (ISO 21496-1 `tmap`)	Chrome and Edge 129+, in full from 137; Safari 26+
HEIC (ISO 21496-1 `tmap`)	Safari 26+ and Apple platforms
JPEG XL (`jhgm`)	Nothing yet

Firefox does not render gain maps in any format. Chrome enabled AVIF gain maps by default in version 129, before ISO 21496-1 was final; files written against the final metadata render from version 137 onward.

sandbox-demo — hdr=true — the gain map is carried into the output

HDR is invisible on an SDR display

On a standard display these two renders look identical — that is the point of the format. Verifying hdr=true by eye requires an HDR display and a browser that renders gain maps.

The difference is in the file rather than on screen. The hdr=true render carries the Ultra HDR v1 hdrgm metadata, the ISO 21496-1 marker, and a second embedded image holding the map; the hdr=false render carries none of them and is a single ordinary JPEG.

Sample image from the Android platform samples, used under the Apache License 2.0.

Carrying and generating

hdr=true covers two different sources of dynamic range:

Carrying an uploaded map. If the source file already has a gain map, that map is transformed alongside the image and written into the output. Imgix reads the Ultra HDR v1 and ISO 21496-1 forms in JPEG, Apple’s iOS 14–17 HDRGainMap form, the iOS 18+ tmap and iOS 14–17 auxiliary forms in HEIC, the tmap item in AVIF, and the jhgm box in JPEG XL.
Generating a new map. If the source is PQ or HLG with no gain map, Imgix decodes it at 16 bits and computes a map against the tone-mapped SDR base.

Supported output formats

A gain map is only written into formats that can carry one:

Output	Gain map
`fm=jpg`, `fm=pjpg`	Ultra HDR v1 and ISO 21496-1
`fm=avif` (still)	ISO 21496-1 tmap item
`fm=heic` (still)	ISO 21496-1 tmap item
`fm=jxl` (still)	`jhgm` box
`fm=webp`, `fm=png`, animated AVIF	None

Requesting hdr=true on a format that cannot carry a map is not an error — the image renders normally, just without the map.

JPEG XL gain maps are written but not yet rendered

No browser or viewer currently reads the jhgm box, so a JPEG XL output displays as SDR everywhere today. The box is written now so that viewers which add support will pick it up with no change on your side.

auto=format resolves to AVIF for Chrome, and for Safari 16.4 and later. Those are browsers that render AVIF gain maps, so HDR survives most auto=format traffic.

Which operations keep the map

Transformations fall into four groups:

Behavior	Operations
Map transformed with the image	Geometry (resize, crop, rotate, warp), tone and color adjustments such as `exp`, `con`, `sat` and `hue`, and spatial filters such as `blur` and `px`
Map neutralized under painted areas	Watermarks, text, background boxes, borders, drop shadows, and padded or appended regions
Map dropped entirely	`halftone`, edge detection, `invert`, `duotone`, and `gradient-map`
Map depends on the source	Color space changes — see below

Neutralizing means the gain is set to zero wherever something was painted on top, so a white watermark over a bright sky stays at SDR brightness instead of glowing.

Color space changes

A single-channel gain map — the form Pixel phones write — survives any color space change. A three-channel map is dropped when the output color space differs from the source’s, which includes cs=, gamut=, and auto=compress applied to a non-sRGB source.

Turning HDR off explicitly

hdr=false strips the gain map and its metadata, producing a plain SDR file.

hdr forces a re-encode

hdr is not on the pass-through skip list, so adding it to a URL that would otherwise be served untouched causes the image to be re-encoded. This applies to hdr=true and hdr=false alike — the trigger is the parameter, not the value. Only set it when you need the map carried, generated, or removed.

Both hdr=true and hdr=false appear in the X-Imgix-Params response header.

Choosing HDR per display

Because a gain-mapped file is safe everywhere, a single URL is usually the right answer. Reach for a split only when you want to avoid sending the extra gain map bytes to clients that cannot use them — it costs you a second cache variant, so weigh that against the bytes saved.

Whether a display can show HDR is only known on the client, through the CSS dynamic-range: high media query. Use a <picture> element to let the browser pick:

<picture>
  <source
    media="(dynamic-range: high)"
    srcset="https://assets.imgix.net/docs/ultrahdr-cityscape.jpg?w=800&hdr=true"
  />
  <img src="https://assets.imgix.net/docs/ultrahdr-cityscape.jpg?w=800" alt="City skyline at dusk" />
</picture>

Chrome evaluates the query against the display the window is currently on, so dragging a window between an HDR and an SDR monitor re-resolves it.

Limitations

Renders routed through Imgix Video are encode-only and carry no gain map.
A source whose base image is already the HDR rendition drops its map.
An uploaded map keeps its original metadata — headroom, min and max, gamma and offsets — unchanged.
A malformed gain map is discarded and the SDR base is served.

Download Icon Sizes