6.4. tracer.color Submodule¶

6.4.1. tracer.color.tools¶

optrace.tracer.color.tools.blackbody(wl, T=6504.0)¶

Get the spectral radiance of a planck blackbody curve. Unit is W/(sr m³).

Parameters:

wl (ndarray) – wavelength vector in nm (numpy 1D array)
T (float) – blackbody temperature in Kelvin (float)

Returns:

blackbody curve values (numpy 1D array)

Return type:

ndarray

optrace.tracer.color.tools.normalized_blackbody(wl, T=6504.0)¶

Get the spectral power density of a planck blackbody curve. The values are normalized so that the highest value in the visible region, defined by global_options.wavelength_range is equal to 1.

Parameters:

wl (ndarray) – wavelength vector in nm (numpy 1D array)
T (float) – blackbody temperature in Kelvin (float)

Returns:

blackbody curve values (numpy 1D array)

Return type:

ndarray

optrace.tracer.color.tools.wavelengths(N)¶

Get a wavelength range array with equal spacing and N points. The first and last wavelength are specified by global_options.wavelength_range

Parameters:: N (int) – number of values
Returns:: wavelength vector in nm, 1D numpy array
Return type:: ndarray

6.4.2. tracer.color.illuminants¶

optrace.tracer.color.illuminants.a_illuminant(wl)¶

A standard illuminant (CIE Colorimetry, 3. Edition, 2004). Typical, domestic, tungsten-filament lighting. Color temperature of 2856K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.c_illuminant(wl)¶

C standard illuminant (CIE Colorimetry, 3. Edition, 2004). Obsolete, average / north sky daylight. Color temperature of 6774K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.d50_illuminant(wl)¶

D50 standard illuminant (CIE Colorimetry, 3. Edition, 2004). Horizon light. Color temperature of 5003K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.d55_illuminant(wl)¶

D55 standard illuminant (CIE Colorimetry, 3. Edition, 2004). Mid-morning/mid-afternoon daylight. Color temperature of 5503K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.d65_illuminant(wl)¶

D65 standard illuminant (CIE Colorimetry, 3. Edition, 2004). Noon daylight. Color temperature of 6504K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.d75_illuminant(wl)¶

D75 standard illuminant (CIE Colorimetry, 3. Edition, 2004). North sky daylight. Color temperature of 7504K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.e_illuminant(wl)¶

E standard illuminant (CIE Colorimetry, 3. Edition, 2004). Equal energy radiator with a color temperature of 5455K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.f11_illuminant(wl)¶

F11 standard illuminant (CIE Colorimetry, 3. Edition, 2004). Narrowband triband fluorescent lamp in R, G, B regions. Color temperature of 4000K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.f2_illuminant(wl)¶

F2 standard illuminant (CIE Colorimetry, 3. Edition, 2004). Fluorescent lamp with two semi-broadband emissions. Color temperature of 4230K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.f7_illuminant(wl)¶

F7 standard illuminant (CIE Colorimetry, 3. Edition, 2004). Broadband fluorescent lamp with multiple phosphors. Color temperature of 6500K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.led_b1_illuminant(wl)¶

LED-B1 standard illuminant (CIE Colorimetry, 4th Edition, 2018) Blue excited phosphor type LED with a color temperature of 2733K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.led_b2_illuminant(wl)¶

LED-B2 standard illuminant (CIE Colorimetry, 4th Edition, 2018) Blue excited phosphor type LED with a color temperature of 2998K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.led_b3_illuminant(wl)¶

LED-B3 standard illuminant (CIE Colorimetry, 4th Edition, 2018) Blue excited phosphor type LED with a color temperature of 4103K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.led_b4_illuminant(wl)¶

LED-B4 standard illuminant (CIE Colorimetry, 4th Edition, 2018) Blue excited phosphor type LED with a color temperature of 5109K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.led_b5_illuminant(wl)¶

LED-B5 standard illuminant (CIE Colorimetry, 4th Edition, 2018) Blue excited phosphor type LED with a color temperature of 6598K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.led_bh1_illuminant(wl)¶

LED-BH1 standard illuminant (CIE Colorimetry, 4th Edition, 2018) Hybrid type white LED with added red. Color temperature of 2851K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.led_rgb1_illuminant(wl)¶

LED-RGB1 standard illuminant (CIE Colorimetry, 4th Edition, 2018) Tri-led RGB source with a color temperature of 2840K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.led_v1_illuminant(wl)¶

LED-V1 standard illuminant (CIE Colorimetry, 4th Edition, 2018) Violet enhanced blue excited phosphor LED with a color temperature of 2724K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.illuminants.led_v2_illuminant(wl)¶

