colourlab.space module

space: Colour spaces, part of the colourlab package

Copyright (C) 2013-2016 Ivar Farup

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class colourlab.space.Space

Bases: object

Base class for the colour space classes.

empty_matrix(ndata)

Return list of emtpy (zero) matrixes suitable for jacobians etc.

Parameters:ndata (ndarray) – List of colour data. Returns:empty_matrix – List of empty matrices of dimensions corresponding to ndata. Return type:ndarray

inv_jacobian_XYZ(data)

Return the inverse Jacobian to XYZ, dXYZ^i/dx^j.

The inverse Jacobian is calculated at the given data points (of the Points class) by inverting the Jacobian.

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians from XYZ. Return type:ndarray

jacobian_XYZ(data)

Return the Jacobian to XYZ, dx^i/dXYZ^j.

The Jacobian is calculated at the given data points (of the Points class) by inverting the inverse Jacobian.

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to XYZ. Return type:ndarray

metrics_from_XYZ(points_data, metrics_ndata)

Convert metric data from the XYZ colour space.

Parameters:

• points_data (Points) – The colour data points.
• metrics_ndata (ndarray) – Array of colour metric tensors in XYZ.

Returns:

metrics – Array of colour metric tensors in the current colour space.

Return type:

ndarray

metrics_to_XYZ(points_data, metrics_ndata)

Convert metric data to the XYZ colour space.

Parameters:

• points_data (Points) – The colour data points.
• metrics_ndata (ndarray) – Array of colour metric tensors in current colour space.

Returns:

xyz_metrics – Array of colour metric tensors in XYZ.

Return type:

ndarray

vectors_from_XYZ(points_data, vectors_ndata)

Convert metric data from the XYZ colour space.

Parameters:

• points_data (Points) – The colour data points.
• vectors_ndata (ndarray) – Array of colour metric tensors in XYZ.

Returns:

vectors – Array of colour vectors in the current colour space.

Return type:

ndarray

vectors_to_XYZ(points_data, vectors_ndata)

Convert metric data to the XYZ colour space.

Parameters:

• points_data (Points) – The colour data points.
• vectors_ndata (ndarray) – Array of colour metric tensors in current colour space.

Returns:

xyz_vectors – Array of colour vectors in XYZ.

Return type:

ndarray

white_A = array([1.0985 , 1. , 0.35585])

white_B = array([0.99072, 1. , 0.85223])

white_C = array([0.98074, 1. , 0.8232 ])

white_D50 = array([0.96422, 1. , 0.82521])

white_D55 = array([0.95682, 1. , 0.92149])

white_D65 = array([0.95047, 1. , 1.08883])

white_D75 = array([0.94972, 1. , 1.22638])

white_E = array([1., 1., 1.])

white_F11 = array([1.00962, 1. , 0.6435 ])

white_F2 = array([0.99186, 1. , 0.67393])

white_F7 = array([0.95041, 1. , 1.08747])

class colourlab.space.Transform(base)

Bases: colourlab.space.Space

Base class for colour space transforms.

Real transforms (children) must implement to_base, from_base and either jacobian_base or inv_jacobian_base.

from_XYZ(ndata)

Transform data from XYZ using the transformation to the base.

Parameters:ndata (ndarray) – Colour data in the XYZ colour space. Returns:xyz – Colour data in the current colour space. Return type:ndarray

inv_jacobian_XYZ(data)

Return the inverse Jacobian to XYZ, dXYZ^i/dx^j.

The Jacobian is calculated at the given data points (of the Points class) using the inverse jacobian to the base and the inverse Jacobian of the base space.

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians from XYZ. Return type:ndarray

inv_jacobian_base(data)

Return the inverse Jacobian to base, dbase^i/dx^j.

The inverse Jacobian is calculated at the given data points (of the Points class) by inverting the Jacobian.

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians from the base colour space. Return type:ndarray

jacobian_XYZ(data)

Return the Jacobian to XYZ, dx^i/dXYZ^j.

The Jacobian is calculated at the given data points (of the Points class) using the jacobian to the base and the Jacobian of the base space.

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to XYZ. Return type:ndarray

jacobian_base(data)

Return the Jacobian to base, dx^i/dbase^j.

The Jacobian is calculated at the given data points (of the Points class) by inverting the inverse Jacobian.

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_XYZ(ndata)

Transform data to XYZ by using the transformation to the base.

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:xyz – Colour data in the XYZ colour space Return type:ndarray

class colourlab.space.TransformCIEDE00(base)

Bases: colourlab.space.Transform

The CIELAB to CIEDE00 L’a’b’ colour space transform.

from_base(ndata)

Convert from CIELAB (base) to CIEDE00.

