Skip to content
/ luxpy Public
forked from ksmet1977/luxpy

Python library for lighting and color science

License

View license
0 stars 31 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

sariths/luxpy

BranchesTags
 
 

Repository files navigation

luxpy: Python package for lighting and color science

  • Author: K. A.G. Smet
  • Version: 1.1.5
  • Date: Sep 11, 2017
  • License: GPLv3

Overview of modules (in order as loaded in init):

0.1.  helpers.py (imported directly into luxpy namespace, details see end of this file)
0.2.  math.py (imported as math into the luxpy namespace, details see end of this file)

1.  cmf.py
2.  spectral.py
3.  spectral_databases
4.  colortransforms.py (imported directly into luxpy namespace)
5.  cct.py (imported directly into luxpy namespace)
6.  chromaticadaptation.py (imported in luxpy namespace as .cat)
7.  colorappearancemodels.py (imported in luxpy namespace as .cam)
8.  colortf.py (imported directly into luxpy namespace)
9.  colorrenditionindices.py (imported in luxpy namespace as .cri)
10. plotters.py (imported directly into luxpy namespace)

1. cmf.py

_cmf:

Dict with info on several sets of color matching functions:

  • '1931_2', '1964_10','2006_2','2006_10' (CIE 1931 2°, CIE 1964 10°, CIE 2006 2° and CIE 2006 10° observers)
  • Dict keys are: 'types, 'K' (lm/W), 'M' (xyz -- > lms conversion matrix), 'bar' (color matching functions, downloaded from cvrl.org)

2. spectral.py

_wl3:

Default wavelength specification in vector-3 format: [start, end, spacing]

_BB:

Constants for blackbody radiator calculation (c1, c2, n)

_S012_daylightphase:

CIE S0,S1, S2 curves for daylight phase calculation.

_interp_types:

Dict with interpolation types associated with various types of spectral data according to CIE recommendation

_S_interp_type:

Interpolation type for light source spectral data

_R_interp_type:

Interpolation type for reflective/transmissive spectral data

_cri_ref_type:

Dict with blackbody to daylight transition (mixing) ranges for various types of reference illuminants used in color rendering index calculations.

getwlr():

Get/construct a wavelength range from a 3-vector (start, stop, spacing), output is a (n,)-vector.

getwld():

Get wavelength spacing of np.array input.

normalize_spd():

Spectrum normalization (supports: area, max and lambda)

cie_interp():

Interpolate / extrapolate (i.e. flat: replicate closest known values) following CIE15:2004.

spd():

All-in-one function: convert spd-like data from np.array to pd.dataframe, interpolate (use wl and interpolation like in cie_interp), normalize.

xyzbar():

Get color matching functions from file (./data/cmfs/) Load cmfs from file or get from dict defined in .cmf.py.

spd_to_xyz():

Calculates xyz from spd following CIE15:2004. If rfl input argument is not None, the first input argument is assumed to contain light source spectra illuminating the spectral reflection functions contained in 'rfl'. Output will be [N x M x 3], with N number of light source spectra, M, number of spectral reflectance function and last axis referring to xyz.

blackbody():

Calculate blackbody radiator spd for correlated color temperature = cct. (CIE15:2004) Input cct must be float (for multiple cct, use cri_ref() with ref_type = 'BB').

daylightlocus():

Calculates daylight chromaticity for cct (CIE15:2004).

daylightphase():

Calculate daylight phase spd for correlated color temperature = cct. (CIE15:2004) Default lower cct-limit is 4000 K, but can be turned off by setting 'force_daylight_below4000K' to True Input cct must be float (for multiple cct, use cri_ref() with ref_type = 'DL').

cri_ref():

Calculates a reference illuminant for cri calculation based on cct. Type and CIE observer can be set in resp. ref_type and cieobs. Input cct can be np.array, in which case output is 2d-array of spectra.

3. spectral_databases.py

_S_dir:

Folder with light source spectra data.

_R_dir:

Folder with spectral reflectance data

_iestm30:

Database with spectral reflectances related to and light source spectra contained excel calculator of IES TM30-15 publication.

_cie_illuminants:

Database with CIE illuminants:

  • 'E', 'D65', 'A', 'C', 'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12'

