Skip to content

Film Spectral

film_spectral

The main class for handling all film data procesing 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:

CCT_to_XYZ staticmethod 

CCT_to_XYZ(CCT: float | int, Y=1.0, tint=0.0)

Converts from a color temperature in kelvin to a XYZ triplet.

add_photographic_inversion staticmethod 

add_photographic_inversion(add, negative_film, projector_kelvin, pipeline)

Simualtes a simple inversion of a scan with a virtual camera.

compute_print_matrix 

compute_print_matrix(print_film, **kwargs)

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

Parameters:

  • print_film
    –

    The film to print onto.

  • **kwargs
    –

    Args passed to compute_printer_light.

Returns:

  • –

    The printing matrix and the exposure for zero density.

compute_printer_light 

compute_printer_light(print_film, red_light=0, green_light=0, blue_light=0, **kwargs)

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

Parameters:

  • print_film
    –

    Film stock to print onto.

  • red_light
    –

    Red printer light offset.

  • green_light
    –

    Green printer light offset.

  • blue_light
    –

    Blue printer light offset.

  • **kwargs
    –

    Not used.

Returns:

  • –

    Printer light as spectral curve.

compute_projection_light 

compute_projection_light(
    projector_kelvin=5500, reference_kelvin=6504, white_comp=True
) -> tuple[ndarray, ndarray]

Computes a projection light of the specified temperature whose intensity is scaled so that minimum density of the current film will produce the specified white point in linear rec. 709 on the maximum color channel. Also gives scaled XYZ cmfs for use in conjunction with that light.

Parameters:

  • projector_kelvin
    –

    The light temperature of the projection lamp.

  • reference_kelvin
    –

    The reference temperature for the XYZ cmfs calibration. Should be left unchanged under normal circumstances.

  • white_comp
    –

    Whether to scale the output to clip at 1.0 in sRGB gamut.

Returns:

  • tuple[ndarray, ndarray] –

    A tuple (projector_light, xyz_cmfs).

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=3)

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

Parameters:

  • height
    –

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

gamut_compression staticmethod 

gamut_compression(image: ndarray, strength=0.95, clip_highlights=True)

A simple gamut compression that limits the maximal relative distance from the achromatic. Inspired by ACES Reference Gamut Compression. Has been simplified to be color space agnostic and use a simple clipping function instead of a roll-off. It is not perceptually neutral and should be used conservatively. It is intended to fix numeric issues in highly saturated colors, and not to be part of look creation.

Parameters:

  • image
    (ndarray) –

    The image to transform.

  • strength
    –

    How strong to compress. strength=1 is uncompressed and strength=0 is fully desaturated.

  • clip_highlights
    –

    Whether to clip highlights at 1.

Returns:

  • –

    The compressed image.

gaussian_extrapolation staticmethod 

gaussian_extrapolation(sd)

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

Parameters:

  • sd
    –

    Spectral density data to extrapolate.

Returns:

  • –

    Extrapolated spectral density.

generate_conversion staticmethod 

generate_conversion(
    negative_film,
    print_film=None,
    input_colourspace: None | str = "ARRI Wide Gamut 4",
    measure_time=False,
    output_gamut="Rec. 709",
    gamma_func="Gamma 2.4",
    projector_kelvin=6500,
    matrix_method=False,
    exp_comp=0,
    white_comp=True,
    mode="full",
    exposure_kelvin=5500,
    halation_func=None,
    pre_flash_neg=-4,
    pre_flash_print=-4,
    gamut_compression=0.2,
    shadow_comp=0,
    photo_inversion=False,
    color_masking=None,
    tint=0,
    sat_adjust=1,
    adx=True,
    adx_scaling=1.0,
    **kwargs,
)

The main function that performs the film simulation.

get_d_ref 

get_d_ref(color_masking: float | None = None)

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

Parameters:

  • color_masking
    (float | None, default: None ) –

    Color masking factor. If None use default value for current film. Safe values are in the range [0, 1], but higher values can be used to get a highly saturated look.

Returns:

  • –

    np.array: d_ref value for each channel.

get_density_curve 

get_density_curve(color_masking=None)

Get characteristic density curve for current film stock.

Parameters:

  • color_masking
    –

    Color Masking factor in range [0, 1]. If None use default for

Returns:

  • –

    The density curve.

get_spectral_density 

get_spectral_density(color_masking=None)

Get spectral density for current film stock.

Parameters:

  • color_masking
    –

    Color Masking factor in range [0, 1]. If None use default for

Returns:

  • –

    Spectral density.

grain_transform 

grain_transform(rgb, scale=1.0, std_div=1.0)

Encoding for the grain intensity LUT.

log_exposure_to_density 

log_exposure_to_density(log_exposure, color_masking=0, pre_flash=-4)

Convert log_exposure to density values for current film stock.

Parameters:

  • log_exposure
    –

    Log exposure data to convert as array.

  • color_masking
    –

    Color Masking factor in range [0, 1].

  • pre_flash
    –

    Intensity of pre-flash exposure in number of stops below middle

output_to_density staticmethod 

output_to_density(y, a, b, x0=None, method='lm')
Numerically invert the mapping

y = (10 ** -(x @ a.T)) @ b

to recover x.

Parameters

y : array-like, shape (p,) Output vector. a : array-like, shape (m, n) Density matrix (used in forward map). b : array-like, shape (m, p) Output matrix (used in forward map). x0 : array-like, shape (n,), optional Initial guess for x. Defaults to zeros. method : str, optional Least-squares solver method: 'lm', 'trf', or 'dogbox'.

Returns

x : ndarray, shape (n,) Estimated vector such that (10 ** -(x @ a.T)) @ b ≈ y

plot_data 

plot_data(film_b=None, color_masking=None)

Plots the spectral density, sensitivity, and sensiometric curve.

prepare_rms_data staticmethod 

prepare_rms_data(rms, density)

Align the provided rms granularity and density data.

Parameters:

  • rms
    –

    RMS granularity data in relation to exposure.

  • density
    –

    Density values for each channel in relation to exposure..

Returns:

  • –

    Aligned rms and density data.

saturation_adjust_oklch staticmethod 

saturation_adjust_oklch(image, sat_adjust: float)

Adjust saturation using a simple matrix transform. Matrix is derived by adjusting saturation of colorchecker values in Oklab, transforming to XYZ, and fitting a transformation matrix in XYZ space with least-squares. Should be used in conjunction with a later gamut compression.

Parameters:

  • image
    –

    The image to transform. Expects XYZ input.

  • sat_adjust
    (float) –

    Multiplicative saturation factor. 1 leaves unchanged.

Returns:

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.

shadow_compensation staticmethod 

shadow_compensation(image: ndarray, intensity) -> ndarray

Raises or lowers shadows. Has been computed to act as an OOTF for the ITU-R BT.1886 curve. Setting gamma to Gamma 2.4 and Black offset to 1.0 will yield essentially Rec. 709. Setting gamma to Rec. 709 and Black offset to -1.0 in turn gives essentially Gamma 2.4. Has been computed from BT.1886 as to not be piecewise, and to not overfit to Rec. 709.

Parameters:

  • image
    (ndarray) –

    The image to transform. Assumed to be in linear gamma.

  • intensity
    –

    How much to lift or lower particularly dark areas. For 0 no effect, 1 and -1 act as forward and inverse OOTFs respectively.

  • gamma
    –

    The assumed viewing gamma for the OOTF modeling.

  • black_level
    –

    The assumed viewing black level for OOTF modeling.

Returns:

  • ndarray –

    The shadow compensated image.