colour.volume Package

Module Contents

colour.volume.is_within_macadam_limits(xyY, illuminant, tolerance=None)

Returns if given CIE xyY colourspace array is within MacAdam limits of given illuminant.

Parameters:
  • xyY (array_like) – CIE xyY colourspace array.
  • illuminant (unicode) – Illuminant.
  • tolerance (numeric, optional) – Tolerance allowed in the inside-triangle check.
Returns:

Is within MacAdam limits.
Return type:

bool

Notes

  • Input CIE xyY colourspace array is in domain [0, 1].
  • This definition requires scipy to be installed.

Examples

>>> is_within_macadam_limits(np.array([0.3205, 0.4131, 0.51]), 'A')
array(True, dtype=bool)
>>> a = np.array([[0.3205, 0.4131, 0.51],
...               [0.0005, 0.0031, 0.001]])
>>> is_within_macadam_limits(a, 'A')
array([ True, False], dtype=bool)
colour.volume.is_within_mesh_volume(points, mesh, tolerance=None)

Returns if given points are within given mesh volume using Delaunay triangulation.

Parameters:
  • points (array_like) – Points to check if they are within mesh volume.
  • mesh (array_like) – Points of the volume used to generate the Delaunay triangulation.
  • tolerance (numeric, optional) – Tolerance allowed in the inside-triangle check.
Returns:

Is within mesh volume.
Return type:

bool

Notes

  • This definition requires scipy to be installed.

Examples

>>> mesh = np.array([[-1.0, -1.0, 1.0],
...                  [1.0, -1.0, 1.0],
...                  [1.0, -1.0, -1.0],
...                  [-1.0, -1.0, -1.0],
...                  [0.0, 1.0, 0.0]])
>>> is_within_mesh_volume(np.array([0.0005, 0.0031, 0.0010]), mesh)
array(True, dtype=bool)
>>> a = np.array([[0.0005, 0.0031, 0.0010],
...               [0.3205, 0.4131, 0.5100]])
>>> is_within_mesh_volume(a, mesh)
array([ True, False], dtype=bool)
colour.volume.is_within_pointer_gamut(XYZ, tolerance=None)

Returns if given CIE XYZ tristimulus values are within Pointer’s Gamut volume.

Parameters:
  • XYZ (array_like) – CIE XYZ tristimulus values.
  • tolerance (numeric, optional) – Tolerance allowed in the inside-triangle check.
Returns:

Is within Pointer’s Gamut.
Return type:

bool

Notes

  • Input CIE XYZ tristimulus values are in domain [0, 1].
  • This definition requires scipy to be installed.

Examples

>>> import numpy as np
>>> is_within_pointer_gamut(np.array([0.3205, 0.4131, 0.5100]))
array(True, dtype=bool)
>>> a = np.array([[0.3205, 0.4131, 0.5100],
...               [0.0005, 0.0031, 0.0010]])
>>> is_within_pointer_gamut(a)
array([ True, False], dtype=bool)
colour.volume.is_within_visible_spectrum(XYZ, cmfs=<colour.colorimetry.cmfs.XYZ_ColourMatchingFunctions object at 0x2abef8d86c10>, tolerance=None)

Returns if given CIE XYZ tristimulus values are within visible spectrum volume / given colour matching functions volume.

Parameters:
  • XYZ (array_like) – CIE XYZ tristimulus values.
  • cmfs (XYZ_ColourMatchingFunctions) – Standard observer colour matching functions.
  • tolerance (numeric, optional) – Tolerance allowed in the inside-triangle check.
Returns:

Is within visible spectrum.
Return type:

bool

Notes

  • Input CIE XYZ tristimulus values are in domain [0, 1].
  • This definition requires scipy to be installed.

Examples

>>> import numpy as np
>>> is_within_visible_spectrum(np.array([0.3205, 0.4131, 0.51]))
array(True, dtype=bool)
>>> a = np.array([[0.3205, 0.4131, 0.51],
...               [-0.0005, 0.0031, 0.001]])
>>> is_within_visible_spectrum(a)
array([ True, False], dtype=bool)
colour.volume.RGB_colourspace_limits(colourspace, illuminant=(0.34567, 0.3585))

Computes given RGB colourspace volume limits in Lab colourspace.

Parameters:
  • colourspace (RGB_Colourspace) – RGB colourspace to compute the volume of.
  • illuminant_Lab (array_like, optional) – Lab colourspace illuminant chromaticity coordinates.
Returns:

RGB colourspace volume limits.
Return type:

ndarray

Examples

>>> from colour import sRGB_COLOURSPACE as sRGB
>>> RGB_colourspace_limits(sRGB)  
array([[   0...        ,  100...        ],
       [ -79.2263741...,   94.6657491...],
       [-114.7846271...,   96.7135199...]])
