API Reference

`ColorImage`(args, *kwargs)	2D 3-channel color image using float32.
`MonoImage`(args, *kwargs)	2D monochromatic image using float32.
`Color`(args, *kwargs)	3-component float32 color type.
`Chromaticity`(args, *kwargs)	2-component float32 CIE xy chromaticity type.
`ColorSpace`()	Color space conversion.
`TransferFunction`()	Opto-electronic/electro-optical transfer functions.
`ToneMapping`()	Map high-dynamic-range values to low-dynamic-range.
`ColorCorrection`()	Apply color correction to an image.
`LookupTable`(size[, lattice, lut_format])	Color lookup table.
`WhiteBalance`()	Adjust white balance of an image.
`Spectral`()	Spectral color matching functions.
`Codec`()	Encoder/decoder for high-dynamic-range data.

class tinycio.ColorImage(*args, **kwargs)[source]

Bases: Tensor

2D 3-channel color image using float32. Convenience wrapper around a [C=3, H, W] sized PyTorch image tensor. This is the most hands-off abstraction, as it automatically handles color space conversion as needed.

Note

All transformative methods will create a new ColorImage instance without altering the current state. PyTorch methods and operations will work as expected but will return with the color space set to UNKNOWN. Exceptions include .clamp(), .lerp(), .minimum(), and .maximum(), which will retain the current state for convenience.

Note

Assumes size/shape [C, H, W] for both PyTorch tensor or NumPy array inputs.

Parameters:

param0 (torch.Tensor | numpy.ndarray) – [C=3, H, W] sized tensor/array
color_space (str | ColorSpace.Variant) – Color space of the image.

correct(cc)[source]

Apply color correction and return as new ColorImage.

Parameters:: cc (ColorCorrection) – Color correction object.
Returns:: New ColorImage with color correction applied.
Return type:: ColorImage

info(printout=True)[source]

Print or return a string describing the properties of the image for debugging.

Parameters:: printout – Print string if True, return string if False
Return type:: bool | str

static load(fp, color_space=Variant.UNKNOWN, graphics_format=GraphicsFormat.UNKNOWN)[source]

Load image from file

Parameters:

fp (str) – Image file path.
color_space (str | ColorSpace.Variant) – Image color space.
graphics_format (str | fsio.GraphicsFormat) – Image graphics format.

Returns:

New ColorImage loaded from file.

Return type:

ColorImage

lut(lut, lut_format=LUTFormat.UNKNOWN)[source]

Apply a LookupTable and return as new ColorImage.

Parameters:

lut (str | LookupTable) – LookupTable or LUT file path
lut_format – Format of the LUT, if loading from file.

Returns:

New ColorImage with LUT applied.

Return type:

ColorImage

save(fp, graphics_format=GraphicsFormat.UNKNOWN)[source]

Save image to file

Warning

This will overwrite existing files.

Parameters:

fp (str) – Image file path.
graphics_format (str | fsio.GraphicsFormat) – Image graphics format.

Returns:

True if successful

Return type:

bool

to_color_space(color_space)[source]

Convert the image to a different color space and return as new ColorImage.

Parameters:: color_space (str | ColorSpace.Variant) – the destination color space
Returns:: New ColorImage in designated color space.
Return type:: ColorImage

tone_map(tone_mapper, target_color_space=Variant.SRGB_LIN)[source]

Apply tone mapping and return as new ColorImage.

Note

Image will be returned and (if the TMO allows) tone mapped in the desired target color space. Any needed color space conversion will be handled automatically.

Parameters:

tone_mapper (str | ToneMapping.Variant) – Tone mapper to use.
target_color_space (str | ColorSpace.Variant) – The desired color space the image should be tone mapped for. Must be a scene-linear RGB color space. The image will be returned in this color space. If the TMO requires a different color space, the image will converted after tone mapping. Some TMOs may have been designed with linear sRGB in mind and may not perform as expected in a different color space.

Returns:

New tone mapped ColorImage.

Return type:

ColorImage

white_balance(source_white='auto', target_white=Illuminant.NONE)[source]

White balance the image and return as new ColorImage.

Note

Any needed color space conversion will be handled automatically.

Parameters:

source_white (str | Float2 | Chromaticity | int | Illuminant) –
Source white point - can be any of:
- string “auto” for automatic (wp_from_image())
- int for correlated color temperature (wp_from_cct())
- Illuminant or matching string (wp_from_illuminant())
- CIE 1931 xy coordinates as Float2/Chromaticity
target_white (str | Float2 | Chromaticity | int | Illuminant) –
Target white point - can be any of:
- int for correlated color temperature (wp_from_cct())
- Illuminant or matching string (wp_from_illuminant())
- CIE 1931 xy coordinates as Float2/Chromaticity

Returns:

New ColorImage with white balance applied.

Return type:

ColorImage

class tinycio.MonoImage(*args, **kwargs)[source]

Bases: Tensor

2D monochromatic image using float32. Convenience wrapper around a [C=1, H, W] sized PyTorch image tensor. This is a utility class that has no built-in functionality beyond enforcing a single channel for initial inputs. Can be converted to ColorImage with ColorImage(mono_im.repeat(3,1,1)).

Note

Assumes size/shape [C, H, W] for both PyTorch tensor or NumPy array inputs.

Parameters:: param0 (torch.Tensor | numpy.ndarray) – [C=1, H, W] sized tensor/array

info(printout=True)[source]

Print or return a string describing the properties of the image for debugging.

Parameters:: printout – Print string if True, return string if False
Return type:: bool | str

class tinycio.Color(*args, **kwargs)[source]

Bases: Float3

3-component float32 color type. Convenience wrapper around Float3, which is in turn a shape [3] numpy.ndarray. Example:

a = Color(1, 2, 3)
b = Color(torch.tensor([1, 2, 3]))
c = Color(numpy.array([1, 2, 3]))
d = Color(torch.tensor([1, 2, 3]).unsqueeze(-1).unsqueeze(-1))
numpy.array_equal(a,b) & numpy.array_equal(b,c) & numpy.array_equal(c,d) # True

Note

This data type is color space agnostic until a ColorImage is requested. Swizzling is allowed, but a numeric type will be returned if the number of swizzled components is not 3.

Parameters:

option1_param0 (float) – x/r component
option1_param1 (float) – y/g component
option1_param2 (float) – z/b component
option2_param0 (float) – value of every component
option3_param0 (torch.Tensor | numpy.ndarray | Float3 | list | tuple) – 3-component tensor, array, list or tuple (a 2D tensor/array image is allowed if the number of pixel values is 1)

convert(source, destination)[source]

Convert color value from one color space to another.

Parameters:

source (str | ColorSpace.Variant) – Color space to convert from.
destination (str | ColorSpace.Variant) – Color space to convert to.

Return type:

Color

image(color_space=Variant.UNKNOWN)[source]

Unsqueeze to a [C=3, H, W] sized PyTorch image tensor.

Parameters:: color_space (str | ColorSpace.Variant) – Color space of the image.
Returns:: Expanded [C=3, H=1, W=1] float32 “image” tensor.
Return type:: ColorImage

class tinycio.Chromaticity(*args, **kwargs)[source]

Bases: Float2

2-component float32 CIE xy chromaticity type. Convenience wrapper around Float2, which is in turn a shape [2] numpy.ndarray.

Parameters:

option1_param0 (float) – x component
option1_param1 (float) – y component
option2_param0 (float) – Value of both components.
option3_param0 (torch.Tensor | numpy.ndarray | Float2) – 2-component tensor or array. (a 2D tensor/array image is allowed if the number of pixel values is 1)

to_xyy(luminance=1.0)[source]

Returns CIE xyY color

Parameters:: luminance (float) – Y luminance
Returns:: CIE xyY color
Return type:: Color

to_xyz(luminance=1.0)[source]

Returns CIE XYZ color

Parameters:: luminance (float) – Y luminance
Returns:: CIE XYZ color
Return type:: Color

class tinycio.ColorSpace[source]

Bases: object

Color space conversion. Applies OETFs and EOTFs as needed but omits tonemapping. Cylindrical transformations are treated as distinct color spaces. Example:

cs_in = ColorSpace.Variant.SRGB_LIN
cs_out = ColorSpace.Variant.OKLAB
oklab_image = ColorSpace.convert(srgb_image, source=cs_in, destination=cs_out)