_cri_rfl:

Database with spectral reflectance functions for various color rendition calculators

_munsell:

Database with 1269 Munsell spectral reflectance functions + Value (V), Chroma (C), hue (h) and (ab) specifications.

4. colortransforms.py

Module with basic colorimetric functions (xyz_to_chromaticity, chromaticity_to_xyz conversions):

xyz_to_Yxy(), Yxy_to_xyz():

CIE xyz <--> CIE Yxy

xyz_to_Yuv(), Yuv_to_xyz():

CIE xyz <--> CIE 1976 Yu'v'

Yxy_to_Yuv(), Yuv_to_Yxy():

CIE 1976 Yu'v' <--> CIE Yxy

xyz_to_xyz():

CIE xyz <--> CIE xyz (forward = inverse)

xyz_to_lab(), lab_to_xyz():

CIE xyz <--> CIELAB

lab_to_xyz(), xyz_to_luv():

CIE xyz <--> CIELUV

xyz_to_Vrb_mb(), Vrb_mb_to_xyz():

CIE xyz <--> Macleod-Boyton type coordinates (V,r,b) = (V,l,s) with V = L + M, l=L/V, m = M/V (related to luminance)

xyz_to_ipt(), ipt_to_xyz():

CIE xyz <--> IPT ()

xyz_to_Ydlep(), Ydlep_to_xyz():

CIE xyz <--> Y, dominant / complementary wavelength (dl, compl. wl: specified by < 0) and excitation purity (ep)

5. cct.py

_cct_lut_dir:

Folder with Look-Up-Tables (LUT) for correlated color temperature calculation followings Ohno's method.

_cct_LUT:

Dict with LUT.

xyz_to_cct():

Calculates CCT,Duv from XYZ, wrapper for ..._ohno() & ..._search()

xyz_to_duv():

Calculates Duv, (CCT) from XYZ, wrapper for ..._ohno() & ..._search()

cct_to_xyz():

Calculates xyz from CCT, Duv [100 K < CCT < 10**20]

xyz_to_cct_mcamy():

Calculates CCT from XYZ using Mcamy model:

xyz_to_cct_HA():

Calculate CCT from XYZ using Hernández-Andrés et al. model .

xyz_to_cct_ohno():

Calculates CCT,Duv from XYZ using LUT following:

xyz_to_cct_search():

Calculates CCT,Duv from XYZ using brute-force search algorithm (between 1e2 K - 1e20 K on a log scale)

cct_to_mired():

Converts from CCT to Mired scale (or back)

6. chromaticadaptation.py (cat)

cat._white_point:

Default adopted white point

cat._La:

Default luminance of adapting field

cat._mcats:

Default chromatic adaptation sensor spaces

cat.check_dimensions():

Check if dimensions of data and xyzw match. If xyzw.shape[0] > 1 then len(data.shape) > 2 & (data.shape[0] = xyzw.shape[0]).

cat.get_transfer_function():

Calculate the chromatic adaptation diagonal matrix transfer function Dt. Default = 'vonkries' (others: 'rlab')

cat.smet2017_D():

Calculate the degree of adaptation based on chromaticity.

cat.get_degree_of_adaptation():

Calculates the degree of adaptation. D passes either right through or D is calculated following some D-function (Dtype) published in literature (cat02, cat16, cmccat, smet2017, manual).

cat.parse_x1x2_parameters():

Local helper function that parses input parameters and makes them the target_shape for easy calculation

cat.apply():

Applies a von kries (independent rescaling of 'sensor sensitivity' = diag. tf.) to adapt from current adaptation conditions (1) to the new conditions (2).

7. colorappearancemodels.py (cam)

cam._unique_hue_data:

Database of unique hues with corresponding Hue quadratures and eccentricity factors (ciecam02, cam16, ciecam97s, cam15u)

cam._surround_parameters:

Database of surround parameters c, Nc, F and FLL for ciecam02, cam16, ciecam97s and cam15u.

cam._naka_rushton_parameters:

Database with parameters (n, sig, scaling and noise) for the Naka-Rushton function: scaling * ((data^n) / ((data^n) + (sig^n))) + noise