RGB_colourspace_volume_MonteCarlo(colourspace, samples=10000000.0, limits=array([[ 0, 100],
[-150, 150],
[-150, 150]]), illuminant_Lab=(0.34567, 0.3585), chromatic_adaptation_method=u'CAT02', random_generator=<function random_triplet_generator at 0x2abef83460c8>, random_state=None, processes=None)

Performs given RGB colourspace volume computation using Monte Carlo method and multiprocessing.

Parameters:
  • colourspace (RGB_Colourspace) – RGB colourspace to compute the volume of.
  • samples (numeric, optional) – Samples count.
  • limits (array_like, optional) – Lab colourspace volume.
  • illuminant_Lab (array_like, optional) – Lab colourspace illuminant chromaticity coordinates.
  • chromatic_adaptation_method (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation method.
  • random_generator (generator, optional) – Random triplet generator providing the random samples within the Lab colourspace volume.
  • random_state (RandomState, optional) – Mersenne Twister pseudo-random number generator to use in the random number generator.
  • processes (integer, optional) – Processes count, default to multiprocessing.cpu_count() definition.
Returns:

RGB colourspace volume.
Return type:

float

Notes

The doctest is assuming that np.random.RandomState() definition will return the same sequence no matter which OS or Python version is used. There is however no formal promise about the prng sequence reproducibility of either Python or *Numpy implementations: Laurent. (2012). Reproducibility of python pseudo-random numbers across systems and versions? Retrieved January 20, 2015, from http://stackoverflow.com/questions/8786084/reproducibility-of-python-pseudo-random-numbers-across-systems-and-versions

Examples

>>> from colour import sRGB_COLOURSPACE as sRGB
>>> prng = np.random.RandomState(2)
>>> processes = 1
>>> RGB_colourspace_volume_MonteCarlo(  
...     sRGB, 10e3, random_state=prng, processes=processes)
859...
colour.volume.RGB_colourspace_volume_coverage_MonteCarlo(colourspace, coverage_sampler, samples=10000000.0, random_generator=<function random_triplet_generator at 0x2abef83460c8>, random_state=None)

Returns given RGB colourspace percentage coverage of an arbitrary volume.

Parameters:
  • colourspace (RGB_Colourspace) – RGB colourspace to compute the volume coverage percentage.
  • coverage_sampler (object) – Python object responsible for checking the volume coverage.
  • samples (numeric, optional) – Samples count.
  • random_generator (generator, optional) – Random triplet generator providing the random samples.
  • random_state (RandomState, optional) – Mersenne Twister pseudo-random number generator to use in the random number generator.
Returns:

Percentage coverage of volume.
Return type:

float

Notes

  • This definition requires scipy to be installed.

Examples

>>> from colour import sRGB_COLOURSPACE as sRGB
>>> prng = np.random.RandomState(2)
>>> RGB_colourspace_volume_coverage_MonteCarlo(  
...     sRGB,
...     is_within_pointer_gamut,
...     10e3,
...     random_state=prng)
83...
colour.volume.RGB_colourspace_pointer_gamut_coverage_MonteCarlo(colourspace, samples=10000000.0, random_generator=<function random_triplet_generator at 0x2abef83460c8>, random_state=None)

Returns given RGB colourspace percentage coverage of Pointer’s Gamut volume using Monte Carlo method.

Parameters:
  • colourspace (RGB_Colourspace) – RGB colourspace to compute the Pointer’s Gamut coverage percentage.
  • samples (numeric, optional) – Samples count.
  • random_generator (generator, optional) – Random triplet generator providing the random samples.
  • random_state (RandomState, optional) – Mersenne Twister pseudo-random number generator to use in the random number generator.
Returns:

Percentage coverage of Pointer’s Gamut volume.
Return type:

float

Notes

  • This definition requires scipy to be installed.

Examples

>>> from colour import sRGB_COLOURSPACE as sRGB
>>> prng = np.random.RandomState(2)
>>> RGB_colourspace_pointer_gamut_coverage_MonteCarlo(
...     sRGB,
...     10e3,
...     random_state=prng)  
83...
colour.volume.RGB_colourspace_visible_spectrum_coverage_MonteCarlo(colourspace, samples=10000000.0, random_generator=<function random_triplet_generator at 0x2abef83460c8>, random_state=None)

Returns given RGB colourspace percentage coverage of visible spectrum volume using Monte Carlo method.

Parameters:
  • colourspace (RGB_Colourspace) – RGB colourspace to compute the visible spectrum coverage percentage.
  • samples (numeric, optional) – Samples count.
  • random_generator (generator, optional) – Random triplet generator providing the random samples.
  • random_state (RandomState, optional) – Mersenne Twister pseudo-random number generator to use in the random number generator.
Returns:

Percentage coverage of visible spectrum volume.
Return type:

float

Notes

  • This definition requires scipy to be installed.

Examples

>>> from colour import sRGB_COLOURSPACE as sRGB
>>> prng = np.random.RandomState(2)
>>> RGB_colourspace_visible_spectrum_coverage_MonteCarlo(
...     sRGB,
...     10e3,
...     random_state=prng)  
36...