psychopy.tools.colorspacetools

Functions and classes related to color space conversion.

dkl2rgb(dkl[, conversionMatrix]) Convert from DKL color space (Derrington, Krauskopf & Lennie) to RGB.
dklCart2rgb(LUM, LM, S[, conversionMatrix]) Like dkl2rgb except that it uses cartesian coords (LM,S,LUM) rather than spherical coords for DKL (elev, azim, contr).
rgb2dklCart(picture[, conversionMatrix]) Convert an RGB image into Cartesian DKL space.
hsv2rgb(hsv_Nx3) Convert from HSV color space to RGB gun values.
lms2rgb(lms_Nx3[, conversionMatrix]) Convert from cone space (Long, Medium, Short) to RGB.
rgb2lms(rgb_Nx3[, conversionMatrix]) Convert from RGB to cone space (LMS).
dkl2rgb(dkl[, conversionMatrix]) Convert from DKL color space (Derrington, Krauskopf & Lennie) to RGB.
cielab2rgb(lab[, whiteXYZ, …]) Transform CIE L*a*b* (1976) color space coordinates to RGB tristimulus values.
cielch2rgb(lch[, whiteXYZ, …]) Transform CIE L*C*h* coordinates to RGB tristimulus values.
srgbTF(rgb[, reverse]) Apply sRGB transfer function (or gamma) to linear RGB values.
rec709TF(rgb, **kwargs) Apply the Rec.

Function details

psychopy.tools.colorspacetools.dkl2rgb(dkl, conversionMatrix=None)[source]

Convert from DKL color space (Derrington, Krauskopf & Lennie) to RGB.

Requires a conversion matrix, which will be generated from generic Sony Trinitron phosphors if not supplied (note that this will not be an accurate representation of the color space unless you supply a conversion matrix).

usage:

rgb(Nx3) = dkl2rgb(dkl_Nx3(el,az,radius), conversionMatrix)
rgb(NxNx3) = dkl2rgb(dkl_NxNx3(el,az,radius), conversionMatrix)
psychopy.tools.colorspacetools.dklCart2rgb(LUM, LM, S, conversionMatrix=None)[source]

Like dkl2rgb except that it uses cartesian coords (LM,S,LUM) rather than spherical coords for DKL (elev, azim, contr).

NB: this may return rgb values >1 or <-1

psychopy.tools.colorspacetools.rgb2dklCart(picture, conversionMatrix=None)[source]

Convert an RGB image into Cartesian DKL space.

psychopy.tools.colorspacetools.hsv2rgb(hsv_Nx3)[source]

Convert from HSV color space to RGB gun values.

usage:

rgb_Nx3 = hsv2rgb(hsv_Nx3)

Note that in some uses of HSV space the Hue component is given in radians or cycles (range 0:1]). In this version H is given in degrees (0:360).

Also note that the RGB output ranges -1:1, in keeping with other PsychoPy functions.

psychopy.tools.colorspacetools.lms2rgb(lms_Nx3, conversionMatrix=None)[source]

Convert from cone space (Long, Medium, Short) to RGB.

Requires a conversion matrix, which will be generated from generic Sony Trinitron phosphors if not supplied (note that you will not get an accurate representation of the color space unless you supply a conversion matrix)

usage:

rgb_Nx3 = lms2rgb(dkl_Nx3(el,az,radius), conversionMatrix)
psychopy.tools.colorspacetools.rgb2lms(rgb_Nx3, conversionMatrix=None)[source]

Convert from RGB to cone space (LMS).

Requires a conversion matrix, which will be generated from generic Sony Trinitron phosphors if not supplied (note that you will not get an accurate representation of the color space unless you supply a conversion matrix)

usage:

lms_Nx3 = rgb2lms(rgb_Nx3(el,az,radius), conversionMatrix)
psychopy.tools.colorspacetools.dkl2rgb(dkl, conversionMatrix=None)[source]

Convert from DKL color space (Derrington, Krauskopf & Lennie) to RGB.

Requires a conversion matrix, which will be generated from generic Sony Trinitron phosphors if not supplied (note that this will not be an accurate representation of the color space unless you supply a conversion matrix).

usage:

rgb(Nx3) = dkl2rgb(dkl_Nx3(el,az,radius), conversionMatrix)
rgb(NxNx3) = dkl2rgb(dkl_NxNx3(el,az,radius), conversionMatrix)
psychopy.tools.colorspacetools.cielab2rgb(lab, whiteXYZ=None, conversionMatrix=None, transferFunc=None, clip=False, **kwargs)[source]

Transform CIE L*a*b* (1976) color space coordinates to RGB tristimulus values.

