colourlab.data module

data: Colour data, part of the colourlab package

Copyright (C) 2013-2017 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.data.Points(sp, ndata)

Bases: object

Class for keeping colour data in various colour spaces and shapes.

flatten(ndata)

Shape the data so that is becomes an PxC matrix or C vector.

The data should be of the shape M x … x N x C, where C is the number of colour channels. Returns the shaped data as a P x C matrix where P = M x … x N, as well as the shape of the input data. Get back to original shape by reshape(data, shape).

Parameters:ndata (ndarray) – M x … x N x C array of colour data Returns:ndata – P x C array of colour data, P = M * … * N Return type:ndarray

get(sp)

Return colour data in required colour space.

If the data do not currently exist in the required colour space, the necessary colour conversion will take place, and the results stored in the object or future use.

Parameters:sp (space.Space) – The colour space for the returned data. Returns:ndata – The colour data in the given colour space. Return type:ndarray

get_flattened(sp)

Return colour data in required colour space in PxC format.

If the data do not currently exist in the required colour space, the necessary colour conversion will take place, and the results stored in the object or future use.

Parameters:sp (space.Space) – The colour space for the returned data. Returns:ndata – The flattend colour data in the given colour space. Return type:ndarray

new_white_point(sp, from_white, to_white)

Return new data set with new white point.

The transformation is done using the von Kries transformation in the given colour space.

Parameters:

• sp (space.Space) – The colour space for the von Kries transformation.
• from_white (data.Points) – The white point of the current data set.
• to_white (data.Points) – The white point of the new data set.

Returns:

data – The new colour data with changed white point.

Return type:

data.Points

set(sp, ndata)

Set colour space and data.

A new dictionary is constructed, and the data are added in the provided colour space, as well as in the XYZ colour space (using the SpaceXYZ class).

Parameters:

• sp (space.Space) – The colour space for the given instanisiation data.
• ndata (ndarray) – The colour data in the given space.

class colourlab.data.Tensors(sp, metrics_ndata, points_data)

Bases: object

Class for keeping colour metric data in various colour spaces.

flatten(ndata)

Shape the data so that is becomes an PxCxC matrix or CxC matrix

The data should be of the shape M x … x N x C x D, where C is the number of colour channels. Returns the shaped data as a P x C matrix where P = M x … x N, as well as the shape of the input data. Get back to original shape by reshape(data, shape).

Parameters:ndata (ndarray) – M x … x N x C x C array of colour metrics Returns:ndata – P x C x C array of colour metrics, P = M * … * N Return type:ndarray

get(sp)

Return metric data in required colour space.

If the data do not currently exist in the required colour space, the necessary colour conversion will take place, and the results stored in the object or future use.

Parameters:sp (space.Space) – The colour space in which to return the tensor data. Returns:tensors – Array of tensors in the given colour space. Return type:ndarray

get_ellipse_parameters(sp, plane=slice(0, 2, None), scale=1)

Return ellipse parameters a, b, theta in the required plane.

The plane is in the given space. For now, plane is represented by a slice giving the correct range for the arrays. Should perhaps be changed in the future.

Parameters:

• sp (space.Space) – The space in which to give the ellipse parameters.
• plane (slice) – The principal plan for the ellipsoid cross sections.
• scale (float) – The scaling (magnification) factor for the ellipses.

Returns:

a_b_theta – N x 3 array of a, b, theta ellipse parameters.

Return type:

ndarray

get_ellipses(sp, plane=slice(0, 2, None), scale=1)

Return Ellipse objects in the required plane of the given space.

For now, plane is represented by a slice giving the correct range for the arrays. Should perhaps be changed in the future.

Parameters:

• sp (space.Space) – The space in which to give the ellipse parameters.
• plane (slice) – The principal plan for the ellipsoid cross sections.
• scale (float) – The scaling (magnification) factor for the ellipses.

Returns:

ellipses – List of Ellipse objects.

Return type:

list

get_flattened(sp)

Return colour data in required colour space in PxC format.

If the data do not currently exist in the required colour space, the necessary colour conversion will take place, and the results stored in the object or future use.

