heygen-com/hyperframes · error · ValueError

probe index ${i} out of range [0, 255]

Error message

probe index ${i} out of range [0, 255]

What it means

Thrown by emit_probes() in the LUT reference generator script when a probe index is outside the inclusive range [0, 255]. The script generates sRGB-to-BT.2020 (HLG/PQ) lookup table reference values and can emit a subset of probe entries for test fixtures. Each probe index must correspond to a valid 8-bit sRGB input value.

Source

Thrown at packages/engine/scripts/generate-lut-reference.py:130

    return out


# Mirror SRGB_TO_HDR_REFERENCE indices in alphaBlit.test.ts. Endpoints
# (0, 1, 254, 255) catch off-by-one regressions; mid-range values (32, 64,
# 96, 128, 160, 192, 224) sample the middle of both transfer curves.
DEFAULT_PROBES: tuple[int, ...] = (0, 1, 10, 32, 64, 96, 128, 160, 192, 224, 254, 255)


def emit_json(hlg: list[int], pq: list[int]) -> None:
    print(json.dumps({"size": 256, "hlg": hlg, "pq": pq}, indent=2))


def emit_probes(hlg: list[int], pq: list[int], probes: Iterable[int]) -> None:
    # Output is paste-ready TS for SRGB_TO_HDR_REFERENCE in alphaBlit.test.ts.
    print("const SRGB_TO_HDR_REFERENCE: readonly SrgbHdrProbe[] = [")
    for i in probes:
        if not 0 <= i <= 255:
            raise ValueError(f"probe index {i} out of range [0, 255]")
        print(f"  {{ srgb: {i}, hlg: {hlg[i]}, pq: {pq[i]} }},")
    print("];")


def parse_indices(s: str) -> list[int]:
    return [int(x.strip()) for x in s.split(",") if x.strip()]


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Regenerate sRGB → BT.2020 (HLG/PQ) LUT reference values.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument(
        "--probes",
        action="store_true",
        help="Emit a TS snippet ready to paste over SRGB_TO_HDR_REFERENCE.",
    )

View on GitHub (pinned to c2996c8626)

Solutions

1. Check the --probes argument for values outside 0-255 and correct them.
2. If generating probes programmatically, clamp: index = max(0, min(255, index)).
3. Use the default probe set (omit --probes) which is pre-validated: (0, 1, 10, 32, 64, 96, 128, 160, 192, 224, 254, 255).
4. Run with --help to see accepted ranges and examples.

Example fix

# before
python generate-lut-reference.py --probes 0,128,256

# after
python generate-lut-reference.py --probes 0,128,255

def validate_probes(probes):
    for i in probes:
        if not 0 <= i <= 255:
            raise ValueError(f'probe index {i} out of range [0, 255]')
    return probes

When it happens

Trigger: The script is invoked with --probes '0,1,10,32,...' (or DEFAULT_PROBES) and one of the comma-separated values is negative, > 255, or non-integer. parse_indices() converts strings to int, then emit_probes() validates each with 0 <= i <= 255.

Common situations: A developer hand-edits the --probes argument and mistypes a value (e.g., 256 instead of 255). A script generates probe indices programmatically and produces an out-of-range value. The default probe list was modified to include edge cases beyond 8-bit range.

Related errors

• Curve LUT size must be at least 2
• A color curve requires at least two points
• Color curve inputs must be strictly increasing
• Curve output bounds must be finite and increasing
• Curve outputs must be between ${outputMin} and ${outputMax}

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/d77fa2873c850911. Report an issue: GitHub.