skinoptics.colors module

SkinOptics
Copyright (C) 2024 Victor Lima
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 <https://www.gnu.org/licenses/>.
Victor Lima
victorporto@ifsc.usp.br
victor.lima@ufscar.br
Release Date:
October 2024
Last Modification:
October 2024
References:
[CCH91] Chardon, Cretois & Hourseau 1991.
Skin colour typology and suntanning pathways.
[T*94] Takiwaki, Shirai, Kanno, Watanabe & Arase 1994.
Quantification of erythema and pigmentation using a videomicroscope and a computer.
[F*96] Fullerton, Fischer, Lahti, Wilhelm, Takiwaki & Serup 1996.
Guidetines for measurement of skin colour and erythema: A report from the Standardization Group of the European Society of Contact Dermatitis.
[S*96] Stokes, Anderson, Chandrasekar & Motta 1996.
A Standard Default Color Space for the Internet - sRGB.
[IEC99] IEC 1999.
Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB.
IEC 61966-2-1:1999
[CIE04] CIE 2004.
Colorimetry, 3rd edition.
CIE 15:2004
[D*06] Del Bino, Sok, Bessac & Bernerd 2006.
Relationship between skin response to ultraviolet exposure and skin color type.
[S07] Schanda (editor) 2007.
Colorimetry: Understanding the CIE System.
[HP11] Hunt & Pointer 2011.
Measuring Colour.
[DB13] Del Bino & Bernerd 2013.
Variations in skin colour and the biological consequences of ultraviolet radiation exposure.
[WSS13] Wyman, Sloan & Shirley 2013.
Simple Analytic Approximations to the CIE XYZ Color Matching Functions.
[CIE18a] CIE 2018.
CIE standard illuminant A - 1 nm.
[CIE18b] CIE 2018.
CIE standard illuminant D55.
[CIE18c] CIE 2018.
CIE standard illuminant D75.
[CIE19a] CIE 2019.
CIE 1931 colour-matching functions, 2 degree observer.
[CIE19b] CIE 2019.
CIE 1964 colour-matching functions, 10 degree observer
[L*20] Ly, Dyer, Feig, Chien & Del Bino 2020.
Research Techniques Made Simple: Cutaneous Colorimetry: A Reliable Technique for Objective Skin Color Measurement.
[CIE22a] CIE 2022.
CIE standard illuminant D50.
[CIE22b] CIE 2022.
CIE standard illuminant D65.
skinoptics.colors.Delta_E(L0, a0, b0, L1, a1, b1)

Calculate the color difference \(\Delta E^*\) between between a reference color (\(L^*_0\), \(a^*_0\), \(b^*_0\)) and a test color (\(L^*_1\), \(a^*_1\), \(b^*_1\)).

\(\Delta E^* = \sqrt{(L^*_1 - L^*_0)^2 + (a^*_1 - a^*_0)^2 + (b^*_1 - b^*_0)^2}\)

Parameters:
  • L0 (float or np.ndarray) – reference color L* coordinate [-]

  • a0 (float or np.ndarray) – reference color a* coordinate [-]

  • b0 (float or np.ndarray) – reference color b* coordinate [-]

  • L1 (float or np.ndarray) – test color L* coordinate [-]

  • a1 (float or np.ndarray) – test color a* coordinate [-]

  • b1 (float or np.ndarray) – test color b* coordinate [-]

Returns:

  • delta_E (float or np.ndarray) – color difference [-]

skinoptics.colors.Delta_L(L0, L1)

Calculate the lightness difference \(\Delta L^*\) between a reference color lightness \(L^*_0\) and a test color lightness \(L^*_1\).

\(\Delta L^* = L^*_1 - L^*_0\)

Parameters:
  • L0 (float or np.ndarray) – reference color L* coordinate [-]

  • L1 (float or np.ndarray) – test color L* coordinate [-]

Returns:

  • delta_L (float or np.ndarray) – lightness difference [-]

skinoptics.colors.Delta_a(a0, a1)

Calculate the difference \(\Delta a^*\) between a reference color \(a^*_0\) coordinate and a test color \(a^*_1\) coordinate.

\(\Delta a^* = a^*_1 - a^*_0\)

Parameters:
  • a0 (float or np.ndarray) – reference color a* coordinate [-]

  • a1 (float or np.ndarray) – test color a* coordinate [-]

Returns:

  • delta_a (float or np.ndarray) – a* difference [-]