Parameters:sp (space.Space) – The colour space for the returned data. Returns:ndata – The flattend colour data in the given colour space. Return type:ndarray

inner(sp, vec1, vec2)

Return the inner product of the two vectors in the given space.

The result should in theory be invariant with respect to the colour space.

Parameters:

• sp (space.Space) – The space in which to compute the inner product
• vec1 (Vectors) – The first vector
• vec2 (Vectors) – The second vector

Returns:

inner – The inner products (scalars)

Return type:

ndarray

norm(sp, vec)

Compute the norm of a vector data set with a given metric tensor.

The vector set and the tensor data set must have corresponding dimensions.

Parameters:

• sp (space.Space) – The space in which to compute the inner product
• vec (Vectors) – The vectors

Returns:

norms – Array with numerical (scalar) values of the norm.

Return type:

ndarray

norm_sq(sp, vec)

Return the squared norm of a vector data set given the metric tensor.

The vector set and the tensor data set must have corresponding dimensions.

Parameters:

• sp (space.Space) – The space in which to compute the inner product
• vec (Vectors) – The vectors

Returns:

norms – Array with numerical (scalar) values of the squared norm.

Return type:

ndarray

plane_01 = slice(0, 2, None)

plane_10 = slice(1, None, -1)

plane_12 = slice(1, 3, None)

plane_20 = slice(2, None, -2)

plane_aL = slice(1, None, -1)

plane_ab = slice(1, 3, None)

plane_bL = slice(2, None, -2)

plane_xy = slice(0, 2, None)

set(sp, metrics_ndata, points_data)

Set colour sp, points, and metrics data.

The points_data are taken care already of the type Points. A new dictionary is constructed, and the metrics_ndata are added in the provided colour space, as well as in the XYZ colour space (using thespace.SpaceXYZ class).

Parameters:

• sp (space.Space) – The colour space for the given tensor data.
• metrics_ndata (ndarray) – The tensor data in the given colour space at the given points.
• points_data (data.Points) – The colour points for the given tensor data.

class colourlab.data.Vectors(sp, vectors_ndata, points_data)

Bases: object

Class for keeping contravariant vector data in various colour spaces.

flatten(ndata)

Shape the data so that is becomes an PxC matrix or C vector.

The data should be of the shape M x … x N x C, where C is the number of colour channels. Returns the shaped data as a P x C matrix where P = M x … x N, as well as the shape of the input data. Get back to original shape by reshape(data, shape).

Parameters:ndata (ndarray) – M x … x N x C array of colour data Returns:ndata – P x C array of colour data, P = M * … * N Return type:ndarray

get(sp)

Return colour vector data in required colour space.

If the data do not currently exist in the required colour space, the necessary colour conversion will take place, and the results stored in the object or future use.

Parameters:sp (space.Space) – The colour space for the returned data. Returns:ndata – The colour vector data in the given colour space. Return type:ndarray

get_flattened(sp)

Return colour vector data in required colour space in PxC format.

If the data do not currently exist in the required colour space, the necessary colour conversion will take place, and the results stored in the object or future use.

Parameters:sp (space.Space) – The colour space for the returned data. Returns:ndata – The flattend colour vector data in the given colour space. Return type:ndarray

set(sp, vectors_ndata, points_data)

Set colour sp, points, and vectorss data.

The points_data are taken care already of the type Points. A new dictionary is constructed, and the vectors_ndata are added in the provided colour space, as well as in the XYZ colour space (using the SpaceXYZ class).

Parameters:

• sp (space.Space) – The colour space for the given tensor data.
• vectors_ndata (ndarray) – The vector data in the given colour space at the given points.
• points_data (data.Points) – The colour points for the given tensor data.

colourlab.data.d_Melgosa()

The data points for the Melgosa Ellipsoids (RIT-DuPont).

Copied verbatim from pdf of CRA paper. Uses the ellipsoids fitted in CIELAB and returns Tensors.

Returns:d_Melgosa – The centre points of Melgosa’s RIT-DuPont ellipsoids. Return type:data.Points

colourlab.data.d_Munsell(dataset='real')

