colour.plotting.volume Module

Colour Models Volume Plotting

Defines colour models volume and gamut plotting objects:

colour.plotting.volume.REFERENCE_COLOURSPACES_TO_LABELS = {'CIE Lab': ('a', 'b', '$L^*$'), 'CIE UVW': ('U', 'V', 'W'), 'CIE xyY': ('x', 'y', 'Y'), 'CIE XYZ': ('X', 'Y', 'Z'), 'CIE Luv': ('$u^\\prime$', '$v^\\prime$', '$L^*$'), 'CIE UCS': ('U', 'V', 'W'), 'IPT': ('P', 'T', 'I')}

Reference colourspaces to labels mapping.

REFERENCE_COLOURSPACES_TO_LABELS : dict
{‘CIE XYZ’, ‘CIE xyY’, ‘CIE Lab’, ‘CIE Luv’, ‘CIE UCS’, ‘CIE UVW’, ‘IPT’}
colour.plotting.volume.nadir_grid(limits=None, segments=10, labels=None, axes=None, **kwargs)[source]

Returns a grid on xy plane made of quad geometric elements and its associated faces and edges colours. Ticks and labels are added to the given axes accordingly to the extended grid settings.

Parameters:
  • limits (array_like, optional) – Extended grid limits.
  • segments (int, optional) – Edge segments count for the extended grid.
  • labels (array_like, optional) – Axis labels.
  • axes (matplotlib.axes.Axes, optional) – Axes to add the grid.
  • **kwargs (**) – {‘grid_face_colours’, ‘grid_edge_colours’, ‘grid_face_alpha’, ‘grid_edge_alpha’, ‘x_axis_colour’, ‘y_axis_colour’, ‘x_ticks_colour’, ‘y_ticks_colour’, ‘x_label_colour’, ‘y_label_colour’, ‘ticks_and_label_location’}, Arguments for the nadir grid such as {'grid_face_colours': (0.25, 0.25, 0.25), 'grid_edge_colours': (0.50, 0.50, 0.50), 'grid_face_alpha': 0.1, 'grid_edge_alpha': 0.5, 'x_axis_colour': (0.0, 0.0, 0.0, 1.0), 'y_axis_colour': (0.0, 0.0, 0.0, 1.0), 'x_ticks_colour': (0.0, 0.0, 0.0, 0.85), 'y_ticks_colour': (0.0, 0.0, 0.0, 0.85), 'x_label_colour': (0.0, 0.0, 0.0, 0.85), 'y_label_colour': (0.0, 0.0, 0.0, 0.85), 'ticks_and_label_location': ('-x', '-y')}
Returns:

Grid quads, faces colours, edges colours.
Return type:

tuple

Examples

>>> c = 'Rec. 709'
>>> RGB_scatter_plot(c)  
True
colour.plotting.volume.XYZ_to_reference_colourspace(XYZ, illuminant, reference_colourspace)[source]

Converts from CIE XYZ tristimulus values to given reference colourspace.

Parameters:
  • XYZ (array_like) – CIE XYZ tristimulus values.
  • illuminant (array_like) – CIE XYZ tristimulus values illuminant xy chromaticity coordinates.
  • reference_colourspace (unicode) – {‘CIE XYZ’, ‘CIE xyY’, ‘CIE xy’, ‘CIE Lab’, ‘CIE Luv’, ‘CIE Luv uv’, ‘CIE UCS’, ‘CIE UCS uv’, ‘CIE UVW’, ‘IPT’}, Reference colourspace to convert the CIE XYZ tristimulus values to.
Returns:

Reference colourspace values.
Return type:

ndarray

Examples

>>> import numpy as np
>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> W = np.array([0.34567, 0.35850])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'CIE XYZ')
array([ 0.0704953...,  0.1008    ,  0.0955831...])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'CIE xyY')
array([ 0.2641477...,  0.3777000...,  0.1008    ])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'CIE xy')
array([ 0.2641477...,  0.3777000...])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'CIE Lab')
array([-23.6230288...,  -4.4141703...,  37.9856291...])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'CIE LCHab')
array([  24.0319036...,  190.5841597...,   37.9856291...])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'CIE Luv')
array([-28.7922944...,  -1.3558195...,  37.9856291...])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'CIE Luv uv')
array([ 0.1508531...,  0.4853297...])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'CIE LCHuv')
array([  28.82419932,  182.69604747,   37.9856291 ])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'CIE UCS uv')
array([ 0.1508531...,  0.32355314...])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'CIE UVW')
array([-28.0483277...,  -0.8805242...,  37.0041149...])
>>> XYZ_to_reference_colourspace(  
... XYZ, W, 'IPT')
array([-0.1111479...,  0.0159474...,  0.3657112...])
colour.plotting.volume.RGB_identity_cube(plane=None, width_segments=16, height_segments=16, depth_segments=16)[source]

