Film Spectral

film_spectral

The main class for handling all film data processing and rendering.

Classes:

FilmSpectral –

The main class that profiles a film stock from its raw data and provides functions

FilmSpectral

FilmSpectral(film_data: FilmData, gray_value=0.18)

The main class that profiles a film stock from its raw data and provides functions for simulating the look of printed or scanned film.

Profiles a film stock from its raw data as reported in a datasheet.

Methods:

adx_decoding –

Decode layer activation from ADX16 data in the [0, 1] range to absolute
adx_encoding –

Encode layer activation in absolute densities as ADX16 data in the [0, 1] range.
apd_alignment_matrix –

Compute matrix to make APD scan closer to proper print exposure.
apd_to_layer_activation_matrix –

Get the matrix that converts from ACES Printing Density to layer activation for
compute_lad –

Find the Lab Aim Density for a neutral gray.
compute_print_matrix –

Computed matrix to convert from density of current film stock to log exposure of
compute_printer_light –

Compute printer light needed to print onto target print film to generate neutral
estimate_d_min_sd –

Certain film stocks provide the minimum density for each layer, but they don't
extend_characteristic_curve –

Extend the characteristic curve of the current film with a smooth rolloff.
gaussian_extrapolation –

Extrapolate using a Gaussian distribution. Intended to be used for extrapolating
get_color_masking_matrix –

Computes the 3x3 Log-E exposure inhibition matrix for film color masking.
get_d_ref –

Get the d_ref of the current film stock under specified color masking intensity.
get_density_curve –

Get characteristic density curve for current film stock.
get_grain_curve –

Compute grain intensity 1D LUT.
get_input_lut –

Compute a 2D LUT for use with apply_2d_lut that converts from scene linear
grain_transform –

Compute a grain intensity map from an image containing density values.
input_transform –

Transform from scene referred image data to the per layer activation in absolute
layer_activation_to_apd_matrix –

Get the matrix that converts from layer activation to ACES Printing Density for
log_exposure_to_density –

Convert log_exposure to density values for current film stock.
plot_data –

Plots the spectral density, sensitivity, and sensiometric curve.
prepare_rms_data –

Align the provided rms granularity and density data.
print_from_apd –

Converts independent APD intermediate densities into this print film's
print_to –

Print to another film stock.
printing_process –

Print from one film stock onto another.
project –

Get the scene referred output from projection or viewing under an illuminant.
scan_with_apd –

Print from one film stock onto another.
set_color_checker –

Simulate the look of the 2005 ColorChecker photographed with the current film

Attributes:

cid_to_xyz –

A per negative film stock optimized inversion matrix for use with apd_to_xyz.

cid_to_xyz `property`

cid_to_xyz

A per negative film stock optimized inversion matrix for use with apd_to_xyz. The matrix assumes row vectors and therefore does not need to be transposed.

adx_decoding

adx_decoding(
    image: ndarray, scaling: float = 1.0, apd_intermediate: bool = False
) -> ndarray

Decode layer activation from ADX16 data in the [0, 1] range to absolute densities.

Parameters:

image
(ndarray) –

The image (or LUT) encoded in ADX.
scaling
(float, default: 1.0 ) –

Linear scaling applied to the endoced values. For 1.0 it is ADX16-like and for 4.0 it is ADX10-like.

Returns:

ndarray –

The image (or LUT) represented as absolute layer activations.

adx_encoding

adx_encoding(
    image: ndarray, scaling: float = 1.0, apd_intermediate: bool = False
) -> ndarray

Encode layer activation in absolute densities as ADX16 data in the [0, 1] range.

Parameters:

image
(ndarray) –

The image (or LUT) containing layer activations.
scaling
(float, default: 1.0 ) –

Linear scaling applied to the values. For 1.0 it is ADX16-like and for 4.0 it is ADX10-like.

Returns:

ndarray –

The image (or LUT) encoded in ADX.

apd_alignment_matrix `cached`

apd_alignment_matrix(
    reference_negative: FilmSpectral, max_delta: float = 0.05
) -> ndarray

Compute matrix to make APD scan closer to proper print exposure.

apd_to_layer_activation_matrix

apd_to_layer_activation_matrix() -> ndarray

Get the matrix that converts from ACES Printing Density to layer activation for ADX decoding.

compute_lad

compute_lad(luminance=0.1)

Find the Lab Aim Density for a neutral gray.

compute_print_matrix