The Munsell renotation data under illuminant C for the 2 degree observer.

Parameters:dataset (string) – Which data set. Either ‘all’, ‘real’, or ‘1929’. See http://www.cis.rit.edu/research/mcsl2/online/munsell.php for details. Returns:

• d_Munsell (data.Points) – The Munsell colours.
• munsell_names (list) – The standard Munsell value names (H, V, C).
• munsell_lab (ndarray) – Numeric version of the Munsell values names in a normalised Lab type coordinate system. Follows the layout of McCann J. Elect. Imag. 1999

colourlab.data.d_XYZ_31()

Read CIE XYZ 1931 functions.

Returns:xyz_31 – The XYZ 1931 colour matching functions. Return type:data.Points

colourlab.data.d_XYZ_64()

Read CIE XYZ 1964 functions.

Returns:xyz_64 – The XYZ 1964 colour matching functions. Return type:data.Points

colourlab.data.d_regular(sp, x_val, y_val, z_val)

Build regular data set of colour data in the given colour space.

x_val, y_val, and z_val should be one-dimensional arrays.

Parameters:

• sp (space.Space) – The given colour space.
• x_val (ndarray) – Array of x values.
• y_val (ndarray) – Array of y values.
• z_val (ndarray) – Array of z values.

Returns:

data – Regular structure of colour data in the given colour space.

Return type:

data.Points

colourlab.data.g_BFD(dataset='P')

Return the BFD data set ellipses of the required type.

Parameters:dataset (string) – The data set to use, either ‘P’, ‘A’, or ‘2’, for perceptual, accept, and both, respectively. Returns:bfd – The BDF data set of the required type Return type:Tensors

colourlab.data.g_MacAdam()

MacAdam ellipses (defined in xy, extended arbitrarily to xyY).

Arbitrarily uses Y=0.4 and g33 = 1e3 for extension to 3D.

Returns:MacAdam – The metric tensors corresponding to the MacAdam ellipsoids. Return type:Tensors

colourlab.data.g_Melgosa_Lab()

Melgosa’s CIELAB-fitted ellipsoids for the RIT-DuPont data.

Copied verbatim from pdf of CRA paper. Uses the ellipsoids fitted in CIELAB and returns Tensors.

Returns:Melgosa – The metric tensors corresponding to Melgosa’s ellipsoids. Return type:Tensors

colourlab.data.g_Melgosa_xyY()

Melgosa’s xyY-fitted ellipsoids for the RIT-DuPont data.

Copied verbatim from pdf of CRA paper. Uses the ellipsoids fitted in xyY and returns Tensors.

Returns:Melgosa – The metric tensors corresponding to Melgosa’s ellipsoids. Return type:Tensors

colourlab.data.g_three_observer()

Wyszecki and Fielder’s three observer data set.

Arbitrarily uses Y=0.4 and g33 = 1e3 for extension to 3D. It seems by comparing the data file to the original paper by Wyszecki and Fielder (JOSA, 1971) that only one of the data sets (GW) is represented in the file. Also, the paper reports a full 3D metric, so the arbitrary extension to 3D used here is not really called for.

Returns:threeObserver – The metric tensors corresponding to the three observer ellipsoids. Return type:Tensors

colourlab.data.m_rit_dupont()

Read the full RIT-DuPont individual colour difference data from file.

Returns:rit_dupont – Dictionary with two datasets, dV, weights, and various metrics. Return type:dict

colourlab.data.m_rit_dupont_T50()

Read the reduced RIT-DuPont T50 colour difference data from file.

Returns:rit_dupont – Dictionary with two datasets and dV. Return type:dict

colourlab.data.read_csv_file(filename, pad=-inf)

Read a CSV file and return pylab array.

Parameters:

• filename (string) – Name of the CSV file to read
• pad (float) – Value to pad for missing values.

Returns:

csv_array – The content of the file plus padding.

Return type:

ndarray

colourlab.data.resource_path(relative)

Extend relative path to full path (mainly for setuptools integration).

Parameters:relative (string) – The relative path name. Returns:absolute – The absolute path name. Return type:string