Returns an RGB identity cube made of quad geometric elements and its associated RGB colours.

Parameters:
  • plane (array_like, optional) – Any combination of {‘+x’, ‘-x’, ‘+y’, ‘-y’, ‘+z’, ‘-z’}, Included grids in the cube construction.
  • width_segments (int, optional) – Cube segments, quad counts along the width.
  • height_segments (int, optional) – Cube segments, quad counts along the height.
  • depth_segments (int, optional) – Cube segments, quad counts along the depth.
Returns:

Cube quads, RGB colours.
Return type:

tuple

Examples

>>> vertices, RGB = RGB_identity_cube(None, 1, 1, 1)
>>> vertices
array([[[ 0.,  0.,  0.],
        [ 1.,  0.,  0.],
        [ 1.,  1.,  0.],
        [ 0.,  1.,  0.]],

       [[ 0.,  0.,  1.],
        [ 1.,  0.,  1.],
        [ 1.,  1.,  1.],
        [ 0.,  1.,  1.]],

       [[ 0.,  0.,  0.],
        [ 1.,  0.,  0.],
        [ 1.,  0.,  1.],
        [ 0.,  0.,  1.]],

       [[ 0.,  1.,  0.],
        [ 1.,  1.,  0.],
        [ 1.,  1.,  1.],
        [ 0.,  1.,  1.]],

       [[ 0.,  0.,  0.],
        [ 0.,  1.,  0.],
        [ 0.,  1.,  1.],
        [ 0.,  0.,  1.]],

       [[ 1.,  0.,  0.],
        [ 1.,  1.,  0.],
        [ 1.,  1.,  1.],
        [ 1.,  0.,  1.]]])
>>> RGB
array([[ 0.5,  0.5,  0. ],
       [ 0.5,  0.5,  1. ],
       [ 0.5,  0. ,  0.5],
       [ 0.5,  1. ,  0.5],
       [ 0. ,  0.5,  0.5],
       [ 1. ,  0.5,  0.5]])
colour.plotting.volume.RGB_colourspaces_gamuts_plot(colourspaces=None, reference_colourspace='CIE xyY', segments=8, grid=True, grid_segments=10, spectral_locus=False, spectral_locus_colour=None, cmfs='CIE 1931 2 Degree Standard Observer', **kwargs)[source]

Plots given RGB colourspaces gamuts in given reference colourspace.

Parameters:
  • colourspaces (array_like, optional) – RGB colourspaces to plot the gamuts.
  • reference_colourspace (unicode, optional) – {‘CIE XYZ’, ‘CIE xyY’, ‘CIE Lab’, ‘CIE Luv’, ‘CIE UCS’, ‘CIE UVW’, ‘IPT’}, Reference colourspace to plot the gamuts into.
  • segments (int, optional) – Edge segments count for each RGB colourspace cubes.
  • grid (bool, optional) – Display a grid at the bottom of the RGB colourspace cubes.
  • grid_segments (bool, optional) – Edge segments count for the grid.
  • spectral_locus (bool, optional) – Is spectral locus line plotted.
  • spectral_locus_colour (array_like, optional) – Spectral locus line colour.
  • cmfs (unicode, optional) – Standard observer colour matching functions used for spectral locus.
  • **kwargs (**) –

    {‘face_colours’, ‘edge_colours’, ‘edge_alpha’, ‘face_alpha’}, Arguments for each given colourspace where each key has an array_like value such as: { 'face_colours': (None, (0.5, 0.5, 1.0)), 'edge_colours': (None, (0.5, 0.5, 1.0)), 'edge_alpha': (0.5, 1.0), 'face_alpha': (0.0, 1.0)}

    {‘grid_face_colours’, ‘grid_edge_colours’, ‘grid_face_alpha’, ‘grid_edge_alpha’, ‘x_axis_colour’, ‘y_axis_colour’, ‘x_ticks_colour’, ‘y_ticks_colour’, ‘x_label_colour’, ‘y_label_colour’, ‘ticks_and_label_location’}, Arguments for the nadir grid such as {'grid_face_colours': (0.25, 0.25, 0.25), 'grid_edge_colours': (0.50, 0.50, 0.50), 'grid_face_alpha': 0.1, 'grid_edge_alpha': 0.5, 'x_axis_colour': (0.0, 0.0, 0.0, 1.0), 'y_axis_colour': (0.0, 0.0, 0.0, 1.0), 'x_ticks_colour': (0.0, 0.0, 0.0, 0.85), 'y_ticks_colour': (0.0, 0.0, 0.0, 0.85), 'x_label_colour': (0.0, 0.0, 0.0, 0.85), 'y_label_colour': (0.0, 0.0, 0.0, 0.85), 'ticks_and_label_location': ('-x', '-y')}
