colourlab.gamut module¶

gamut: Colour gamut operaions. Part of the colourlab package.

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.gamut.Gamut(sp, points, gamma=1, center=None)[source]¶

Bases: object

Class for representing colour gamuts.

The gamuts can be computed in various colour spaces.

HPminDE(c_data)[source]¶

The HPminDE gamut mapping algorithm.

A general implementation of the gamut mapping algorithm HPminDE. Maps all points that lie outside of.. the gamut to the nearest point on the plane formed by the point and the L axe in the CIELAB colour space.

Parameters:	c_data (data.Points) – The colour points.
Returns:	The mapped points.
Return type:	data.Points

static center_of_mass(points)[source]¶

Finds the center of mass of the points given.

To find the “geometric center” of a gamut lets points be only the vertices of the gamut.

Thanks to: http://stackoverflow.com/questions/8917478/center-of-mass-of-a-numpy-array-how-to-make-less-verbose

Parameters:	points (ndarray) – Shape(N, 3), a list of points
Returns:	center – Shape(3,), the coordinate of the center of mass.
Return type:	ndarray

clip_constant_angle(sp, c_data, axis)[source]¶

Find the nearest point with the same angle.

For all points in c_data, this method finds the nearest point on the gamut, constrained to the plane defined by axis and each point. Make sure all points in c_data are outside the gamut. This method maps all points to the gamuts surface.

Parameters:	sp (space.Space) – The color space to work in, usually cielab for this method. c_data (data.Points) – A set of colour points. axis (int) – 0, 1, 2 indicating with axis to use.
Returns:	The nearest points.
Return type:	data.Points

clip_nearest(sp, c_data)[source]¶

Return the nearest points on the gamut surface.

Parameters:	sp (space.Space) – A colour space c_data (data.Points) – A data.Points object with the points to use.
Returns:	The clipped data points.
Return type:	data.Points

compress_axis(sp, c_data, ax)[source]¶

Compress the points linearly in the given axis and colour space.

Parameters:	sp (space.Space) – The colour space to work in. c_data (data.Points) – The points to be compressed. ax (int) – Integer representing which axis to do the compressing.
Returns:	Returns a data.Points object with the new points.
Return type:	data.Points

static find_plane(points)[source]¶

Compute the parameters of the plane.

Find the normal point to a plane(simplices) and the distance from p to the cross point.

Parameters:	points (ndarray) – the start point.
Returns:	n – Returns ndarray with normal points distance. [x, y, z, distance]
Return type:	ndarray

fix_orientation()[source]¶

Fixes the orientation of the facets.

Fixes the orientation of the facets in the hull, so their normal vector points outwards.

static get_alpha(q, center, n)[source]¶

Get the Alpha value by computing.

Parameters:	q (ndarray) – The start point. center (ndarray) – The center is a end point in the color space. n (ndarray) – The normal and distance value for the simplex
Returns:	alpha – Returns alpha value.
Return type:	float

get_coordinates(indices)[source]¶

Return the coordinates of the points correlating to the the indices.

Parameters:	indices (ndarray) – shape(N,), list of indices
Returns:	shape(N, 3)
Return type:	ndarray

get_vertices(nd_data)[source]¶

Get all hull vertices and save them in a array list.

Parameters:	nd_data (ndarray) – Shape(N, 3) A list of points to return vertices from. The a copy of gamut.points pre-converted to a desired colour space.
Returns:	The coordinates of the requested vertices
Return type:	ndarray

static in_line(line, q, true_interior=False)[source]¶

Checks if a point P is on the line segment AB.

Parameters:	line (ndarray) – line segment from point A to point B q (ndarray) – Vector from A to P true_interior (bool) – Set to True if you want to exclude the end points in the search for inclusion.
Returns:	True is P in in the line segment from A to P.
Return type:	bool

in_polygon(points, q, true_interior=False)[source]¶

Checks if q is in the polygon formed by pts

Parameters:	points (ndarray) – shape(4, 3). Points on a polygon. Must be coplanar. q (ndarray) – Point to be tested for inclusion true_interior (boolean) – Activate to exclude the edges from the search

in_tetrahedron(t, p, true_interior=False)[source]¶

Checks if the point p, is inside the tetrahedron.

Checks if the point p (including the surface) is inside the tetrahedron. If ‘p’ is not guaranteed a true tetrahedron, use interior().

Parameters:	t (ndarray) – The four points of a tetrahedron p (ndarray) – The point to be tested for inclusion in the tetrahedron. true_interior (bool) – Activate to exclude the surface of the tetrahedron from the search.
Returns:	True if q is inside, or on the surface of the tetrahedron.
Return type:	bool

in_triangle(triangle, q, true_interior=False)[source]¶

Check if the point q is in the given triangle.

