Utils

utils

Additional utility functions.

Functions:

apply_lut_tetrahedral_int –

Apply a 3D LUT using tetrahedral interpolation.
create_lut –

Creates a 3D LUT using film spectral conversions with selectable
film_conversion –

Emulates the full film pipeline including exposure, printing, and projection.
linear_roll_off –

Function that rolls-off smoothly towards 0.
log_clip –

Apply log10 efficiently and clip to 1e-16 for safety.
multi_channel_interp –

Interpolate values in an N-D array over the last dimension.
smooth_roll_off –

Function that rolls-off smoothly towards 0.

Attributes:

MODES –

Conversion modes, i.e., what steps of the pipeline to activate.

MODES `module-attribute`

MODES = Literal['full', 'print', 'negative', 'grain']

Conversion modes, i.e., what steps of the pipeline to activate.

apply_lut_tetrahedral_int

apply_lut_tetrahedral_int(
    image: ndarray, lut: ndarray, bit_depth: int = 16, lut_depth: int = 8
) -> ndarray

Apply a 3D LUT using tetrahedral interpolation.

The input image is expected to have dtype uint16 with values in the range [0, 65535]. The output image has dtype uint8 with values in the range [0, 255].

Parameters:

image
(ndarray) –

Input image of shape (H, W, 3), dtype uint16 or uint8.
lut
(ndarray) –

3D lookup table of shape (size, size, size, 3), dtype uint16 or uint8.
bit_depth
(int, default: 16 ) –

Bit depth of the image.
lut_depth
(int, default: 8 ) –

Bit depth of the lookup table.

Returns:

ndarray –

Output image of shape (H, W, 3), dtype uint8.

create_lut

create_lut(
    negative_film,
    print_film=None,
    lut_size: int = 33,
    name: str = "test",
    cube: bool = True,
    verbose: bool = False,
    linear_scaling: float = 1.0,
    filter_mode: Literal["oversampling", "shift"] | None = None,
    **kwargs,
) -> ndarray | str

Creates a 3D LUT using film spectral conversions with selectable oversampling and cell-shift filtering modes.

Modes

'oversampling' : (2N-1)^3 grid, 3x3x3 3D median filter + direct decimation.
'shift' : (N+1)^3 dual grid, 8-corner cell voxel median.
None : Standard N^3 evaluation without oversampling.

film_conversion

film_conversion(
    image: ndarray,
    negative_film: FilmSpectral,
    print_film: FilmSpectral | None = None,
    mode: MODES = "full",
    input_colorspace: LiteralRGBColourspace | None = None,
    exp_kelvin: int | float = 6500,
    tint: float = 0.0,
    exp_comp: float = 0.0,
    color_masking: None | float = None,
    adx_coding: bool = True,
    adx_scaling: float | int = 1.0,
    red_light: float = 0.0,
    green_light: float = 0.0,
    blue_light: float = 0.0,
    projector_kelvin: int | float = 6500,
    white_clip: bool = True,
    white_balance: int = 1,
    output_gamut: COLOR_SPACE_KEYS = "Rec. 709",
    sat_adjust: float = 1.0,
    shadow_comp: float = 0.0,
    gamma_func: GAMMA_KEYS = "Gamma 2.4",
    push_pull: float = 0.0,
    inversion: bool = False,
    custom_inversion: bool = False,
    inversion_gamma: float = 3.0,
    idealized_curve: bool = False,
    apd_intermediate: bool = False,
    reference_negative: FilmSpectral | None = None,
    upsampling_method: UpsampleMethod | str = "SFL upsampling",
) -> ndarray

Emulates the full film pipeline including exposure, printing, and projection.

Parameters:

custom_inversion
(bool, default: False ) –

Use optimized inversion instead of ACES based inversion matrix.
upsampling_method
(UpsampleMethod | str, default: 'SFL upsampling' ) –

How to perform spectral upsampling.
reference_negative
(FilmSpectral | None, default: None ) –

Negative film used as reference for balancing intermediate ADX encoding.
apd_intermediate
(bool, default: False ) –

Whether to convert to APD values from layer activation values for the intermediate step between negative and print.
image
(ndarray) –

The image (or LUT) containing the scene referred data.
negative_film
(FilmSpectral) –

The film stock to capture the scene.
print_film
(FilmSpectral | None, default: None ) –

The optional print stock.
mode
(MODES, default: 'full' ) –

Which part of the pipeline to emulate.
input_colorspace
(LiteralRGBColourspace | None, default: None ) –

The colorspace if the image. If None CIE XYZ is used.
exp_kelvin
(int | float, default: 6500 ) –

The scene WB in kelvin.
tint
(float, default: 0.0 ) –

The tint adjustment on the green -- red/purple axis.
exp_comp
(float, default: 0.0 ) –

Exposure compensation in stops.
color_masking
(None | float, default: None ) –

How strong the color mask is on the negative film. 0 for no mask. 1 for a perfectly optimized mask (no pollution of other layers). >1 for increased saturation. Most film stocks don't provide exact data. For films with orange mask can be close to 1, for other (e.g. slide film) should be set quite low.
adx_scaling
(float | int, default: 1.0 ) –