compute_print_matrix(print_film: FilmSpectral, **kwargs: Any) -> ndarray

Computed matrix to convert from density of current film stock to log exposure of print film stock.

Parameters:

print_film
(FilmSpectral) –

The film to print onto.
**kwargs
(Any, default: {} ) –

Args passed to compute_printer_light.

Returns:

ndarray –

The printing matrix and the exposure for zero density.

compute_printer_light

compute_printer_light(
    print_film: FilmSpectral,
    red_light: float = 0.0,
    green_light: float = 0.0,
    blue_light: float = 0.0,
) -> ndarray

Compute printer light needed to print onto target print film to generate neutral exposure.

Parameters:

print_film
(FilmSpectral) –

Film stock to print onto.
red_light
(float, default: 0.0 ) –

Red printer light offset.
green_light
(float, default: 0.0 ) –

Green printer light offset.
blue_light
(float, default: 0.0 ) –

Blue printer light offset.

Returns:

ndarray –

Printer light as spectral curve.

estimate_d_min_sd

estimate_d_min_sd()

Certain film stocks provide the minimum density for each layer, but they don't subtract the base density of the material, resulting in low saturation during emulation. To separate the layers more clearly we estimate the base density by subtracting the lower hull of the combined layers.

extend_characteristic_curve

extend_characteristic_curve(height: float = 3.0)

Extend the characteristic curve of the current film with a smooth rolloff.

Parameters:

height
(float, default: 3.0 ) –

Assumed height of the logistic curve used for extrapolation in density steps.

gaussian_extrapolation `staticmethod`

gaussian_extrapolation(sd: SpectralDistribution) -> SpectralDistribution

Extrapolate using a Gaussian distribution. Intended to be used for extrapolating spectral data.

Parameters:

sd
(SpectralDistribution) –

Spectral density data to extrapolate.

Returns:

SpectralDistribution –

Extrapolated spectral density.

get_color_masking_matrix

get_color_masking_matrix(
    color_masking: float | None = None, force_simple: bool = False
) -> ndarray

Computes the 3x3 Log-E exposure inhibition matrix for film color masking.

Models interlayer development interactions and optical masking effects in the relative log-exposure (Log-H) domain. For negative stocks measured in Status M, it derives an empirical unmixing matrix by bridging the stock's spectral dye densities with ACES APD densitometry. For slide stocks (or when forced), it falls back to a row-normalized isotropic inhibition matrix scaled by relative layer sensitivities.

Parameters:

color_masking
(float | None, default: None ) –

The strength of the color masking / interlayer effect. 0.0 corresponds to no masking (identity operation). 1.0 represents full APD-based or baseline chemical unmixing. Values greater than 1.0 extrapolate the effect to increase saturation.
force_simple
(bool, default: False ) –

If True, bypasses the APD-based spectral unmixing branch and uses the simple isotropic interimage model regardless of the stock's density measurement standard.

Returns:

ndarray –

A 3x3 float numpy array representing the transformation matrix to be
ndarray –

applied via right-matrix multiplication (image @ M_log.T) in Log-E space.

get_d_ref

get_d_ref() -> ndarray

Get the d_ref of the current film stock under specified color masking intensity.

Returns:

ndarray –

d_ref value for each channel.

get_density_curve

get_density_curve(push_pull: float = 0.0) -> ndarray

Get characteristic density curve for current film stock.

Parameters:

push_pull
(float, default: 0.0 ) –

By how many stops to push/pull the negative to adjust contrast.

Returns:

ndarray –

The density curve.

get_grain_curve

get_grain_curve(
    scale: float = 1.0,
    std_div: float = 1.0,
    adx: bool = True,
    bw_grain: bool = False,
    apd_intermediate: bool = False,
) -> ndarray

Compute grain intensity 1D LUT.

get_input_lut

get_input_lut(
    exposure_kelvin: int | float = 6500,
    tint: float = 0.0,
    exp_comp: float = 0.0,
    upsampling_method: UpsampleMethod | str = "SFL upsampling",
) -> ndarray

Compute a 2D LUT for use with apply_2d_lut that converts from scene linear CIE XYZ the per layer exposure.

Parameters:

exposure_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.
upsampling_method
(UpsampleMethod | str, default: 'SFL upsampling' ) –

Method for reconstructing a spectral distribution from CIE XYZ values.

Returns:

ndarray –

The 2D LUT of shape (n, n, 3).

grain_transform