class Variant(value)[source]

Bases: IntEnum

Color space enum. For a list of available options, see Color spaces.

classmethod convert(im, source, destination)[source]

Change the color space of an image. Cylindrical transformations HSV/HSL are treated as their own color spaces and assumed to be relative to sRGB linear. Unless otherwise noted or required by specification (e.g. ACES), we assume D65 white point.

Warning

Tone mapping is not automatically included. Thus, converting a wide-gamut color space to one with a narrower gamut, or converting HDR values to a nominally LDR-designated color space will not automatically remap out-of-gamut color to in-gamut or reduce dynamic range. It will likely yield out-of-gamut (positive of negative) or out-of-range values. These values should still, at some point, be tone mapped or clamped to the desired output range.

Warning

Cylindrical transformations (HSL, HSV) should be given input in [0, 1] linear sRGB range (or equivalent). This is not strictly enforced but input outside this range may yield unpredictable results or NaN values.

Parameters:

im (torch.Tensor | ColorImage) – [C=3, H, W] image tensor
source (Variant) – color space to convert from
destination (Variant) – color space to convert to

Returns:

image tensor in designated color space

Return type:

torch.Tensor

class tinycio.TransferFunction[source]

Bases: object

Opto-electronic/electro-optical transfer functions. Example:

im_srgb = TransferFunction.srgb_oetf(im_linear)

Note

These transfer functions are applied automatically by ColorSpace.convert when appropriate, but can instead be used explicitly.

Note

Out-of-gamut values will be accepted, but the values returned may not be well-defined or meaningful. The goal is only to keep them consistent and out of range.

static dcip3_eotf(im)[source]

DCI P3 electro-optical transfer function (DCI P3 gamma to linear)

Parameters:: im (torch.Tensor) – DCI P3 image tensor
Returns:: linear P3 gamut image tensor
Return type:: torch.Tensor

static dcip3_oetf(im)[source]

DCI P3 opto-electronic transfer function (linear to DCI P3 gamma)

Parameters:: im (torch.Tensor) – linear P3 gamut image tensor
Returns:: DCI P3 image tensor
Return type:: torch.Tensor

static log_c_eotf(im)[source]

LogC electro-optical transfer function

Parameters:: im (torch.Tensor) – LogC encoded image tensor
Returns:: linear image tensor
Return type:: torch.Tensor

static log_c_oetf(im)[source]

LogC opto-electronic transfer function

Parameters:: im (torch.Tensor) – linear image tensor
Returns:: LogC encoded image tensor
Return type:: torch.Tensor

static rec2020_eotf(im)[source]

Rec. 2020 electro-optical transfer function (Rec. 2020 gamma to linear)

Parameters:: im (torch.Tensor) – Rec. 2020 image tensor
Returns:: linear Rec. 2020 gamut image tensor
Return type:: torch.Tensor

static rec2020_oetf(im)[source]

Rec. 2020 opto-electronic transfer function (linear to Rec. 2020 gamma)

Parameters:: im (torch.Tensor) – linear Rec. 2020 gamut image tensor
Returns:: Rec. 2020 image tensor
Return type:: torch.Tensor

static rec709_eotf(im)[source]

Rec. 709 electro-optical transfer function (Rec. 709 gamma to linear sRGB)

Parameters:: im (torch.Tensor) – Rec. 709 image tensor
Returns:: linear sRGB image tensor (same primaries)
Return type:: torch.Tensor

static rec709_oetf(im)[source]

Rec. 709 opto-electronic transfer function (linear sRGB to Rec. 709 gamma)

Parameters:: im (torch.Tensor) – linear sRGB image tensor (same primaries)
Returns:: Rec. 709 image tensor
Return type:: torch.Tensor

static s_log_eotf(im)[source]

S-Log electro-optical transfer function

Parameters:: im (torch.Tensor) – S-Log encoded image tensor
Returns:: linear image tensor
Return type:: torch.Tensor

static s_log_oetf(im)[source]

S-Log opto-electronic transfer function

Parameters:: im (torch.Tensor) – linear image tensor
Returns:: S-Log encoded image tensor
Return type:: torch.Tensor

static srgb_eotf(im)[source]

