HDR export: 10/12-bit AVIF & JPEG XL (BT.2020 PQ/HLG)

[KaiserRuben]

Motivation

Modern full-frame sensors capture far more dynamic range than 8-bit sRGB can show. After editing a Sony A7C II raw, the highlight detail is in the file — but the export step throws it away, clamping everything to 8-bit sRGB. Meanwhile HDR stills now render correctly across the ecosystem: Google Photos, iOS/Android, Chrome/Safari, and the major social platforms all decode HDR AVIF.

RapidRAW already grades in a wide-gamut, scene-linear pipeline that carries real headroom above diffuse white. This PR adds an export path that keeps that headroom instead of discarding it: 10/12-bit AVIF and JPEG XL, tagged BT.2020 + PQ (or HLG).

Summary

• Adds a true HDR export path; the existing 8-bit SDR export is unchanged byte-for-byte (HDR runs on a separate, lazily-built GPU pipeline).
• UI exposes the full color configuration behind plain-language presets, with an optional Advanced section for everything underneath.
• Fixes a real bug along the way: large 4:2:2 AVIF exports previously produced a non-conformant AV1 bitstream that strict decoders rejected ("Decoding of color planes failed"). 4:2:0/4:4:4 now round-trip at full resolution; 4:2:2 is bounded to what AV1 encodes as a single tile, with a loud error past the limit — never a silent downgrade.

UI

The SDR default is untouched — same controls, same output:

A "Color profile" dropdown picks the intent in one step; each preset configures everything below it:

"Custom" reveals the Advanced section — bit depth, transfer, gamut, encoding/matrix, chroma, range, reference white — each with non-expert help text:

Scope & compatibility

• Size: 24 files, +3,738 / −197 (2 new files, 22 modified). The bulk is hdr.rs + tests; the SDR-affecting surface is small.
• SDR unchanged: the 8-bit path is byte-identical (proven by a GPU end-to-end test, below).
• Presets load unchanged: new fields are optional and default to SDR (bitDepth ?? 8, etc.), so existing saved presets behave exactly as before.
• Default export is still JPEG/SDR. HDR is opt-in.

What's included

• HDR color science (src-tauri/src/hdr.rs): pinned SMPTE ST.2084 (PQ) / ITU-R BT.2100 (HLG) transfer functions with the ISO 22028-5 203-nit reference-white anchor, BT.2087 Rec.709→Rec.2020 and Rec.709→Display-P3 matrices, CICP/nclx tag mapping, full/limited-range quantization, and the AVIF + JXL encoders. One source of truth, shared by the encoders and the test harness.
• AVIF via pure-Rust rav1e + avif-serialize (no runtime system deps).
• JPEG XL via jpegxl-rs + system libjxl, behind an optional hdr_jxl cargo feature (default builds need no libjxl).
• GPU output path promoted to rgba16float on a pipeline that shares the SDR shader; an IS_HDR pipeline-overridable constant switches on headroom-preserving behavior so values above diffuse white survive the look stage instead of clipping to [0,1].
• Configurable export UI (ExportPanel.tsx): the presets dropdown (SDR / HDR10 / HLG / Max quality / Archival / Custom) plus the Advanced section, all with non-expert help text. Strings localized into 10 languages.

How it works (data flow)

scene-linear RGBA32F  (diffuse white = 1.0, highlights > 1.0)
      │  GPU pipeline — IS_HDR override on, rgba16float target
      ▼  look stage keeps values > 1.0 (no [0,1] clamp, no dither)
f16 readback → invert extended-sRGB → linear ImageRgba32F
      │  encoder (hdr.rs):
      │    Rec.709 → Rec.2020 matrix
      │    L = linear · 203 / 10000        (ISO 22028-5 reference white)
      │    PQ (ST.2084) or HLG (BT.2100) OETF
      ▼  quantize 10/12-bit
AVIF / JPEG XL  + CICP nclx tags

The HDR shader is the same WGSL as the SDR path, gated by the IS_HDR override constant — so the headroom-preserving differences (extended-sRGB encode, dropped store clamp, disabled dither, no tone-curve snapping at the top) are compiler-checked rather than patched in by string replacement. The one thing WGSL can't express as an override — the storage texture format — is the single remaining textual swap (rgba8unorm→rgba16float).

4:2:2 handling (the conformance fix)

rav1e only encodes AV1 4:2:2 ("Professional" profile) conformantly as a single AV1 tile. AV1's per-tile caps (4096 px wide, 4096·2304 = 9,437,184 px area) force a multi-tile layout on larger frames, which its 4:2:2 path mis-codes. 4:2:0 and 4:4:4 tile correctly at any size. So:

