Skip to content

pixtreme.values

values

Pixel-value range, quantization, and storage operations.

__all__ = ('quantize', 'dequantize', 'full_to_legal', 'legal_to_full', 'cast_dtype', 'recode_dtype') module-attribute

cast_dtype(frame, *, dtype)

Cast storage while preserving literal numeric values.

This is a direct CuPy astype operation: it adds no scaling, clipping, or explicit rounding. Metadata is unchanged and every call returns a new allocation. Use :func:recode_dtype when normalized image meaning must be preserved across storage dtypes. Use :func:quantize or :func:dequantize when an explicit bit-depth grid defines the scale.

recode_dtype(frame, *, dtype)

Recode storage while preserving normalized image meaning.

Unsigned integer containers map their complete code range to [0, 1]. Floating-point values map to unsigned integers by clipping to [0, 1], scaling to the target container maximum, and rounding half away from zero. Float-to-float conversion is a literal cast. Metadata is unchanged and every call returns a new allocation, including same-dtype conversion.

Use :func:cast_dtype for literal numeric preservation. Use :func:quantize and :func:dequantize for the explicit bit-depth grid lane when effective code bits, rather than the storage container, define the scale.

Compress full-range fp32 values to H.273 legal positions without clipping.

R, G, B, and Y use the luma interval; Cb and Cr use the chroma interval. bit_depth accepts 8, 10, 12, 14, or 16. Metadata and input storage are unchanged.

legal_to_full(frame, *, bit_depth=8)

Expand H.273 legal code positions to full-range fp32 without clipping.

R, G, B, and Y use the luma interval; Cb and Cr use the chroma interval. bit_depth accepts 8, 10, 12, 14, or 16. Metadata and input storage are unchanged.

To repair RGB produced by applying a matrix before legal-range expansion, reverse that composition in the same matrix domain::

restored_ycbcr = px.color.rgb_to_ycbcr(frame, matrix="BT.709")
full_ycbcr = px.values.legal_to_full(restored_ycbcr, bit_depth=8)
corrected_rgb = px.color.ycbcr_to_rgb(full_ycbcr, matrix="BT.709")

dequantize(frame, *, bit_depth)

Map unsigned integer codes to fp32 by dividing by 2^bit_depth - 1.

bit_depth accepts 8, 10, 12, 14, or 16. Input storage must be uint8 for 8-bit codes and uint16 for 10-16-bit codes. Codes above the declared maximum are not clipped and therefore remain above 1.0. Frame stores no bit-depth state. Use :func:cast_dtype for literal storage conversion.

quantize(frame, *, bit_depth)

Quantize normalized fp32 values onto a uniform unsigned full-scale grid.

bit_depth accepts 8, 10, 12, 14, or 16 and defines maximum code 2^bit_depth - 1. Values are clipped to [0, 1], scaled, and rounded half away from zero. The result uses uint8 for 8-bit codes and uint16 for 10-16-bit codes.

This is per-call pixel-value quantization, not palette quantization or ML affine quantization. Frame stores no bit-depth state. Use :func:cast_dtype when literal numeric values, rather than their normalized meaning, must be preserved.