sRGB electro-optical transfer function (sRGB gamma to linear sRGB)

Parameters:: im (torch.Tensor) – sRGB image tensor
Returns:: linear sRGB image tensor
Return type:: torch.Tensor

static srgb_oetf(im)[source]

sRGB opto-electronic transfer function (linear sRGB to sRGB gamma)

Parameters:: im (torch.Tensor) – linear sRGB image tensor
Returns:: sRGB image tensor
Return type:: torch.Tensor

class tinycio.ToneMapping[source]

Bases: object

Map high-dynamic-range values to low-dynamic-range. LDR is typically sRGB in [0, 1] range. Example:

tm = ToneMapping.Variant.HABLE
tonemapped_image = ToneMapping.apply(input_im, tone_mapper=tm)

class Variant(value)[source]

Bases: IntEnum

Tone mapper enum. Available options are:

- NONE
- CLAMP
- AGX
- AGX_PUNCHY
- HABLE
- REINHARD
- ACESCG

classmethod apply(im, tone_mapper)[source]

Apply tone mapping to HDR image tensor. Input data is expected to be in the correct color space for the chosen tone mapper.

Note

ACESCG tone mapping is performed on AP1 primaries and expects input in the ACESCG color space. All other tone mappers expect SRGB_LIN. The tone_map() method of ColorImage handles this conversion automatically.

Parameters:

im (torch.Tensor) – [C=3, H, W] sized image tensor
tone_mapper (ToneMapping.Variant) – tonemapper to be used

Returns:

image tensor

Return type:

torch.Tensor

class tinycio.ColorCorrection[source]

Bases: object

Apply color correction to an image. Example:

cc = ColorCorrection()
cc.set_contrast(1.3)
im_corrected = cc.apply(im_cc)

Note

Any hue and saturation parameters use perceptually linear values of the OKHSV color space.

apply(im)[source]

Apply color correction to image tensor in ACEScc color space.

Parameters:: im (torch.Tensor) – Image tensor sized [C=3, H, W] in ACEScc color space.
Returns:: Color corrected image tensor.
Return type:: torch.Tensor

bake_lut(lut_size=64, lut_color_space=Variant.ACESCC)[source]

Bake color correction to a CUBE LUT.

Note

Regardless of working color space, the LUT will be limited to a [0, 1] range of values.

Parameters:

lut_size (int) – Size of the LUT. Range [4, 512].
lut_color_space (str | Variant) – The color space that the LUT should be baked for, as string or IntEnum.

Returns:

The baked LUT.

Return type:

LookupTable

fit_to_image(im_source, im_target, steps=500, learning_rate=0.003, strength=1.0, allow_hue_shift=False, fit_height=512, fit_width=512, device=None, context=None)[source]

Perform gradient descent on the color correction settings, so that the appearance of the source image matches the target.

Note

Images need to be in ACEScc color space.

Parameters:

im_source (torch.Tensor | ColorImage) – Source image tensor in ACEScc color space. Values must be in range [0, 1].
im_target (torch.Tensor | ColorImage) – Target image tensor in ACEScc color space.
steps (int) – Number of optimization steps.
learning_rate (float) – Learning rate for gradient descent.
strength (float) – Strength of the effect in range [0, 1].
allow_hue_shift (bool) – Allow the optimizer to shift the hue.
fit_height (int) – Image tensors will be interpolated to this height for evaluation.
fit_width (int) – Image tensors will be interpolated to this width for evaluation.
context (callable) – The Python context to use (see util.progress_bar()).
device (str) – Device for gradient descent (if None will use input tensor device).

Returns:

True when completed

Return type:

ColorCorrection

info(printout=True)[source]

Print or return a string describing the current color correction settings.

Parameters:: printout (bool) – Print string if True, return string if False
Return type:: bool | str

classmethod load(fp, force=False)[source]

Load color correction settings from toml file.

Parameters:

fp (str) – File path of toml file to be loaded.
force (bool) – If set to True, ignores version mismatch forces loading the file.

Returns:

ColorCorrection object with settings loaded.

Return type:

ColorCorrection

save(fp)[source]

Save color correction settings to a toml file.

Parameters:: fp (str) – Output file path of toml file to be saved.
Returns:: True if successful.
Return type:: bool