skinoptics.colors.Delta_b(b0, b1)

Calculate the difference \(\Delta b^*\) between a reference color \(b^*_0\) coordinate and a test color \(b^*_1\) coordinate.

\(\Delta b^* = b^*_1 - b^*_0\)

Parameters:
  • b0 (float or np.ndarray) – reference color b* coordinate [-]

  • b1 (float or np.ndarray) – test color b* coordinate [-]

Returns:

  • delta_b (float or np.ndarray) – b* difference [-]

skinoptics.colors.EI(R_green, R_red)
Calculate the Erythema Index (EI) from the reflectances on chosen green
(usually approx. 568 nm) and red bands (usually approx. 655 nm).
For details please check Takiwaki et al. 1994 [T*94] and Fullerton et al. 1996 [F*96].

\(\mbox{EI} = 100 \mbox{ } [\mbox{log}_{10}(R_\mbox{red}) - \mbox{log}_{10}(R_\mbox{green})]\)

Parameters:
  • R_green (float or np.ndarray) – reflectance on a chosen green band [%]

  • R_red (float or np.ndarray) – reflectance on a chosen red band [%]

Returns:

  • EI (float or np.ndarray) – Erythema Index [-]

skinoptics.colors.ITA(L, b, L0=50.0)
Calculate the Individual Typology Angle (ITA) from L* and b* coordinates.
For details please check Chardon, Cretois & Hourseau 1991 [CCH91], Del Bino et al. 2006 [D*06],
Del Bino & Bernerd 2013 [DB13] and Ly et al. [L*20].

\(\mbox{ITA} = \arctan\left(\frac{L^*-L_0^*}{b^*}\right) \times \frac{180}{\pi}\)

Parameters:
  • L (float or np.ndarray) – L* coordinate [-]

  • b (float or np.ndarray) – b* coordinate [-]

  • L0 (float) – L0 coordinate [-] (default to 50.)

Returns:

  • ITA (float or np.ndarray) – Individual Typology Angle [degrees]

skinoptics.colors.ITA_class(ITA)
Skin color classification based on the Individual Typology Angle skinoptics.colors.ITA().
For details please check Chardon, Cretois & Hourseau 1991 [CCH91], Del Bino et al. 2006 [D*06],
Del Bino & Bernerd 2013 [DB13] and Ly et al. [L*20].

skin color classification

ITA range

very light

ITA \(> 55^\circ\)

light

\(41^\circ <\) ITA \(\le 55^\circ\)

intermediate

\(28^\circ <\) ITA \(\le 41^\circ\)

tan

\(10^\circ <\) ITA \(\le 28^\circ\)

brown

\(-30^\circ <\) ITA \(\le 10^\circ\)

dark

ITA \(\le -30^\circ\)

Parameters:

ITA (float or np.ndarray) – Individual Typology Angle [degrees] (must be greater than -90 and less than 90)

Returns:

  • ITA_class (str or np.ndarray) – skin color classification based on the Individual Typology Angle

skinoptics.colors.Lab_from_XYZ(X, Y, Z, illuminant='D65', observer='10o', K=1.0)
Calculate CIE L*a*b* coordinates from CIE XYZ coordinates.
CIE XYZ and CIE L*a*b* coordinates must be for the same standard illuminant and standard observer.
For detailts please check CIE [CIE04], Schanda 2006 [S06] and Hunt & Pointer 2011 [HP11].
\(L^* = 116 \mbox{ } f(Y/Y_n) - 16\)
\(a^* = 500 \mbox{ } [f(X/X_n) - f(Y/Y_n)]\)
\(b^* = 200 \mbox{ } [f(Y/Y_n) - f(Z/Z_n)]\)

in which (\(X_n\), \(Y_n\), \(Z_n\)) is the white point and

