Convert HDR files to Gain Map HDR

A macOS tool for converting HDR files to Adaptive (Gain Map) HDR / ISO HDR.

Include:

1. toGainMapHDR, which convert png, tiff etc. HDR file to Adaptive HDR (gain map heic file) / ISO HDR (PQ or HLG curve image). The program will read a image as both SDR and HDR image, then calculate difference between two images as gain map.
2. heic_hdr.py, a ChatGPT generated python script to convert all TIFF file to HEIC.
3. GainMapKernel.ci.metallib, library needed to output Apple gain map.

GUI program created by @vincenttsang HDR-Gain-Map-Convert

Lightroom Plugin created by @fengshenx LR_GainMap_HDR_Export_Plugin

Usage

toGainMapHDR

Convert any HDR Files to Gain_Map_HDR.heic by toGainMapHDR:

./toGainMapHDR $file_dir $folder_dir $options

Supported input format:

• AVIF、JXL、HEIF (in PQ/HLG/gain map)
• TIFF (in PQ/HLG/Linear32)
• PNG (in PQ/HLG)
• ISO gain map HDR
• EXR、HDR

Supported output format:

• ISO Gain Map HDR in HEIC/JPG (default)
• Apple Gain Map HDR in HEIC/JPG
• PQ/HLG HDR in HEIC
• Tone mapped SDR in HEIC/JPG

Note:

Some formats have width/height limitation, only support the image file which could be openned by preview.app

CIImage cannot handle the brightness of Apple gain map HDR correctly, not recommended to input in this format.

System Require

Require macOS 15.0+. Fully tested on Apple Silicon.

There are some issues with Intel Mac, not all features available.

PLEASE UPGRADE your system to LATEST version for more compatibility.

Options:

default: output HDR-heic with ISO gain map in RGB

-q <value>: image quality (default: 0.85)

-r <value>: SDR tone mapping ratio (≥1.0, default: 3.0)

ratio = 1.0: keep full highlight details
ratio >> 10: lose all highlight details

-b <file_path>: specify the base image

-t <text>: add extra text after the output file name

-c <color space>: specify output color space (srgb, p3, rec2020)

-d <color depth>: specify output color depth (default: 8)

-g: output Apple gain map HDR, which generated by CIFilter **

-H <value>: scaling Apple gain map, between 1.0 (full size, default) and 2.0 (half size)

-m: export ISO gain map HDR in monochrome

-s: export tone mapped SDR image without HDR gain map

-p: export 10-bit PQ HDR heic image

-h: export HLG HDR heic image (default in 10-bit)

-j: export image in JPEG format (work with SDR or gain map HDR exporting)

-help: print help information

File Size and Quality

Input image: Half Dome sunset, 16-bit TIFF, 4000x6000 px, 144 MB.

| options | JPG | HEIC | PSNR/dB | PSNR/dB | | ---------------------------------- | ------- | ---------- | ------- | ------- | | -p (PQ HDR 10 bit) | - | 5.6 MB | | 43.93 | | -p -q 100 | - | 21.5 MB | | 50.42 | | -h -d 8 (HLG 8 bit) | - | 3.3 MB | | ≈40.14 | | -h (HLG 10 bit) | - | 7.4 MB | | ≈44.82 | | -s (SDR image) | 7.5 MB | 3.9 MB | 27.94 | 27.83 | | -g (Apple HDR 1) | 11.1 MB | 6.5 MB | 40.83 | ≈39.47 | | -g -H 1.5 (Apple HDR 1 with scale) | 9.2 MB | 5.2 MB | 40.62 | ≈39.25 | | -g -H 2.0 (Apple HDR 1 with scale) | 8.4 MB | 4.6 MB | 40.66 | ≈39.27 | | -g -d 10 (Apple HDR 1 in 10 bit) | - | 11.0 MB | | ≈42.38 | | -g -H 1.5 -d 10 | - | 9.7 MB | | ≈42.08 | | default (ISO Gain Map HDR) | 11.5 MB | 7.4 MB | 43.03 | 41.43 | | -d 10 (ISO Gain Map HDR in 10 bit) | - | 11.9 MB | | 46.08 | | -q 100 (ISO Gain Map best quality) | 27.5 MB | 26.4 MB | 48.75 | 48.49 |

Compare with other HDR formats exported by LR.

| Format | Size | PSNR/dB | | ------------------------------- | ---------- | ------- | | UltraHDR (quality 60) | 5.1 MB | 36.96 | | UltraHDR (quality 85) | 19.7 MB | 45.58 | | AVIF (quality 70 with gain map) | 4.7 MB | 38.65 | | AVIF (quality 85 with gain map) | 7.3 MB | 41.37 | | AVIF (quality 85, PQ HDR) | 1.9 MB | 37.76 | | AVIF (quality 95, PQ HDR) | 2.7 MB | 39.63 | | AVIF (quality 100, PQ HDR) | 7.7 MB | 46.31 | | JXL (quality 85, PQ HDR) | 4.9 MB | 41.30 |

Sample images for options

Quality for 8 bit heic SDR export: (-s -q 0.2~1.0)

| -s -q | | | | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | quality0.2 34.22 dB | quality0.4 37.78 dB | quality0.6 41.34 dB | | | | | | quality0.8 45.33 dB | quality1.0 50.31 dB | | | | | |

SDR mapping ratio for jpg SDR export: (-s -j -r 1.0~50.0)

| ratio1.0 | ratio2.0 | ratio3.0 | | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | | | | | ratio6.0 | ratio20.0 | ratio50.0 | | | | |

HDR export: (-j -r 1.0~50.0). Edge.app on macOS not support RGB HDR, view HDR effect on Safari.app.

| ratio1.0 | ratio2.0 | ratio3.0 | | -------- | --------- | -------- | | | | | | ratio6.0 | ratio20.0 | ratio50.0| | | | |

Apple Gain Map scaling ratio: (-j -g -H1.0~2.0).

| H1.0 725K | H1.2 644K | H1.4 606K | | -------- | --------- | -------- | | | | | | H1.6 574K | H1.8 536K | H2.0 556K | | | | |

Sample command：

./toGainMapHDR ~/Downloads/abc.png ~/Documents/ -q 0.95 -d 10 -c rec2020

./toGainMapHDR ~/Downloads/abc.tiff ~/Documents/ -q 0.80 -j

convert gain map abc.avif to gain map heic file and keep base image:

./toGainMapHDR ~/Downloads/abc.avif ~/Documents/ -b ./Downloads/abc.avif

convert abc.tiff to Apple HDR by CIFilter and scale gain map to 0.67x:

./toGainMapHDR ~/Downloads/abc.tiff ~/Documents/ -g -H 1.5

convert abc.tiff to HLG HDR file:

./toGainMapHDR ~/Downloads/abc.tiff ~/Documents/ -h

convert RGB gain map (adaptive HDR) file to monochrome gain map (Apple HDR) heic file:

./toGainMapHDR ~/Downloads/abc.heic ~/Downloads/ -g -t -mono

Note:

1. Using a specific base photo will result larger file size
2. Scaling the gain map can reduce file size, with slightly lose highlight detail
3. ** Monochrome gain map compatible with Google Photos (Android version), Instagram, Edge Browser etc. Recommended to use for sharing.
4. When exporting 8-bit heic image, color discontinuity may occur in low-texture areas, like clouds, lakes.

heic_hdr.py

Batch convert all tiff files in a folder by heic_hdr.py:

1. Clone \bin to a folder (or download them from release):

`