Embed Size (px)
Citation preview
xy_color DocumentationRelease 0.1.dev
Ying Xiong
May 22, 2017
Contents
1 Getting Started 3
2 Introduction 52.1 Names and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 Demos 73.1 Show Spectral Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Show Monochromatic Curve in 3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.3 Show Horseshoe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4 Color Space Transform 11
5 Data 13
6 Utilities 15
7 A Simple Web Application 17
8 Indices and tables 19
Python Module Index 21
i
ii
xy_color Documentation, Release 0.1.dev
Utilities and demos for color science in Python.
Contents 1
xy_color Documentation, Release 0.1.dev
2 Contents
CHAPTER 1
Getting Started
Install xy_python_utils as a prerequisite:
git clone https://github.com/yxiong/xy_python_utilscd xy_python_utilspython setup.py developcd ..
Install this package in development mode:
python setup.py develop
Run demos:
cd xy_colorpython demos.py
Run unit tests:
cd xy_colorpython -m unittest discover -p "*_test.py"cd ..
Generate documentation:
cd docsmake htmlcd ..
3
xy_color Documentation, Release 0.1.dev
4 Chapter 1. Getting Started
CHAPTER 2
Introduction
Names and acronyms
SPD: spectrual power distribution. This is a function of wavelength 𝜆, and describes the power per unit area per unitwavelength of an illumination.
CMF: color matching function. This is a function of wavelength 𝜆 describing the chromatic response of the “ob-server”. A CMF �̄�(·) will have response �̄�(𝜆) at a unit-power light of single wavelength 𝜆, and given a spectral powerdistribution 𝐼(𝜆), the response will be 𝑋 =
∫︀𝐼(𝜆)�̄�(𝜆)𝑑𝜆.
Note that SPD and CMF should not be mistaken with each another. For example, the CIE-RGB color space uses threemonochromatic (single-wavelength) primary colors, which means their SPDs are delta functions, but their CMFs arenot.
LMS: a color space represented by the response of three types of cones of the human eye.
WL: wavelength list. This is a 1D ndarray with equally-spaced entries in increasing order. The wavelength entries arein unit of nano-meter. A typically used WL for visible light range is np.arange(360, 831, 1).
FW: function of wavelength. For a single function, it is represented as a 1D ndarray of length N. For multiple functions,they are represented as a 2D ndarray of shape (K, N), where K is the number of loaded functions, and fw[k] is the k-thfunction, with 0 <= k < K.
5
xy_color Documentation, Release 0.1.dev
6 Chapter 2. Introduction
CHAPTER 3
Demos
Show Spectral Functions
Show common spectral functions (SPDs and CMFs).
Show Monochromatic Curve in 3D
Draw the monochromatic colors of different wavelengths in 3D. This is an interactive demo.
7
xy_color Documentation, Release 0.1.dev
Show Horseshoe
Draw the “color horseshoe”, with useful quantities annotated on it.
8 Chapter 3. Demos
xy_color Documentation, Release 0.1.dev
3.3. Show Horseshoe 9
xy_color Documentation, Release 0.1.dev
10 Chapter 3. Demos
CHAPTER 4
Color Space Transform
color_space_transform.color_space_transform(src_data, src_space, dst_space)Transform an image from a one color space to another color space.
Parameters src_data: ndarray
The input data to be transformed, of either one of following form:
1. a 3xN matrix, with each column representing a color vector.
2. an MxNx3 or MxNx4 image. The alpha channel will be preserved if present.
src_space, dst_space: string
Color spaces to be transformed from and to. Current supported color spaces are: “CIE-XYZ”, “CIE-xyY”, “sRGB-linear”, “sRGB” and “CIE-L*a*b*”.
Returns dst_data : ndarray
The output data after transformation. It will be an ndarray of the same size as src_data.
11
xy_color Documentation, Release 0.1.dev
12 Chapter 4. Color Space Transform
CHAPTER 5
Data
data.adjust_wl(fw_in, wl_in, wl_out)Adjust the wavelength list of the input function(s).
data.adobe_abs_to_norm_xyz(abs_xyz)Converting the absolute XYZ to Adobe normalized XYZ.
The conversion formula is:
Xn = (Xa - Xk) / (Xw - Xk) * Xw / YwYn = (Ya - Yk) / (Yw - Yk)Zn = (Za - Zk) / (Zw - Zk) * Zw / Yw
where (Xa, Ya, Za) is absolute XYZ value, (Xk, Yk, Zk) = (0.5282, 0.5557, 0.6052) is the reference display blackpoint, (Xw, Yw, Zw) = (152.07, 160.00, 174.25) is the reference display white point, and (Xn, Yn, Zn) is thenormalized XYZ value.
Parameters abs_xyz: ndarray
Absolute XYZ values, of the following format:
• 1D ndarray of length 3.
• 2D ndarray of size (3,N).
Returns An ndarray of the same format as input.
References
Accessed from: http://www.adobe.com/digitalimag/pdfs/AdobeRGB1998.pdf.Accessed on: Nov 30, 2014.
data.adobe_gamma(linear_data)The per-channel, nonlinear transfer function used in Adobe RGB (1998) color space.
𝐶 = (𝐶𝑙𝑖𝑛𝑒𝑎𝑟)1/2.19921875
The value 2.19921875 is obtained from (2 + 51/256).
Accessed from: http://www.adobe.com/digitalimag/pdfs/AdobeRGB1998.pdf. Accessed on: Nov 30, 2014.
data.get_blackbody_spd(temperature, wl)Get blackbody radiation spectral power distribution.
13
xy_color Documentation, Release 0.1.dev
data.load_fw(name, wl=None)Load function of wavelength.
Parameters name: str
A string for the name of function, currently support:
• “xyz-cmfs”: CIE-XYZ color matching functions.
• “d65-spd”: CIE-D65 spectral power distribution.
wl: ndarray
Wavelength list, optional.
Returns fw : ndarray
The loaded function(s) of wavelength.
wl : ndarray
It will be the same as input wl if it is not None, or will be loaded together with fw asinput data.
data.read_cvrl_csv(csv_filename, empty_val=0.0)Read a csv file downloaded from cvrl.org.
Some of the entries in the csv are empty, and will be filled with ‘empty_val’. If reading linear data, ‘empty_val’should be set as 0.0, and if reading log data, it should be set as -np.inf.
Returns A ndarray of size Nx2 or Nx4.
The first column is wavelength in unit of nm, and following columns the correspondingfunctions with respect to wavelength.
data.srgb_gamma(linear_data)The per-channel, nonlinear transfer function used in sRGB.
The conversion formula is:
C = 12.92 * C_linear, if C_linear <= 0.00313081.055 * C_linear ** (1/2.4) - 0.055, otherwise
Accessed from: http://www.color.org/chardata/rgb/srgb.pdf.Accessed on: Oct 28, 2014.
data.srgb_inverse_gamma(nonlinear_data)The per-channel transform from nonlinear sRGB data to linear sRGB data.
The conversion formula is:
C_linear = C / 12.92, if C <= 0.04045((C + 0.055) / 1.055) ^ 2.4, otherwise
Accessed from: http://www.color.org/chardata/rgb/srgb.pdf.Accessed on: Apr 24, 2015.
14 Chapter 5. Data
CHAPTER 6
Utilities
utils.normalize_columns(matrix)Normalize the input matrix such that each column of the result matrix sums to one.
utils.normalize_rows(matrix)Normalize the input matrix such that each row of the result matrix sums to one.
utils.xy_inside_horseshoe(xx, yy, horseshoe_curve)Check whether a set of coordinates are inside the horseshoe shape.
Parameters xx, yy: ndarrays of the same size
The (x,y) coordinates to be determined whether inside the horseshoe.
horseshoe_curve: ndarray of size ‘Nx2‘
Each row of the matrix is an (x,y) coordinate for a monochromatic color, and the wave-length of those colors should increase from short (blue) to long (red) monotonically.
Returns A boolean ndarray of the same size as xx and yy.
15
xy_color Documentation, Release 0.1.dev
16 Chapter 6. Utilities
CHAPTER 7
A Simple Web Application
We provide a simple web application:
cd xy_colorpython web.py # This will laucn the web app at localhost:8888.cd ..
17
xy_color Documentation, Release 0.1.dev
18 Chapter 7. A Simple Web Application
CHAPTER 8
Indices and tables
• genindex
• modindex
• search
19
xy_color Documentation, Release 0.1.dev
20 Chapter 8. Indices and tables
Python Module Index
ccolor_space_transform, 11
ddata, 13
uutils, 15
21
xy_color Documentation, Release 0.1.dev
22 Python Module Index
Index
Aadjust_wl() (in module data), 13adobe_abs_to_norm_xyz() (in module data), 13adobe_gamma() (in module data), 13
Ccolor_space_transform (module), 11color_space_transform() (in module
color_space_transform), 11
Ddata (module), 13
Gget_blackbody_spd() (in module data), 13
Lload_fw() (in module data), 13
Nnormalize_columns() (in module utils), 15normalize_rows() (in module utils), 15
Rread_cvrl_csv() (in module data), 14
Ssrgb_gamma() (in module data), 14srgb_inverse_gamma() (in module data), 14
Uutils (module), 15
Xxy_inside_horseshoe() (in module utils), 15
23