cam._camucs_parameters:

Database with parameters specifying the conversion from ciecam02/cam16 to cam[x]ucs (uniform color space), cam[x]lcd (large color diff.), cam[x]scd (small color diff).

cam._cam15u_parameters:

Database with CAM15u model parameters.

cam._cam_sww_2016_parameters:

Database with cam_sww_2016 parameters (model by Smet, Webster and Whitehead published in JOSA A in 2016)

cam._cam_default_white_point:

Default internal reference white point (xyz)

cam.naka_rushton():

Applies a Naka-Rushton function to the input (forward and inverse available)

cam.hue_angle():

Calculates a positive hue_angle

cam.hue_quadrature():

Calculates the hue_quadrature from the hue and the parameters in the _unique_hue_data database

cam.cam_structure_ciecam02_cam16():

Basic structure of both the ciecam02 and cam16 models. Has 'forward' (xyz --> color attributes) and 'inverse' (color attributes --> xyz) modes.

cam.ciecam02():

Calculates ciecam02 output (wrapper for cam_structure_ciecam02_cam16 with specifics of ciecam02)

cam.cam16():

Calculates cam16 output (wrapper for cam_structure_ciecam02_cam16 with specifics of cam16)

cam.camucs_structure():

Basic structure to go to ucs, lcd and scd color spaces (forward + inverse available)

cam.cam02ucs():

Calculates ucs (or lcd, scd) output based on ciecam02 (forward + inverse available)

cam.cam16ucs():

Calculates ucs (or lcd, scd) output based on cam16 (forward + inverse available)

cam.cam15u():

Calculates the output for the CAM15u model for self-luminous unrelated stimuli.

cam_sww_2016():

Calculates output for the principled color appearance model developped by Smet, Webster and Whitehead that is based on a mapping of the Munsell color system. This function implements the JOSA A (parameters = 'JOSA') published model (with a correction for the parameter in Eq.4 of Fig. 11: 0.952 --> -0.952 and the delta_ac and delta_bc white-balance shifts in Eq. 5e & 5f should be: -0.028 & 0.821), as well as using a set of other parameters providing a better fit (parameters = 'best fit').

specific wrappers in the xyz_to_...() and ..._to_xyz() format:

  • 'xyz_to_jabM_ciecam02', 'jabM_ciecam02_to_xyz',
  • 'xyz_to_jabC_ciecam02', 'jabC_ciecam02_to_xyz',
  • 'xyz_to_jabM_cam16', 'jabM_cam16_to_xyz',
  • 'xyz_to_jabC_cam16', 'jabC_cam16_to_xyz',
  • 'xyz_to_jab_cam02ucs', 'jab_cam02ucs_to_xyz',
  • 'xyz_to_jab_cam02lcd', 'jab_cam02lcd_to_xyz',
  • 'xyz_to_jab_cam02scd', 'jab_cam02scd_to_xyz',
  • 'xyz_to_jab_cam16ucs', 'jab_cam16ucs_to_xyz',
  • 'xyz_to_jab_cam16lcd', 'jab_cam16lcd_to_xyz',
  • 'xyz_to_jab_cam16scd', 'jab_cam16scd_to_xyz',
  • 'xyz_to_qabW_cam15u', 'qabW_cam15u_to_xyz'
  • 'xyz_to_lab_cam_sww_2016', 'lab_cam_sww_2016_to_xyz'

These functions are imported directly into the luxpy namespace.

8. colortf.py

colortf():

Calculates conversion between any two color spaces for which xyz_to_...() and ..._to_xyz() exists.

9. colorrenditionindices.py (cri)

cri._cri_defaults:

Default settings for different color rendition indices: (major dict has 9 keys (04-Jul-2017):

  • sampleset [str/dict], ref_type [str], cieobs [str], avg [fcn handle], scale [dict], cspace [dict], catf [dict], rg_pars [dict], cri_specific_pars [dict]

Supported cri-types:

  • 'ciera', 'ciera-8', 'ciera-14', 'cierf', 'iesrf', 'cri2012', 'cri2012-hl17', 'cri2012-hl1000', 'cri2012-real210', 'cqs-v7.5', 'cqs-v9.0', mcri'

cri.linear_scale():

Linear color rendering index scale from CIE13.3-1974/1995: Ri,a = 100 - c1*DEi,a. (c1 = 4.6)

cri.log_scale():

Log-based color rendering index scale from Davis & Ohno (2010): Ri,a = 10 * ln(exp((100 - c1*DEi,a)/10) + 1)

cri.psy_scale():

Psychometric based color rendering index scale from CRI2012 (Smet et al. 2013, LRT): Ri,a = 100 * (2 / (exp(c1*abs(DEi,a)**(c2) + 1))) ** c3

cri.process_cri_type_input():

Load a cri_type dict but overwrites any keys that have a non-None input in calling function

cri.gamut_slicer():

Slices the gamut in nhbins slices and provides normalization of test gamut to reference gamut.

cri.jab_to_rg():

Calculates gamut area index, Rg based on hue-ordered jabt and jabr input (first element must also be last)

cri.spd_to_jab_t_r():

Calculates jab color values for a sample set illuminated with test source and its reference illuminant. (inputs are subset of spd_o_cri())

cri.spd_to_rg():

Calculates the color gamut index of data (= np.array([[wl,spds]]) (data_axis = 0) for a sample set illuminated with test source (data) with respect to some reference illuminant. (inputs are subset of spd_o_cri())

cri.spd_to_DEi():

Calculates color difference (~fidelity) of data (= np.array([[wl,spds]]) (data_axis = 0) between sample set illuminated with test source (data) and some reference illuminant. (inputs are subset of spd_o_cri())

cri.optimize_scale_factor():

Optimize scale_factor of cri-model in cri_type such that average Ra for a set of light sources is the same as that of a target-cri (default: 'ciera').

cri.spd_to_cri():

Calculates color rendition (~fidelity) index of data (= np.array([[wl,spds]]) (data_axis = 0) free choice of:

  • out = output requested (e.g. 'Ra', 'Ri' or 'Ra,Ri', or 'Ra, Ri, cct', ...; default = 'Ra', 'a' stands for average --> general color rendition index, i for individual regardless of cri_type

  • wl: wavelengths (or [start, end, spacing]) to interpolate the SPD's in data argument to. Default = None (no interpolation)

  • cri_type: str input specifying dict with default settings or user defined dict with parameters specifying color rendering index specifics (see e.g. luxpy.cri._cri_defaults['cierf']) non-None input arguments to function will override defaults in cri_type dict

  • cri_type keys / further function arguments:

    1. sampleset: np.array([[wl,rfl]]) or str for built-in rfl-set
    2. ref_type: reference illuminant type ('BB' : Blackbody radiatiors, 'DL': daylightphase, 'ciera': used in CIE CRI-13.3-1995, 'cierf': used in CIE 224-2017, 'iesrf': used in TM30-15, ...)
    3. cieobs: dict:
      • 'xyz': cie observer for calculating xyz of samples and white
      • 'cct': cie observer for calculating cct
    4. cspace:
      • 'type': color space used to calculate color differences
      • 'xyzw': white point of color space, (None: use xyzw of test / reference (after chromatic adaptation, if specified))
      • ' ...' : other possible parameters needed for color space calculation
    5. catf: None: don't apply a cat (other than perhaps the one built into the colorspace), OR dict:
      • 'D': degree of adaptation
      • 'mcat': sensor matrix specification,
      • 'xyzw': (None: use xyzw of reference otherwise transform both test and ref to xyzw)
    6. avg: averaging function (handle) for color differences, DEi (e.g. numpy.mean, .math.rms, .math.geomean)
    7. scale
      • 'fcn': function handle to type of cri scale, e.g. linear_scale, log_scale, psy_scale
      • 'cfactor': factors used in scaling function: if True: cfactor will be optimized to minimize the rms between the Ra's of the requested metric and some target metric specified in:
        • opt_cri_type: str (one of the preset _cri_defaults) or dict (dict must contain all keys as normal), default = 'ciera' (if 'opt_cri_type' -key not in 'scale' dict)
        • opt_spd_set: set of light source spds used to optimize cfactor, default = 'F1-F12' (if 'opt_spd_set' -key not in 'scale' dict)
    8. opt_scale_factor: True: optimize c-factor, else do nothing and use value of cfactor in 'scale'.
    9. cri_specific_pars: other parameters specific to type of cri, e.g. maxC for CQS calculations
    10. rg_pars: dict containing:
      • 'nhbins' (int): number of hue bins to divide the gamut in
      • 'start_hue' (float,°): hue at which to start slicing
      • 'normalize_gamut' (bool): normalize gamut or not before calculating a gamut area index Rg.

wrapper functions for fidelity type metrics:

cri.spd_to_mcri():

Calculates the memory color rendition index, Rm:

cri.spd_to_cqs():

Versions 7.5 and 9.0 are supported.

10. plotters.py

plot_color_data():

Plot color data (local helper function)

plotDL():

Plot daylight locus (for 'ccts', default = 4000 K to 1e19 K) for 'cieobs' in 'cspace'.

plotBB():

Plot blackbody locus (for 'ccts', default = 4000 K to 1e19 K) for 'cieobs' in 'cspace'.

plotSL():

Plot spectrum locus for 'cieobs' in 'cspace'. plotBB and plotDL are also called, but can be turned off.

plotceruleanline():

Plot cerulean (yellow (577 nm) - blue (472 nm)) line (Kuehni, CRA, 2013: Table II: spectral lights).

plotUH():

Plot unique hue line from centerpoint xyz0 (Kuehni, CRA, 2013: uY,uB,uG: Table II: spectral lights; uR: Table IV: Xiao data)

0.1. helpers.py

np2d():

Make a tupple, list or numpy array at least 2d array.

np2dT():

Make a tupple, list or numpy array at least 2d array and tranpose.

np3d():

Make a tupple, list or numpy array at least 3d array.

np3dT():

Make a tupple, list or numpy array at least 3d array and tranpose (swap) first two axes.

normalize_3x3_matrix():

Normalize 3x3 matrix to xyz0 -- > [1,1,1]

put_args_in_db():

Overwrites values in dict db with 'not-None' input arguments from function (obtained with built-in locals()). See put_args_in_db? for more info.

getdata():

Get data from csv-file or convert between pandas dataframe (kind = 'df') and numpy 2d-array (kind = 'np').

dictkv():

Easy input of of keys and values into dict (both should be iterable lists).

OD():

Provides a nice way to create OrderedDict "literals".

meshblock():

Create a meshed black (similar to meshgrid, but axis = 0 is retained) to enable fast blockwise calculation.

aplit():

Split np.array data on (default = last) axis.

ajoin():

Join tupple of np.array data on (default = last) axis.

broadcast_shape():

Broadcasts shapes of data to a target_shape, expand_2d_to_3d if not None and data.ndim == 2, axis0,1_repeats specify how many times data much be repeated along axis (default = same axis size). Useful for block/vector calculation in which nupy fails to broadcast correctly.

0.2. math.py

line_intersect():

Line intersection of two line segments a and b (Nx2) specified by their end points 1,2.

positive_arctan():

Calculates positive angle (0°-360° or 0 - 2*pi rad.) from x and y.

dot23():

Dot product of a (M x N) 2-d np.array with a (N x K x L) 3-d np.array using einsum().

check_symmetric():

Checks if A is symmetric (returns bool).

check_posdef():

Checks positive definiteness of matrix. Returns true when input is positive-definite, via Cholesky

symmM_to_posdefM():

Converts a symmetric matrix to a positive definite one. Two methods are supported:

bvgpdf():

Calculates bivariate Gaussian (PD) function, with center mu and shape and orientation determined by sigmainv.

mahalanobis2():

Calculates mahalanobis.^2 distance with center mu and shape and orientation determined by sigmainv.

rms():

Calculates root-mean-square along axis.

geomean():

Calculates geometric mean along axis.

polyarea():

Calculates area of polygon. (first coordinate should also be last)

erf(), erfinv():

erf-function (and inverse), direct import from scipy.special

About

Python library for lighting and color science

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

4 watching

Forks

0 forks
Report repository

Releases

4 tags

Packages

No packages published

Languages

  • Python 80.7%
  • Jupyter Notebook 19.3%