Warning

This will overwrite existing files.

set_color_filter(hue=0.0, saturation=0.0)[source]

Set a color filter. Idempotent assignment.

Parameters:

hue (float) – Filter hue - perceptually linear (the H from OKHSV). Range [0, 1].
saturation (float) – Filter saturation - perceptually linear (the S from OKHSV). Range [0, 1].

Returns:

True if successful

Return type:

bool

set_contrast(contrast=1.0)[source]

Set the contrast. Idempotent assignment.

Parameters:: contrast (float) – Contrast. Range [0, 4].
Returns:: True if successful
Return type:: bool

set_exposure_bias(exposure_bias=0.0)[source]

Set the exposure bias. Idempotent assignment.

Parameters:: exposure_bias (float) – Exposure bias in f-stops. Range [-5, 5].
Returns:: True if successful
Return type:: bool

set_highlight_color(hue=0.0, saturation=0.0)[source]

Set the highlight color. Uses OKHSV model - value fixed at 1. Idempotent assignment.

Parameters:

hue (float) – Highlight hue in range [0, 1] - perceptually linear (the H from OKHSV)
saturation (float) – Highlight saturation in range [0, 1] - perceptually linear (the S from OKHSV)

Returns:

True if successful

Return type:

bool

set_highlight_offset(offset=0.0)[source]

Set the shadow offset in range [-2, 2]. Idempotent assignment.

Parameters:: offset (float) – Highlight offset.
Returns:: True if successful
Return type:: bool

set_hue_delta(hue_delta=0.0)[source]

Set the hue delta, shifting an image’s hues. Idempotent assignment.

Parameters:: hue_delta (float) – Amount of hue shift - perceptually linear. Range [-1, 1].
Returns:: True if successful
Return type:: bool

set_midtone_color(hue=0.0, saturation=0.0)[source]

Set the midtone color. Uses OKHSV model - value fixed at 1. Idempotent assignment.

Parameters:

hue (float) – Midtone hue in range [0, 1] - perceptually linear (the H from OKHSV)
saturation (float) – Midtone saturation in range [0, 1] - perceptually linear (the S from OKHSV)

Returns:

True if successful

Return type:

bool

set_midtone_offset(offset=0.0)[source]

Set the shadow offset in range [-2, 2]. Idempotent assignment.

Parameters:: offset (float) – Midtone offset.
Returns:: True if successful
Return type:: bool

set_saturation(saturation=1.0)[source]

Set the color saturation. Idempotent assignment.

Parameters:: saturation (float) – Amount of saturation. Range [0, 4].
Returns:: True if successful
Return type:: bool

set_shadow_color(hue=0.0, saturation=0.0)[source]

Set the shadow color. Uses OKHSV model - value fixed at 1. Idempotent assignment.

Parameters:

hue (float) – Shadow hue in range [0, 1] - perceptually linear (the H from OKHSV)
saturation (float) – Shadow saturation in range [0, 1] - perceptually linear (the S from OKHSV)

Returns:

True if successful

Return type:

bool

set_shadow_offset(offset=0.0)[source]

Set the shadow offset in range [-2, 2]. Idempotent assignment.

Parameters:: offset (float) – Shadow offset.
Returns:: True if successful
Return type:: bool

class tinycio.LookupTable(size, lattice=None, lut_format=LUTFormat.CUBE_3D)[source]

Bases: object

Color lookup table. Example:

lut = LookupTable.get_negative()
im_negative = lut.apply(im)

Parameters:

size (int) – Size of the LUT.
lattice (torch.Tensor) – Lattice as tensor (defaults to linear).
lut_format (LUTFormat) – Format of the LUT.

apply(im)[source]

Apply LUT to image tensor.

Parameters:: im (torch.Tensor | ColorImage) – Input image tensor
Returns:: Image tensor with LUT applied
Return type:: torch.Tensor

fit_to_image(im_source, im_target, steps=500, learning_rate=0.003, strength=1.0, fit_height=512, fit_width=512, device='cuda', context=None)[source]

Perform gradient descent on the lattice, so that the appearance of the source image matches the target.

Parameters:

im_source (torch.Tensor | ColorImage) – Source image tensor. Values must be in range [0, 1].
im_target (torch.Tensor | ColorImage) – Target image tensor.
steps (int) – Number of optimization steps.
learning_rate (float) – Learning rate for gradient descent.
strength (float) – Strength of the effect in range [0, 1].
fit_height (int) – Image tensors will be interpolated to this height for evaluation.
fit_width (int) – Image tensors will be interpolated to this width for evaluation.
device (Union[str, None]) – Device for gradient descent (if None will use input tensor device).
context (callable)

Returns:

True when completed

Return type:

bool

classmethod get_empty(size=32, lut_format=LUTFormat.CUBE_3D)[source]

Returns empty LUT. All values mapped to 0.

Parameters:

size (int) – Size of the LUT.
lut_format (LUTFormat) – Format of the LUT.

Return type:

LookupTable

classmethod get_linear(size=32, lut_format=LUTFormat.CUBE_3D)[source]

Returns linear LUT. Has no effect: when applied, output matches input ([0, 1] range).

Parameters:

size (int) – Size of the LUT.
lut_format (LUTFormat) – Format of the LUT.

Return type:

LookupTable

classmethod get_negative(size=32, lut_format=LUTFormat.CUBE_3D)[source]

Returns negative LUT. Output is inverted ([0, 1] range).

Parameters:

size (int) – Size of the LUT.
lut_format (LUTFormat) – Format of the LUT.

Return type:

LookupTable

classmethod get_random(size=32, lut_format=LUTFormat.CUBE_3D)[source]

Returns random LUT. Everything mapped to random values ([0, 1] range).

Parameters:

size (int) – Size of the LUT.
lut_format (LUTFormat) – Format of the LUT.

Return type:

LookupTable

classmethod load(fp, lut_format=LUTFormat.UNKNOWN)[source]

Load LUT from file.

Parameters:

fp (str) – File path.
lut_format (LUTFormat) – Format of the LUT.

Return type:

LookupTable

save(fp, lut_format=LUTFormat.UNKNOWN)[source]

Save LUT to file.

Warning

This will overwrite existing files.

Parameters:

fp (str) – File path.
lut_format (LUTFormat) – Format of the LUT.

class tinycio.WhiteBalance[source]

Bases: object

Adjust white balance of an image. Example:

source_white = WhiteBalance.wp_from_image(input_image)
target_white = WhiteBalance.wp_from_illuminant(WhiteBalance.Illuminant.NORTH_SKY)
white_balanced_image = WhiteBalance.apply(input_image, source_white, target_white)

class Illuminant(value)[source]

Bases: IntEnum

CIE 1931 2° standard illuminant. Available options are:

- NONE
- A (INCANDESCENT, TUNGSTEN)
- D50 (HORIZON)
- D55 (MIDMORNING)
- D65 (DAYLIGHT_NOON)
- D75 (NORTH SKY)
- D93 (BLUE_PHOSPHOR)
- E (EQUAL_ENERGY)
- F1 (FLUORESCENT_DAYLIGHT1)
- F2 (FLUORESCENT_COOL_WHITE)
- F3 (FLUORESCENT_WHITE)
- F4 (FLUORESCENT_WARM_WHITE)
- F5 (FLUORESCENT_DAYLIGHT2)
- F6 (FLUORESCENT_LIGHT_WHITE)
- F7 (D65_SIMULATOR, DAYLIGHT_SIMULATOR)
- F8 (D50_SIMULATOR, SYLVANIA_F40)
- F9 (FLOURESCENT_COOL_WHITE_DELUXE)
- F10 (PHILIPS_TL85, ULTRALUME_50)
- F11 (PHILIPS_TL84, ULTRALUME_40)
- F12 (PHILIPS_TL83, ULTRALUME_30)
- LED_B1 (PHOSPHOR_CONVERTED_BLUE1)
- LED_B2 (PHOSPHOR_CONVERTED_BLUE2)
- LED_B3 (PHOSPHOR_CONVERTED_BLUE3)
- LED_B4 (PHOSPHOR_CONVERTED_BLUE4)
- LED_B5 (PHOSPHOR_CONVERTED_BLUE5)
- LED_BH1
- LED_RGB1
- LED_V1 (LED_VIOLET1)
- LED_V2 (LED_VIOLET2)