LED-V2 standard illuminant (CIE Colorimetry, 4th Edition, 2018) Violet enhanced blue excited phosphor LED with a color temperature of 4070K.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

6.4.3. tracer.color.observers¶

optrace.tracer.color.observers.x_observer(wl)¶

CIE 1931 2° colorimetric standard observer x.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.observers.y_observer(wl)¶

CIE 1931 2° colorimetric standard observer y.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

optrace.tracer.color.observers.z_observer(wl)¶

CIE 1931 2° colorimetric standard observer z.

Parameters:: wl (ndarray) – wavelength array in nm
Returns:: value array
Return type:: ndarray

6.4.4. tracer.color.xyz¶

optrace.tracer.color.xyz.complementary_wavelength(XYZ_s, res=10000)¶

Calculate the complementary wavelength for a given XYZ color coordinate and the D65 whitepoint.

Parameters:

XYZ_s (ndarray) – 3 element array with the XYZ values
res (int) – spectral locus sampling resolution

Returns:

complementary wavelength in nm

Return type:

float

optrace.tracer.color.xyz.dominant_wavelength(XYZ_s, res=10000)¶

Calculate the dominant wavelength for a given XYZ color coordinate and the D65 whitepoint.

Parameters:

XYZ_s (ndarray) – 3 element array with the XYZ values
res (int) – spectral locus sampling resolution

Returns:

dominant wavelength in nm

Return type:

float

optrace.tracer.color.xyz.xyY_to_xyz(xyy)¶

Convert xyY to XYZ colorspace values.

Parameters:: xyy (ndarray) – xyY values, 2D image with channels in third dimension
Returns:: converted values, same shape as input
Return type:: ndarray

optrace.tracer.color.xyz.xyz_from_spectrum(wl, spec, method='sum')¶

Calculate the tristimulus values XYZ from a spectral distribution.

Parameters:

wl – 1D wavelength vector
spec – 1D spectral value vector, same shape as wl parameter
method – “sum” or “trapz”, method for numerical integration

Returns:

numpy array of 3 elements

Return type:

ndarray

optrace.tracer.color.xyz.xyz_to_xyY(xyz)¶

Convert XYZ to xyY coordinates. Black gets mapped to the whitepoint and Y=0

Parameters:: xyz (ndarray) – input values, 2D image with channels in third dimension
Returns:: converted values with same shape as input
Return type:: ndarray

optrace.tracer.color.xyz.WP_D65_XY: list[float, float] = [0.31272, 0.32903]¶: whitepoint D65 xy chromaticity coordinates, see CIE Colorimetry, 3. Edition, 2004, table 11.3

optrace.tracer.color.xyz.WP_D65_XYZ: list[float, float, float] = [0.95047, 1.0, 1.08883]¶: whitepoint D65 in XYZ, see https://en.wikipedia.org/wiki/Illuminant_D65

6.4.5. tracer.color.srgb¶

optrace.tracer.color.srgb.gauss(x, mu, sig)¶

Gauss Function / Normal distribution. Normalized so peak value is 1.

Parameters:

x (ndarray) – 1D value vector
mu (float) – mean value
sig (float) – standard deviation

Returns:

function values with same shape as x

Return type:

ndarray

optrace.tracer.color.srgb.get_chroma_scale(Luv, L_th=0.0)¶

Calculate the chroma scaling factor for xyz_to_srgb_linear with mode “Perceptual” Ignore values below L_th*np.max(L) with L being the lightness. Impossible colors are also ignored.

This functions determines the needed scaling factor so all image colors are inside the sRGB gamut.

Parameters:

Luv (ndarray) – CIELUV image values (shape (Ny, Nx, 3))
L_th – optional lightness threshold as fraction of the peak lightness (range 0 - 1)

Returns:

saturation scaling factor (0-1)

optrace.tracer.color.srgb.log_srgb(img)¶

Logarithmically scale sRGB values. This is done by rescaling the lightness of the colors (in CIELUV) while keeping the chromaticities the same.

Parameters:: img (ndarray) – input image, shape (Ny, Nx, 3) in sRGB
Returns:: logarithmically scaled sRGB values
Return type:: ndarray

optrace.tracer.color.srgb.outside_srgb_gamut(xyz)¶

Checks if the XYZ colors produce valid colors inside the sRGB gamut

Parameters:: xyz (ndarray) – XYZ values, shape (Ny, Nx, 3)
Returns:: boolean 2D image, shape (Ny, Nx)
Return type:: ndarray

optrace.tracer.color.srgb.power_from_srgb_linear(rgbl)¶

Get a measure of pixel power/probability with the sRGB primaries above.