Parameters:ndata (ndarray) – Colour data in the base colour space. Returns:labp – Colour data in the CIEDE00 L’a’b’ colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian to CIELAB (base), dCIEDE00^i/dCIELAB^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Convert from CIEDE00 to CIELAB (base).

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformCIELAB(base, white_point=array([0.95047, 1., 1.08883]))

Bases: colourlab.space.Transform

The XYZ to CIELAB colour space transform.

The white point is a parameter in the transform.

dfdx(ndata)

Auxiliary function for the Jacobian.

Returns the derivative of the function f above. Works for arrays.

epsilon = 0.008856451679035631

f(ndata)

Auxiliary function for the conversion.

from_base(ndata)

Convert from XYZ (base) to CIELAB.

Parameters:ndata (ndarray) – Colour data in the base colour space. Returns:col – Colour data in the current colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian to XYZ (base), dCIELAB^i/dXYZ^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

kappa = 903.2962962962963

to_base(ndata)

Convert from CIELAB to XYZ (base).

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformCIELUV(base, white_point=array([0.95047, 1., 1.08883]))

Bases: colourlab.space.Transform

The XYZ to CIELUV colour space transform.

The white point is a parameter in the transform.

dfdx(ndata)

Auxiliary function for the Jacobian.

Returns the derivative of the function f above. Works for arrays.

epsilon = 0.008856451679035631

f(ndata)

Auxiliary function for the conversion.

from_base(ndata)

Convert from XYZ (base) to CIELUV.

Parameters:ndata (ndarray) – Colour data in the base colour space. Returns:col – Colour data in the current colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian to XYZ (base), dCIELUV^i/dXYZ^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

kappa = 903.2962962962963

to_base(ndata)

Convert from CIELUV to XYZ (base).

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformCartesian(base)

Bases: colourlab.space.Transform

Transform form polar to Cartesian coordinates in the two last variables.

For example CIELCH to CIELAB.

from_base(ndata)

Convert from polar to Cartesian.

Parameters:ndata (ndarray) – Colour data in the base colour space. Returns:col – Colour data in the current colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian from CIELCh (base), dCIELAB^i/dCIELCH^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Convert from Cartesian (base) to polar.

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformGamma(base, gamma=1)

Bases: colourlab.space.Transform

General gamma transform, transformed = base**gamma

Uses absolute value and sign for negative base values: transformed = sign(base) * abs(base)**gamma

from_base(ndata)

Convert from XYZ to gamma corrected.

Parameters:ndata (ndarray) – Colour data in the base colour space. Returns:col – Colour data in the current colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian to XYZ (base), dgamma^i/dXYZ^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Convert from gamma corrected to XYZ (base).

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformLGJE(base)

Bases: colourlab.space.Transform

Transform from LGJOSA type coordinates to L_E, G_E, J_E.

from_base(ndata)

Transform from LGJOSA (base) to LGJE.

Parameters:ndata (ndarray) – Colour data in the base colour space (LGJOSA). Returns:col – Colour data in the LGJOSA colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian from LGJOSA (base), dLGJE^i/dLGJOSA^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Convert from LGJE to LGJOSA (base).

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformLGJOSA(base)

Bases: colourlab.space.Transform

Transform from XYZ type coordinates to L_osa G J.

err_func(xyz, lgj)

from_base(ndata)

Transform from base to LGJ OSA.

Parameters:ndata (ndarray) – Colour data in the base colour space (XYZ). Returns:col – Colour data in the LGJOSA colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian from XYZ (base), dLGJOSA^i/dXYZ^j.

The Jacobian is calculated at the given data points (of the Points class). Like the colour space, a terrible mess…

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Convert from LGJOSA to XYZ (base).

Implemented as numerical inversion of the from_base method, since the functions unfortunately are not analytically invertible.

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformLinear(base, M=array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]))

Bases: colourlab.space.Transform

General linear transform, transformed = M * base

from_base(ndata)

Convert from the base to linear.

Parameters:ndata (ndarray) – Colour data in the base colour space. Returns:col – Colour data in the current colour space. Return type:ndarray

inv_jacobian_base(data)

Return the Jacobian from XYZ (base), dXYZ^i/dlinear^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian to XYZ (base), dlinear^i/dXYZ^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Convert from linear to the base.

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformLogCompressC(base, aC, bC)

Bases: colourlab.space.Transform

Perform parametric logarithmic compression of chroma.

As in the DIN99x formulae.

from_base(ndata)

Transform from Lab (base) to La’b’.

Parameters:ndata (ndarray) – Colour data in the base colour space (Lab). Returns:col – Colour data in the La’b’ colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian from Lab (base), dLa’b’^i/dLab^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Transform from La’b’ to Lab (base).

Parameters:ndata (ndarray) – Colour data in L’ab colour space. Returns:col – Colour data in the Lab colour space. Return type:ndarray

