|
| 1 | +#!/usr/bin/env python3 |
| 2 | +""" |
| 3 | +Regenerate the sRGB → BT.2020 (HLG/PQ) LUT reference values pinned by |
| 4 | +packages/engine/src/utils/alphaBlit.test.ts. |
| 5 | +
|
| 6 | +This is a paste-helper for the *very rare* case the LUT genuinely needs to |
| 7 | +shift — e.g. a spec update changes one of the OETF constants, or we change |
| 8 | +the SDR-white reference level in the PQ branch. The reference values in |
| 9 | +alphaBlit.test.ts are byte-exact integers, and updating ~12 hand-edited |
| 10 | +literals (or all 256 of them, if the test grows) is exactly the kind of |
| 11 | +mechanical churn we want to keep out of the diff. |
| 12 | +
|
| 13 | +Usage: |
| 14 | + # Regenerate the probe table that lives in alphaBlit.test.ts (paste over |
| 15 | + # the SRGB_TO_HDR_REFERENCE literal): |
| 16 | + python3 packages/engine/scripts/generate-lut-reference.py --probes |
| 17 | +
|
| 18 | + # Dump the full 256-entry LUTs as JSON (for ad-hoc analysis or new tests): |
| 19 | + python3 packages/engine/scripts/generate-lut-reference.py |
| 20 | +
|
| 21 | + # Override the probe set: |
| 22 | + python3 packages/engine/scripts/generate-lut-reference.py --probes \ |
| 23 | + --probe-indices 0,32,64,128,192,255 |
| 24 | +
|
| 25 | +## How to use this when the LUT changes |
| 26 | +
|
| 27 | +1. Edit buildSrgbToHdrLut() in packages/engine/src/utils/alphaBlit.ts. |
| 28 | +2. Mirror the same edit here (constants, branch logic — keep them in sync). |
| 29 | +3. Run with --probes and paste the output over SRGB_TO_HDR_REFERENCE in |
| 30 | + alphaBlit.test.ts. Update the asymmetric-R/G/B and BT.2408-invariant |
| 31 | + tests by hand if those probe values shifted. |
| 32 | +4. Re-run `bun test src/utils/alphaBlit.test.ts` to confirm the engine LUT |
| 33 | + and the test-pinned values still agree. |
| 34 | +
|
| 35 | +## Why Python (not TS)? |
| 36 | +
|
| 37 | +A standalone script avoids dragging the engine's bun/Node/build environment |
| 38 | +into a one-off codegen flow, and matches the existing fixture-generation |
| 39 | +pattern at packages/producer/tests/hdr-regression/scripts/generate-hdr-photo-pq.py. |
| 40 | +Python's math.log / math.pow are libm-backed and produce IEEE-754-equivalent |
| 41 | +results to JS's Math.log / Math.pow for these inputs — see js_round_nonneg |
| 42 | +below for the one rounding quirk we have to match by hand. |
| 43 | +
|
| 44 | +## Drift contract |
| 45 | +
|
| 46 | +This file MIRRORS buildSrgbToHdrLut() in alphaBlit.ts. If the two diverge, |
| 47 | +this script silently emits wrong values. Any change to one MUST be reflected |
| 48 | +in the other; run the script and the test suite together to catch drift. |
| 49 | +""" |
| 50 | + |
| 51 | +import argparse |
| 52 | +import json |
| 53 | +import math |
| 54 | +import sys |
| 55 | +from collections.abc import Iterable |
| 56 | + |
| 57 | +# HLG OETF constants (Rec. 2100) — keep in sync with alphaBlit.ts |
| 58 | +HLG_A = 0.17883277 |
| 59 | +HLG_B = 1 - 4 * HLG_A |
| 60 | +HLG_C = 0.5 - HLG_A * math.log(4 * HLG_A) |
| 61 | + |
| 62 | +# PQ (SMPTE 2084) OETF constants — keep in sync with alphaBlit.ts |
| 63 | +PQ_M1 = 0.1593017578125 |
| 64 | +PQ_M2 = 78.84375 |
| 65 | +PQ_C1 = 0.8359375 |
| 66 | +PQ_C2 = 18.8515625 |
| 67 | +PQ_C3 = 18.6875 |
| 68 | +PQ_MAX_NITS = 10000.0 |
| 69 | +SDR_NITS = 203.0 # BT.2408 SDR-reference white in PQ |
| 70 | + |
| 71 | + |
| 72 | +def js_round_nonneg(x: float) -> int: |
| 73 | + """ |
| 74 | + Match JS Math.round semantics for non-negative inputs. |
| 75 | +
|
| 76 | + JS Math.round rounds half toward +∞ (Math.round(0.5) === 1). Python's |
| 77 | + built-in round() uses banker's rounding (round half to even, so |
| 78 | + round(0.5) === 0 and round(2.5) === 2), which would diverge from |
| 79 | + Math.round for the ~ten or so probe values that fall on a half-integer |
| 80 | + after signal*65535. This helper is only correct for x >= 0 — that's |
| 81 | + fine because signal is always in [0, 1] here. |
| 82 | + """ |
| 83 | + return int(math.floor(x + 0.5)) |
| 84 | + |
| 85 | + |
| 86 | +def srgb_eotf(i: int) -> float: |
| 87 | + """sRGB 8-bit code value → linear light in [0, 1] relative to SDR white.""" |
| 88 | + v = i / 255 |
| 89 | + return v / 12.92 if v <= 0.04045 else math.pow((v + 0.055) / 1.055, 2.4) |
| 90 | + |
| 91 | + |
| 92 | +def hlg_oetf(linear: float) -> float: |
| 93 | + if linear <= 1 / 12: |
| 94 | + return math.sqrt(3 * linear) |
| 95 | + return HLG_A * math.log(12 * linear - HLG_B) + HLG_C |
| 96 | + |
| 97 | + |
| 98 | +def pq_oetf(linear: float) -> float: |
| 99 | + # Place SDR-reference white at 203 nits within the 10000-nit PQ peak. |
| 100 | + # This is what reserves headroom for HDR highlights above SDR-white. |
| 101 | + lp = max(0.0, (linear * SDR_NITS) / PQ_MAX_NITS) |
| 102 | + lm1 = math.pow(lp, PQ_M1) |
| 103 | + return math.pow((PQ_C1 + PQ_C2 * lm1) / (1.0 + PQ_C3 * lm1), PQ_M2) |
| 104 | + |
| 105 | + |
| 106 | +def build_lut(transfer: str) -> list[int]: |
| 107 | + out: list[int] = [] |
| 108 | + for i in range(256): |
| 109 | + linear = srgb_eotf(i) |
| 110 | + signal = hlg_oetf(linear) if transfer == "hlg" else pq_oetf(linear) |
| 111 | + out.append(min(65535, js_round_nonneg(signal * 65535))) |
| 112 | + return out |
| 113 | + |
| 114 | + |
| 115 | +# Mirror SRGB_TO_HDR_REFERENCE indices in alphaBlit.test.ts. Endpoints |
| 116 | +# (0, 1, 254, 255) catch off-by-one regressions; mid-range values (32, 64, |
| 117 | +# 96, 128, 160, 192, 224) sample the middle of both transfer curves. |
| 118 | +DEFAULT_PROBES: tuple[int, ...] = (0, 1, 10, 32, 64, 96, 128, 160, 192, 224, 254, 255) |
| 119 | + |
| 120 | + |
| 121 | +def emit_json(hlg: list[int], pq: list[int]) -> None: |
| 122 | + print(json.dumps({"size": 256, "hlg": hlg, "pq": pq}, indent=2)) |
| 123 | + |
| 124 | + |
| 125 | +def emit_probes(hlg: list[int], pq: list[int], probes: Iterable[int]) -> None: |
| 126 | + # Output is paste-ready TS for SRGB_TO_HDR_REFERENCE in alphaBlit.test.ts. |
| 127 | + print("const SRGB_TO_HDR_REFERENCE: readonly SrgbHdrProbe[] = [") |
| 128 | + for i in probes: |
| 129 | + if not 0 <= i <= 255: |
| 130 | + raise ValueError(f"probe index {i} out of range [0, 255]") |
| 131 | + print(f" {{ srgb: {i}, hlg: {hlg[i]}, pq: {pq[i]} }},") |
| 132 | + print("];") |
| 133 | + |
| 134 | + |
| 135 | +def parse_indices(s: str) -> list[int]: |
| 136 | + return [int(x.strip()) for x in s.split(",") if x.strip()] |
| 137 | + |
| 138 | + |
| 139 | +def main() -> int: |
| 140 | + parser = argparse.ArgumentParser( |
| 141 | + description="Regenerate sRGB → BT.2020 (HLG/PQ) LUT reference values.", |
| 142 | + formatter_class=argparse.RawDescriptionHelpFormatter, |
| 143 | + ) |
| 144 | + parser.add_argument( |
| 145 | + "--probes", |
| 146 | + action="store_true", |
| 147 | + help="Emit a TS snippet ready to paste over SRGB_TO_HDR_REFERENCE.", |
| 148 | + ) |
| 149 | + parser.add_argument( |
| 150 | + "--probe-indices", |
| 151 | + type=parse_indices, |
| 152 | + default=list(DEFAULT_PROBES), |
| 153 | + help="Comma-separated probe indices (default mirrors alphaBlit.test.ts).", |
| 154 | + ) |
| 155 | + args = parser.parse_args() |
| 156 | + |
| 157 | + hlg = build_lut("hlg") |
| 158 | + pq = build_lut("pq") |
| 159 | + |
| 160 | + if args.probes: |
| 161 | + emit_probes(hlg, pq, args.probe_indices) |
| 162 | + else: |
| 163 | + emit_json(hlg, pq) |
| 164 | + return 0 |
| 165 | + |
| 166 | + |
| 167 | +if __name__ == "__main__": |
| 168 | + sys.exit(main()) |
0 commit comments