\(f(u) = \left\{ \begin{matrix} \sqrt[3]{u}, & \mbox{if } u > \left(\frac{6}{29}\right)^3 \\ \frac{1}{3}\left(\frac{29}{6}\right)^2 u + \frac{4}{29}, & \mbox{if } u \le \left(\frac{6}{29}\right)^3 \end{matrix}\right.\)

Parameters:
  • X (float or np.ndarray) – X coordinate [-]

  • Y (float or np.ndarray) – Y coordinate [-]

  • Z (float or np.ndarray) – Z coordinate [-]

  • illuminant (str) – the user can choose one of the following… ‘A’, ‘D50’, ‘D55’, ‘D65’ or ‘D75’

  • observer (str) – the user can choose one of the following… ‘2o’ or ‘10o’

  • K (float) – scaling factor (usually 1. or 100.) [-] (default to 1.)

‘A’ refers to the CIE standard illuminant A
‘D50’ refers to the CIE standard illuminant D50
‘D55’ refers to the CIE standard illuminant D55
‘D65’ refers to the CIE standard illuminant D65
‘D75’ refers to the CIE standard illuminant D75
‘2o’ refers to the CIE 1931 2 degree standard observer
‘10o’ refers to the CIE 1964 10 degree standard observer
K = 1. for CIE XYZ coordinates in range [0, 1]
K = 100. for CIE XYZ coordinates in range [0, 100]
Returns:

  • L (float or np.ndarray) – L* coordinate [-]

  • a (float or np.ndarray) – a* coordinate [-]

  • b (float or np.ndarray) – b* coordinate [-]

skinoptics.colors.Lab_from_spectrum(all_lambda, spectrum, lambda_min=360, lambda_max=830, lambda_step=1, illuminant='D65', observer='10o', cmfs_model='CIE', interp1d_kind='cubic')
Calculate the CIE L*a*b* coordinates from the reflectance or the transmittance spectrum.
First calculate CIE XYZ coordinates from the spectrum for a chosen standard illuminant
and standard observer and then calculate CIE L*a*b* coordinates from CIE XYZ coordinates
Parameters:
  • all_lambda (np.ndarray) – wavelength array

  • spectrum (np.ndarray) – reflectance or transmittance spectrum respective to the wavelength array [%]

  • lambda_min (float) – lower limit of summation/integration (minimum wavelength to take into account) [nm] (default to 360.)

  • lambda_max (float) – upper limit of summation/integration (maximum wavelength to take into account) [nm] (default to 830.)

  • lambda_step – summation interval (wavelength step) [nm] (default to 1.)

  • observer (str) – the user can choose one of the following… ‘2o’ or ‘10o’

  • cmfs_model (str) – the user can choose one of the following… ‘CIE’, ‘Wyman_singlelobe’ or ‘Wyman_multilobe’ (default to ‘CIE’)

  • interp1d_kind (str) – kind argument of scipy.interpolation.interp1d (default to ‘cubic’ [CIE04] (see their section 7.2.1.1))

‘A’ refers to the CIE standard illuminant A
‘D50’ refers to the CIE standard illuminant D50
‘D55’ refers to the CIE standard illuminant D55
‘D65’ refers to the CIE standard illuminant D65
‘D75’ refers to the CIE standard illuminant D75
‘2o’ refers to the CIE 1931 2 degree standard observer
‘10o’ refers to the CIE 1964 10 degree standard observer
‘CIE’ for the linear interpolation of data from CIE datasets [CIE19a] [CIE19b]
‘Wyman_singlelobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.1)
‘Wyman_multilobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.2)
Returns:

  • L (float) – L* coordinate [-]

  • a (float) – a* coordinate [-]

  • b (float) – b* coordinate [-]

skinoptics.colors.MI(R_red)
Calculate the Melanin Index (MI) from the reflectance on a chosen red band
(usually approx. 655 nm).
For details please check Takiwaki et al. 1994 [T*94] and Fullerton et al. 1996 [F*96].

\(\mbox{MI} = 100 \mbox{ } [-\mbox{log}_{10}(R_\mbox{red})]\)

Parameters:

R_red (float or np.ndarray) – reflectance on a chosen red band [%]

