Skip to content

Color Processing

color_processing

Color processing transforms not directly related to film.

Functions:

Attributes:

COLORCHECKER_2005 module-attribute 

COLORCHECKER_2005 = np.asarray(COLORCHECKER_2005, DEFAULT_DTYPE)

The XYZ value for the colorchecker 2005 data.

CCT_to_XYZ 

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

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

CCT_to_xy 

CCT_to_xy(CCT)

Convert from a color temperature in kelvin to the closest xy pair.

apd_to_xyz 

apd_to_xyz(
    apd: ndarray,
    inversion_gamma: float = 2.0,
    projector_kelvin: float | int = 6500,
    exp_to_xyz: ndarray | None = None,
) -> ndarray

Adaptation of the ADX to ACES transform to take APD input and map them ot ACES instead of the original ADX10 to ACES AP0.

Parameters:

  • apd

    (ndarray) –

    The input APD data.

  • inversion_gamma

    (float, default: 2.0 ) –

    The gamma to apply.

  • projector_kelvin

    (float | int, default: 6500 ) –

    White point in kelvin.

  • exp_to_xyz

    (ndarray | None, default: None ) –

    Matrix used for converting from layer exposure to CIE XYZ.

Returns:

  • ndarray –

    The transformed image in CIE XYZ.

bw_inversion 

bw_inversion(
    apd: ndarray, inversion_gamma: float = 2.0, projector_kelvin: float | int = 6500
) -> ndarray

Invert BW APD density values similar to apd_to_xyz.

Parameters:

  • apd

    (ndarray) –

    The input APD data.

  • inversion_gamma

    (float, default: 2.0 ) –

    The gamma to apply.

  • projector_kelvin

    (float | int, default: 6500 ) –

    White point in kelvin.

Returns:

  • ndarray –

    The transformed image in CIE XYZ.

compress_gamut 

compress_gamut(image: ndarray, gamut_compression: float | None = None) -> ndarray

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.

  • gamut_compression

    (float | None, default: None ) –

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

Returns:

  • ndarray –

    The compressed image.

output_color_transform 

output_color_transform(
    image: ndarray,
    output_gamut: COLOR_SPACE_KEYS = "Rec. 709",
    sat_adjust: float = 1.0,
    lut_size: int = 33,
    rolloff: bool = False,
    gamma_func: GAMMA_KEYS = "Gamma 2.4",
    gamut_compression: None | float = None,
) -> ndarray

Transform from XYZ to the target gamut and adjust the saturation. Saturation adjustment is performed in OkLch for visual uniformity. Gamut compression is performed to avoid visual artifacts. To preserve high performance the transforms are applied as a 2D xy LUT.

Parameters:

  • image

    (ndarray) –

    The XYZ image to transform.

  • output_gamut

    (COLOR_SPACE_KEYS, default: 'Rec. 709' ) –

    The name of the output color space.

  • sat_adjust

    (float, default: 1.0 ) –

    By what factor to multiply the saturation.

  • lut_size

    (int, default: 33 ) –

    The size of the LUT. Default is 33x33.

Returns:

  • ndarray –

    The transformed image in the output gamut.

output_transform 

output_transform(
    image: ndarray,
    output_gamut: COLOR_SPACE_KEYS,
    sat_adjust: float = 1.0,
    lut_size: int = 33,
    shadow_comp: float = 0.0,
    gamma_func: GAMMA_KEYS = "Gamma 2.4",
    rolloff: bool = False,
    gamut_compression: None | float = None,
) -> ndarray

Transform display referred linear CIE XYZ data to a display color space with some post-processing adjustments.

Parameters:

  • image

    (ndarray) –

    The image (or LUT) in linear CIE XYZ in the range [0, 1] to transform.

  • output_gamut

    (COLOR_SPACE_KEYS) –

    The output display gamut.

  • sat_adjust

    (float, default: 1.0 ) –

    How much to adjust the saturation. Unchanged for 1.0, BW for 0.0, and increased saturation for >1.0.

  • lut_size

    (int, default: 33 ) –

    The size of the 2D xy LUT used to apply output color transform.

  • shadow_comp

    (float, default: 0.0 ) –

    How much to compensate the shadows in the range [-1, 1].

  • gamma_func

    (GAMMA_KEYS, default: 'Gamma 2.4' ) –

    The gamma function to encode the output in.

Returns:

  • ndarray –

    The transformed image in the target gamma and gamut.

shadow_compensation 

shadow_compensation(image: ndarray, intensity: float = 0.0) -> 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

    (float, default: 0.0 ) –

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

Returns:

  • ndarray –

    The shadow compensated image.

simple_shadow_compensation 

simple_shadow_compensation(
    image: ndarray, intensity: float = 0.0, d_max: float = 2.0
) -> ndarray

A simpler shadow compensation function. For it is designed so that for an intensity of 1.0 we lift the shadow such that the black level is that of a print with density d_min. The functions is supposed to be simple, but still resemble the natural shadow roll-off of a photographic print. \(\sqrt{x^2 + black^2}\), where \(black = 10^{-d_{max}}\).

For negative intensities we apply the same function, but then shift and scale it so that 0% brightness stays at 0% and 100% stays at 100%.

Parameters:

  • image

    (ndarray) –

    The image (or LUT) to transform.

  • intensity

    (float, default: 0.0 ) –

    The intensity in the range [-1, 1], where 0 has no effect.

  • d_max

    (float, default: 2.0 ) –

    The maximal density that is achieved when intensity = 1.

Returns:

  • ndarray –

    The image with adjusted shadow compensation.