CIE L*a*b* are first transformed into CIE XYZ (1931) color space, then the RGB conversion is applied. By default, the sRGB conversion matrix is used with a reference D65 white point. You may specify your own RGB conversion matrix and white point (in CIE XYZ) appropriate for your display.

Parameters:
  • lab (tuple, list or ndarray) – 1-, 2-, 3-D vector of CIE L*a*b* coordinates to convert. The last dimension should be length-3 in all cases specifying a single coordinate.
  • whiteXYZ (tuple, list or ndarray) – 1-D vector coordinate of the white point in CIE-XYZ color space. Must be the same white point needed by the conversion matrix. The default white point is D65 if None is specified, defined as X, Y, Z = 0.9505, 1.0000, 1.0890.
  • conversionMatrix (tuple, list or ndarray) – 3x3 conversion matrix to transform CIE-XYZ to RGB values. The default matrix is sRGB with a D65 white point if None is specified. Note that values must be gamma corrected to appear correctly according to the sRGB standard.
  • transferFunc (pyfunc or None) – Signature of the transfer function to use. If None, values are kept as linear RGB (it’s assumed your display is gamma corrected via the hardware CLUT). The TF must be appropriate for the conversion matrix supplied (default is sRGB). Additional arguments to ‘transferFunc’ can be passed by specifying them as keyword arguments. Gamma functions that come with PsychoPy are ‘srgbTF’ and ‘rec709TF’, see their docs for more information.
  • clip (bool) – Make all output values representable by the display. However, colors outside of the display’s gamut may not be valid!
Returns:

Array of RGB tristimulus values.

Return type:

ndarray

Example

Converting a CIE L*a*b* color to linear RGB:

import psychopy.tools.colorspacetools as cst
cielabColor = (53.0, -20.0, 0.0)  # greenish color (L*, a*, b*)
rgbColor = cst.cielab2rgb(cielabColor)

Using a transfer function to convert to sRGB:

rgbColor = cst.cielab2rgb(cielabColor, transferFunc=cst.srgbTF)
psychopy.tools.colorspacetools.cielch2rgb(lch, whiteXYZ=None, conversionMatrix=None, transferFunc=None, clip=False, **kwargs)[source]

Transform CIE L*C*h* coordinates to RGB tristimulus values.

Parameters:
  • lch (tuple, list or ndarray) – 1-, 2-, 3-D vector of CIE L*C*h* coordinates to convert. The last dimension should be length-3 in all cases specifying a single coordinate. The hue angle *h is expected in degrees.
  • whiteXYZ (tuple, list or ndarray) – 1-D vector coordinate of the white point in CIE-XYZ color space. Must be the same white point needed by the conversion matrix. The default white point is D65 if None is specified, defined as X, Y, Z = 0.9505, 1.0000, 1.0890
  • conversionMatrix (tuple, list or ndarray) – 3x3 conversion matrix to transform CIE-XYZ to RGB values. The default matrix is sRGB with a D65 white point if None is specified. Note that values must be gamma corrected to appear correctly according to the sRGB standard.
  • transferFunc (pyfunc or None) – Signature of the transfer function to use. If None, values are kept as linear RGB (it’s assumed your display is gamma corrected via the hardware CLUT). The TF must be appropriate for the conversion matrix supplied. Additional arguments to ‘transferFunc’ can be passed by specifying them as keyword arguments. Gamma functions that come with PsychoPy are ‘srgbTF’ and ‘rec709TF’, see their docs for more information.
  • clip (boolean) – Make all output values representable by the display. However, colors outside of the display’s gamut may not be valid!
Returns:

array of RGB tristimulus values

Return type:

ndarray

psychopy.tools.colorspacetools.srgbTF(rgb, reverse=False, **kwargs)[source]

Apply sRGB transfer function (or gamma) to linear RGB values.

Input values must have been transformed using a conversion matrix derived from sRGB primaries relative to D65.

Parameters:
  • rgb (tuple, list or ndarray of floats) – Nx3 or NxNx3 array of linear RGB values, last dim must be size == 3 specifying RBG values.
  • reverse (boolean) – If True, the reverse transfer function will convert sRGB -> linear RGB.
Returns:

Array of transformed colors with same shape as input.

Return type:

ndarray

psychopy.tools.colorspacetools.rec709TF(rgb, **kwargs)[source]

Apply the Rec. 709 transfer function (or gamma) to linear RGB values.

This transfer function is defined in the ITU-R BT.709 (2015) recommendation document (http://www.itu.int/rec/R-REC-BT.709-6-201506-I/en) and is commonly used with HDTV televisions.

Parameters:rgb (tuple, list or ndarray of floats) – Nx3 or NxNx3 array of linear RGB values, last dim must be size == 3 specifying RBG values.
Returns:Array of transformed colors with same shape as input.
Return type:ndarray

Back to top