Returns:

Definition success.
Return type:

bool

Examples

>>> c = ['Rec. 709', 'ACEScg', 'S-Gamut']
>>> RGB_colourspaces_gamuts_plot(c)  
True
colour.plotting.volume.RGB_scatter_plot(RGB, colourspace, reference_colourspace='CIE xyY', colourspaces=None, segments=8, grid=True, grid_segments=10, spectral_locus=False, spectral_locus_colour=None, points_size=12, cmfs='CIE 1931 2 Degree Standard Observer', **kwargs)[source]

Plots given RGB colourspace array in a scatter plot.

Parameters:
  • RGB (array_like) – RGB colourspace array.
  • colourspace (RGB_Colourspace) – RGB colourspace of the RGB array.
  • reference_colourspace (unicode, optional) – {‘CIE XYZ’, ‘CIE xyY’, ‘CIE Lab’, ‘CIE Luv’, ‘CIE UCS’, ‘CIE UVW’, ‘IPT’}, Reference colourspace for colour conversion.
  • colourspaces (array_like, optional) – RGB colourspaces to plot the gamuts.
  • segments (int, optional) – Edge segments count for each RGB colourspace cubes.
  • grid (bool, optional) – Display a grid at the bottom of the RGB colourspace cubes.
  • grid_segments (bool, optional) – Edge segments count for the grid.
  • spectral_locus (bool, optional) – Is spectral locus line plotted.
  • spectral_locus_colour (array_like, optional) – Spectral locus line colour.
  • points_size (numeric, optional) – Scatter points size.
  • cmfs (unicode, optional) – Standard observer colour matching functions used for spectral locus.
  • **kwargs (**) –

    {‘face_colours’, ‘edge_colours’, ‘edge_alpha’, ‘face_alpha’}, Arguments for each given colourspace where each key has an array_like value such as: { 'face_colours': (None, (0.5, 0.5, 1.0)), 'edge_colours': (None, (0.5, 0.5, 1.0)), 'edge_alpha': (0.5, 1.0), 'face_alpha': (0.0, 1.0)}

    {‘grid_face_colours’, ‘grid_edge_colours’, ‘grid_face_alpha’, ‘grid_edge_alpha’, ‘x_axis_colour’, ‘y_axis_colour’, ‘x_ticks_colour’, ‘y_ticks_colour’, ‘x_label_colour’, ‘y_label_colour’, ‘ticks_and_label_location’}, Arguments for the nadir grid such as {'grid_face_colours': (0.25, 0.25, 0.25), 'grid_edge_colours': (0.50, 0.50, 0.50), 'grid_face_alpha': 0.1, 'grid_edge_alpha': 0.5, 'x_axis_colour': (0.0, 0.0, 0.0, 1.0), 'y_axis_colour': (0.0, 0.0, 0.0, 1.0), 'x_ticks_colour': (0.0, 0.0, 0.0, 0.85), 'y_ticks_colour': (0.0, 0.0, 0.0, 0.85), 'x_label_colour': (0.0, 0.0, 0.0, 0.85), 'y_label_colour': (0.0, 0.0, 0.0, 0.85), 'ticks_and_label_location': ('-x', '-y')}
Returns:

Definition success.
Return type:

bool

Examples

>>> c = 'Rec. 709'
>>> RGB_scatter_plot(c)  
True