class colourlab.space.TransformLogCompressL(base, aL, bL)

Bases: colourlab.space.Transform

Perform parametric logarithmic compression of lightness.

As in the DIN99x formulae.

from_base(ndata)

Transform from Lab (base) to L’ab.

Parameters:ndata (ndarray) – Colour data in the base colour space (Lab). Returns:col – Colour data in the La’b’ colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian from Lab (base), dL’ab^i/dLab^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Transform from L’ab to Lab (base).

Parameters:ndata (ndarray) – Colour data in L’ab colour space. Returns:col – Colour data in the Lab colour space. Return type:ndarray

class colourlab.space.TransformPoincareDisk(base, R=1.0)

Bases: colourlab.space.Transform

Transform from Cartesian coordinates to Poincare disk coordinates.

The coordinate transform only changes the radius (chroma, typically), and does so in a way that preserves the radial distance with respect to the Euclidean metric and the Poincare disk metric in the source and target spaces, respectively.

from_base(ndata)

Transform from base to Poincare disk

Parameters:ndata (ndarray) – Colour data in the base colour space. Returns:col – Colour data in the current colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian from CIELAB (base), dLxy^i/dCIELAB^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Transform from Poincare disk to base.

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformPolar(base)

Bases: colourlab.space.Transform

Transform form Cartesian to polar coordinates in the two last variables.

For example CIELAB to CIELCH.

from_base(ndata)

Convert from Cartesian (base) to polar.

Parameters:ndata (ndarray) – Colour data in the base colour space. Returns:col – Colour data in the current colour space. Return type:ndarray

inv_jacobian_base(data)

Return the Jacobian from CIELAB (base), dCIELAB^i/dCIELCH^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Convert from polar to Cartesian.

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformProjective(base, M=array([[1, 0, 0], [0, 1, 0], [1, 1, 1], [0, 1, 0]]))

Bases: colourlab.space.Transform

General projective transform of the XYZ to xyY type.

from_base(ndata)

Convert from XYZ to xyY.

Parameters:ndata (ndarray) – Colour data in the base colour space. Returns:col – Colour data in the current colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian to XYZ, dxyY^i/dXYZ^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Convert from xyY to XYZ.

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.TransformSRGB(base)

Bases: colourlab.space.Transform

Transform linear RGB with sRGB primaries to sRGB.

from_base(ndata)

Convert from linear RGB to sRGB. Performs gamut clipping if necessary.

Parameters:ndata (ndarray) – Colour data in the linear colour space Returns:col – Colour data in the sRGB colour space Return type:ndarray

jacobian_base(data)

Return the Jacobian to linear RGB (base), dsRGB^i/dRGB^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Convert from sRGB to linear RGB. Performs gamut clipping if necessary.

Parameters:ndata (ndarray) – Colour data in the sRGB colour space Returns:col – Colour data in the linear RGB colour space Return type:ndarray

class colourlab.space.TransformxyY(base)

Bases: colourlab.space.Transform

The XYZ to xyY projective transform.

from_base(ndata)

Convert from XYZ to xyY.

Parameters:ndata (ndarray) – Colour data in the base colour space. Returns:col – Colour data in the current colour space. Return type:ndarray

inv_jacobian_base(data)

Return the Jacobian from XYZ, dXYZ^i/dxyY^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

jacobian_base(data)

Return the Jacobian to XYZ, dxyY^i/dXYZ^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to the base colour space. Return type:ndarray

to_base(ndata)

Convert from xyY to XYZ.

Parameters:ndata (ndarray) – Colour data in the current colour space Returns:col – Colour data in the base colour space Return type:ndarray

class colourlab.space.XYZ

Bases: colourlab.space.Space

The XYZ colour space.

Assumes that the CIE 1931 XYZ colour matching functions are used. The white point is D65. Serves a special role in the code in that it serves as a common reference point.

from_XYZ(ndata)

Convert from XYZ to current colour space.

Parameters:ndata (ndarray) – Colour data in the XYZ colour space. Returns:xyz – Colour data in the current colour space. Return type:ndarray

inv_jacobian_XYZ(data)

Return the inverse Jacobian to XYZ, dXYZ^i/dx^j.

The inverse Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians from XYZ. Return type:ndarray

jacobian_XYZ(data)

Return the Jacobian to XYZ, dx^i/dXYZ^j.

The Jacobian is calculated at the given data points (of the Points class).

Parameters:data (Points) – Colour data points for the jacobians to be computed. Returns:jacobian – The list of Jacobians to XYZ. Return type:ndarray

to_XYZ(ndata)

Convert from current colour space to XYZ.

Parameters:ndata (ndarray) – Colour data in the current colour space. Returns:xyz – Colour data in the XYZ colour space. Return type:ndarray