Add hdr_mode option: raw code-value decode for HDR sources

[ksindi]

HDR and wide-gamut sources, such as PQ, HLG, or BT.2020 content, are currently always passed through a tone-mapping pipeline before decoding: linearize with zscale, apply Hable tone mapping, then convert to BT.709. As a result, float32 output from HDR sources is an SDR preview intended for display, not a faithful representation of the original signal.

That is a problem for use cases that need the original HDR code values, such as training on PQ masters or performing colorimetric measurements. Until now, there was no way to disable tone mapping. On a PQ BT.2020 mezzanine file, for example, the tone-mapped output showed 2.34 times more chroma and higher luminance than the true source values.

The new hdr_mode="raw" option skips the HDR tone-mapping stage. YUV-to-RGB conversion still respects the stream’s tagged matrix and range, but the transfer function is left unchanged. The default, "tonemap", remains byte-for-byte identical to the current behavior.

[upwind-code-us]

Upwind IaC Scan - 🔍 Scan in progress…

Upwind is scanning this PR. Results will appear here when the scan completes.

[upwind-code-us]

Upwind Code Scan - 🔍 Scan in progress…

Upwind is scanning this PR. Results will appear here when the scan completes.

[ksindi]

Runtime verification with the built wheel, on the PQ BT.2020 12-bit mezzanine (frame-0 float32 RGB vs an ffmpeg format=gbrpf32le tag-honoring reference of the same file):

mode	mean abs diff vs PQ code values	chroma ratio	frame max
default (tonemap)	0.07059	2.362×	0.833
hdr_mode="raw"	0.00000	1.000×	0.598

raw reproduces the source code values exactly; the default is unchanged. Invalid values error with the accepted set (hdr_mode must be "tonemap" or "raw").

[RikHeijdens]

Left a few nits

[ksindi]

Note on the last two commits: we briefly considered making raw the default, then reverted to keep tonemap as the default after weighing usage: most Runway corpora are SDR with occasional stray HDR files, and for those pipelines tone-mapping strays into the display-referred domain is the correct normalization — a raw default would silently feed washed-out PQ frames to headless SDR pipelines. Signal-domain consumers (HDR training/measurement) are few and deliberate, and opt in explicitly with hdr_mode="raw". Net: the PR remains purely additive with byte-identical default behavior, as approved.