grain_transform(
    image: ndarray,
    scale: float = 1.0,
    std_div: float = 1.0,
    adx: bool = True,
    bw_grain: bool = False,
    apd_intermediate: bool = False,
) -> ndarray

Compute a grain intensity map from an image containing density values.

Parameters:

image
(ndarray) –

The image containing density values.
scale
(float, default: 1.0 ) –

The scaling of the intensity of the grain. Can either be the max density for an ADX encoded LUT or the size scalling in pixels per mm.
std_div
(float, default: 1.0 ) –

The std_div of the gaussian noise for which the intensity map is to be used.
adx
(bool, default: True ) –

Whether
bw_grain
(bool, default: False ) –

Returns:

input_transform

input_transform(
    image: ndarray,
    colorspace: LiteralRGBColourspace | None = None,
    exp_comp: float = 0.0,
    exp_kelvin: int | float = 6500,
    tint: float = 0.0,
    color_masking: None | float = None,
    push_pull: float = 0.0,
    upsampling_method: UpsampleMethod | str = "barycentric_nnls_all",
) -> ndarray

Transform from scene referred image data to the per layer activation in absolute densities.

Parameters:

image
(ndarray) –

The image (or LUT) in a scene referred color space.
colorspace
(LiteralRGBColourspace | None, default: None ) –

What color space the input is encoded in.
exp_comp
(float, default: 0.0 ) –

The exposure adjustment.
exp_kelvin
(int | float, default: 6500 ) –

The scene white balance in kelving.
tint
(float, default: 0.0 ) –

The tint adjustment on the green -- red/purple axis.
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.
push_pull
(float, default: 0.0 ) –

By how many stops to push/pull the negative to adjust contrast.

Returns:

ndarray –

The resulting layer activation as densities.

layer_activation_to_apd_matrix

layer_activation_to_apd_matrix()

Get the matrix that converts from layer activation to ACES Printing Density for ADX encoding.

log_exposure_to_density

log_exposure_to_density(
    log_exposure: ndarray,
    push_pull: float = 0.0,
    idealized_curve: bool = False,
    idealized_gamma: float = 3.0,
    d_min: float = 0.0,
) -> ndarray

Convert log_exposure to density values for current film stock.

Parameters:

log_exposure
(ndarray) –

Log exposure data to convert as array.
push_pull
(float, default: 0.0 ) –

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

Replace the characteristic curve with an ideal gamma curve.
idealized_gamma
(float, default: 3.0 ) –

The gamma of the idealized curve when it is used.

plot_data

plot_data(film_b=None)

Plots the spectral density, sensitivity, and sensiometric curve.

prepare_rms_data `staticmethod`

prepare_rms_data(rms: dict, density: dict) -> tuple[ndarray, ndarray]

Align the provided rms granularity and density data.

Parameters:

rms
(dict) –

RMS granularity data in relation to exposure.
density
(dict) –

Density values for each channel in relation to exposure..

Returns:

tuple[ndarray, ndarray] –

Aligned rms and density data.

print_from_apd

print_from_apd(
    apd_image: ndarray,
    idealized_curve: bool = False,
    idealized_gamma: float = 3.0,
    reference_negative: FilmSpectral | None = None,
    d_min: float = 0.0,
) -> ndarray

Converts independent APD intermediate densities into this print film's native layer activations, properly calibrated for mid-gray exposure.

print_to

print_to(
    image: ndarray,
    print_film: FilmSpectral,
    red_light: float = 0.0,
    green_light: float = 0.0,
    blue_light: float = 0.0,
    idealized_curve: bool = False,
    idealized_gamma: float = 3.0,
    d_min: float = 0.0,
) -> ndarray

Print to another film stock.

Parameters:

image
(ndarray) –

The image (or LUT) containing layer activations in absolute densities.
print_film
(FilmSpectral) –

The film stock to print onto.
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.
idealized_curve
(bool, default: False ) –

Replace the characteristic curve of the print stock with an ideal gamma curve.
idealized_gamma
(float, default: 3.0 ) –

The gamma of the idealized curve when it is used.

Returns:

ndarray –

The resulting layer activations of the print stock.

printing_process `staticmethod`

printing_process(
    image: ndarray,
    negative_film: FilmSpectral,
    print_film: FilmSpectral,
    red_light: float = 0.0,
    green_light: float = 0.0,
    blue_light: float = 0.0,
    idealized_curve: bool = False,
    idealized_gamma: float = 3.0,
    d_min: float = 1.0,
) -> ndarray

Print from one film stock onto another.