Parameters:: rgbl (ndarray) – linear sRGB image (2D, with channels in third dimension)
Returns:: power/probability image with two dimensions
Return type:: ndarray

optrace.tracer.color.srgb.random_wavelengths_from_srgb(rgb)¶

Choose random wavelengths from sRGB colors.

Parameters:: rgb (ndarray) – RGB values (numpy 2D array, RGB channels in second dimension)
Returns:: random wavelengths for every color (numpy 1D array)
Return type:: ndarray

optrace.tracer.color.srgb.spectral_colormap(wl)¶

Get a spectral colormap in sRGB for wavelength values. The Hue is rendered physically correct, however the lightness and saturation are set to be visually pleasing

Parameters:: wl (ndarray) – wavelength array. Values must be inside global_options.wavelength_ramge
Returns:: sRGBA array (numpy 2D array, shape (N, 4)) with values ranging 0-1
Return type:: ndarray

optrace.tracer.color.srgb.srgb_b_primary(wl)¶

Exemplary sRGB b primary curve.

Parameters:: wl (ndarray) – wavelength vector, 1D numpy array
Returns:: curve values, 1D numpy array
Return type:: ndarray

optrace.tracer.color.srgb.srgb_g_primary(wl)¶

Exemplary sRGB g primary curve.

Parameters:: wl (ndarray) – wavelength vector, 1D numpy array
Returns:: curve values, 1D numpy array
Return type:: ndarray

optrace.tracer.color.srgb.srgb_linear_to_srgb(rgbl)¶

Conversion linear RGB to sRGB. Values should be inside range [0, 1], however this is not enforced. For negative values srgb(-a) is the same as -srgb(a)

Parameters:: rgbl (ndarray) – linear RGB values (numpy 1D, 2D or 3D array)
Returns:: sRGB image (same shape as input)
Return type:: ndarray

optrace.tracer.color.srgb.srgb_linear_to_xyz(rgbl)¶

Conversion from linear sRGB values to XYZ

Parameters:: rgbl (ndarray) – linear RGB image (numpy 3D array, RGB channels in third dimension)
Returns:: XYZ image (numpy 3D array)
Return type:: ndarray

optrace.tracer.color.srgb.srgb_r_primary(wl)¶

Exemplary sRGB r primary curve.

Parameters:: wl (ndarray) – wavelength vector, 1D numpy array
Returns:: curve values, 1D numpy array
Return type:: ndarray

optrace.tracer.color.srgb.srgb_to_srgb_linear(rgb)¶

Conversion from sRGB to linear RGB values. sRGB values should be inside range [0, 1], however this is not checked or enforced. For negative values -a srgb_to_srgb_linear(-a) is the same as -srgb_to_srgb_linear(a)

Parameters:: rgb (ndarray) – RGB values (numpy 1D, 2D or 3D array)
Returns:: linear RGB values, array with same shape as input
Return type:: ndarray

optrace.tracer.color.srgb.srgb_to_xyz(rgb)¶

Conversion from sRGB to XYZ.

Parameters:: rgb (ndarray) – sRGB image (numpy 3D array, shape (Ny, Nx, 3) )
Returns:: XYZ image (shape (Ny, Nx, 3))
Return type:: ndarray

optrace.tracer.color.srgb.xyz_to_srgb(xyz, normalize=True, clip=True, rendering_intent='Absolute', L_th=0, chroma_scale=None)¶

Conversion of XYZ to sRGB Linear to sRGB.

see function :srgb_linear_to_srgb() for detail on rendering intents.

Parameters:

xyz (ndarray) – XYZ image (numpy 3D array, XYZ channels in third dimension)
normalize (bool) – if values are normalized before conversion (bool)
rendering_intent (str) – one of SRGB_RENDERING_INTENTS (“Ignore”, “Absolute”, “Perceptual”)
clip (bool) – if sRGB values are clipped before gamma correction
L_th (float) – lightness threshold for mode “Perceptual”.
chroma_scale (float) – chroma_scale option for mode “sRGB (Perceptual RI)”

Returns:

sRGB image (numpy 3D array)

Return type:

ndarray

optrace.tracer.color.srgb.xyz_to_srgb_linear(xyz, normalize=True, rendering_intent='Absolute', L_th=0.0, chroma_scale=None)¶

Conversion XYZ to linear RGB values.

Ignore: Leave out of gamut colors as is Absolute: Clip the saturation of out-of-bound colors, but preserve hue and brightness