Returns:

  • MI (float or np.ndarray – Melanin Index [-]

skinoptics.colors.XYZ_from_Lab(L, a, b, illuminant='D65', observer='10o', K=1.0)
Calculate CIE XYZ coordinates from CIE L*a*b* coordinates.
CIE XYZ and CIE L*a*b* coordinates must be for the same standard illuminant and standard observer.
For detailts please check CIE [CIE04], Schanda 2006 [S06] and Hunt & Pointer 2011 [HP11].
\(X = f^{-1}[(L^* + 16)/116 + a^*/500] \mbox{ } X_n\)
\(Y = f^{-1}[(L^* + 16)/116] \mbox{ } Y_n\)
\(Z = f^{-1}[(L^* + 16)/116 - b^*/200] \mbox{ } Z_n\)

in which (\(X_n\), \(Y_n\), \(Z_n\)) is the white point and

\(f^{-1}(u) = \left\{ \begin{matrix} u^3, & \mbox{if } u > \frac{6}{29} \\ 3 \mbox{ } \left(\frac{6}{29}\right)^2\left(u - \frac{4}{29} \right), & \mbox{if } u \le \frac{6}{29} \end{matrix}\right.\)

Parameters:
  • L (float or np.ndarray) – L* coordinate [-] (must be in range [0, 100])

  • a (float or np.ndarray) – a* coordinate [-]

  • b (float or np.ndarray) – b* coordinate [-]

  • illuminant (str) – the user can choose one of the following… ‘A’, ‘D50’, ‘D55’, ‘D65’ or ‘D75’

  • observer (str) – the user can choose one of the following… ‘2o’ or ‘10o’

  • K (float) – scaling factor (usually 1. or 100.) [-] (default to 1.)

‘A’ refers to the CIE standard illuminant A
‘D50’ refers to the CIE standard illuminant D50
‘D55’ refers to the CIE standard illuminant D55
‘D65’ refers to the CIE standard illuminant D65
‘D75’ refers to the CIE standard illuminant D75
‘2o’ refers to the CIE 1931 2 degree standard observer
‘10o’ refers to the CIE 1964 10 degree standard observer
K = 1. for CIE XYZ coordinates in range [0, 1]
K = 100. for CIE XYZ coordinates in range [0, 100]
Returns:

  • X (float or np.ndarray) – X* coordinate [-]

  • Y (float or np.ndarray) – Y* coordinate [-]

  • Z (float or np.ndarray) – Z* coordinate [-]

skinoptics.colors.XYZ_from_sRGB(R, G, B, K=1.0, sRGB_scale='norm')
Calculate CIE XYZ coordinates from sRGB coordinates.
The obtained CIE XYZ coordinates are respective to the standard illuminant D65 and the
2 degree standard observer.
For details please check Stokes et al. [S*96] and IEC [IEC99].

\(\begin{bmatrix} X \\ Y \\ Z \end{bmatrix} = \mathcal{M}^{-1} \begin{bmatrix} R_{linear} \\ G_{linear} \\ B_{linear} \end{bmatrix}\)

in which

\(\begin{bmatrix} R_{linear} \\ G_{linear} \\ B_{linear} \end{bmatrix} = \begin{bmatrix} \gamma^{-1}(R) \\ \gamma^{-1}(G) \\ \gamma^{-1}(B) \end{bmatrix}\)

and

\(\gamma^{-1}(u) = \left \{ \begin{matrix} u/12.92, & \mbox{if } u \le 0.04045 \\ [(u + 0.055)/1.055]^{2.4}, & \mbox{if } u > 0.04045 \\ \end{matrix} \right.\)

Parameters:
  • R (float or np.ndarray) – R coordinate [-]

  • G (float or np.ndarray) – G coordinate [-]

  • B (float or np.ndarray) – B coordinate [-]

  • K (float) – scaling factor (usually 1. or 100.) [-] (default to 1.)

  • sRGB_scale – the user can choose one of the following… ‘norm’ or ‘8bit’

K = 1. for CIE XYZ coordinates in range [0, 1]
K = 100. for CIE XYZ coordinates in range [0, 100]
‘norm’ for sRGB coordinates in range [0,1] (normalized scale)
‘8bit’ for sRGB coordinates in range [0, 255] (8-bit scale)
Returns:

  • X (float or np.ndarray) – X coordinate [-]

  • Y (float or np.ndarray) – Y coordinate [-]

  • Z (float or np.ndarray) – Z coordinate [-]

skinoptics.colors.XYZ_from_spectrum(all_lambda, spectrum, lambda_min=360.0, lambda_max=830.0, lambda_step=1.0, illuminant='D65', observer='10o', cmfs_model='CIE', K=1.0, interp1d_kind='cubic')
Calculate the CIE XYZ coordinates from the reflectance spectrum \(R(\lambda)\) or the
transmittance spectrum \(T(\lambda)\) for a chosen standard illuminant and standard observer.
Integration using the composite trapezoid rule from 360 nm to 830 nm (as default).
If the wavelength array does not cover the whole region, a constant extrapolation is perfomed.
For details please check CIE [CIE04] (see their section 7).
\(X = \frac{K}{N} \int_\lambda \mbox{ } R(\lambda) \mbox{ } S(\lambda) \mbox{ } \bar{x}(\lambda) \mbox{ } d\lambda\)
\(Y = \frac{K}{N} \int_\lambda \mbox{ } R(\lambda) \mbox{ } S(\lambda) \mbox{ } \bar{y}(\lambda) \mbox{ } d\lambda\)
\(Z = \frac{K}{N} \int_\lambda \mbox{ } R(\lambda) \mbox{ } S(\lambda) \mbox{ } \bar{z}(\lambda) \mbox{ } d\lambda\)

in which

\(N = \int_\lambda \mbox{ } S(\lambda) \mbox{ } \bar{y}(\lambda) \mbox{ } d\lambda\)

The reflectance spectrum \(R(\lambda)\) is replaced by the transmittance spectrum \(T(\lambda)\) when dealing with color in some cases.

Parameters:
  • all_lambda (np.ndarray) – wavelength array

  • spectrum (np.ndarray) – reflectance or transmittance spectrum respective to the wavelength array [%]

  • lambda_min (float) – lower limit of summation/integration (minimum wavelength to take into account) [nm] (default to 360.)

  • lambda_max (float) – upper limit of summation/integration (maximum wavelength to take into account) [nm] (default to 830.)

  • lambda_step – summation interval (wavelength step) [nm] (default to 1.)

  • observer (str) – the user can choose one of the following… ‘2o’ or ‘10o’

  • cmfs_model (str) – the user can choose one of the following… ‘CIE’, ‘Wyman_singlelobe’ or ‘Wyman_multilobe’ (default to ‘CIE’)

  • K (float) – scaling factor (usually 1. or 100.) [-] (default to 1.)

  • interp1d_kind (str) – kind argument of scipy.interpolation.interp1d (default to ‘cubic’ [CIE04] (see their section 7.2.1.1))

‘A’ refers to the CIE standard illuminant A
‘D50’ refers to the CIE standard illuminant D50
‘D55’ refers to the CIE standard illuminant D55
‘D65’ refers to the CIE standard illuminant D65
‘D75’ refers to the CIE standard illuminant D75
‘2o’ refers to the CIE 1931 2 degree standard observer
‘10o’ refers to the CIE 1964 10 degree standard observer
‘CIE’ for the linear interpolation of data from CIE datasets [CIE19a] [CIE19b]
‘Wyman_singlelobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.1)
‘Wyman_multilobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.2)
K = 1. for CIE XYZ coordinates in range [0, 1]
K = 100. for CIE XYZ coordinates in range [0, 100]
Returns:

  • X (float) – X coordinate [-]

  • Y (float) – Y coordinate [-]

  • Z (float) – Z coordinate [-]

skinoptics.colors.XYZ_wp(illuminant, observer, cmfs_model='CIE', K=1.0)

The white point CIE XYZ coordinates for a chosen standard illuminant and standard observer.

Parameters:
  • illuminant (str) – the user can choose one of the following… ‘A’, ‘D50’, ‘D55’, ‘D65’ or ‘D75’

  • observer (str) – the user can choose one of the following… ‘2o’ or ‘10o’

  • cmfs_model (str) – the user can choose one of the following… ‘CIE’, ‘Wyman_singlelobe’ or ‘Wyman_multilobe’ (default to ‘CIE’)

  • K (float) – scaling factor (usually 1. or 100.) [-] (default to 1.)

‘A’ refers to the CIE standard illuminant A
‘D50’ refers to the CIE standard illuminant D50
‘D55’ refers to the CIE standard illuminant D55
‘D65’ refers to the CIE standard illuminant D65
‘D75’ refers to the CIE standard illuminant D75
‘2o’ refers to the CIE 1931 2 degree standard observer
‘10o’ refers to the CIE 1964 10 degree standard observer
‘CIE’ for the linear interpolation of data from CIE datasets [CIE19a] [CIE19b]
‘Wyman_singlelobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.1)
‘Wyman_multilobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.2)
K = 1. for CIE XYZ coordinates in range [0, 1]
K = 100. for CIE XYZ coordinates in range [0, 100]
Returns:

  • Xn (float) – white point X coordinate [-]

  • Yn (float) – white point Y coordinate [-]

  • Zn (float) – white point Z coordinate [-]

