Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions clean/k/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`) |
Expand Down
56 changes: 56 additions & 0 deletions clean/k/reference/exposure.py
Original file line number Diff line number Diff line change
@@ -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
4 changes: 3 additions & 1 deletion clean/k/reference/instage.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"])
Expand Down
3 changes: 2 additions & 1 deletion clean/k/reference/outstage.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"])
Expand Down
52 changes: 52 additions & 0 deletions clean/k/tests/test_k_exposure_rule.py
Original file line number Diff line number Diff line change
@@ -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()
Loading