Perceptual: Scale the chroma of all pixels so saturation ratios stay the same. Scaling factor is determined so all colors are representable. Additional lightness L_th threshold: L_th = 0.01 ignores all colors below 1% of the peak brightness for saturation detection. Prevents dark, merely visible pixels from scaling down the saturation of the whole image. Impossible colors are left untouched by this mode, so clipping the output values is recommended. Alternatively the chroma_scale parameter can be provided that scales the chroma down by a fixed amount. The colors still outside the gamut after the operation are chroma clipped like in Absolute RI. So Perceptual RI with L_th or chroma_scale can be seen as hybrid method, perceptual for colors meeting the criteria, Absolute RI for colors not doing so.

Parameters:

xyz (ndarray) – XYZ image (shape (Ny, Nx, 3))
normalize (bool) – if image is normalized to highest value before conversion (bool)
rendering_intent (str) – “Absolute”, “Perceptual” or “Ignore”, see above
L_th (float) – lightness threshold for mode “Perceptual”.
chroma_scale (float) – chroma_scale option for mode “Perceptual”

Returns:

linear sRGB image (shape (Ny, Nx, 3))

Return type:

ndarray

optrace.tracer.color.srgb.SRGB_B_XY: list[float, float] = [0.15, 0.06]¶: sRGB blue primary in xy coordinates

optrace.tracer.color.srgb.SRGB_G_XY: list[float, float] = [0.3, 0.6]¶: sRGB green primary in xy coordinates

optrace.tracer.color.srgb.SRGB_RENDERING_INTENTS: list[str, str, str] = ['Ignore', 'Absolute', 'Perceptual']¶: Rendering intents for XYZ to sRGB conversion

optrace.tracer.color.srgb.SRGB_R_XY: list[float, float] = [0.64, 0.33]¶: sRGB red primary in xy coordinates

6.4.6. tracer.color.luv¶

optrace.tracer.color.luv.luv_chroma(luv)¶

Get Chroma from CIELUV values. Calculation using https://en.wikipedia.org/wiki/Colorfulness#Chroma

Parameters:: luv (ndarray) – Luv Image, np.ndarray with shape (Ny, Nx, 3)
Returns:: Chroma Image, np.ndarray with shape (Ny, Nx)
Return type:: ndarray

optrace.tracer.color.luv.luv_hue(luv)¶

Get Hue from CIELUV values. Calculation using https://en.wikipedia.org/wiki/Colorfulness#Chroma

Parameters:: luv (ndarray) – Luv Image, np.ndarray with shape (Ny, Nx, 3)
Returns:: Hue Image, np.ndarray with shape (Ny, Nx)
Return type:: ndarray

optrace.tracer.color.luv.luv_saturation(luv)¶

Get Chroma from CIELUV values. Calculation using https://en.wikipedia.org/wiki/Colorfulness#Saturation

Parameters:: luv (ndarray) – Luv Image, np.ndarray with shape (Ny, Nx, 3)
Returns:: Saturation Image, np.ndarray with shape (Ny, Nx)
Return type:: ndarray

optrace.tracer.color.luv.luv_to_u_v_l(luv)¶

Convert to CIE 1976 LUV to chromaticity color space u’v’L (uniform chromaticity scale diagram coordinates)

Parameters:: luv (ndarray) – CIELUV image, shape (Ny, Nx, 3)
Returns:: u’v’L image, same shape as input
Return type:: ndarray

optrace.tracer.color.luv.luv_to_xyz(luv)¶

Convert CIE 1976 LUV back to XYZ.

Parameters:: luv (ndarray) – CIELUV image (2D, with channels in third dimension)
Returns:: XYZ image, same shape as input
Return type:: ndarray

optrace.tracer.color.luv.xyz_to_luv(xyz, normalize=True)¶

Convert XYZ values to CIE 1976 LUV colorspace.

Parameters:

xyz (ndarray) – XYZ image (2D with channels in third dimension)
normalize (bool) – if should be normalized with the highest value in Y

Returns:

CIELUV image, same shape as input

Return type:

ndarray

optrace.tracer.color.luv.SRGB_B_UV: list[float, float] = [0.1754385965, 0.1578947368]¶: sRGBgblue primary in u’v’ coordinates

optrace.tracer.color.luv.SRGB_G_UV: list[float, float] = [0.125, 0.5625]¶: sRGB green primary in u’v’ coordinates

optrace.tracer.color.luv.SRGB_R_UV: list[float, float] = [0.4507042254, 0.5228873239]¶: sRGB red primary in u’v’ coordinates

optrace.tracer.color.luv.WP_D65_LUV: list[float, float, float] = [100, 0.19783982, 0.4683363]¶: whitepoint D65 in Lu’v’, calculate from whitepoint XYZ coordinates

optrace.tracer.color.luv.WP_D65_UV: list[float, float] = [0.19783982, 0.4683363]¶: whitepoint D65 in u’v’, calculated from XYZ coordinates