skinoptics.colors.chroma(a, b)

Calculate the chroma C* from a* and b* coordinates.

\(C^* = \sqrt{a^{*2} + b^{*2}}\)

Parameters:
  • a (float or np.ndarray) – a* coordinate [-]

  • b (float or np.ndarray) – b* coordinate [-]

Returns:

  • chroma (float or np.ndarray) – chroma [-]

skinoptics.colors.cmfs(lambda0, observer, cmfs_model='CIE')
The CIE color-matching functions \(\bar{x}(\lambda)\), \(\bar{y}(\lambda)\) and \(\bar{z}(\lambda)\) for a chosen standard observer
as a function of wavelength.
wavelength range: [360 nm, 830 nm] (at 1 nm intervals for cmfs_model = ‘CIE’)
Parameters:
  • lambda0 (float or np.ndarray) – wavelength [nm] (must be in range [360., 830.] for cmfs_model = ‘CIE’)

  • observer (str) – the user can choose one of the following… ‘2o’ or ‘10o’

  • cmfs_model (str) – the user can choose one of the following… ‘CIE’, ‘Wyman_singlelobe’ or ‘Wyman_multilobe’ (default to ‘CIE’)

‘2o’ refers to the CIE 1931 2 degree standard observer
‘10o’ refers to the CIE 1964 10 degree standard observer
‘CIE’ for the linear interpolation of data from CIE datasets [CIE19a] [CIE19b]
‘Wyman_singlelobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.1)
‘Wyman_multilobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.2)
Returns:

  • xbar (float or np.ndarray) – \(\bar{x}(\lambda\)) color-matching function [-]

  • ybar (float or np.ndarray) – \(\bar{y}(\lambda\)) color-matching function [-]

  • zbar (float or np.ndarray) – \(\bar{z}(\lambda\)) color-matching function [-]