static apply(im_lms, source_white, target_white)[source]

Apply white balance.

Parameters:

im_lms (torch.Tensor) – Image tensor in LMS color space
source_white (torch.Tensor) – Source white point in LMS space
target_white (torch.Tensor) – Target white point in LMS space

Returns:

White balanced image tensor

Return type:

torch.Tensor

static wp_from_cct(cct)[source]

Compute CIE xy chromaticity coordinates (white point) from correlated color temperature.

Parameters:: cct (int) – Correlated color temperature in range [4000, 25000]
Returns:: White point coordinates (CIE xy)
Return type:: Float2

classmethod wp_from_illuminant(illuminant)[source]

Look up chromaticity coordinates (white point) of a CIE 1931 2° standard illuminant.

Parameters:: illuminant (Illuminant) – Standard illuminant
Returns:: White point coordinates (CIE xy)
Return type:: Float2

static wp_from_image(im_xyz)[source]

Estimate the dominant illuminant of an environment map or a target image directly and return its approximate CIE xy chromaticity coordinates (white point).

Warning

This is a lazy method that just averages the pixels in the image tensor. There is no spherical mapping, nor PCA, nor any serious attempt to analyze the image.

Parameters:: im_xyz (torch.Tensor | ColorImage) – Image tensor in CIE XYZ color space
Returns:: Estimated white point coordinates (CIE xy)
Return type:: Float2

class tinycio.Spectral[source]

Bases: object

Spectral color matching functions. Example:

xyz_col = Spectral.wl_to_xyz(550)

classmethod cm_table(normalize_xyz=False)[source]

Returns color matching table as tensor of size [81, 3]. The table contains CIE XYZ values, arranged by wavelength, in increments of 5nm, from 380nm to 780nm.

Parameters:: normalize_xyz (bool) – Normalize XYZ color, such that X=X/(X+Y+Z), etc
Returns:: Color matching function table
Return type:: torch.Tensor

classmethod wl_to_srgb(wl, normalize=False, lum_scale=0.25)[source]

Wavelength (nm) to normalized, approximate sRGB color, clamped to [0, 1] range, with sRGB gamma curve.

Note

Wolfram Alpha doesn’t quite agree, but it’s rather close. This produces a plausible-looking spectrum, but there is probably some missing (pre?) normalization step. Take the RGB outputs with a grain of salt.

Parameters:

wl (float) – wavelength in nm
normalize (bool) – normalize sRGB color
lum_scale (float)

Returns:

sRGB linear color

Return type:

Float3

classmethod wl_to_srgb_linear(wl, normalize=False, lum_scale=0.25)[source]

Wavelength (nm) to normalized, approximate linear sRGB color, clamped to [0, 1] range.

Parameters:

wl (float) – wavelength in nm
normalize (bool) – normalize sRGB color
lum_scale (float)

Returns:

sRGB linear color

Return type:

Float3

classmethod wl_to_xyz(wl)[source]

Wavelength (nm) to CIE XYZ color, linearly interpolated. Precision is limited to interpolated 5nm increments.

Note

These coordinates will often fall outside the sRGB gamut. Direct color space conversion will yield invalid sRGB values.

Parameters:: wl (float) – wavelength in nm
Returns:: CIE XYZ color
Return type:: Float3

class tinycio.Codec[source]

Bases: object

Encoder/decoder for high-dynamic-range data. Example:

encoded_image = Codec.logluv_encode(hdr_rgb_image)

classmethod logluv_decode(im)[source]

Decode LOGLUV to HDR floating point RGB data.

Note

4 channels in, 3 channels out.

Parameters:: im (torch.Tensor) – LOGLUV encoded [C=4, H, W] sized image tensor (4 channels)
Returns:: Decoded HDR image tensor (3 channels)
Return type:: torch.Tensor

classmethod logluv_encode(im)[source]

Encode HDR floating point RGB data to LOGLUV for 32bpp (RGBA) image file.

Note

3 channels in, 4 channels out.

Parameters:: im (torch.Tensor | ColorImage) – HDR [C=3, H, W] sized image tensor
Returns:: LOGLUV encoded image tensor (4 channels)
Return type:: torch.Tensor