tessl/pypi-colour-science
Comprehensive Python library providing algorithms and datasets for colour science computations, including chromatic adaptation, colour appearance models, colorimetry, and spectral analysis.
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
colour-models.mddocs/
Colour Models and Space Conversions
Comprehensive colour space conversion functions covering CIE standards, RGB models, advanced perceptual models, and automatic conversions between any supported colour spaces.
Capabilities
Universal Colour Space Conversion
The main entry point for automatic colour space conversion using an intelligent graph-based system.
def convert(a: ArrayLike, source: str, target: str, **kwargs) -> NDArray:
"""
Convert colour data between any supported colour spaces using automatic path finding.
Parameters:
- a: colour data array to convert
- source: source colour space (e.g., 'XYZ', 'sRGB', 'Lab', 'Oklab')
- target: target colour space (e.g., 'XYZ', 'sRGB', 'Lab', 'Oklab')
- **kwargs: additional parameters for specific conversions (illuminant, colourspace, etc.)
Returns:
Converted colour data in target colour space
Supported Colour Spaces:
- CIE: XYZ, xyY, Lab, Luv, UCS, UVW
- RGB: sRGB, Adobe RGB, Rec.2020, ACES, ProPhoto, DCI-P3, etc.
- Advanced: Jzazbz, Oklab, CAM16, IPT, OSA-UCS
- Polar: LCHab, LCHuv, HSV, HSL, HCL
- Video: YCbCr, YCoCg, ICtCp
"""
def describe_conversion_path(source: str, target: str) -> str:
"""
Describe the automatic conversion path between two colour spaces.
Parameters:
- source: source colour space name
- target: target colour space name
Returns:
Human-readable description of conversion steps
"""CIE Standard Colour Spaces
Core CIE colour space transformations forming the foundation for colour science computations.
def XYZ_to_Lab(XYZ: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
"""
Convert CIE XYZ tristimulus values to CIE L*a*b* colour space.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
- illuminant: reference illuminant CIE xy chromaticity coordinates or xyY values
Returns:
CIE L*a*b* colour space array, shape (..., 3)
Notes:
L* ranges [0, 100], a* and b* range approximately [-100, 100]
"""
def Lab_to_XYZ(Lab: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
"""
Convert CIE L*a*b* colour space to CIE XYZ tristimulus values.
Parameters:
- Lab: CIE L*a*b* colour space array, shape (..., 3)
- illuminant: reference illuminant CIE xy chromaticity coordinates or xyY values
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_Luv(XYZ: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
"""
Convert CIE XYZ tristimulus values to CIE L*u*v* colour space.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
- illuminant: reference illuminant CIE xy chromaticity coordinates or xyY values
Returns:
CIE L*u*v* colour space array, shape (..., 3)
"""
def Luv_to_XYZ(Luv: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
"""
Convert CIE L*u*v* colour space to CIE XYZ tristimulus values.
Parameters:
- Luv: CIE L*u*v* colour space array, shape (..., 3)
- illuminant: reference illuminant CIE xy chromaticity coordinates or xyY values
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_xyY(XYZ: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
"""
Convert CIE XYZ tristimulus values to CIE xyY colour space.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
- illuminant: reference illuminant for handling zero luminance cases
Returns:
CIE xyY colour space array, shape (..., 3)
Notes:
x, y are chromaticity coordinates [0, 1], Y is luminance [0, 1]
"""
def xyY_to_XYZ(xyY: ArrayLike) -> NDArray:
"""
Convert CIE xyY colour space to CIE XYZ tristimulus values.
Parameters:
- xyY: CIE xyY colour space array, shape (..., 3)
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_xy(XYZ: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
"""
Convert CIE XYZ tristimulus values to CIE xy chromaticity coordinates.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
- illuminant: reference illuminant for handling zero luminance cases
Returns:
CIE xy chromaticity coordinates, shape (..., 2)
"""
def xy_to_XYZ(xy: ArrayLike) -> NDArray:
"""
Convert CIE xy chromaticity coordinates to CIE XYZ tristimulus values.
Assumes Y = 1 for the conversion.
Parameters:
- xy: CIE xy chromaticity coordinates, shape (..., 2)
Returns:
CIE XYZ tristimulus values with Y=1, shape (..., 3)
"""CIE Uniform Colour Spaces
Legacy CIE uniform colour space transformations.
def XYZ_to_UVW(XYZ: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
"""
Convert CIE XYZ tristimulus values to CIE 1964 U*V*W* colour space.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
- illuminant: reference illuminant CIE xy chromaticity coordinates
Returns:
CIE 1964 U*V*W* colour space array, shape (..., 3)
"""
def UVW_to_XYZ(UVW: ArrayLike, illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["D65"]) -> NDArray:
"""
Convert CIE 1964 U*V*W* colour space to CIE XYZ tristimulus values.
Parameters:
- UVW: CIE 1964 U*V*W* colour space array, shape (..., 3)
- illuminant: reference illuminant CIE xy chromaticity coordinates
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_CIE1960UCS(XYZ: ArrayLike) -> NDArray:
"""
Convert CIE XYZ tristimulus values to CIE 1960 UCS colour space.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
Returns:
CIE 1960 UCS colour space array, shape (..., 3)
"""
def CIE1960UCS_to_XYZ(UCS: ArrayLike) -> NDArray:
"""
Convert CIE 1960 UCS colour space to CIE XYZ tristimulus values.
Parameters:
- UCS: CIE 1960 UCS colour space array, shape (..., 3)
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_CIE1976UCS(XYZ: ArrayLike) -> NDArray:
"""
Convert CIE XYZ tristimulus values to CIE 1976 UCS colour space.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
Returns:
CIE 1976 UCS colour space array, shape (..., 3)
"""
def CIE1976UCS_to_XYZ(UCS: ArrayLike) -> NDArray:
"""
Convert CIE 1976 UCS colour space to CIE XYZ tristimulus values.
Parameters:
- UCS: CIE 1976 UCS colour space array, shape (..., 3)
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""RGB Colour Spaces and Models
Comprehensive RGB colour space support with device-dependent transformations.
class RGB_Colourspace:
"""
RGB colour space definition with primaries, whitepoint, and transfer functions.
Parameters:
- name: colour space name
- primaries: RGB primaries as CIE xy chromaticity coordinates, shape (3, 2)
- whitepoint: whitepoint CIE xy chromaticity coordinates, shape (2,)
- whitepoint_name: optional whitepoint name
- matrix_RGB_to_XYZ: transformation matrix from RGB to XYZ, shape (3, 3)
- matrix_XYZ_to_RGB: transformation matrix from XYZ to RGB, shape (3, 3)
- cctf_encoding: colour component transfer function (gamma encoding)
- cctf_decoding: inverse colour component transfer function (gamma decoding)
"""
def __init__(self, name: str, primaries: ArrayLike, whitepoint: ArrayLike, whitepoint_name: str = None,
matrix_RGB_to_XYZ: ArrayLike = None, matrix_XYZ_to_RGB: ArrayLike = None,
cctf_encoding: Callable = None, cctf_decoding: Callable = None): ...
def RGB_to_XYZ(RGB: ArrayLike, colourspace: Union[RGB_Colourspace, str] = RGB_COLOURSPACE_sRGB,
illuminant: ArrayLike = None, chromatic_adaptation_transform: str = "CAT02",
apply_cctf_decoding: bool = False) -> NDArray:
"""
Convert RGB values to CIE XYZ tristimulus values.
Parameters:
- RGB: RGB colour array, shape (..., 3)
- colourspace: RGB colour space or name (e.g., 'sRGB', 'Adobe RGB (1998)', 'Rec. 2020')
- illuminant: target illuminant for chromatic adaptation
- chromatic_adaptation_transform: chromatic adaptation method ('CAT02', 'Bradford', etc.)
- apply_cctf_decoding: whether to apply gamma decoding before conversion
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_RGB(XYZ: ArrayLike, colourspace: Union[RGB_Colourspace, str] = RGB_COLOURSPACE_sRGB,
illuminant: ArrayLike = None, chromatic_adaptation_transform: str = "CAT02",
apply_cctf_encoding: bool = False) -> NDArray:
"""
Convert CIE XYZ tristimulus values to RGB values.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
- colourspace: RGB colour space or name (e.g., 'sRGB', 'Adobe RGB (1998)', 'Rec. 2020')
- illuminant: source illuminant for chromatic adaptation
- chromatic_adaptation_transform: chromatic adaptation method ('CAT02', 'Bradford', etc.)
- apply_cctf_encoding: whether to apply gamma encoding after conversion
Returns:
RGB colour array, shape (..., 3)
"""
def RGB_to_RGB(RGB: ArrayLike, input_colourspace: Union[RGB_Colourspace, str],
output_colourspace: Union[RGB_Colourspace, str],
chromatic_adaptation_transform: str = "CAT02") -> NDArray:
"""
Convert RGB values between different RGB colour spaces.
Parameters:
- RGB: RGB colour array in input colourspace, shape (..., 3)
- input_colourspace: source RGB colour space
- output_colourspace: target RGB colour space
- chromatic_adaptation_transform: chromatic adaptation method
Returns:
RGB colour array in output colourspace, shape (..., 3)
"""
# Common RGB colour space constants
RGB_COLOURSPACE_sRGB: RGB_Colourspace
RGB_COLOURSPACE_ADOBE_RGB1998: RGB_Colourspace
RGB_COLOURSPACE_REC_2020: RGB_Colourspace
RGB_COLOURSPACE_DCI_P3: RGB_Colourspace
RGB_COLOURSPACE_DISPLAY_P3: RGB_Colourspace
RGB_COLOURSPACE_PROPHOTO_RGB: RGB_Colourspace
RGB_COLOURSPACE_ACES2065_1: RGB_Colourspace
RGB_COLOURSPACE_ACESCG: RGB_Colourspace
RGB_COLOURSPACE_BT709: RGB_Colourspace
RGB_COLOURSPACE_BT2020: RGB_ColourspaceRGB Cylindrical Representations
Convert between RGB and cylindrical colour representations.
def RGB_to_HSV(RGB: ArrayLike) -> NDArray:
"""
Convert RGB values to HSV (Hue, Saturation, Value) colour space.
Parameters:
- RGB: RGB colour array, shape (..., 3), values in [0, 1]
Returns:
HSV colour array, shape (..., 3)
H in [0, 360], S in [0, 1], V in [0, 1]
"""
def HSV_to_RGB(HSV: ArrayLike) -> NDArray:
"""
Convert HSV (Hue, Saturation, Value) values to RGB colour space.
Parameters:
- HSV: HSV colour array, shape (..., 3)
H in [0, 360], S in [0, 1], V in [0, 1]
Returns:
RGB colour array, shape (..., 3), values in [0, 1]
"""
def RGB_to_HSL(RGB: ArrayLike) -> NDArray:
"""
Convert RGB values to HSL (Hue, Saturation, Lightness) colour space.
Parameters:
- RGB: RGB colour array, shape (..., 3), values in [0, 1]
Returns:
HSL colour array, shape (..., 3)
H in [0, 360], S in [0, 1], L in [0, 1]
"""
def HSL_to_RGB(HSL: ArrayLike) -> NDArray:
"""
Convert HSL (Hue, Saturation, Lightness) values to RGB colour space.
Parameters:
- HSL: HSL colour array, shape (..., 3)
H in [0, 360], S in [0, 1], L in [0, 1]
Returns:
RGB colour array, shape (..., 3), values in [0, 1]
"""
def RGB_to_HCL(RGB: ArrayLike) -> NDArray:
"""
Convert RGB values to HCL (Hue, Chroma, Luma) colour space.
Parameters:
- RGB: RGB colour array, shape (..., 3), values in [0, 1]
Returns:
HCL colour array, shape (..., 3)
"""
def HCL_to_RGB(HCL: ArrayLike) -> NDArray:
"""
Convert HCL (Hue, Chroma, Luma) values to RGB colour space.
Parameters:
- HCL: HCL colour array, shape (..., 3)
Returns:
RGB colour array, shape (..., 3), values in [0, 1]
"""Advanced Perceptual Colour Models
Modern colour models designed for perceptual uniformity and wide gamut applications.
def XYZ_to_Oklab(XYZ: ArrayLike) -> NDArray:
"""
Convert CIE XYZ tristimulus values to Oklab colour space.
Oklab is a perceptually uniform colour space designed for image processing
with better performance than CIE Lab for wide gamut and HDR applications.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
Returns:
Oklab colour space array, shape (..., 3)
L in [0, 1], a and b approximately [-0.5, 0.5]
"""
def Oklab_to_XYZ(Oklab: ArrayLike) -> NDArray:
"""
Convert Oklab colour space to CIE XYZ tristimulus values.
Parameters:
- Oklab: Oklab colour space array, shape (..., 3)
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_Jzazbz(XYZ: ArrayLike, method: str = "Safdar 2017") -> NDArray:
"""
Convert CIE XYZ tristimulus values to Jzazbz colour space.
Jzazbz is designed for high dynamic range (HDR) and wide colour gamut applications,
providing better perceptual uniformity than CIE Lab in these contexts.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
- method: computational method ('Safdar 2017')
Returns:
Jzazbz colour space array, shape (..., 3)
"""
def Jzazbz_to_XYZ(Jzazbz: ArrayLike, method: str = "Safdar 2017") -> NDArray:
"""
Convert Jzazbz colour space to CIE XYZ tristimulus values.
Parameters:
- Jzazbz: Jzazbz colour space array, shape (..., 3)
- method: computational method ('Safdar 2017')
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_IPT(XYZ: ArrayLike) -> NDArray:
"""
Convert CIE XYZ tristimulus values to IPT colour space.
IPT colour space designed for better hue constancy and perceptual uniformity.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
Returns:
IPT colour space array, shape (..., 3)
"""
def IPT_to_XYZ(IPT: ArrayLike) -> NDArray:
"""
Convert IPT colour space to CIE XYZ tristimulus values.
Parameters:
- IPT: IPT colour space array, shape (..., 3)
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_OSA_UCS(XYZ: ArrayLike) -> NDArray:
"""
Convert CIE XYZ tristimulus values to OSA-UCS colour space.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
Returns:
OSA-UCS colour space array (L, j, g), shape (..., 3)
"""
def OSA_UCS_to_XYZ(OSA_UCS: ArrayLike) -> NDArray:
"""
Convert OSA-UCS colour space to CIE XYZ tristimulus values.
Parameters:
- OSA_UCS: OSA-UCS colour space array (L, j, g), shape (..., 3)
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""CAM16 Colour Appearance Model
Convert between XYZ and CAM16 uniform colour spaces designed for colour appearance applications.
def XYZ_to_CAM16UCS(XYZ: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
"""
Convert CIE XYZ tristimulus values to CAM16-UCS colour space.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
- coefficients: CAM16 viewing conditions coefficients
Returns:
CAM16-UCS colour space array, shape (..., 3)
"""
def CAM16UCS_to_XYZ(UCS: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
"""
Convert CAM16-UCS colour space to CIE XYZ tristimulus values.
Parameters:
- UCS: CAM16-UCS colour space array, shape (..., 3)
- coefficients: CAM16 viewing conditions coefficients
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_CAM16LCD(XYZ: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
"""
Convert CIE XYZ tristimulus values to CAM16-LCD colour space.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
- coefficients: CAM16 viewing conditions coefficients
Returns:
CAM16-LCD colour space array, shape (..., 3)
"""
def CAM16LCD_to_XYZ(LCD: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
"""
Convert CAM16-LCD colour space to CIE XYZ tristimulus values.
Parameters:
- LCD: CAM16-LCD colour space array, shape (..., 3)
- coefficients: CAM16 viewing conditions coefficients
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""
def XYZ_to_CAM16SCD(XYZ: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
"""
Convert CIE XYZ tristimulus values to CAM16-SCD colour space.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
- coefficients: CAM16 viewing conditions coefficients
Returns:
CAM16-SCD colour space array, shape (..., 3)
"""
def CAM16SCD_to_XYZ(SCD: ArrayLike, coefficients: ArrayLike = CAM_KWARGS_CAM16_sRGB) -> NDArray:
"""
Convert CAM16-SCD colour space to CIE XYZ tristimulus values.
Parameters:
- SCD: CAM16-SCD colour space array, shape (..., 3)
- coefficients: CAM16 viewing conditions coefficients
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""Polar Coordinate Conversions
Convert between Cartesian and polar representations of various colour spaces.
def Lab_to_LCHab(Lab: ArrayLike) -> NDArray:
"""
Convert CIE L*a*b* to CIE L*C*H*ab polar representation.
Parameters:
- Lab: CIE L*a*b* colour space array, shape (..., 3)
Returns:
CIE L*C*H*ab polar coordinates, shape (..., 3)
L* [0, 100], C*ab [0, 100+], H*ab [0, 360]
"""
def LCHab_to_Lab(LCHab: ArrayLike) -> NDArray:
"""
Convert CIE L*C*H*ab polar coordinates to CIE L*a*b*.
Parameters:
- LCHab: CIE L*C*H*ab polar coordinates, shape (..., 3)
Returns:
CIE L*a*b* colour space array, shape (..., 3)
"""
def Luv_to_LCHuv(Luv: ArrayLike) -> NDArray:
"""
Convert CIE L*u*v* to CIE L*C*H*uv polar representation.
Parameters:
- Luv: CIE L*u*v* colour space array, shape (..., 3)
Returns:
CIE L*C*H*uv polar coordinates, shape (..., 3)
"""
def LCHuv_to_Luv(LCHuv: ArrayLike) -> NDArray:
"""
Convert CIE L*C*H*uv polar coordinates to CIE L*u*v*.
Parameters:
- LCHuv: CIE L*C*H*uv polar coordinates, shape (..., 3)
Returns:
CIE L*u*v* colour space array, shape (..., 3)
"""
def Oklab_to_Oklch(Oklab: ArrayLike) -> NDArray:
"""
Convert Oklab to Oklch polar representation.
Parameters:
- Oklab: Oklab colour space array, shape (..., 3)
Returns:
Oklch polar coordinates, shape (..., 3)
L [0, 1], C [0, 0.5+], h [0, 360]
"""
def Oklch_to_Oklab(Oklch: ArrayLike) -> NDArray:
"""
Convert Oklch polar coordinates to Oklab.
Parameters:
- Oklch: Oklch polar coordinates, shape (..., 3)
Returns:
Oklab colour space array, shape (..., 3)
"""
def Jzazbz_to_JzCHab(Jzazbz: ArrayLike) -> NDArray:
"""
Convert Jzazbz to JzCHab polar representation.
Parameters:
- Jzazbz: Jzazbz colour space array, shape (..., 3)
Returns:
JzCHab polar coordinates, shape (..., 3)
"""
def JzCHab_to_Jzazbz(JzCHab: ArrayLike) -> NDArray:
"""
Convert JzCHab polar coordinates to Jzazbz.
Parameters:
- JzCHab: JzCHab polar coordinates, shape (..., 3)
Returns:
Jzazbz colour space array, shape (..., 3)
"""
def IPT_to_ICH(IPT: ArrayLike) -> NDArray:
"""
Convert IPT to ICH polar representation.
Parameters:
- IPT: IPT colour space array, shape (..., 3)
Returns:
ICH polar coordinates, shape (..., 3)
"""
def ICH_to_IPT(ICH: ArrayLike) -> NDArray:
"""
Convert ICH polar coordinates to IPT.
Parameters:
- ICH: ICH polar coordinates, shape (..., 3)
Returns:
IPT colour space array, shape (..., 3)
"""Video and Digital Imaging Colour Spaces
Colour spaces commonly used in video production and digital imaging.
def RGB_to_YCbCr(RGB: ArrayLike, K: ArrayLike = WEIGHTS_YCBCR["ITU-R BT.709"],
in_bits: int = 10, in_legal: bool = False, in_int: bool = False,
out_bits: int = 10, out_legal: bool = False, out_int: bool = False) -> NDArray:
"""
Convert RGB values to YCbCr colour space.
Parameters:
- RGB: RGB colour array, shape (..., 3)
- K: luma coefficients (ITU-R BT.601, BT.709, BT.2020, etc.)
- in_bits: input bit depth
- in_legal: whether input uses legal range
- in_int: whether input is integer
- out_bits: output bit depth
- out_legal: whether output uses legal range
- out_int: whether output is integer
Returns:
YCbCr colour array, shape (..., 3)
"""
def YCbCr_to_RGB(YCbCr: ArrayLike, K: ArrayLike = WEIGHTS_YCBCR["ITU-R BT.709"],
in_bits: int = 10, in_legal: bool = False, in_int: bool = False,
out_bits: int = 10, out_legal: bool = False, out_int: bool = False) -> NDArray:
"""
Convert YCbCr colour space to RGB values.
Parameters:
- YCbCr: YCbCr colour array, shape (..., 3)
- K: luma coefficients
- in_bits: input bit depth
- in_legal: whether input uses legal range
- in_int: whether input is integer
- out_bits: output bit depth
- out_legal: whether output uses legal range
- out_int: whether output is integer
Returns:
RGB colour array, shape (..., 3)
"""
def RGB_to_YCoCg(RGB: ArrayLike) -> NDArray:
"""
Convert RGB values to YCoCg colour space.
Parameters:
- RGB: RGB colour array, shape (..., 3)
Returns:
YCoCg colour array, shape (..., 3)
"""
def YCoCg_to_RGB(YCoCg: ArrayLike) -> NDArray:
"""
Convert YCoCg colour space to RGB values.
Parameters:
- YCoCg: YCoCg colour array, shape (..., 3)
Returns:
RGB colour array, shape (..., 3)
"""
def XYZ_to_ICtCp(XYZ: ArrayLike) -> NDArray:
"""
Convert CIE XYZ tristimulus values to ICtCp colour space.
ICtCp is designed for HDR and wide colour gamut content.
Parameters:
- XYZ: CIE XYZ tristimulus values, shape (..., 3)
Returns:
ICtCp colour space array, shape (..., 3)
"""
def ICtCp_to_XYZ(ICtCp: ArrayLike) -> NDArray:
"""
Convert ICtCp colour space to CIE XYZ tristimulus values.
Parameters:
- ICtCp: ICtCp colour space array, shape (..., 3)
Returns:
CIE XYZ tristimulus values, shape (..., 3)
"""Transfer Functions
Gamma correction and other transfer functions for colour encoding/decoding.
def eotf_sRGB(V: ArrayLike) -> NDArray:
"""
Apply sRGB electro-optical transfer function (gamma decoding).
Parameters:
- V: electrical signal values, shape (...,)
Returns:
Optical signal values (linear light), shape (...,)
"""
def eotf_inverse_sRGB(L: ArrayLike) -> NDArray:
"""
Apply inverse sRGB electro-optical transfer function (gamma encoding).
Parameters:
- L: optical signal values (linear light), shape (...,)
Returns:
Electrical signal values, shape (...,)
"""
def oetf_BT709(L: ArrayLike) -> NDArray:
"""
Apply ITU-R BT.709 opto-electronic transfer function.
Parameters:
- L: optical signal values, shape (...,)
Returns:
Electrical signal values, shape (...,)
"""
def oetf_inverse_BT709(V: ArrayLike) -> NDArray:
"""
Apply inverse ITU-R BT.709 opto-electronic transfer function.
Parameters:
- V: electrical signal values, shape (...,)
Returns:
Optical signal values, shape (...,)
"""
def oetf_BT2020(L: ArrayLike) -> NDArray:
"""
Apply ITU-R BT.2020 opto-electronic transfer function.
Parameters:
- L: optical signal values, shape (...,)
Returns:
Electrical signal values, shape (...,)
"""
def oetf_inverse_BT2020(V: ArrayLike) -> NDArray:
"""
Apply inverse ITU-R BT.2020 opto-electronic transfer function.
Parameters:
- V: electrical signal values, shape (...,)
Returns:
Optical signal values, shape (...,)
"""
def eotf_ST2084(N: ArrayLike) -> NDArray:
"""
Apply SMPTE ST 2084 electro-optical transfer function (Perceptual Quantizer).
Parameters:
- N: non-linear signal values, shape (...,)
Returns:
Optical signal values (cd/m²), shape (...,)
"""
def eotf_inverse_ST2084(L: ArrayLike) -> NDArray:
"""
Apply inverse SMPTE ST 2084 electro-optical transfer function.
Parameters:
- L: optical signal values (cd/m²), shape (...,)
Returns:
Non-linear signal values, shape (...,)
"""Usage Examples
Basic Colour Space Conversions
import numpy as np
import colour
# Convert sRGB to CIE Lab via automatic conversion
rgb = np.array([0.5, 0.3, 0.8])
lab = colour.convert(rgb, 'sRGB', 'Lab')
print(f"sRGB {rgb} -> Lab {lab}")
# Convert using specific functions
xyz = colour.sRGB_to_XYZ(rgb)
lab_direct = colour.XYZ_to_Lab(xyz)
print(f"Direct: Lab {lab_direct}")
# Convert to modern perceptual spaces
oklab = colour.convert(rgb, 'sRGB', 'Oklab')
jzazbz = colour.convert(rgb, 'sRGB', 'Jzazbz')
print(f"Oklab: {oklab}")
print(f"Jzazbz: {jzazbz}")RGB Colour Space Transformations
# Convert between different RGB colour spaces
srgb = np.array([0.5, 0.3, 0.8])
# Convert sRGB to Adobe RGB (1998)
adobe_rgb = colour.RGB_to_RGB(
srgb,
colour.RGB_COLOURSPACE_sRGB,
colour.RGB_COLOURSPACE_ADOBE_RGB1998
)
# Convert sRGB to Rec. 2020 for HDR content
rec2020 = colour.RGB_to_RGB(
srgb,
colour.RGB_COLOURSPACE_sRGB,
colour.RGB_COLOURSPACE_BT2020
)
print(f"sRGB: {srgb}")
print(f"Adobe RGB: {adobe_rgb}")
print(f"Rec. 2020: {rec2020}")Cylindrical Colour Representations
# Convert RGB to HSV for colour manipulation
rgb = np.array([0.8, 0.2, 0.4])
hsv = colour.RGB_to_HSV(rgb)
print(f"RGB {rgb} -> HSV {hsv}")
# Modify hue and convert back
hsv_modified = hsv.copy()
hsv_modified[0] = (hsv_modified[0] + 60) % 360 # Shift hue by 60 degrees
rgb_modified = colour.HSV_to_RGB(hsv_modified)
print(f"Modified RGB: {rgb_modified}")
# Polar coordinate representations for perceptual uniformity
lab = colour.convert(rgb, 'sRGB', 'Lab')
lchab = colour.Lab_to_LCHab(lab)
print(f"Lab {lab} -> LCHab {lchab}")
oklab = colour.convert(rgb, 'sRGB', 'Oklab')
oklch = colour.Oklab_to_Oklch(oklab)
print(f"Oklab {oklab} -> Oklch {oklch}")Advanced Colour Space Applications
# HDR-capable colour space conversions
hdr_rgb = np.array([2.0, 1.5, 0.8]) # HDR values > 1.0
# Use Jzazbz for HDR content
jzazbz = colour.convert(hdr_rgb, 'BT2020', 'Jzazbz')
print(f"HDR RGB -> Jzazbz: {jzazbz}")
# Convert to ICtCp for video processing
ictcp = colour.convert(hdr_rgb, 'BT2020', 'ICtCp')
print(f"HDR RGB -> ICtCp: {ictcp}")
# Wide gamut colour space handling
wide_gamut_rgb = np.array([0.9, -0.1, 0.7]) # Out-of-sRGB-gamut colour
p3_rgb = colour.convert(wide_gamut_rgb, 'BT2020', 'Display P3')
print(f"BT2020 -> Display P3: {p3_rgb}")Automatic Conversion Path Analysis
# Understand conversion paths
path = colour.describe_conversion_path('sRGB', 'Oklab')
print("sRGB to Oklab conversion path:")
print(path)
# Multiple conversion paths available
path_cam16 = colour.describe_conversion_path('Lab', 'CAM16UCS')
print("\nLab to CAM16UCS conversion path:")
print(path_cam16)Install with Tessl CLI
npx tessl i tessl/pypi-colour-science