skinoptics.colors.f_Lab_from_XYZ(u)
The function \(f(u)\) used to calculate CIE L*a*b* coordinates from CIE XYZ coordinates

\(f(u) = \left\{ \begin{matrix} \sqrt[3]{u}, & \mbox{if } u > \left(\frac{6}{29}\right)^3 \\ \frac{1}{3}\left(\frac{29}{6}\right)^2 u + \frac{4}{29}, & \mbox{if } u \le \left(\frac{6}{29}\right)^3 \end{matrix}\right.\)

Parameters:

u (float or np.ndarray) – X/Xn, Y/Yn or Z/Zn ratio[-]

Returns:

  • f (float or np.ndarray) – evaluated function [-]

skinoptics.colors.hue(a, b)

Calculate the hue angle h* from a* and b* coordinates.

\(h^* = \mbox{arctan2 } (b^*, a^*) \times \frac{180}{\pi}\)

Parameters:
  • a (float or np.ndarray) – a* coordinate [-]

  • b (float or np.ndarray) – b* coordinate [-]

Returns:

  • hue (float or np.ndarray) – hue angle [degrees] (in range [0, 360])

skinoptics.colors.inv_f_Lab_from_XYZ(u)

The \(f^{-1}(u)\) function, i.e. the inverse of the \(f(u)\) function skinoptics.colors.f_Lab_from_XYZ().

\(f^{-1}(u) = \left\{ \begin{matrix} u^3, & \mbox{if } u > \frac{6}{29} \\ 3 \mbox{ } \left(\frac{6}{29}\right)^2\left(u - \frac{4}{29} \right), & \mbox{if } u \le \frac{6}{29} \end{matrix}\right.\)

Parameters:

u (float or np.ndarray) – function variable [-]

Returns:

  • f (float or np.ndarray) – evaluated function [-]

skinoptics.colors.inv_nonlinear_corr_sRGB(u)

The inverse nonlinear correction for sRGB coordinates.

\(\gamma^{-1}(u) = \left \{ \begin{matrix} u/12.92, & \mbox{if } u \le 0.04045 \\ [(u + 0.055)/1.055]^{2.4}, & \mbox{if } u > 0.04045 \\ \end{matrix} \right.\)

Parameters:

u (float or np.ndarray) – nonlinear R, G or B coordinate [-]

Returns:

  • inv_gamma (float or np.ndarray) – linear R, G or B coordinate [-]

skinoptics.colors.nonlinear_corr_sRGB(u)

The nonlinear correction for sRGB coordinates.

\(\gamma(u) = \left \{ \begin{matrix} 12.92 \mbox{ } u, & \mbox{if } u \le 0.0031308 \\ 1.055 \mbox{ } u^{1/2.4} - 0.055, & \mbox{if } u > 0.0031308 \\ \end{matrix} \right.\)

Parameters:

u (float or np.ndarray) – linear R, G or B coordinate [-]

Returns:

  • gamma (float or np.ndarray) – nonlinear R, G or B coordinate [-]

skinoptics.colors.rspd(lambda0, illuminant)
The relative spectral power distribution S(\(\lambda\)) of a chosen standard illuminant
as a function of wavelength.
Linear interpolation of data from CIE datasets [CIE18a] [CIE22a] [CIE18b] [CIE22b] [CIE18c].
wavelength range:
[300 nm, 830 nm] (at 1 nm intervals, for illuminant = ‘A’, ‘D50’ or ‘D65’)
or [300 nm, 780 nm] (at 5 nm intervals, for illuminant = ‘D55’ or ‘D75’)
Parameters:
  • lambda0 (float or np.ndarray) – wavelength [nm] (must be in range [300 nm, 830 nm] or [300 nm, 780 nm])

  • illuminant (str) – the user can choose one of the following… ‘A’, ‘D50’, ‘D55’, ‘D65’ or ‘D75’

‘A’ refers to the CIE standard illuminant A
‘D50’ refers to the CIE standard illuminant D50
‘D55’ refers to the CIE standard illuminant D55
‘D65’ refers to the CIE standard illuminant D65
‘D75’ refers to the CIE standard illuminant D75
Returns:

  • rspd (float or np.ndarray) – relative spectral power distribution [-]

skinoptics.colors.sRGB_from_XYZ(X, Y, Z, K=1.0, sRGB_scale='norm')
Calculate sRGB coordinates from CIE XYZ coordinates.
CIE XYZ coordinates must be for the standard illuminant D65 and the 2 degree standard observer.
For details please check Stokes et al. [S*96] and IEC [IEC99].

\(\begin{bmatrix} R \\ G \\ B \end{bmatrix} = \begin{bmatrix} \gamma(R_{linear}) \\ \gamma(G_{linear}) \\ \gamma(B_{linear}) \end{bmatrix}\)

in which

\(\begin{bmatrix} R_{linear} \\ G_{linear} \\ B_{linear} \end{bmatrix} = \mathcal{M} \begin{bmatrix} X \\ Y \\ Z \end{bmatrix}\)

and

\(\gamma(u) = \left \{ \begin{matrix} 12.92 \mbox{ } u, & \mbox{if } u \le 0.0031308 \\ 1.055 \mbox{ } u^{1/2.4} - 0.055, & \mbox{if } u > 0.0031308 \\ \end{matrix} \right.\)

Parameters:
  • X (float or np.ndarray) – X coordinate [-]

  • Y (float or np.ndarray) – Y coordinate [-]

  • Z (float or np.ndarray) – Z coordinate [-]

  • K (float) – scaling factor (usually 1. or 100.) [-] (default to 1.)

  • sRGB_scale – the user can choose one of the following… ‘norm’ or ‘8bit’

K = 1. for CIE XYZ coordinates in range [0, 1]
K = 100. for CIE XYZ coordinates in range [0, 100]
‘norm’ for sRGB coordinates in range [0,1] (normalized scale)
‘8bit’ for sRGB coordinates in range [0, 255] (8-bit scale)
Returns:

  • R (float or np.ndarray) – R coordinate [-]

  • G (float or np.ndarray) – G coordinate [-]

  • B (float or np.ndarray) – B coordinate [-]

skinoptics.colors.sRGB_from_lambda0(lambda0, cmfs_model='CIE', sRGB_scale='norm')
Calculate the sRGB coordinates respective to the color of a monochromatic light
(single wavelength).

wavelength range: [360 nm, 830 nm]

Parameters:
  • lambda0 (float or np.ndarray) – wavelength of the monochromatic light [nm]

  • cmfs_model (str) – the user can choose one of the following… ‘CIE’, ‘Wyman_singlelobe’ or ‘Wyman_multilobe’ (default to ‘CIE’)

  • sRGB_scale (str) – the user can choose one of the following… ‘norm’ or ‘8bit’ (default to ‘norm’)

‘CIE’ for the linear interpolation of data from CIE datasets [CIE19a] [CIE19b]
‘Wyman_singlelobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.1)
‘Wyman_multilobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.2)
‘norm’ for sRGB coordinates in range [0,1] (normalized scale)
‘8bit’ for sRGB coordinates in range [0, 255] (8-bit scale)
Returns:

  • R (float or np.ndarray) – R coordinate [-]

  • G (float or np.ndarray) – G coordinate [-]

  • B (float or np.ndarray) – B coordinate [-]

skinoptics.colors.sRGB_from_spectrum(all_lambda, spectrum, lambda_min=360, lambda_max=830, lambda_step=1, cmfs_model='CIE', interp1d_kind='cubic', sRGB_scale='norm')
Calculate the sRGB coordinates from the reflectance or the transmittance spectrum.
First calculate CIE XYZ coordinates (respective to the standard illuminant D65 and
the 2 degree standard observer) from the spectrum and then calculate sRGB coordinates
from CIE XYZ coordinates (see functions skinoptics.colors.sRGB_from_XYZ() and
Parameters:
  • all_lambda (np.ndarray) – wavelength array

  • spectrum (np.ndarray) – reflectance or transmittance spectrum respective to the wavelength array [%]

  • lambda_min (float) – lower limit of summation/integration (minimum wavelength to take into account) [nm] (default to 360.)

  • lambda_max (float) – upper limit of summation/integration (maximum wavelength to take into account) [nm] (default to 830.)

  • lambda_step (float) – summation interval (wavelength step) [nm] (default to 1.)

  • cmfs_model (str) – the user can choose one of the following… ‘CIE’, ‘Wyman_singlelobe’ or ‘Wyman_multilobe’ (default to ‘CIE’)

  • interp1d_kind (str) – kind argument of scipy.interpolation.interp1d (default to ‘cubic’ [CIE04] (see their section 7.2.1.1))

  • sRGB_scale (str) – the user can choose one of the following… ‘norm’ or ‘8bit’ (default to ‘norm’)

‘CIE’ for the linear interpolation of data from CIE datasets [CIE19a] [CIE19b]
‘Wyman_singlelobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.1)
‘Wyman_multilobe’ for the functions from Wyman, Sloan & Shirley 2013 [WSS13] (section 2.2)
‘norm’ for sRGB coordinates in range [0,1] (normalized scale)
‘8bit’ for sRGB coordinates in range [0, 255] (8-bit scale)
Returns:

  • R (float) – R coordinate [-]

  • G (float) – G coordinate [-]

  • B (float) – B coordinate [-]

skinoptics.colors.transf_matrix_sRGB_linear_from_XYZ()

The transformation matrix employed to obtain linear sRGB coordinates from CIE XYZ coordinates.

\(\mathcal{M} = \begin{bmatrix} 3.24062 & -1.5372 & -0.4986 \\ -0.9689 & 1.8758 & 0.0415 \\ 0.0557 & -0.2040 & 1.0570 \end{bmatrix}\)

Returns:

  • M (np.ndarray) – transformation matrix

skinoptics.colors.xy_from_XYZ(X, Y, Z)
Calculate CIE xy chromaticities from CIE XYZ coordinates.
\(x = \frac{X}{X + Y + Z}\)
\(y = \frac{Y}{X + Y + Z}\)
Parameters:
  • X (float or np.ndarray) – X coordinate [-]

  • Y (float or np.ndarray) – Y coordinate [-]

  • Z (float or np.ndarray) – Z coordinate [-]

Returns:

  • x (float or np.ndarray) – x chromaticity [-]

  • y (float or np.ndarray) – y chromaticity [-]

skinoptics.colors.xy_wp(illuminant, observer)
The white point CIE xy chromaticities for a chosen standard illuminant and standard observer.
Calculated from the white point CIE XYZ coordinates (see function skinoptics.colors.XYZ_wp()).
Parameters:
  • illuminant (str) – the user can choose one of the following… ‘A’, ‘D50’, ‘D55’, ‘D65’ or ‘D75’

  • observer (str) – the user can choose one of the following… ‘2o’ or ‘10o’

‘A’ refers to the CIE standard illuminant A
‘D50’ refers to the CIE standard illuminant D50
‘D55’ refers to the CIE standard illuminant D55
‘D65’ refers to the CIE standard illuminant D65
‘D75’ refers to the CIE standard illuminant D75
‘2o’ refers to the CIE 1931 2 degree standard observer
‘10o’ refers to the CIE 1964 10 degree standard observer
Returns:

  • xn (float) – white point CIE x chromaticity [-]

  • yn (float) – white point CIE y chromaticity [-]