Takes three points of a triangle in 3d, and determines if the point w is within that triangle. This function utilizes the baycentric technique explained here https://blogs.msdn.microsoft.com/rezanour/2011/08/07/barycentric-coordinates-and-point-in-triangle-tests/

Parameters:	triangle (ndarray) – An ndarray with shape: (3,3), with points A, B and C being triangle[0]..[2] q (ndarray) – An ndarray with shape: (3,), the point to be tested for inclusion in the triangle. true_interior (bool) – If true_interior is set to True, returns False if ‘P’ is on one of the triangles edges.
Returns:	True if ‘w’ is within the triangle ABC.
Return type:	bool

initialize_convex_hull(center)[source]¶

Initializes the gamuts convex hull in the desired colour space.

Parameters:	sp (space.Space) – points (data.Points) – The colour points for the gamut.

initialize_modified_convex_hull(gamma, center)[source]¶

Initializes the gamut with the modified convex hull method.

Thanks to Divakar from stackoverflow. http://stackoverflow.com/questions/42763615/proper-python-way-to- work-on-original-in-for-loop?noredirect=1#comment72645178_42763615

Parameters:	gamma (float) – The exponent for modifying the radius. center (ndarray) – Center of expansion.

interior(points, q, true_interior=False)[source]¶

Check if the point is interior to the convex shape.

Finds the vertices of pts convex shape, and calls the appropriate function to test for inclusion. Is not designed to work with more than 4 points.

Parameters:	points (ndarray) – Shape(n, 3). 0 < n < 5. q (ndarray) – Point to be tested for inclusion in pts true shape. true_interior (boolean) – Activate to exclude the edges if pts is actually a triangle or polygon with 4 vertices, or the surface if pts is a tetrahedron
Returns:	True if the point was inside.
Return type:	boolean

intersection_in_line(sp, c_data, center=None)[source]¶

Returns an array containing the nearest point on the gamuts surface.

Returns an array containing the nearest point on the gamuts surface, for every point in the c_data object. Cell number i in the returned array corresponding to cell number i from the ‘c_data’ parameter. Handles input on the format Nx…xMx3.

Parameters:	sp (space.Space) – The colour space c_data (data.Points) – All the points. center (ndarray) – Center point to use when computing the nearest point.
Returns:	Shape(3,) containing the nearest point on the gamuts surface.
Return type:	ndarray

static is_coplanar(p)[source]¶

Checks if the points provided are coplanar.

Does not handle more than 4 points.

Parameters:	p (ndarray) – The points to be tested
Returns:	True if the points are coplanar
Return type:	bool

is_inside(sp, c_data, t=False)[source]¶

For the given data points checks if points are inn the convex hull.

Parameters:	sp (space.Space) – The colour space for computing the gamut. c_data (data.Points) – Points object with the colour points for the gamut. t (boolean) – True if use the traverse method, false if use the flatten method.
Returns:	An array shaped (c_data.get()-1) that contains True for each point included in the convexHull, else False.
Return type:	ndarray

static line_alpha(alpha, q, center)[source]¶

Equation for calculating the nearest point.

Parameters:	alpha (float) – The highest given alpha value q (ndarray) – The start point. center (ndarray) – The center is a end point in the color space.
Returns:	Return the nearest point.
Return type:	ndarray

minDE(c_data)[source]¶

Minimum Delta E clipping.

A general implementation of the gamut mapping algorithm minDE. Maps all points that lie outside of.. the gamut to the nearest point on the gamut in CIELAB colour space.

Parameters:	c_data (data.Points) – All the points.
Returns:	Returns the nearest points.
Return type:	data.Points

plot_surface(sp, ax)[source]¶

Plot all the vertices points on the received axel

Parameters:	ax (Axis) – The axis to draw the points on sp (space.Space) – The colour space for computing the gamut.

static sign(t)[source]¶

Calculates the orientation of the tetrahedron.

Parameters:	t (ndarray) – shape(4,3) The four coordinates of the tetrahedron who’s signed volume is to be calculated
Returns:	1 if tetrahedron is POSITIVE orientated(signed volume > 0) 0 if volume is 0 -1 if tetrahedron is NEGATIVE orientated(signed volume < 0)
Return type:	int

traverse_ndarray(n_data, indices, bool_array)[source]¶

Check if the points are in the convex hull.

For the given data points recursively traverse the dimensions to check if points are inn the convexhull.

Parameters:	n_data (ndarray) – An n-dimensional array containing the remaining dimensions to iterate. indices (array) – The dimensional path to the coordinate. Needs to be as long as the (amount of dimensions)-1 in nda and filled with -1’s bool_array (ndarray) – Array containing true/false in last dimension.

true_shape(points)[source]¶

Removes all points that do not belong to it’s convex polygon.

Works with 4 or less coplanar points.

Parameters:	points (ndarray) – Shape(N, 3) Points in 3d
Returns:	The vertices of a assuming it is supposed to represent a convex shape
Return type:	ndarray