Parameters:

image
(ndarray) –

The image (or LUT) containing layer activations in absolute densities.
negative_film
(FilmSpectral) –

The film stock from which to print.
print_film
(FilmSpectral) –

The film stock to print onto.
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.
idealized_curve
(bool, default: False ) –

Replace the characteristic curve of the print stock with an ideal gamma curve.
idealized_gamma
(float, default: 3.0 ) –

The gamma of the idealized curve when it is used.

Returns:

ndarray –

The resulting layer activations of the print stock.

project

project(
    image: ndarray,
    projector_kelvin: int | float = 6500,
    white_comp: bool = False,
    white_balance: int = 0,
) -> tuple[ndarray, ndarray | None]

Get the scene referred output from projection or viewing under an illuminant.

Parameters:

image
(ndarray) –

The image (or LUT) containing layer activations in absolute densities.
projector_kelvin
(int | float, default: 6500 ) –

The white balance in kelvin of the projection lamp.
white_comp
(bool, default: False ) –

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

White balance mode for slide projection: 0 disabled, 1 based on mid gray, 2 based on peak white.

Returns:

tuple[ndarray, ndarray | None] –

The projected image in linear CIE XYZ color space.

scan_with_apd

scan_with_apd(
    image: ndarray,
    red_light: float = 0.0,
    green_light: float = 0.0,
    blue_light: float = 0.0,
) -> ndarray

Print from one film stock onto another.

Parameters:

image
(ndarray) –

The image (or LUT) containing layer activations in absolute densities.
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.

Returns:

ndarray –

The resulting layer activations of the print stock.

set_color_checker

set_color_checker(
    negative: FilmSpectral | None = None, print_stock: FilmSpectral | None = None
)

Simulate the look of the 2005 ColorChecker photographed with the current film stock.

Parameters:

negative
(FilmSpectral | None, default: None ) –

When a negative film is provided assume current film is print film.
print_stock
(FilmSpectral | None, default: None ) –

Use this film as the print film for the color checker if provided.

Film Spectral

film_spectral

FilmSpectral

cid_to_xyz property

adx_decoding

image

scaling

adx_encoding

image

scaling

apd_alignment_matrix cached

apd_to_layer_activation_matrix

compute_lad

compute_print_matrix

print_film

**kwargs

compute_printer_light

print_film

red_light

green_light

blue_light

estimate_d_min_sd

extend_characteristic_curve

height

gaussian_extrapolation staticmethod

sd

get_color_masking_matrix

color_masking

force_simple

get_d_ref

get_density_curve

push_pull

get_grain_curve

get_input_lut

exposure_kelvin

tint

exp_comp

upsampling_method

grain_transform

image

scale

std_div

adx

bw_grain

input_transform

image

colorspace

exp_comp

exp_kelvin

tint

color_masking

push_pull

layer_activation_to_apd_matrix

log_exposure_to_density

log_exposure

push_pull

idealized_curve

idealized_gamma

plot_data

prepare_rms_data staticmethod

rms

density

print_from_apd

print_to

image

print_film

red_light

green_light

blue_light

idealized_curve

idealized_gamma

printing_process staticmethod

image

negative_film

print_film

red_light

green_light

blue_light

idealized_curve

idealized_gamma

cid_to_xyz `property`

`image`

`scaling`

`image`

`scaling`

apd_alignment_matrix `cached`

`print_film`

`kwargs`**

`print_film`

`red_light`

`green_light`

`blue_light`

`height`

gaussian_extrapolation `staticmethod`

`sd`

`color_masking`

`force_simple`

`push_pull`

`exposure_kelvin`

`tint`

`exp_comp`

`upsampling_method`

`image`

`scale`

`std_div`

`adx`

`bw_grain`

`image`

`colorspace`

`exp_comp`

`exp_kelvin`

`tint`

`color_masking`

`push_pull`

`log_exposure`

`push_pull`

`idealized_curve`

`idealized_gamma`

prepare_rms_data `staticmethod`

`rms`

`density`

`image`

`print_film`

`red_light`

`green_light`

`blue_light`

`idealized_curve`

`idealized_gamma`

printing_process `staticmethod`

`image`

`negative_film`

`print_film`

`red_light`

`green_light`

`blue_light`

`idealized_curve`

`idealized_gamma`

`image`

`projector_kelvin`

`white_comp`

`white_balance`

`image`

`red_light`

`green_light`

`blue_light`

`negative`

`print_stock`