Format color conversion docstrings.

This commit is contained in:
Stefan van der Walt
2013-10-27 22:06:13 +02:00
parent 888ef05b63
commit 3dd1bc1794
2 changed files with 94 additions and 92 deletions
+73 -73
View File
@@ -34,7 +34,7 @@ Supported color spaces
perceptually uniform
* LCH CIE : Lightness, Chroma, Hue
Defined in terms of LAB CIE. C and H are the polar representation of
a and b. The polar angle C is defined to be on (0, 2*pi)
a and b. The polar angle C is defined to be on ``(0, 2*pi)``
:author: Nicolas Pinto (rgb2hsv)
:author: Ralf Gommers (hsv2rgb)
@@ -71,7 +71,7 @@ def guess_spatial_dimensions(image):
-------
spatial_dims : int or None
The number of spatial dimensions of `image`. If ambiguous, the value
is `None`.
is ``None``.
Raises
------
@@ -125,12 +125,12 @@ def convert_colorspace(arr, fromspace, tospace):
The image to convert.
fromspace : str
The color space to convert from. Valid color space strings are
['RGB', 'HSV', 'RGB CIE', 'XYZ']. Value may also be specified as lower
case.
``['RGB', 'HSV', 'RGB CIE', 'XYZ']``. Value may also be specified as
lower case.
tospace : str
The color space to convert to. Valid color space strings are
['RGB', 'HSV', 'RGB CIE', 'XYZ']. Value may also be specified as lower
case.
``['RGB', 'HSV', 'RGB CIE', 'XYZ']``. Value may also be specified as
lower case.
Returns
-------
@@ -140,7 +140,7 @@ def convert_colorspace(arr, fromspace, tospace):
Notes
-----
Conversion occurs through the "central" RGB color space, i.e. conversion
from XYZ to HSV is implemented as XYZ -> RGB -> HSV instead of directly.
from XYZ to HSV is implemented as ``XYZ -> RGB -> HSV`` instead of directly.
Examples
--------
@@ -184,17 +184,17 @@ def rgb2hsv(rgb):
Parameters
----------
rgb : array_like
The image in RGB format, in a 3-D array of shape (.., .., 3).
The image in RGB format, in a 3-D array of shape ``(.., .., 3)``.
Returns
-------
out : ndarray
The image in HSV format, in a 3-D array of shape (.., .., 3).
The image in HSV format, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `rgb` is not a 3-D array of shape (.., .., 3).
If `rgb` is not a 3-D array of shape ``(.., .., 3)``.
Notes
-----
@@ -262,21 +262,21 @@ def hsv2rgb(hsv):
Parameters
----------
hsv : array_like
The image in HSV format, in a 3-D array of shape (.., .., 3).
The image in HSV format, in a 3-D array of shape ``(.., .., 3)``.
Returns
-------
out : ndarray
The image in RGB format, in a 3-D array of shape (.., .., 3).
The image in RGB format, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `hsv` is not a 3-D array of shape (.., .., 3).
If `hsv` is not a 3-D array of shape ``(.., .., 3)``.
Notes
-----
The conversion assumes an input data range of [0, 1] for all
The conversion assumes an input data range of ``[0, 1]`` for all
color components.
Conversion between RGB and HSV color spaces results in some loss of
@@ -471,17 +471,17 @@ def xyz2rgb(xyz):
Parameters
----------
xyz : array_like
The image in XYZ format, in a 3-D array of shape (.., .., 3).
The image in XYZ format, in a 3-D array of shape ``(.., .., 3)``.
Returns
-------
out : ndarray
The image in RGB format, in a 3-D array of shape (.., .., 3).
The image in RGB format, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `xyz` is not a 3-D array of shape (.., .., 3).
If `xyz` is not a 3-D array of shape ``(.., .., 3)``.
Notes
-----
@@ -516,18 +516,18 @@ def rgb2xyz(rgb):
----------
rgb : array_like
The image in RGB format, in a 3- or 4-D array of shape
(.., ..,[ ..,] 3).
``(.., ..,[ ..,] 3)``.
Returns
-------
out : ndarray
The image in XYZ format, in a 3- or 4-D array of shape
(.., ..,[ ..,] 3).
``(.., ..,[ ..,] 3)``.
Raises
------
ValueError
If `rgb` is not a 3- or 4-D array of shape (.., ..,[ ..,] 3).
If `rgb` is not a 3- or 4-D array of shape ``(.., ..,[ ..,] 3)``.
Notes
-----
@@ -559,17 +559,17 @@ def rgb2rgbcie(rgb):
Parameters
----------
rgb : array_like
The image in RGB format, in a 3-D array of shape (.., .., 3).
The image in RGB format, in a 3-D array of shape ``(.., .., 3)``.
Returns
-------
out : ndarray
The image in RGB CIE format, in a 3-D array of shape (.., .., 3).
The image in RGB CIE format, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `rgb` is not a 3-D array of shape (.., .., 3).
If `rgb` is not a 3-D array of shape ``(.., .., 3)``.
References
----------
@@ -591,17 +591,17 @@ def rgbcie2rgb(rgbcie):
Parameters
----------
rgbcie : array_like
The image in RGB CIE format, in a 3-D array of shape (.., .., 3).
The image in RGB CIE format, in a 3-D array of shape ``(.., .., 3)``.
Returns
-------
out : ndarray
The image in RGB format, in a 3-D array of shape (.., .., 3).
The image in RGB format, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `rgbcie` is not a 3-D array of shape (.., .., 3).
If `rgbcie` is not a 3-D array of shape ``(.., .., 3)``.
References
----------
@@ -624,8 +624,8 @@ def rgb2gray(rgb):
Parameters
----------
rgb : array_like
The image in RGB format, in a 3-D array of shape (.., .., 3),
or in RGBA format with shape (.., .., 4).
The image in RGB format, in a 3-D array of shape ``(.., .., 3)``,
or in RGBA format with shape ``(.., .., 4)``.
Returns
-------
@@ -635,8 +635,8 @@ def rgb2gray(rgb):
Raises
------
ValueError
If `rgb2gray` is not a 3-D array of shape (.., .., 3) or
(.., .., 4).
If `rgb2gray` is not a 3-D array of shape ``(.., .., 3)`` or
``(.., .., 4)``.
References
----------
@@ -701,18 +701,18 @@ def xyz2lab(xyz):
----------
xyz : array_like
The image in XYZ format, in a 3- or 4-D array of shape
(.., ..,[ ..,] 3).
``(.., ..,[ ..,] 3)``.
Returns
-------
out : ndarray
The image in CIE-LAB format, in a 3- or 4-D array of shape
(.., ..,[ ..,] 3).
``(.., ..,[ ..,] 3)``.
Raises
------
ValueError
If `xyz` is not a 3-D array of shape (.., ..,[ ..,] 3).
If `xyz` is not a 3-D array of shape ``(.., ..,[ ..,] 3)``.
Notes
-----
@@ -758,21 +758,21 @@ def lab2xyz(lab):
Parameters
----------
lab : array_like
The image in lab format, in a 3-D array of shape (.., .., 3).
The image in lab format, in a 3-D array of shape ``(.., .., 3)``.
Returns
-------
out : ndarray
The image in XYZ format, in a 3-D array of shape (.., .., 3).
The image in XYZ format, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `lab` is not a 3-D array of shape (.., .., 3).
If `lab` is not a 3-D array of shape ``(.., .., 3)``.
Notes
-----
Observer= 2A, Illuminant= D65
Observer = 2A, Illuminant = D65
CIE XYZ tristimulus values x_ref = 95.047, y_ref = 100., z_ref = 108.883
References
@@ -807,18 +807,18 @@ def rgb2lab(rgb):
----------
rgb : array_like
The image in RGB format, in a 3- or 4-D array of shape
(.., ..,[ ..,] 3).
``(.., ..,[ ..,] 3)``.
Returns
-------
out : ndarray
The image in Lab format, in a 3- or 4-D array of shape
(.., ..,[ ..,] 3).
``(.., ..,[ ..,] 3)``.
Raises
------
ValueError
If `rgb` is not a 3- or 4-D array of shape (.., ..,[ ..,] 3).
If `rgb` is not a 3- or 4-D array of shape ``(.., ..,[ ..,] 3)``.
Notes
-----
@@ -833,17 +833,17 @@ def lab2rgb(lab):
Parameters
----------
rgb : array_like
The image in Lab format, in a 3-D array of shape (.., .., 3).
The image in Lab format, in a 3-D array of shape ``(.., .., 3)``.
Returns
-------
out : ndarray
The image in RGB format, in a 3-D array of shape (.., .., 3).
The image in RGB format, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `lab` is not a 3-D array of shape (.., .., 3).
If `lab` is not a 3-D array of shape ``(.., .., 3)``.
Notes
-----
@@ -858,7 +858,7 @@ def xyz2luv(xyz):
Parameters
----------
xyz : (M, N, [P,] 3) array_like
The 3 or 4 dimensional image in XYZ format. Final dimension denotes
The 3 or 4 dimensional image in XYZ format. Final dimension denotes
channels.
Returns
@@ -869,12 +869,12 @@ def xyz2luv(xyz):
Raises
------
ValueError
If `xyz` is not a 3-D or 4-D array of shape `(M, N, [P,] 3)`.
If `xyz` is not a 3-D or 4-D array of shape ``(M, N, [P,] 3)``.
Notes
-----
XYZ conversion weights use Observer = 2A. Reference whitepoint for D65
Illuminant, with XYZ tristimulus values of `(95.047, 100., 108.883)`.
XYZ conversion weights use Observer = 2A. Reference whitepoint for D65
Illuminant, with XYZ tristimulus values of ``(95.047, 100., 108.883)``.
References
----------
@@ -936,12 +936,12 @@ def luv2xyz(luv):
Raises
------
ValueError
If `luv` is not a 3-D or 4-D array of shape `(M, N, [P,] 3)`.
If `luv` is not a 3-D or 4-D array of shape ``(M, N, [P,] 3)``.
Notes
-----
XYZ conversion weights use Observer = 2A. Reference whitepoint for D65
Illuminant, with XYZ tristimulus values of `(95.047, 100., 108.883)`.
XYZ conversion weights use Observer = 2A. Reference whitepoint for D65
Illuminant, with XYZ tristimulus values of ``(95.047, 100., 108.883)``.
References
----------
@@ -986,7 +986,7 @@ def rgb2luv(rgb):
Parameters
----------
rgb : (M, N, [P,] 3) array_like
The 3 or 4 dimensional image in RGB format. Final dimension denotes
The 3 or 4 dimensional image in RGB format. Final dimension denotes
channels.
Returns
@@ -997,7 +997,7 @@ def rgb2luv(rgb):
Raises
------
ValueError
If `rgb` is not a 3-D or 4-D array of shape `(M, N, [P,] 3)`.
If `rgb` is not a 3-D or 4-D array of shape ``(M, N, [P,] 3)``.
Notes
-----
@@ -1023,7 +1023,7 @@ def luv2rgb(luv):
Raises
------
ValueError
If `luv` is not a 3-D or 4-D array of shape `(M, N, [P,] 3)`.
If `luv` is not a 3-D or 4-D array of shape ``(M, N, [P,] 3)``.
Notes
-----
@@ -1038,17 +1038,17 @@ def rgb2hed(rgb):
Parameters
----------
rgb : array_like
The image in RGB format, in a 3-D array of shape (.., .., 3).
The image in RGB format, in a 3-D array of shape ``(.., .., 3)``.
Returns
-------
out : ndarray
The image in HED format, in a 3-D array of shape (.., .., 3).
The image in HED format, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `rgb` is not a 3-D array of shape (.., .., 3).
If `rgb` is not a 3-D array of shape ``(.., .., 3)``.
References
@@ -1074,17 +1074,17 @@ def hed2rgb(hed):
Parameters
----------
hed : array_like
The image in the HED color space, in a 3-D array of shape (.., .., 3).
The image in the HED color space, in a 3-D array of shape ``(.., .., 3)``.
Returns
-------
out : ndarray
The image in RGB, in a 3-D array of shape (.., .., 3).
The image in RGB, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `hed` is not a 3-D array of shape (.., .., 3).
If `hed` is not a 3-D array of shape ``(.., .., 3)``.
References
----------
@@ -1110,19 +1110,19 @@ def separate_stains(rgb, conv_matrix):
Parameters
----------
rgb : array_like
The image in RGB format, in a 3-D array of shape (.., .., 3).
The image in RGB format, in a 3-D array of shape ``(.., .., 3)``.
conv_matrix: ndarray
The stain separation matrix as described by G. Landini [1]_.
Returns
-------
out : ndarray
The image in stain color space, in a 3-D array of shape (.., .., 3).
The image in stain color space, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `rgb` is not a 3-D array of shape (.., .., 3).
If `rgb` is not a 3-D array of shape ``(.., .., 3)``.
Notes
-----
@@ -1164,19 +1164,19 @@ def combine_stains(stains, conv_matrix):
Parameters
----------
stains : array_like
The image in stain color space, in a 3-D array of shape (.., .., 3).
The image in stain color space, in a 3-D array of shape ``(.., .., 3)``.
conv_matrix: ndarray
The stain separation matrix as described by G. Landini [1]_.
Returns
-------
out : ndarray
The image in RGB format, in a 3-D array of shape (.., .., 3).
The image in RGB format, in a 3-D array of shape ``(.., .., 3)``.
Raises
------
ValueError
If `stains` is not a 3-D array of shape (.., .., 3).
If `stains` is not a 3-D array of shape ``(.., .., 3)``.
Notes
-----
@@ -1226,9 +1226,9 @@ def lab2lch(lab):
Parameters
----------
lab : array_like
The N-D image in CIE-LAB format. The last (`N+1`th) dimension must have
at least 3 elements, corresponding to the ``L``, ``a``, and ``b`` color
channels. Subsequent elements are copied.
The N-D image in CIE-LAB format. The last (``N+1``-th) dimension must
have at least 3 elements, corresponding to the ``L``, ``a``, and ``b``
color channels. Subsequent elements are copied.
Returns
-------
@@ -1242,7 +1242,7 @@ def lab2lch(lab):
Notes
-----
The Hue is expressed as an angle between (0, 2*pi)
The Hue is expressed as an angle between ``(0, 2*pi)``
Examples
--------
@@ -1262,7 +1262,7 @@ def lab2lch(lab):
def _cart2polar_2pi(x, y):
"""convert cartesian coordiantes to polar (uses non-standard theta range!)
NON-STANDARD RANGE! Maps to (0, 2*pi) rather than usual (-pi, +pi)
NON-STANDARD RANGE! Maps to ``(0, 2*pi)`` rather than usual ``(-pi, +pi)``
"""
r, t = np.hypot(x, y), np.arctan2(y, x)
t += np.where(t < 0., 2 * np.pi, 0)
@@ -1277,9 +1277,9 @@ def lch2lab(lch):
Parameters
----------
lch : array_like
The N-D image in CIE-LCH format. The last (`N+1`th) dimension must have
at least 3 elements, corresponding to the ``L``, ``a``, and ``b`` color
channels. Subsequent elements are copied.
The N-D image in CIE-LCH format. The last (``N+1``-th) dimension must
have at least 3 elements, corresponding to the ``L``, ``a``, and ``b``
color channels. Subsequent elements are copied.
Returns
-------
+21 -19
View File
@@ -71,24 +71,24 @@ class TestColorconv(TestCase):
colbars_point75_array = np.swapaxes(colbars_point75.reshape(3, 4, 2), 0, 2)
xyz_array = np.array([[[0.4124, 0.21260, 0.01930]], # red
[[0, 0, 0]], # black
[[.9505, 1., 1.089]], # white
[[.1805, .0722, .9505]], # blue
[[.07719, .15438, .02573]], # green
])
[[0, 0, 0]], # black
[[.9505, 1., 1.089]], # white
[[.1805, .0722, .9505]], # blue
[[.07719, .15438, .02573]], # green
])
lab_array = np.array([[[53.233, 80.109, 67.220]], # red
[[0., 0., 0.]], # black
[[100.0, 0.005, -0.010]], # white
[[32.303, 79.197, -107.864]], # blue
[[46.229, -51.7, 49.898]], # green
])
[[0., 0., 0.]], # black
[[100.0, 0.005, -0.010]], # white
[[32.303, 79.197, -107.864]], # blue
[[46.229, -51.7, 49.898]], # green
])
luv_array = np.array([[[53.233, 175.053, 37.751]], # red
[[0., 0., 0.]], # black
[[100., 0.001, -0.017]], # white
[[32.303, -9.400, -130.358]], # blue
[[46.228, -43.774, 56.589]], # green
])
[[0., 0., 0.]], # black
[[100., 0.001, -0.017]], # white
[[32.303, -9.400, -130.358]], # blue
[[46.228, -43.774, 56.589]], # green
])
# RGB to HSV
def test_rgb2hsv_conversion(self):
@@ -259,7 +259,8 @@ class TestColorconv(TestCase):
img_rgb = img_as_float(self.img_rgb)
assert_array_almost_equal(lab2rgb(rgb2lab(img_rgb)), img_rgb)
# test matrices for xyz2luv and luv2xyz generated using http://www.easyrgb.com/index.php?X=CALC
# test matrices for xyz2luv and luv2xyz generated using
# http://www.easyrgb.com/index.php?X=CALC
# Note: easyrgb website displays xyz*100
def test_xyz2luv(self):
assert_array_almost_equal(xyz2luv(self.xyz_array),
@@ -277,16 +278,17 @@ class TestColorconv(TestCase):
"""
# Obtained with D65 white point, sRGB model and gamma
gt_for_colbars = np.array([
[100,0,0],
[100, 0, 0],
[97.1393, 7.7056, 106.7866],
[91.1132, -70.4773, -15.2042],
[87.7347, -83.0776, 107.3985],
[60.3242, 84.0714, -108.6834],
[53.2408, 175.0151, 37.7564],
[32.2970, -9.4054, -130.3423],
[0,0,0]]).T
[0, 0, 0]]).T
gt_array = np.swapaxes(gt_for_colbars.reshape(3, 4, 2), 0, 2)
assert_array_almost_equal(rgb2luv(self.colbars_array), gt_array, decimal=2)
assert_array_almost_equal(rgb2luv(self.colbars_array),
gt_array, decimal=2)
def test_luv_rgb_roundtrip(self):
img_rgb = img_as_float(self.img_rgb)