From 112e58d5c504d593044d1d821aada748af1e202f Mon Sep 17 00:00:00 2001 From: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:12:36 -0500 Subject: [PATCH] Model K: the exposure rule in NumPy (which exposure value is which), with CPU tests Refs #15. clean/k/reference/exposure.py states the rule in front of the input and output stage references: E_cur is the game's exposure or 1, E_aux the auto-exposure value when it runs (else E_cur), LDR everything 1, e1 = e2 the game's positive finite scale. The stage references are unchanged (docstrings point at the rule). No kernel, runtime or build change. Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> --- clean/k/README.md | 1 + clean/k/reference/exposure.py | 56 +++++++++++++++++++++++++++ clean/k/reference/instage.py | 4 +- clean/k/reference/outstage.py | 3 +- clean/k/tests/test_k_exposure_rule.py | 52 +++++++++++++++++++++++++ 5 files changed, 114 insertions(+), 2 deletions(-) create mode 100644 clean/k/reference/exposure.py create mode 100644 clean/k/tests/test_k_exposure_rule.py diff --git a/clean/k/README.md b/clean/k/README.md index eb5c3389..1c59fa4d 100644 --- a/clean/k/README.md +++ b/clean/k/README.md @@ -22,6 +22,7 @@ model selection, the build, the runtime's create check). Model M's behaviour is | `runner/k_model.py` | reads the converter's `--raw` output (spec 48) with the preset-K map's names and shapes, and the window-offset table (`net/window_offsets`) | | `reference/fp.py` | exact FP32 / FP16 helpers (fma by round-to-odd, round half away, truncation to FP16) | | `reference/instage.py`, `outstage.py` | spec 42 input stage, spec 43 output stage and filter-shape table (NumPy) | +| `reference/exposure.py` | which exposure value is which (E_cur the game's exposure or 1, E_aux the auto-exposure value, LDR all 1): the rule in front of the two stages | | `kernels/k_fp.h`, `k_io.hip` | the input / output stage kernels (`k_in_color`, `k_in_base`, `k_out_pixel`, `k_out_hidden`) | | `runner/k_io.py` | their launch arguments, host scalars, the exact 2^E table | | `runner/k_frame.py` | one whole frame: input stage → network → output stage, histories and frame index (`KFrame`), and the chained NumPy reference (`reference_frame`) | diff --git a/clean/k/reference/exposure.py b/clean/k/reference/exposure.py new file mode 100644 index 00000000..b2c1bb55 --- /dev/null +++ b/clean/k/reference/exposure.py @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: MIT +"""Model K: which exposure value is which (spec 42 draft 3 section 4), the host rule in front of the input stage +(instage.py) and the output stage (outstage.py), which take E_cur, E_prev, E_aux, e1, e2 as given. + +HDR context: + E_cur = the game's exposure (texture texel or value); 1 if the game passes none. The auto-exposure value never + takes its place. + E_aux = the auto-exposure value (spec 07) when auto-exposure runs; otherwise E_cur. + E_prev = the previous frame's E_cur; E_cur itself on a history reset (and on the first frame). + e1 = e2 = the game's exposure scale if it is positive and finite, else 1 (the per-feature factor that multiplies it + is taken as 1). +LDR context: every value and factor 1. +Auto-exposure runs (HDR only) when the game asks for it at creation. Each value is then read as FP16 with 0 -> 1 by +the stages. So kappa = e1 E_cur / pi, lambda = e2 E_aux / (e1 E_cur), rho = (e1 E_cur) / (e1 E_prev). + +The cases (HDR): no texture + auto-exposure -> E_cur = E_prev = 1, E_aux = measured (lambda = measured); +texture, no auto-exposure -> E_cur = E_aux = texture (lambda = 1); texture + auto-exposure -> E_cur = texture, +E_aux = measured; neither -> all 1. + +This is the rule in NumPy, the one place that states it for the references; a caller (the whole-frame runner, the +runtime's exposure kernel) applies it to get the values the two stages take. +""" +import math + + +def exposure_scale(scale): + """e1 = e2: the game's exposure scale if positive and finite, else 1.""" + try: + s = float(scale) + except (TypeError, ValueError): + return 1.0 + return s if math.isfinite(s) and s > 0.0 else 1.0 + + +def exposure_values(hdr, game_exposure=None, measured=None, scale=None): + """{E_cur, E_aux, e1, e2} of one frame (E_prev is the previous frame's E_cur, kept by the caller). + + hdr: the HDR context flag; game_exposure: the exposure the game passes this frame (its texture's texel or a value; + None: none); measured: the spec 07 auto-exposure value when auto-exposure runs this frame (None: it does not).""" + if not hdr: + return {"E_cur": 1.0, "E_aux": 1.0, "e1": 1.0, "e2": 1.0} + E_cur = 1.0 if game_exposure is None else float(game_exposure) + E_aux = E_cur if measured is None else float(measured) + e = exposure_scale(scale) + return {"E_cur": E_cur, "E_aux": E_aux, "e1": e, "e2": e} + + +def apply_rule(x, hdr): + """x (a frame dict) with E_cur, E_aux, e1, e2 from the rule when it gives the rule's inputs instead: game_exposure + (None or a value), measured (None or the auto-exposure value), exposure_scale (optional). A dict that already + has E_cur is returned unchanged (the stage tests give the values directly).""" + if "E_cur" in x and x["E_cur"] is not None: + return x + d = dict(x) + d.update(exposure_values(hdr, x.get("game_exposure"), x.get("measured"), x.get("exposure_scale"))) + return d diff --git a/clean/k/reference/instage.py b/clean/k/reference/instage.py index 82e0d928..8a289178 100644 --- a/clean/k/reference/instage.py +++ b/clean/k/reference/instage.py @@ -56,7 +56,9 @@ def input_stage(x): """Spec 42 on one frame. x: dict with color [.., .., >=3], motion [.., .., 2], depth [.., ..] ([MVlo]), color_base / motion_base / depth_base (default 0), render_size (r_w, r_h), output_size (W, H), hdr, mv_lowres, depth_inverted, jitter, mv_scale, mv_offset, pre_exposure, reset, E_cur, E_prev, E_aux (FP16 values), e1, e2, - Hc [H16, W16, 4], Hh [Bh, Bw, 4] (FP16). Returns [Bh, Bw, 16] float16.""" + Hc [H16, W16, 4], Hh [Bh, Bw, 4] (FP16). Returns [Bh, Bw, 16] float16. Which exposure value is which (spec 42 + draft 3 section 4: E_cur the game's exposure or 1, E_aux the auto-exposure value, LDR all 1) is the host rule of + clean/k/reference/exposure.py; this stage takes the values as given.""" from clean.k.reference.layout import base_size W, H = (int(v) for v in x["output_size"]) rw, rh = (int(v) for v in x["render_size"]) diff --git a/clean/k/reference/outstage.py b/clean/k/reference/outstage.py index ac6fcd8c..3bc790cd 100644 --- a/clean/k/reference/outstage.py +++ b/clean/k/reference/outstage.py @@ -207,7 +207,8 @@ def output_stage(x): N [Bh, Bw, 40] (FP16 values), color [.., .., >=3 (alpha: 4th channel, else 1)], motion [.., .., 2], depth [.., ..], color_base / motion_base / depth_base (x, y) (default 0), render_size (r_w, r_h), output_size (W, H), hdr, mv_lowres, depth_inverted (bool), jitter (2), mv_scale (2), mv_offset (2), reset (bool), - E_cur, E_prev (FP16 values), e1, pre_exposure, L [2 H16, 2 W16] (FP16), Hc [H16, W16, 4] (FP16), + E_cur, E_prev (FP16 values; which is which: clean/k/reference/exposure.py, spec 42 draft 3 section 4), e1, + pre_exposure, L [2 H16, 2 W16] (FP16), Hc [H16, W16, 4] (FP16), table [2048, 8] (FP16, the frame's set; default: filter_table(filter_level(...))). Returns {"out": [H, W, 4] float32 RGBA, "L": [2 H16, 2 W16] f16, "Hc": [H16, W16, 4] f16, "Hh": [Bh, Bw, 4] f16}.""" W, H = (int(v) for v in x["output_size"]) diff --git a/clean/k/tests/test_k_exposure_rule.py b/clean/k/tests/test_k_exposure_rule.py new file mode 100644 index 00000000..3a2da4d0 --- /dev/null +++ b/clean/k/tests/test_k_exposure_rule.py @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: MIT +"""Model K's exposure rule, CPU only (no device, no emulator, no weights): clean/k/reference/exposure.py, which exposure +value is which. HDR: E_cur is the game's exposure or 1, E_aux the auto-exposure value when it runs (else E_cur), the +measured value never takes E_cur's place; LDR: every value and factor 1; e1 = e2 is the game's positive finite scale, +else 1. + +Run: python -m unittest clean.k.tests.test_k_exposure_rule +""" +import math +import unittest + +from clean.k.reference import exposure + + +class TestExposureRule(unittest.TestCase): + def test_scale(self): + self.assertEqual(exposure.exposure_scale(2.5), 2.5) + for bad in (None, "x", 0.0, -1.0, math.inf, -math.inf, math.nan): + self.assertEqual(exposure.exposure_scale(bad), 1.0, bad) + + def test_ldr_is_all_ones(self): + v = exposure.exposure_values(False, game_exposure=3.0, measured=4.0, scale=5.0) + self.assertEqual(v, {"E_cur": 1.0, "E_aux": 1.0, "e1": 1.0, "e2": 1.0}) + + def test_hdr_cases(self): + # no texture, no auto-exposure: all 1 + self.assertEqual(exposure.exposure_values(True), {"E_cur": 1.0, "E_aux": 1.0, "e1": 1.0, "e2": 1.0}) + # no texture + auto-exposure: E_cur 1, E_aux the measured value (it acts through lambda only) + v = exposure.exposure_values(True, measured=0.5) + self.assertEqual((v["E_cur"], v["E_aux"]), (1.0, 0.5)) + # texture, no auto-exposure: E_aux = E_cur + v = exposure.exposure_values(True, game_exposure=2.0) + self.assertEqual((v["E_cur"], v["E_aux"]), (2.0, 2.0)) + # texture + auto-exposure: the measured value never takes E_cur's place + v = exposure.exposure_values(True, game_exposure=2.0, measured=0.5, scale=3.0) + self.assertEqual((v["E_cur"], v["E_aux"], v["e1"], v["e2"]), (2.0, 0.5, 3.0, 3.0)) + + def test_apply_rule(self): + given = {"E_cur": 0.75, "E_aux": 1.5, "e1": 1.0, "e2": 1.0} + self.assertIs(exposure.apply_rule(given, True), given) # values given directly are left alone + d = exposure.apply_rule({"game_exposure": 2.0, "measured": 0.25, "exposure_scale": 4.0}, True) + self.assertEqual((d["E_cur"], d["E_aux"], d["e1"], d["e2"]), (2.0, 0.25, 4.0, 4.0)) + self.assertEqual(exposure.apply_rule({}, True)["E_cur"], 1.0) + self.assertEqual(exposure.apply_rule({"game_exposure": 9.0}, False)["E_cur"], 1.0) + # the input is not modified + x = {"game_exposure": 2.0} + exposure.apply_rule(x, True) + self.assertEqual(x, {"game_exposure": 2.0}) + + +if __name__ == "__main__": + unittest.main()