colour.plotting.volume Module¶

Colour Models Volume Plotting¶

Defines colour models volume and gamut plotting objects:

RGB_colourspaces_gamuts_plot()
RGB_scatter_plot()

colour.plotting.volume.common_colourspace_model_axis_reorder(a, model=None)[source]¶

Reorder axis of given colourspace model \(a\) values accordingly to its most common volume plotting axis order.

Parameters:	a (array_like) – Colourspace model values \(a\). model (unicode, optional) – {‘CIE XYZ’, ‘CIE xyY’, ‘CIE Lab’, ‘CIE Luv’, ‘CIE UCS’, ‘CIE UVW’, ‘IPT’, ‘Hunter Lab’, ‘Hunter Rdab’} Colourspace model.
Returns:	Reordered colourspace model values.
Return type:	Figure

Examples

>>> a = np.array([0, 1, 2])
>>> common_colourspace_model_axis_reorder(a)
array([0, 1, 2])
>>> common_colourspace_model_axis_reorder(a, 'CIE Lab')
array([1, 2, 0])
>>> common_colourspace_model_axis_reorder(a, 'CIE LCHab')
array([1, 2, 0])
>>> common_colourspace_model_axis_reorder(a, 'CIE Luv')
array([1, 2, 0])
>>> common_colourspace_model_axis_reorder(a, 'CIE LCHab')
array([1, 2, 0])
>>> common_colourspace_model_axis_reorder(a, 'IPT')
array([1, 2, 0])

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.

Other Parameters:
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.
	grid_face_colours (array_like, optional) – Grid face colours array such as grid_face_colours = (0.25, 0.25, 0.25). grid_edge_colours (array_like, optional) – Grid edge colours array such as grid_edge_colours = (0.25, 0.25, 0.25). grid_face_alpha (numeric, optional) – Grid face opacity value such as grid_face_alpha = 0.1. grid_edge_alpha (numeric, optional) – Grid edge opacity value such as grid_edge_alpha = 0.5. x_axis_colour (array_like, optional) – X axis colour array such as x_axis_colour = (0.0, 0.0, 0.0, 1.0). y_axis_colour (array_like, optional) – Y axis colour array such as y_axis_colour = (0.0, 0.0, 0.0, 1.0). x_ticks_colour (array_like, optional) – X axis ticks colour array such as x_ticks_colour = (0.0, 0.0, 0.0, 0.85). y_ticks_colour (array_like, optional) – Y axis ticks colour array such as y_ticks_colour = (0.0, 0.0, 0.0, 0.85). x_label_colour (array_like, optional) – X axis label colour array such as x_label_colour = (0.0, 0.0, 0.0, 0.85). y_label_colour (array_like, optional) – Y axis label colour array such as y_label_colour = (0.0, 0.0, 0.0, 0.85). ticks_and_label_location (array_like, optional) – Location of the X and Y axis ticks and labels such as ticks_and_label_location = (‘-x’, ‘-y’).
Returns:	Grid quads, faces colours, edges colours.
Return type:	tuple

Examples

>>> nadir_grid(segments=1)
(array([[[-1.   , -1.   ,  0.   ],
        [ 1.   , -1.   ,  0.   ],
        [ 1.   ,  1.   ,  0.   ],
        [-1.   ,  1.   ,  0.   ]],

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

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

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

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

       [[-1.   , -0.001,  0.   ],
        [ 1.   , -0.001,  0.   ],
        [ 1.   ,  0.001,  0.   ],
        [-1.   ,  0.001,  0.   ]],

       [[-0.001, -1.   ,  0.   ],
        [ 0.001, -1.   ,  0.   ],
        [ 0.001,  1.   ,  0.   ],
        [-0.001,  1.   ,  0.   ]]]), array([[ 0.25,  0.25,  0.25,  0.1 ],
       [ 0.  ,  0.  ,  0.  ,  0.  ],
       [ 0.  ,  0.  ,  0.  ,  0.  ],
       [ 0.  ,  0.  ,  0.  ,  0.  ],
       [ 0.  ,  0.  ,  0.  ,  0.  ],
       [ 0.  ,  0.  ,  0.  ,  1.  ],
       [ 0.  ,  0.  ,  0.  ,  1.  ]]), array([[ 0.5 ,  0.5 ,  0.5 ,  0.5 ],
       [ 0.75,  0.75,  0.75,  0.25],
       [ 0.75,  0.75,  0.75,  0.25],
       [ 0.75,  0.75,  0.75,  0.25],
       [ 0.75,  0.75,  0.75,  0.25],
       [ 0.  ,  0.  ,  0.  ,  1.  ],
       [ 0.  ,  0.  ,  0.  ,  1.  ]]))

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, display_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.

Other Parameters:
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’, ‘Hunter Lab’, ‘Hunter Rdab’}, Reference colourspace to plot the gamuts into. segments (int, optional) – Edge segments count for each RGB colourspace cubes. display_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 (dict, optional) – {`nadir_grid()`}, Please refer to the documentation of the previously listed definitions. face_colours* (array_like, optional) – Face colours array such as face_colours = (None, (0.5, 0.5, 1.0)). edge_colours (array_like, optional) – Edge colours array such as edge_colours = (None, (0.5, 0.5, 1.0)). face_alpha (numeric, optional) – Face opacity value such as face_alpha = (0.5, 1.0). edge_alpha (numeric, optional) – Edge opacity value such as edge_alpha = (0.0, 1.0).
Returns:	Current figure or None.
Return type:	Figure

Examples

>>> c = ['Rec. 709', 'ACEScg', 'S-Gamut']
>>> RGB_colourspaces_gamuts_plot(c)  

colour.plotting.volume.RGB_scatter_plot(RGB, colourspace, reference_colourspace='CIE xyY', colourspaces=None, segments=8, display_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.

Other Parameters:
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’, ‘Hunter Lab’, ‘Hunter Rdab’}, 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. display_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 (dict, optional*) – {`RGB_colourspaces_gamuts_plot()`}, Please refer to the documentation of the previously listed definitions.
Returns:	Current figure or None.
Return type:	Figure

Examples

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