When ADX encoding is used for negative/print/grain stages, what is by what factor to divide the output. For 1.0 we have pure ADX16 with a max density of 8, and for 4.0 we have ADX10 with a max density of 2.
adx_coding
(bool, default: True ) –

Whether to activate ADX encoding for partial pipelines. Ensures values stay within [0, 1] range. Necessary for save LUT generation.
red_light
(float, default: 0.0 ) –

Offset of the red printer light from neutral.
green_light
(float, default: 0.0 ) –

Offset of the green printer light from neutral.
blue_light
(float, default: 0.0 ) –

Offset of the blue printer light from neutral.
projector_kelvin
(int | float, default: 6500 ) –

The white balance in kelvin of the projection or viewing illuminant.
white_clip
(bool, default: True ) –

Whether to adjust the output brightness that it clips at exactly 1.
white_balance
(int, default: 1 ) –

White balance mode for slide projection: 0 disabled, 1 based on mid gray, 2 based on peak white.
output_gamut
(COLOR_SPACE_KEYS, default: 'Rec. 709' ) –

The gamut of the output color space.
sat_adjust
(float, default: 1.0 ) –

A saturation adjustment factor applied in OkLab. 1.0 for neutral, 0.0 for monochrome, and >1.0 for increased saturation.
shadow_comp
(float, default: 0.0 ) –

Shadow compensation to smoothly brighten or dark areas without clipped details. Function is based on the ITU Bt.1886 function and acts like a OOTF or inverse OOTF function for values of 1.0 and -1.0.
gamma_func
(GAMMA_KEYS, default: 'Gamma 2.4' ) –

The gamma function the output is encoded with.
push_pull
(float, default: 0.0 ) –

By how many stops to push/pull the negative to adjust contrast.
inversion
(bool, default: False ) –

Apply inversion to the final output.
inversion_gamma
(float, default: 3.0 ) –

The gamma used for inversion.
idealized_curve
(bool, default: False ) –

Replace the characteristic curve of the print film with an idealized one using inversion_gamma as the gamma factor.

Returns:

ndarray –

An image (or LUT) representing the transformed scene data after (partial) film
ndarray –

emulation.

linear_roll_off

linear_roll_off(x: ndarray, x0: float | ndarray, y0: float | ndarray, gamma: float)

Function that rolls-off smoothly towards 0.

Parameters:

x
(ndarray) –

Values that are to be mapped.
x0
(float | ndarray) –

At which position to hit y0.
y0
(float | ndarray) –

Which value to hit at x0.
gamma
(float) –

The slope of the curve.

log_clip

log_clip(image: ndarray)

Apply log10 efficiently and clip to 1e-16 for safety.

multi_channel_interp

multi_channel_interp(x: ndarray, curves: ndarray) -> ndarray

Interpolate values in an N-D array over the last dimension.

Interpolates values in an N-dimensional array x across the last dimension (channels) using a precomputed uniform grid defined by xp_common and fp_uniform. Optionally performs linear interpolation or nearest-neighbor selection, and supports linear extrapolation on either end of the grid.

Parameters:

x
(ndarray) –

Input array of shape (..., channels).
curves
(ndarray) –

Single xps and per channel fps stacked to shape (channesl + 1, N).

Returns:

ndarray –

Interpolated array with the same shape as x.

smooth_roll_off

smooth_roll_off(
    x: ndarray,
    x0: float | ndarray,
    y0: float | ndarray,
    gamma: float,
    d_min: float = 0.0,
)

Function that rolls-off smoothly towards 0.

Parameters:

x
(ndarray) –

Values that are to be mapped.
x0
(float | ndarray) –

At which position to hit y0.
y0
(float | ndarray) –

Which value to hit at x0.
gamma
(float) –

The slope of the curve.

Utils

utils

MODES module-attribute

apply_lut_tetrahedral_int

image

lut

bit_depth

lut_depth

create_lut

film_conversion

custom_inversion

upsampling_method

reference_negative

apd_intermediate

image

negative_film

print_film

mode

input_colorspace

exp_kelvin

tint

exp_comp

color_masking

adx_scaling

adx_coding

red_light

green_light

blue_light

projector_kelvin

white_clip

white_balance

output_gamut

sat_adjust

shadow_comp

gamma_func

push_pull

inversion

inversion_gamma

idealized_curve

linear_roll_off

x

x0

y0

gamma

log_clip

multi_channel_interp

x

curves

smooth_roll_off

x

x0

y0

gamma

MODES `module-attribute`

`image`

`lut`

`bit_depth`

`lut_depth`

`custom_inversion`

`upsampling_method`

`reference_negative`

`apd_intermediate`

`image`

`negative_film`

`print_film`

`mode`

`input_colorspace`

`exp_kelvin`

`tint`

`exp_comp`

`color_masking`

`adx_scaling`

`adx_coding`

`red_light`

`green_light`

`blue_light`

`projector_kelvin`

`white_clip`

`white_balance`

`output_gamut`

`sat_adjust`

`shadow_comp`

`gamma_func`

`push_pull`

`inversion`

`inversion_gamma`

`idealized_curve`

`x`

`x0`

`y0`

`gamma`

`x`

`curves`

`x`

`x0`

`y0`

`gamma`