• The encoder errors loudly on an over-size 4:2:2 frame — it does not silently change the user's chosen chroma.
• The limit is one Rust source of truth (hdr::AVIF_422_MAX_WIDTH / AVIF_422_MAX_PIXELS), exposed to the frontend via an avif_422_limits command so the UI derives its cap rather than hardcoding it.
• Selecting 4:2:2 in the panel auto-applies a resolution cap (long edge ≤ √area = 3072 px), visible and overridable in the Resize controls, with a warning if removed.

Verification

src-tauri/tests/hdr_export.rs decodes output with independent decoders (libavif avifdec, jxl-oxide) and parses the raw nclx/av1C boxes from the file bytes. Expected values are pinned ST.2084 ground-truth literals (not derived from the encoder under test):

Output	Tags	Diffuse white	2× / 4× headroom
AVIF 10-bit	primaries 9 / transfer 16 / full-range	code 594	669 / 746
AVIF 12-bit	(same tags)	code 2378	2679 / 2986
JPEG XL (PQ)	PQ Rec.2020	0.58069	—
Large frame 6177×4118	4:2:0 + 4:4:4 round-trip; 4:2:2 round-trips at the single-tile bound and errors past it	—	—
GPU end-to-end (+2 stops white)	SDR clamps to byte 255; HDR recovers linear ~4.0	—	—

The headroom codes are strictly increasing, and the GPU end-to-end case proves both that headroom survives the full look stage and that SDR is byte-identical with the override.

cd src-tauri
cargo test --test hdr_export                                   # AVIF (needs avifdec: brew install libavif)
PKG_CONFIG_PATH="$(brew --prefix jpeg-xl)/lib/pkgconfig:$PKG_CONFIG_PATH" cargo test --features hdr_jxl   # + JXL

Build (cross-platform)

The AVIF path is pure Rust with no platform-specific code; nasm is the only added build-time requirement (rav1e's assembly), available via apt / choco / brew on all three platforms. JPEG XL is opt-in and needs system libjxl.

npm install && npm run tauri build                 # AVIF HDR (needs nasm)
brew install jpeg-xl                               # + JPEG XL HDR:
PKG_CONFIG_PATH="$(brew --prefix jpeg-xl)/lib/pkgconfig:$PKG_CONFIG_PATH" npm run tauri build -- --features hdr_jxl

Built and run locally on macOS arm64. There is no platform-specific code in the HDR path, so Windows/Linux builds should be unaffected — but I have not built them; worth a CI pass.

Known limitations

1. Above-diffuse-white look through user tone curves is a deliberate pass-through, correct for default/identity curves (verified: linear 4.0 survives) but not perceptually validated for arbitrary user curves — see sign-off below.
2. 4:2:2 AVIF is single-tile only (resolution-capped, as above); 4:2:0 / 4:4:4 have no such limit. 4:2:2 also requires AV1 Professional profile, which some viewers decode poorly — 4:2:0 / 4:4:4 are recommended.
3. HLG is tag- and monotonicity-verified only (relative/scene-referred — no single absolute-nit anchor); HLG_PEAK_RATIO = 12 is a reasonable default, not tuned.
4. Watermarking an HDR export clamps the watermarked pixels to SDR (the overlay runs in 8-bit). HDR export without a watermark is unaffected.
5. No EXIF in AVIF/JXL — the metadata writer handles JPEG/PNG/TIFF only (pre-existing); HDR files carry CICP tags but not EXIF.

Dependencies & licensing

• AVIF (always on, pure Rust): rav1e + avif-serialize. Build-time nasm.
• JPEG XL (optional hdr_jxl): jpegxl-rs + system libjxl (GPL-3.0 bindings — compatible with the project's AGPL-3.0). Default builds do not require libjxl.

License unchanged (AGPL-3.0).

[haico1992]

Can you resolve the conflict and merge it please?

[KaiserRuben]

@haico1992 merge possible now, waiting for maintainer to review.

[CyberTimon]

I cannot merge this pull request in its current form. At over 3,000 lines, it introduces too many high-risk changes at once, including modifications to core logic, altered build requirements, and extensive AI-generated comments.

Additionally, regarding the new tests: since our codebase does not currently have a testing framework, we need to either set up a general test suite first or remove these specific tests for now.

To move forward, please:

• Break the changes down into smaller, focused pull requests.
• Align the code and comments with the RapidRAW style guidelines.
• Ensure each part is thoroughly tested on all platforms.

Let me know if you would like to discuss how to structure these smaller PRs.

[KaiserRuben]

@haico1992 You can clone my Fork and build it yourself, as I did. That way, you can utilize the improvements without waiting for the merge. However, you will loose the ability to automatically update.

@CyberTimon I do understand the concern. I will investigate the options to move forward as time allows. Thanks for your feedback.