util module

Warning

Using the color functions here directly is not advised, if an interface exists in the root module.

`version`()	Get current tinycio version.
`version_check_minor`(ver_str)	Verify tinycio version.
`remap`(x, from_start, from_end, to_start, to_end)	Linearly remap scalar or tensor.
`remap_to_01`(x, start, end)	Remap value to [0, 1] range.
`remap_from_01`(x, start, end)	Remap [0, 1] value back to specified range.
`smoothstep`(edge0, edge1, x)	Smooth Hermite interpolation between 0 and 1.
`softsign`(x)	Smooth nonlinearity.
`fract`(x)	Get the fractional part of input (x - floor(x)).
`serialize_tensor`(val)	Convert a tensor into a float or list of floats.
`trilinear_interpolation`(im_3d, indices)	Interpolate 3D image tensor.
`fitted_polynomial_curve_6th_order`(x, fit)	Evaluate 6th-order polynomial curve.
`fitted_polynomial_curve_7th_order`(x, fit)	Evaluate 7th-order polynomial curve.
`progress_bar`()	Context to display a progressbar with tqdm.
`apply_gamma`(im, gamma)	Apply arbitrary gamma correction.
`apply_hue_oklab`(im_oklab, hue_delta)	Manually shift hue by a -1 to +1 delta value.
`srgb_luminance`(im_srgb)	Return relative luminance of linear sRGB image.
`col_hsv_to_rgb`(hsv)	Convert HSV color to RGB.
`col_rgb_to_hsv`(rgb)	Convert RGB color to HSV.
`col_oklab_to_linear_srgb`(lab)	Convert OKLAB color to linear sRGB.
`col_linear_srgb_to_oklab`(srgb)	Convert linear sRGB color to OKLAB.
`col_okhsv_to_srgb`(hsv)	Convert OKHSV color to linear sRGB.
`col_srgb_to_okhsv`(srgb)	Convert linear sRGB color to OKHSV.
`col_okhsl_to_srgb`(hsl)	Convert OKHSL color to linear sRGB.
`col_srgb_to_okhsl`(srgb)	Convert linear sRGB color to OKHSL.
`asc_cdl`(im[, slope, offset, power, eps])	Apply ASC DCL
`lgg`(im[, lift, gamma, gain, eps])	Apply Lift/Gamma/Gain
`xy_to_XYZ`(xy[, luminance])	Convert xy chromaticity to CIE XYZ.
`xyz_mat_from_primaries`(rgb, wp)	Get XYZ transform for arbitrary RGB primaries.
`mat_von_kries_cat`(src_wp_xy, dst_wp_xy, ...)	Compute simple raw LMS Von Kries CAT matrix.

tinycio.util.version()[source]

Get current tinycio version. :return: version string (“major.minor.patch”)

Return type:: str

tinycio.util.version_check_minor(ver_str)[source]

Verify tinycio version. Check if the major and minor version of ver_str matches current.

Parameters:: ver_str (str) – Version string to compare
Returns:: True if major.minor match, else False
Return type:: bool

tinycio.util.remap(x, from_start, from_end, to_start, to_end)[source]

Linearly remap scalar or tensor.

Parameters:

x (float | torch.Tensor) – Input value or tensor
from_start (float) – Start of input range
from_end (float) – End of input range
to_start (float) – Start of target range
to_end (float) – End of target range

Returns:

Remapped and clamped value

Return type:

float | torch.Tensor

tinycio.util.remap_to_01(x, start, end)[source]

Remap value to [0, 1] range.

Parameters:

x (float | torch.Tensor) – Input value or tensor
start (float) – Start of original range
end (float) – End of original range

Returns:

Normalized value clamped to [0, 1]

Return type:

float | torch.Tensor

tinycio.util.remap_from_01(x, start, end)[source]

Remap [0, 1] value back to specified range.

Parameters:

x (float | torch.Tensor) – Normalized value or tensor
start (float) – Target range start
end (float) – Target range end

Returns:

Rescaled value clamped to [start, end]

Return type:

float | torch.Tensor

tinycio.util.smoothstep(edge0, edge1, x)[source]

Smooth Hermite interpolation between 0 and 1. For x in [edge0, edge1].

Parameters:

edge0 (float) – Lower bound of transition
edge1 (float) – Upper bound of transition
x (torch.Tensor) – Input tensor

Returns:

Smoothly interpolated tensor

Return type:

torch.Tensor

tinycio.util.softsign(x)[source]

Smooth nonlinearity. x / (1 + |x|), useful for range compression.

Parameters:: x (float | torch.Tensor) – Input scalar or tensor
Returns:: Softsign result
Return type:: float | torch.Tensor

tinycio.util.fract(x)[source]

Get the fractional part of input (x - floor(x)).

Parameters:: x (float | torch.Tensor) – Input scalar or tensor
Returns:: Fractional part
Return type:: float | torch.Tensor

tinycio.util.serialize_tensor(val)[source]

Convert a tensor into a float or list of floats.

Parameters:: val (torch.Tensor) – Tensor to serialize
Returns:: Scalar if 1-element tensor, else flattened list
Return type:: Union[float, List[float]]

tinycio.util.trilinear_interpolation(im_3d, indices)[source]

Interpolate 3D image tensor.

Parameters:

im_3d (torch.Tensor) – Input 3D image tensor of shape (C, D, H, W).
indices (Union[ColorImage, torch.Tensor]) – Indices into the tensor.

Returns:

Interpolated color values.

Return type:

torch.Tensor

tinycio.util.fitted_polynomial_curve_6th_order(x, fit)[source]

Evaluate 6th-order polynomial curve.

Parameters:

x (torch.Tensor) – Input tensor
fit (torch.Tensor) – Coefficient tensor of shape [7]

Returns:

Evaluated tensor

Return type:

torch.Tensor

tinycio.util.fitted_polynomial_curve_7th_order(x, fit)[source]

Evaluate 7th-order polynomial curve.

Parameters:

x (torch.Tensor) – Input tensor
fit (torch.Tensor) – Coefficient tensor of shape [8]

Returns:

Evaluated tensor

Return type:

torch.Tensor

tinycio.util.progress_bar()[source]: Context to display a progressbar with tqdm.

tinycio.util.apply_gamma(im, gamma)[source]

Apply arbitrary gamma correction.

Parameters:

im (torch.Tensor | ColorImage) – Image tensor
gamma (float) – Gamma correction (should be in the range [0.1, 10.0])

Returns:

Image tensor with correction applied

Return type:

torch.Tensor

tinycio.util.apply_hue_oklab(im_oklab, hue_delta)[source]

Manually shift hue by a -1 to +1 delta value.

Parameters:

im_oklab (torch.Tensor | ColorImage) – Image tensor in OKLAB color space
hue_delta (float) – Hue shift value in the range [-1., 1.]

Returns:

Image tensor in OKLAB color space with adjusted hue

Return type:

torch.Tensor

tinycio.util.srgb_luminance(im_srgb)[source]

Return relative luminance of linear sRGB image.

Parameters:: im_srgb (torch.Tensor | ColorImage) – [C=3, H, W] color image tensor in sRGB color space
Returns:: [C=1, H, W] image tensor
Return type:: torch.Tensor

tinycio.util.col_hsv_to_rgb(hsv)[source]

Convert HSV color to RGB.

Parameters:: hsv (Float3 | Color) – HSV color
Return type:: Float3

tinycio.util.col_rgb_to_hsv(rgb)[source]

Convert RGB color to HSV.

Parameters:: rgb (Float3 | Color) – RGB color
Return type:: Float3

tinycio.util.col_oklab_to_linear_srgb(lab)[source]

Convert OKLAB color to linear sRGB.

Parameters:: lab (Float3 | Color) – OKLAB color
Return type:: Float3

tinycio.util.col_linear_srgb_to_oklab(srgb)[source]

Convert linear sRGB color to OKLAB.

Parameters:: srgb (Float3 | Color) – linear sRGB color
Return type:: Float3

tinycio.util.col_okhsv_to_srgb(hsv)[source]

Convert OKHSV color to linear sRGB.

Parameters:: hsv (Float3 | Color) – OKHSV color
Return type:: Float3

tinycio.util.col_srgb_to_okhsv(srgb)[source]

Convert linear sRGB color to OKHSV.

Parameters:: srgb (Float3 | Color) – linear sRGB color
Return type:: Float3

tinycio.util.col_okhsl_to_srgb(hsl)[source]

Convert OKHSL color to linear sRGB.

Parameters:: hsl (Float3 | Color) – OKHSL color
Return type:: Float3

tinycio.util.col_srgb_to_okhsl(srgb)[source]

Convert linear sRGB color to OKHSL.

Parameters:: srgb (Float3 | Color) – linear sRGB color
Return type:: Float3

tinycio.util.asc_cdl(im, slope=1.0, offset=0.0, power=1.0, eps=1e-07)[source]

Apply ASC DCL

Parameters:

im (torch.Tensor | ColorImage) – Image tensor
slope (float) – slope
offset (float) – offset
power (float) – power
eps (float) – epsilon

Returns:

Image tensor with correction applied

tinycio.util.lgg(im, lift=1.0, gamma=1.0, gain=1.0, eps=1e-07)[source]

Apply Lift/Gamma/Gain

Parameters:

im (torch.Tensor | ColorImage) – Image tensor
lift (float) – slope
gamma – offset
gain (float) – power
eps (float) – epsilon

Returns:

Image tensor with correction applied

tinycio.util.xy_to_XYZ(xy, luminance=1.0)[source]

Convert xy chromaticity to CIE XYZ. (CIE 1931 2°)

Parameters:

xy (tuple | Float2 | Chromaticity) – xy chromaticity
luminance (float) – Y luminance

Returns:

CIE XYZ color

Return type:

tuple

tinycio.util.xyz_mat_from_primaries(rgb, wp)[source]

Get XYZ transform for arbitrary RGB primaries. (CIE 1931 2°)

Parameters:

rgb (list[tuple | Float2 | Chromaticity]) – List of RGB chromaticities
wp (tuple | Float2 | Chromaticity) – white point chromaticity

Returns:

3×3 RGB to XYZ matrix

Return type:

numpy.ndarray

tinycio.util.mat_von_kries_cat(src_wp_xy, dst_wp_xy, cs_to_lms, lms_to_cs)[source]

Compute simple raw LMS Von Kries CAT matrix.

Parameters:

src_wp_xy (list[tuple | Float2 | Chromaticity]) – Source white point
dst_wp_xy (list[tuple | Float2 | Chromaticity]) – Destination/target white point
cs_to_lms (numpy.ndarray) – 3×3 to-LMS matrix
lms_to_cs (numpy.ndarray) – 3×3 from-LMS matrix

Returns:

3×3 chromatic adaptation transform matrix

Return type:

numpy.ndarray