def _massage_output_data_to_original_shape(camout, originalshape):
"""
Massage output data to restore original shape of input.
"""
# Flip light source dim back to axis 1:
camout = np.transpose(camout, axes=(1, 0, 2))
if len(originalshape) < 3:
if camout.shape[1] == 1:
camout = np.squeeze(camout, axis=1)
return camout
def _massage_output_data_to_original_shape(data, originalshape):
"""
Massage output data to restore original shape of original CAM input.
Notes:
For an example on the use, see code _simple_cam() (type: _simple_cam??)
"""
# Flip light source dim back to axis 1:
data = np.transpose(data, axes=(1, 0, 2))
if len(originalshape) < 3:
if data.shape[1] == 1:
data = np.squeeze(data, axis=1)
return data
def lab_to_xyz(lab, xyzw=None, cieobs=_CIEOBS, **kwargs):
"""
Convert CIE 1976 L*a*b* (CIELAB) color coordinates to XYZ tristimulus values.
Args:
:lab:
| ndarray with CIE 1976 L*a*b* (CIELAB) color coordinates
:xyzw:
| None or ndarray with tristimulus values of white point, optional
| None defaults to xyz of CIE D65 using the :cieobs: observer.
:cieobs:
| luxpy._CIEOBS, optional
| CMF set to use when calculating xyzw.
Returns:
:xyz:
| ndarray with tristimulus values
"""
lab = np2d(lab)
if xyzw is None:
xyzw = spd_to_xyz(_CIE_ILLUMINANTS['D65'], cieobs=cieobs)
# make xyzw same shape as data:
xyzw = xyzw * np.ones(lab.shape)
# get L*, a*, b* and Xw, Yw, Zw:
fXYZ = np.empty(lab.shape)
fXYZ[..., 1] = (lab[..., 0] + 16.0) / 116.0
fXYZ[..., 0] = lab[..., 1] / 500.0 + fXYZ[..., 1]
fXYZ[..., 2] = fXYZ[..., 1] - lab[..., 2] / 200.0
# apply 3rd power:
xyz = (fXYZ**3.0) * xyzw
# Now calculate T where T/Tn is below the knee point:
pqr = fXYZ <= (24 / 116) #(24/116)**3**(1/3)
xyz[pqr] = np.squeeze(xyzw[pqr] * ((fXYZ[pqr] - 16.0 / 116.0) /
(841 / 108)))
return xyz
def _process_DEi(DEi, DEtype='jab', avg=None, avg_axis=0, out='DEi'):
"""
Process color difference input DEi for output (helper function).
Args:
:DEi:
| tuple(J ndarray, ab ndarray).
:DEtype:
| 'jab' or str, optional
| Options:
| - 'jab' : calculates full color difference over all 3 dimensions.
| - 'ab' : calculates chromaticity difference.
| - 'j' : calculates lightness or brightness difference
| (depending on :out:).
| - 'j,ab': calculates both 'j' and 'ab' options
| and returns them as a tuple.
:avg:
| None, optional
| None: don't calculate average DE,
| otherwise use function handle in :avg:.
:avg_axis:
| axis to calculate average over, optional
:out:
| 'DEi' or str, optional
| Requested output.
Note:
For the other input arguments, see specific color space used.
Returns:
:returns:
| ndarray with DEi [, DEa] or other as specified by :out:
"""
if (DEi[0].shape[-1] == 1) & (DEi[0].ndim == 3):
DEi = tuple((map(lambda x: np.squeeze(x, axis=x.ndim - 1), DEi)))
# Calculate correct type of DE:
if DEtype == 'jab':
DEi = np.sqrt(DEi[0] + DEi[1])
elif DEtype == 'ab':
DEi = np.sqrt(DEi[1])
elif DEtype == 'j':
DEi = np.sqrt(DEi[0])
# Calculate average when requested:
if (avg is not None) & ('DEa' in out.split(',')):
if isinstance(DEi, tuple):
DEa = (avg(DEi[0], axis=avg_axis,
keepdims=True), avg(DEi[1],
axis=avg_axis,
keepdims=True))
else:
DEa = avg(DEi, axis=avg_axis, keepdims=True)
if out == 'DEi':
return DEi
elif out == 'DEi,DEa':
return DEi, DEa
else:
return eval(out)
def getCatObs(n_cat=10,
fieldsize=2,
out='LMS',
wl=None,
allow_negative_values=False):
"""
Generate cone fundamentals for categorical observers.
Args:
:n_cat:
| 10, optional
| Number of observer CMFs to generate.
:fieldsize:
| fieldsize in degrees (between 2° and 10°), optional
| Defaults to 10°.
:out:
| 'LMS' or str, optional
| Determines output.
:wl:
| None, optional
| Interpolation/extraplation of :LMS: output to specified wavelengths.
| None: output original _WL = np.array([390,780,5])
:allow_negative_values:
| False, optional
| Cone fundamentals or color matching functions
| should not have negative values.
| If False: X[X<0] = 0.
Returns:
:returns:
| LMS [,var_age, vAll]
| - LMS: ndarray with population LMS functions.
| - var_age: ndarray with population observer ages.
| - vAll: dict with population physiological factors (see .keys())
Notes:
1. Categorical observers are observer functions that would represent
color-normal populations. They are finite and discrete as opposed to
observer functions generated from the individual colorimetric observer
model. Thus, they would offer more convenient and practical approaches
for the personalized color imaging workflow and color matching analyses.
Categorical observers were derived in two steps.
At the first step, 10000 observer functions were generated from the
individual colorimetric observer model using Monte Carlo simulation.
At the second step, the cluster analysis, a modified k-medoids
algorithm, was applied to the 10000 observers minimizing the squared
Euclidean distance in cone fundamentals space, and categorical
observers were derived iteratively. Since the proposed categorical
observers are defined by their physiological parameters and ages, their
CMFs can be derived for any target field size.
2. Categorical observers were ordered by the importance;
the first categorical observer vas the average observer equivalent to
CIEPO06 with 38 year-old for a given field size, followed by the second
most important categorical observer, the third, and so on.
3. see: https://www.rit.edu/cos/colorscience/re_AsanoObserverFunctions.php
"""
# Use Iteratively Derived Cat.Obs.:
var_age = _INDVCMF_CATOBSPFCTR['age'].copy()
vAll = _INDVCMF_CATOBSPFCTR.copy()
vAll.pop('age')
# Set requested wavelength range:
if wl is not None:
wl = getwlr(wl3=wl)
else:
wl = _WL
LMS_All = np.zeros((3 + 1, _WL.shape[0], n_cat))
LMS_All.fill(np.nan)
for k in range(n_cat):
t_LMS = cie2006cmfsEx(age = var_age[k],fieldsize = fieldsize, wl = wl,\
var_od_lens = vAll['od_lens'][k],\
var_od_macula = vAll['od_macula'][k],\
var_od_L = vAll['od_L'][k],\
var_od_M = vAll['od_M'][k],\
var_od_S = vAll['od_S'][k],\
var_shft_L = vAll['shft_L'][k],\
var_shft_M = vAll['shft_M'][k],\
var_shft_S = vAll['shft_S'][k],\
out = 'LMS')
LMS_All[:, :, k] = t_LMS
LMS_All[np.where(LMS_All < 0)] = 0
if n_cat == 1:
LMS_All = np.squeeze(LMS_All, axis=2)
if ('xyz' in out.lower().split(',')):
LMS_All = lmsb_to_xyzb(LMS_All,
fieldsize,
out='xyz',
allow_negative_values=allow_negative_values)
out = out.replace('xyz', 'LMS').replace('XYZ', 'LMS')
if ('lms' in out.lower().split(',')):
out = out.replace('lms', 'LMS')
if (out == 'LMS'):
return LMS_All
elif (out == 'LMS,var_age,vAll'):
return LMS_All, var_age, vAll
else:
return eval(out)
def genMonteCarloObs(n_obs=1,
fieldsize=10,
list_Age=[32],
out='LMS',
wl=None,
allow_negative_values=False):
"""
Monte-Carlo generation of individual observer cone fundamentals.
Args:
:n_obs:
| 1, optional
| Number of observer CMFs to generate.
:list_Age:
| list of observer ages or str, optional
| Defaults to 32 (cfr. CIE2006 CMFs)
| If 'us_census': use US population census of 2010
to generate list_Age.
:fieldsize:
| fieldsize in degrees (between 2° and 10°), optional
| Defaults to 10°.
:out:
| 'LMS' or str, optional
| Determines output.
:wl:
| None, optional
| Interpolation/extraplation of :LMS: output to specified wavelengths.
| None: output original _WL = np.array([390,780,5])
:allow_negative_values:
| False, optional
| Cone fundamentals or color matching functions
| should not have negative values.
| If False: X[X<0] = 0.
Returns:
:returns:
| LMS [,var_age, vAll]
| - LMS: ndarray with population LMS functions.
| - var_age: ndarray with population observer ages.
| - vAll: dict with population physiological factors (see .keys())
References:
1. `Asano Y, Fairchild MD, and Blondé L (2016).
Individual Colorimetric Observer Model.
PLoS One 11, 1–19.
<http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0145671>`_
2. `Asano Y, Fairchild MD, Blondé L, and Morvan P (2016).
Color matching experiment for highlighting interobserver variability.
Color Res. Appl. 41, 530–539.
<https://onlinelibrary.wiley.com/doi/abs/10.1002/col.21975>`_
3. `CIE, and CIE (2006).
Fundamental Chromaticity Diagram with Physiological Axes - Part I
(Vienna: CIE).
<http://www.cie.co.at/publications/fundamental-chromaticity-diagram-physiological-axes-part-1>`_
4. `Asano's Individual Colorimetric Observer Model
<https://www.rit.edu/cos/colorscience/re_AsanoObserverFunctions.php>`_
"""
# Scale down StdDev by scalars optimized using Asano's 75 observers
# collected in Germany:
stdDevAllParam = _INDVCMF_STD_DEV_ALL_PARAM.copy()
scale_factors = [0.98, 0.98, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]
scale_factors = dict(zip(list(stdDevAllParam.keys()), scale_factors))
stdDevAllParam = {
k: v * scale_factors[k]
for (k, v) in stdDevAllParam.items()
}
# Get Normally-distributed Physiological Factors:
vAll = getMonteCarloParam(n_obs=n_obs)
if list_Age is 'us_census':
list_Age = getUSCensusAgeDist()
# Generate Random Ages with the same probability density distribution
# as color matching experiment:
sz_interval = 1
list_AgeRound = np.round(np.array(list_Age) / sz_interval) * sz_interval
h = math.histogram(list_AgeRound,
bins=np.unique(list_AgeRound),
bin_center=True)[0]
p = h / h.sum() # probability density distribution
var_age = np.random.choice(np.unique(list_AgeRound), \
size = n_obs, replace = True,\
p = p)
# Set requested wavelength range:
if wl is not None:
wl = getwlr(wl3=wl)
else:
wl = _WL
LMS_All = np.zeros((3 + 1, wl.shape[0], n_obs))
LMS_All.fill(np.nan)
for k in range(n_obs):
t_LMS, t_trans_lens, t_trans_macula, t_sens_photopig = cie2006cmfsEx(age = var_age[k], fieldsize = fieldsize, wl = wl,\
var_od_lens = vAll['od_lens'][k], var_od_macula = vAll['od_macula'][k], \
var_od_L = vAll['od_L'][k], var_od_M = vAll['od_M'][k], var_od_S = vAll['od_S'][k],\
var_shft_L = vAll['shft_L'][k], var_shft_M = vAll['shft_M'][k], var_shft_S = vAll['shft_S'][k],\
out = 'LMS,trans_lens,trans_macula,sens_photopig')
LMS_All[:, :, k] = t_LMS
# listout = out.split(',')
# if ('trans_lens' in listout) | ('trans_macula' in listout) | ('trans_photopig' in listout):
# trans_lens[:,k] = t_trans_lens
# trans_macula[:,k] = t_trans_macula
# sens_photopig[:,:,k] = t_sens_photopig
if n_obs == 1:
LMS_All = np.squeeze(LMS_All, axis=2)
if ('xyz' in out.lower().split(',')):
LMS_All = lmsb_to_xyzb(LMS_All,
fieldsize,
out='xyz',
allow_negative_values=allow_negative_values)
out = out.replace('xyz', 'LMS').replace('XYZ', 'LMS')
if ('lms' in out.lower().split(',')):
out = out.replace('lms', 'LMS')
if (out == 'LMS'):
return LMS_All
elif (out == 'LMS,var_age,vAll'):
return LMS_All, var_age, vAll
else:
return eval(out)
def cam15u(data,
fov=10.0,
inputtype='xyz',
direction='forward',
outin='Q,aW,bW',
parameters=None):
"""
Convert between CIE 2006 10° XYZ tristimulus values (or spectral data)
and CAM15u color appearance correlates.
Args:
:data:
| ndarray of CIE 2006 10° XYZ tristimulus values or spectral data
| or color appearance attributes
:fov:
| 10.0, optional
| Field-of-view of stimulus (for size effect on brightness)
:inputtpe:
| 'xyz' or 'spd', optional
| Specifies the type of input:
| tristimulus values or spectral data for the forward mode.
:direction:
| 'forward' or 'inverse', optional
| -'forward': xyz -> cam15u
| -'inverse': cam15u -> xyz
:outin:
| 'Q,aW,bW' or str, optional
| 'Q,aW,bW' (brightness and opponent signals for amount-of-neutral)
| other options: 'Q,aM,bM' (colorfulness) and 'Q,aS,bS' (saturation)
| Str specifying the type of
| input (:direction: == 'inverse') and
| output (:direction: == 'forward')
:parameters:
| None or dict, optional
| Set of model parameters.
| - None: defaults to luxpy.cam._CAM15U_PARAMETERS
| (see references below)
Returns:
:returns:
| ndarray with color appearance correlates (:direction: == 'forward')
| or
| XYZ tristimulus values (:direction: == 'inverse')
References:
1. `M. Withouck, K. A. G. Smet, W. R. Ryckaert, and P. Hanselaer,
“Experimental driven modelling of the color appearance of
unrelated self-luminous stimuli: CAM15u,”
Opt. Express, vol. 23, no. 9, pp. 12045–12064, 2015.
<https://www.osapublishing.org/oe/abstract.cfm?uri=oe-23-9-12045&origin=search>`_
2. `M. Withouck, K. A. G. Smet, and P. Hanselaer, (2015),
“Brightness prediction of different sized unrelated self-luminous stimuli,”
Opt. Express, vol. 23, no. 10, pp. 13455–13466.
<https://www.osapublishing.org/oe/abstract.cfm?uri=oe-23-10-13455&origin=search>`_
"""
if parameters is None:
parameters = _CAM15U_PARAMETERS
outin = outin.split(',')
#unpack model parameters:
Mxyz2rgb, cA, cAlms, cHK, cM, cW, ca, calms, cb, cblms, cfov, cp, k, unique_hue_data = [
parameters[x] for x in sorted(parameters.keys())
]
# precomputations:
invMxyz2rgb = np.linalg.inv(Mxyz2rgb)
MAab = np.array([cAlms, calms, cblms])
invMAab = np.linalg.inv(MAab)
#initialize data and camout:
data = np2d(data)
if len(data.shape) == 2:
data = np.expand_dims(data, axis=0) # avoid looping if not necessary
if (data.shape[0] > data.shape[1]): # loop over shortest dim.
flipaxis0and1 = True
data = np.transpose(data, axes=(1, 0, 2))
else:
flipaxis0and1 = False
dshape = list(data.shape)
dshape[-1] = len(outin) # requested number of correlates
if (inputtype != 'xyz') & (direction == 'forward'):
dshape[-2] = dshape[
-2] - 1 # wavelength row doesn't count & only with forward can the input data be spectral
camout = np.zeros(dshape)
camout.fill(np.nan)
for i in range(data.shape[0]):
if (inputtype != 'xyz') & (direction == 'forward'):
xyz = spd_to_xyz(data[i], cieobs='2006_10', relative=False)
lms = np.dot(_CMF['2006_10']['M'], xyz.T).T # convert to l,m,s
rgb = (lms /
_CMF['2006_10']['K']) * k # convert to rho, gamma, beta
elif (inputtype == 'xyz') & (direction == 'forward'):
rgb = np.dot(Mxyz2rgb, data[i].T).T
if direction == 'forward':
# apply cube-root compression:
rgbc = rgb**(cp)
# calculate achromatic and color difference signals, A, a, b:
Aab = np.dot(MAab, rgbc.T).T
A, a, b = asplit(Aab)
A = cA * A
a = ca * a
b = cb * b
# calculate colorfullness like signal M:
M = cM * ((a**2.0 + b**2.0)**0.5)
# calculate brightness Q:
Q = A + cHK[0] * M**cHK[
1] # last term is contribution of Helmholtz-Kohlrausch effect on brightness
# calculate saturation, s:
s = M / Q
# calculate amount of white, W:
W = 100.0 / (1.0 + cW[0] * (s**cW[1]))
# adjust Q for size (fov) of stimulus (matter of debate whether to do this before or after calculation of s or W, there was no data on s, M or W for different sized stimuli: after)
Q = Q * (fov / 10.0)**cfov
# calculate hue, h and Hue quadrature, H:
h = hue_angle(a, b, htype='deg')
if 'H' in outin:
H = hue_quadrature(h, unique_hue_data=unique_hue_data)
else:
H = None
# calculate cart. co.:
if 'aM' in outin:
aM = M * np.cos(h * np.pi / 180.0)
bM = M * np.sin(h * np.pi / 180.0)
if 'aS' in outin:
aS = s * np.cos(h * np.pi / 180.0)
bS = s * np.sin(h * np.pi / 180.0)
if 'aW' in outin:
aW = W * np.cos(h * np.pi / 180.0)
bW = W * np.sin(h * np.pi / 180.0)
if (outin != ['Q', 'aW', 'bW']):
camout[i] = eval('ajoin((' + ','.join(outin) + '))')
else:
camout[i] = ajoin((Q, aW, bW))
elif direction == 'inverse':
# get Q, M and a, b depending on input type:
if 'aW' in outin:
Q, a, b = asplit(data[i])
Q = Q / (
(fov / 10.0)**cfov
) #adjust Q for size (fov) of stimulus back to that 10° ref
W = (a**2.0 + b**2.0)**0.5
s = (((100 / W) - 1.0) / cW[0])**(1.0 / cW[1])
M = s * Q
if 'aM' in outin:
Q, a, b = asplit(data[i])
Q = Q / (
(fov / 10.0)**cfov
) #adjust Q for size (fov) of stimulus back to that 10° ref
M = (a**2.0 + b**2.0)**0.5
if 'aS' in outin:
Q, a, b = asplit(data[i])
Q = Q / (
(fov / 10.0)**cfov
) #adjust Q for size (fov) of stimulus back to that 10° ref
s = (a**2.0 + b**2.0)**0.5
M = s * Q
if 'h' in outin:
Q, WsM, h = asplit(data[i])
Q = Q / (
(fov / 10.0)**cfov
) #adjust Q for size (fov) of stimulus back to that 10° ref
if 'W' in outin:
s = (((100.0 / WsM) - 1.0) / cW[0])**(1.0 / cW[1])
M = s * Q
elif 's' in outin:
M = WsM * Q
elif 'M' in outin:
M = WsM
# calculate achromatic signal, A from Q and M:
A = Q - cHK[0] * M**cHK[1]
A = A / cA
# calculate hue angle:
h = hue_angle(a, b, htype='rad')
# calculate a,b from M and h:
a = (M / cM) * np.cos(h)
b = (M / cM) * np.sin(h)
a = a / ca
b = b / cb
# create Aab:
Aab = ajoin((A, a, b))
# calculate rgbc:
rgbc = np.dot(invMAab, Aab.T).T
# decompress rgbc to rgb:
rgb = rgbc**(1 / cp)
# convert rgb to xyz:
xyz = np.dot(invMxyz2rgb, rgb.T).T
camout[i] = xyz
if flipaxis0and1 == True: # loop over shortest dim.
camout = np.transpose(camout, axes=(1, 0, 2))
if camout.shape[0] == 1:
camout = np.squeeze(camout, axis=0)
return camout
def cam_sww16(data, dataw = None, Yb = 20.0, Lw = 400.0, Ccwb = None, relative = True, \
parameters = None, inputtype = 'xyz', direction = 'forward', \
cieobs = '2006_10'):
"""
A simple principled color appearance model based on a mapping
of the Munsell color system.
| This function implements the JOSA A (parameters = 'JOSA') published model.
Args:
:data:
| ndarray with input tristimulus values
| or spectral data
| or input color appearance correlates
| Can be of shape: (N [, xM], x 3), whereby:
| N refers to samples and M refers to light sources.
| Note that for spectral input shape is (N x (M+1) x wl)
:dataw:
| None or ndarray, optional
| Input tristimulus values or spectral data of white point.
| None defaults to the use of CIE illuminant C.
:Yb:
| 20.0, optional
| Luminance factor of background (perfect white diffuser, Yw = 100)
:Lw:
| 400.0, optional
| Luminance (cd/m²) of white point.
:Ccwb:
| None, optional
| Degree of cognitive adaptation (white point balancing)
| If None: use [..,..] from parameters dict.
:relative:
| True or False, optional
| True: xyz tristimulus values are relative (Yw = 100)
:parameters:
| None or str or dict, optional
| Dict with model parameters.
| - None: defaults to luxpy.cam._CAM_SWW_2016_PARAMETERS['JOSA']
| - str: 'best-fit-JOSA' or 'best-fit-all-Munsell'
| - dict: user defined model parameters
| (dict should have same structure)
:inputtype:
| 'xyz' or 'spd', optional
| Specifies the type of input:
| tristimulus values or spectral data for the forward mode.
:direction:
| 'forward' or 'inverse', optional
| -'forward': xyz -> cam_sww_2016
| -'inverse': cam_sww_2016 -> xyz
:cieobs:
| '2006_10', optional
| CMF set to use to perform calculations where spectral data
is involved (inputtype == 'spd'; dataw = None)
| Other options: see luxpy._CMF['types']
Returns:
:returns:
| ndarray with color appearance correlates (:direction: == 'forward')
| or
| XYZ tristimulus values (:direction: == 'inverse')
Notes:
| This function implements the JOSA A (parameters = 'JOSA')
published model.
| With:
| 1. A correction for the parameter
| in Eq.4 of Fig. 11: 0.952 --> -0.952
|
| 2. The delta_ac and delta_bc white-balance shifts in Eq. 5e & 5f
| should be: -0.028 & 0.821
|
| (cfr. Ccwb = 0.66 in:
| ab_test_out = ab_test_int - Ccwb*ab_gray_adaptation_field_int))
References:
1. `Smet, K. A. G., Webster, M. A., & Whitehead, L. A. (2016).
A simple principled approach for modeling and understanding uniform color metrics.
Journal of the Optical Society of America A, 33(3), A319–A331.
<https://doi.org/10.1364/JOSAA.33.00A319>`_
"""
# get model parameters
args = locals().copy()
if parameters is None:
parameters = _CAM_SWW16_PARAMETERS['JOSA']
if isinstance(parameters, str):
parameters = _CAM_SWW16_PARAMETERS[parameters]
parameters = put_args_in_db(
parameters,
args) #overwrite parameters with other (not-None) args input
#unpack model parameters:
Cc, Ccwb, Cf, Mxyz2lms, cLMS, cab_int, cab_out, calpha, cbeta, cga1, cga2, cgb1, cgb2, cl_int, clambda, lms0 = [
parameters[x] for x in sorted(parameters.keys())
]
# setup default adaptation field:
if (dataw is None):
dataw = _CIE_ILLUMINANTS['C'].copy() # get illuminant C
xyzw = spd_to_xyz(dataw, cieobs=cieobs,
relative=False) # get abs. tristimulus values
if relative == False: #input is expected to be absolute
dataw[1:] = Lw * dataw[
1:] / xyzw[:, 1:2] #dataw = Lw*dataw # make absolute
else:
dataw = dataw # make relative (Y=100)
if inputtype == 'xyz':
dataw = spd_to_xyz(dataw, cieobs=cieobs, relative=relative)
# precomputations:
Mxyz2lms = np.dot(
np.diag(cLMS),
math.normalize_3x3_matrix(Mxyz2lms, np.array([[1, 1, 1]]))
) # normalize matrix for xyz-> lms conversion to ill. E weighted with cLMS
invMxyz2lms = np.linalg.inv(Mxyz2lms)
MAab = np.array([clambda, calpha, cbeta])
invMAab = np.linalg.inv(MAab)
#initialize data and camout:
data = np2d(data).copy(
) # stimulus data (can be upto NxMx3 for xyz, or [N x (M+1) x wl] for spd))
dataw = np2d(dataw).copy(
) # white point (can be upto Nx3 for xyz, or [(N+1) x wl] for spd)
# make axis 1 of dataw have 'same' dimensions as data:
if (data.ndim == 2):
data = np.expand_dims(data, axis=1) # add light source axis 1
if inputtype == 'xyz':
if dataw.shape[
0] == 1: #make dataw have same lights source dimension size as data
dataw = np.repeat(dataw, data.shape[1], axis=0)
else:
if dataw.shape[0] == 2:
dataw = np.vstack(
(dataw[0], np.repeat(dataw[1:], data.shape[1], axis=0)))
# Flip light source dim to axis 0:
data = np.transpose(data, axes=(1, 0, 2))
# Initialize output array:
dshape = list(data.shape)
dshape[-1] = 3 # requested number of correlates: l_int, a_int, b_int
if (inputtype != 'xyz') & (direction == 'forward'):
dshape[-2] = dshape[
-2] - 1 # wavelength row doesn't count & only with forward can the input data be spectral
camout = np.zeros(dshape)
camout.fill(np.nan)
# apply forward/inverse model for each row in data:
for i in range(data.shape[0]):
# stage 1: calculate photon rates of stimulus and adapting field, lmst & lmsf:
if (inputtype != 'xyz'):
if relative == True:
xyzw_abs = spd_to_xyz(np.vstack((dataw[0], dataw[i + 1])),
cieobs=cieobs,
relative=False)
dataw[i +
1] = Lw * dataw[i + 1] / xyzw_abs[0, 1] # make absolute
xyzw = spd_to_xyz(np.vstack((dataw[0], dataw[i + 1])),
cieobs=cieobs,
relative=False)
lmsw = 683.0 * np.dot(Mxyz2lms, xyzw.T).T / _CMF[cieobs]['K']
lmsf = (Yb / 100.0
) * lmsw # calculate adaptation field and convert to l,m,s
if (direction == 'forward'):
if relative == True:
data[i, 1:, :] = Lw * data[i, 1:, :] / xyzw_abs[
0, 1] # make absolute
xyzt = spd_to_xyz(data[i], cieobs=cieobs,
relative=False) / _CMF[cieobs]['K']
lmst = 683.0 * np.dot(Mxyz2lms, xyzt.T).T # convert to l,m,s
else:
lmst = lmsf # put lmsf in lmst for inverse-mode
elif (inputtype == 'xyz'):
if relative == True:
dataw[i] = Lw * dataw[i] / 100.0 # make absolute
lmsw = 683.0 * np.dot(
Mxyz2lms, dataw[i].T).T / _CMF[cieobs]['K'] # convert to lms
lmsf = (Yb / 100.0) * lmsw
if (direction == 'forward'):
if relative == True:
data[i] = Lw * data[i] / 100.0 # make absolute
lmst = 683.0 * np.dot(
Mxyz2lms,
data[i].T).T / _CMF[cieobs]['K'] # convert to lms
else:
lmst = lmsf # put lmsf in lmst for inverse-mode
# stage 2: calculate cone outputs of stimulus lmstp
lmstp = math.erf(Cc * (np.log(lmst / lms0) + Cf * np.log(lmsf / lms0)))
lmsfp = math.erf(Cc * (np.log(lmsf / lms0) + Cf * np.log(lmsf / lms0)))
lmstp = np.vstack(
(lmsfp, lmstp)
) # add adaptation field lms temporarily to lmsp for quick calculation
# stage 3: calculate optic nerve signals, lam*, alphp, betp:
lstar, alph, bet = asplit(np.dot(MAab, lmstp.T).T)
alphp = cga1[0] * alph
alphp[alph < 0] = cga1[1] * alph[alph < 0]
betp = cgb1[0] * bet
betp[bet < 0] = cgb1[1] * bet[bet < 0]
# stage 4: calculate recoded nerve signals, alphapp, betapp:
alphpp = cga2[0] * (alphp + betp)
betpp = cgb2[0] * (alphp - betp)
# stage 5: calculate conscious color perception:
lstar_int = cl_int[0] * (lstar + cl_int[1])
alph_int = cab_int[0] * (np.cos(cab_int[1] * np.pi / 180.0) * alphpp -
np.sin(cab_int[1] * np.pi / 180.0) * betpp)
bet_int = cab_int[0] * (np.sin(cab_int[1] * np.pi / 180.0) * alphpp +
np.cos(cab_int[1] * np.pi / 180.0) * betpp)
lstar_out = lstar_int
if direction == 'forward':
if Ccwb is None:
alph_out = alph_int - cab_out[0]
bet_out = bet_int - cab_out[1]
else:
Ccwb = Ccwb * np.ones((2))
Ccwb[Ccwb < 0.0] = 0.0
Ccwb[Ccwb > 1.0] = 1.0
alph_out = alph_int - Ccwb[0] * alph_int[
0] # white balance shift using adaptation gray background (Yb=20%), with Ccw: degree of adaptation
bet_out = bet_int - Ccwb[1] * bet_int[0]
camout[i] = np.vstack(
(lstar_out[1:], alph_out[1:], bet_out[1:])
).T # stack together and remove adaptation field from vertical stack
elif direction == 'inverse':
labf_int = np.hstack((lstar_int[0], alph_int[0], bet_int[0]))
# get lstar_out, alph_out & bet_out for data:
lstar_out, alph_out, bet_out = asplit(data[i])
# stage 5 inverse:
# undo cortical white-balance:
if Ccwb is None:
alph_int = alph_out + cab_out[0]
bet_int = bet_out + cab_out[1]
else:
Ccwb = Ccwb * np.ones((2))
Ccwb[Ccwb < 0.0] = 0.0
Ccwb[Ccwb > 1.0] = 1.0
alph_int = alph_out + Ccwb[0] * alph_int[
0] # inverse white balance shift using adaptation gray background (Yb=20%), with Ccw: degree of adaptation
bet_int = bet_out + Ccwb[1] * bet_int[0]
lstar_int = lstar_out
alphpp = (1.0 / cab_int[0]) * (
np.cos(-cab_int[1] * np.pi / 180.0) * alph_int -
np.sin(-cab_int[1] * np.pi / 180.0) * bet_int)
betpp = (1.0 / cab_int[0]) * (
np.sin(-cab_int[1] * np.pi / 180.0) * alph_int +
np.cos(-cab_int[1] * np.pi / 180.0) * bet_int)
lstar_int = lstar_out
lstar = (lstar_int / cl_int[0]) - cl_int[1]
# stage 4 inverse:
alphp = 0.5 * (alphpp / cga2[0] + betpp / cgb2[0]
) # <-- alphpp = (Cga2.*(alphp+betp));
betp = 0.5 * (alphpp / cga2[0] - betpp / cgb2[0]
) # <-- betpp = (Cgb2.*(alphp-betp));
# stage 3 invers:
alph = alphp / cga1[0]
bet = betp / cgb1[0]
sa = np.sign(cga1[1])
sb = np.sign(cgb1[1])
alph[(sa * alphp) < 0.0] = alphp[(sa * alphp) < 0] / cga1[1]
bet[(sb * betp) < 0.0] = betp[(sb * betp) < 0] / cgb1[1]
lab = ajoin((lstar, alph, bet))
# stage 2 inverse:
lmstp = np.dot(invMAab, lab.T).T
lmstp[lmstp < -1.0] = -1.0
lmstp[lmstp > 1.0] = 1.0
lmstp = math.erfinv(lmstp) / Cc - Cf * np.log(lmsf / lms0)
lmst = np.exp(lmstp) * lms0
# stage 1 inverse:
xyzt = np.dot(invMxyz2lms, lmst.T).T
if relative == True:
xyzt = (100.0 / Lw) * xyzt
camout[i] = xyzt
# if flipaxis0and1 == True: # loop over shortest dim.
# camout = np.transpose(camout, axes = (1,0,2))
# Flip light source dim back to axis 1:
camout = np.transpose(camout, axes=(1, 0, 2))
if camout.shape[0] == 1:
camout = np.squeeze(camout, axis=0)
return camout
def spd_to_xyz(data,
relative=True,
rfl=None,
cieobs=_CIEOBS,
K=None,
out=None,
cie_std_dev_obs=None):
"""
Calculates xyz tristimulus values from spectral data.
Args:
:data:
| ndarray or pandas.dataframe with spectral data
| (.shape = (number of spectra + 1, number of wavelengths))
| Note that :data: is never interpolated, only CMFs and RFLs.
| This way interpolation errors due to peaky spectra are avoided.
| Conform CIE15-2018.
:relative:
| True or False, optional
| Calculate relative XYZ (Yw = 100) or absolute XYZ (Y = Luminance)
:rfl:
| ndarray with spectral reflectance functions.
| Will be interpolated if wavelengths do not match those of :data:
:cieobs:
| luxpy._CIEOBS or str, optional
| Determines the color matching functions to be used in the
| calculation of XYZ.
:K:
| None, optional
| e.g. K = 683 lm/W for '1931_2' (relative == False)
| or K = 100/sum(spd*dl) (relative == True)
:out:
| None or 1 or 2, optional
| Determines number and shape of output. (see :returns:)
:cie_std_dev_obs:
| None or str, optional
| - None: don't use CIE Standard Deviate Observer function.
| - 'f1': use F1 function.
Returns:
:returns:
| If rfl is None:
| If out is None: ndarray of xyz values
| (.shape = (data.shape[0],3))
| If out == 1: ndarray of xyz values
| (.shape = (data.shape[0],3))
| If out == 2: (ndarray of xyz, ndarray of xyzw) values
| Note that xyz == xyzw, with (.shape = (data.shape[0],3))
| If rfl is not None:
| If out is None: ndarray of xyz values
| (.shape = (rfl.shape[0],data.shape[0],3))
| If out == 1: ndarray of xyz values
| (.shape = (rfl.shape[0]+1,data.shape[0],3))
| The xyzw values of the light source spd are the first set
| of values of the first dimension. The following values
| along this dimension are the sample (rfl) xyz values.
| If out == 2: (ndarray of xyz, ndarray of xyzw) values
| with xyz.shape = (rfl.shape[0],data.shape[0],3)
| and with xyzw.shape = (data.shape[0],3)
References:
1. `CIE15:2018, “Colorimetry,” CIE, Vienna, Austria, 2018. <https://doi.org/10.25039/TR.015.2018>`_
"""
data = getdata(data,
kind='np') if isinstance(data, pd.DataFrame) else np2d(
data) # convert to np format and ensure 2D-array
# get wl spacing:
dl = getwld(data[0])
# get cmf,k for cieobs:
if isinstance(cieobs, str):
if K is None: K = _CMF[cieobs]['K']
scr = 'dict'
else:
scr = 'cieobs'
if (K is None) & (relative == False): K = 1
# Interpolate to wl of data:
cmf = xyzbar(cieobs=cieobs, scr=scr, wl_new=data[0], kind='np')
# Add CIE standard deviate observer function to cmf if requested:
if cie_std_dev_obs is not None:
cmf_cie_std_dev_obs = xyzbar(cieobs='cie_std_dev_obs_' +
cie_std_dev_obs.lower(),
scr=scr,
wl_new=data[0],
kind='np')
cmf[1:] = cmf[1:] + cmf_cie_std_dev_obs[1:]
# Rescale xyz using k or 100/Yw:
if relative == True: K = 100.0 / np.dot(data[1:], cmf[2, :] * dl)
# Interpolate rfls to lambda range of spd and calculate xyz:
if rfl is not None:
rfl = cie_interp(data=np2d(rfl), wl_new=data[0], kind='rfl')
rfl = np.concatenate((np.ones((1, data.shape[1])),
rfl[1:])) #add rfl = 1 for light source spectrum
xyz = K * np.array(
[np.dot(rfl, (data[1:] * cmf[i + 1, :] * dl).T)
for i in range(3)]) #calculate tristimulus values
rflwasnotnone = 1
else:
rfl = np.ones((1, data.shape[1]))
xyz = (K * (np.dot((cmf[1:] * dl), data[1:].T))[:, None, :])
rflwasnotnone = 0
xyz = np.transpose(xyz, [1, 2, 0]) #order [rfl,spd,xyz]
# Setup output:
if out == 2:
xyzw = xyz[0, ...]
xyz = xyz[rflwasnotnone:, ...]
if rflwasnotnone == 0: xyz = np.squeeze(xyz, axis=0)
return xyz, xyzw
elif out == 1:
if rflwasnotnone == 0: xyz = np.squeeze(xyz, axis=0)
return xyz
else:
xyz = xyz[rflwasnotnone:, ...]
if rflwasnotnone == 0: xyz = np.squeeze(xyz, axis=0)
return xyz
def cam18sl(data,
datab=None,
Lb=[100],
fov=10.0,
inputtype='xyz',
direction='forward',
outin='Q,aS,bS',
parameters=None):
"""
Convert between CIE 2006 10° XYZ tristimulus values (or spectral data)
and CAM18sl color appearance correlates.
Args:
:data:
| ndarray of CIE 2006 10° absolute XYZ tristimulus values or spectral data
| or color appearance attributes of stimulus
:datab:
| ndarray of CIE 2006 10° absolute XYZ tristimulus values or spectral data
| of stimulus background
:Lb:
| [100], optional
| Luminance (cd/m²) value(s) of background(s) calculated using the CIE 2006 10° CMFs
| (only used in case datab == None and the background is assumed to be an Equal-Energy-White)
:fov:
| 10.0, optional
| Field-of-view of stimulus (for size effect on brightness)
:inputtpe:
| 'xyz' or 'spd', optional
| Specifies the type of input:
| tristimulus values or spectral data for the forward mode.
:direction:
| 'forward' or 'inverse', optional
| -'forward': xyz -> cam18sl
| -'inverse': cam18sl -> xyz
:outin:
| 'Q,aS,bS' or str, optional
| 'Q,aS,bS' (brightness and opponent signals for saturation)
| other options: 'Q,aM,bM' (colorfulness)
| (Note that 'Q,aW,bW' would lead to a Cartesian
| a,b-coordinate system centered at (1,0))
| Str specifying the type of
| input (:direction: == 'inverse') and
| output (:direction: == 'forward')
:parameters:
| None or dict, optional
| Set of model parameters.
| - None: defaults to luxpy.cam._CAM18SL_PARAMETERS
| (see references below)
Returns:
:returns:
| ndarray with color appearance correlates (:direction: == 'forward')
| or
| XYZ tristimulus values (:direction: == 'inverse')
Notes:
| * Instead of using the CIE 1964 10° CMFs in some places of the model,
| the CIE 2006 10° CMFs are used througout, making it more self_consistent.
| This has an effect on the k scaling factors (now different those in CAM15u)
| and the illuminant E normalization for use in the chromatic adaptation transform.
| (see future erratum to Hermans et al., 2018)
| * The paper also used an equation for the amount of white W, which is
| based on a Q value not expressed in 'bright' ('cA' = 0.937 instead of 123).
| This has been corrected for in the luxpy version of the model, i.e.
| _CAM18SL_PARAMETERS['cW'][0] has been changed from 2.29 to 1/11672.
| (see future erratum to Hermans et al., 2018)
| * Default output was 'Q,aW,bW' prior to March 2020, but since this
| is an a,b Cartesian system centered on (1,0), the default output
| has been changed to 'Q,aS,bS'.
References:
1. `Hermans, S., Smet, K. A. G., & Hanselaer, P. (2018).
"Color appearance model for self-luminous stimuli."
Journal of the Optical Society of America A, 35(12), 2000–2009.
<https://doi.org/10.1364/JOSAA.35.002000>`_
"""
if parameters is None:
parameters = _CAM18SL_PARAMETERS
outin = outin.split(',')
#unpack model parameters:
cA, cAlms, cHK, cM, cW, ca, calms, cb, cblms, cfov, cieobs, k, naka, unique_hue_data = [
parameters[x] for x in sorted(parameters.keys())
]
# precomputations:
Mlms2xyz = np.linalg.inv(_CMF[cieobs]['M'])
MAab = np.array([cAlms, calms, cblms])
invMAab = np.linalg.inv(MAab)
#-------------------------------------------------
# setup EEW reference field and default background field (Lr should be equal to Lb):
# Get Lb values:
if datab is not None:
if inputtype != 'xyz':
Lb = spd_to_xyz(datab, cieobs=cieobs, relative=False)[..., 1:2]
else:
Lb = datab[..., 1:2]
else:
if isinstance(Lb, list):
Lb = np2dT(Lb)
# Setup EEW ref of same luminance as datab:
if inputtype == 'xyz':
wlr = getwlr(_CAM18SL_WL3)
else:
if datab is None:
wlr = data[0] # use wlr of stimulus data
else:
wlr = datab[0] # use wlr of background data
datar = np.vstack((wlr, np.ones(
(Lb.shape[0], wlr.shape[0])))) # create eew
xyzr = spd_to_xyz(datar, cieobs=cieobs,
relative=False) # get abs. tristimulus values
datar[1:] = datar[1:] / xyzr[..., 1:2] * Lb
# Create datab if None:
if (datab is None):
if inputtype != 'xyz':
datab = datar.copy()
else:
datab = spd_to_xyz(datar, cieobs=cieobs, relative=False)
# prepare data and datab for loop over backgrounds:
# make axis 1 of datab have 'same' dimensions as data:
if (data.ndim == 2):
data = np.expand_dims(data, axis=1) # add light source axis 1
if inputtype == 'xyz':
datar = spd_to_xyz(datar, cieobs=cieobs,
relative=False) # convert to xyz!!
if datab.shape[
0] == 1: #make datab and datar have same lights source dimension (used to store different backgrounds) size as data
datab = np.repeat(datab, data.shape[1], axis=0)
datar = np.repeat(datar, data.shape[1], axis=0)
else:
if datab.shape[0] == 2:
datab = np.vstack(
(datab[0], np.repeat(datab[1:], data.shape[1], axis=0)))
if datar.shape[0] == 2:
datar = np.vstack(
(datar[0], np.repeat(datar[1:], data.shape[1], axis=0)))
# Flip light source/ background dim to axis 0:
data = np.transpose(data, axes=(1, 0, 2))
#-------------------------------------------------
#initialize camout:
dshape = list(data.shape)
dshape[-1] = len(outin) # requested number of correlates
if (inputtype != 'xyz') & (direction == 'forward'):
dshape[-2] = dshape[
-2] - 1 # wavelength row doesn't count & only with forward can the input data be spectral
camout = np.zeros(dshape)
camout.fill(np.nan)
for i in range(data.shape[0]):
# get rho, gamma, beta of background and reference white:
if (inputtype != 'xyz'):
xyzb = spd_to_xyz(np.vstack((datab[0], datab[i + 1:i + 2, :])),
cieobs=cieobs,
relative=False)
xyzr = spd_to_xyz(np.vstack((datar[0], datar[i + 1:i + 2, :])),
cieobs=cieobs,
relative=False)
else:
xyzb = datab[i:i + 1, :]
xyzr = datar[i:i + 1, :]
lmsb = np.dot(_CMF[cieobs]['M'], xyzb.T).T # convert to l,m,s
rgbb = (lmsb / _CMF[cieobs]['K']) * k # convert to rho, gamma, beta
#lmsr = np.dot(_CMF[cieobs]['M'],xyzr.T).T # convert to l,m,s
#rgbr = (lmsr / _CMF[cieobs]['K']) * k # convert to rho, gamma, beta
#rgbr = rgbr/rgbr[...,1:2]*Lb[i] # calculated EEW cone excitations at same luminance values as background
rgbr = np.ones(xyzr.shape) * Lb[
i] # explicitely equal EEW cone excitations at same luminance values as background
if direction == 'forward':
# get rho, gamma, beta of stimulus:
if (inputtype != 'xyz'):
xyz = spd_to_xyz(data[i], cieobs=cieobs, relative=False)
elif (inputtype == 'xyz'):
xyz = data[i]
lms = np.dot(_CMF[cieobs]['M'], xyz.T).T # convert to l,m,s
rgb = (lms / _CMF[cieobs]['K']) * k # convert to rho, gamma, beta
# apply von-kries cat with D = 1:
if (rgbb == 0).any():
Mcat = np.eye(3)
else:
Mcat = np.diag((rgbr / rgbb)[0])
rgba = np.dot(Mcat, rgb.T).T
# apply naka-rushton compression:
rgbc = naka_rushton(rgba,
n=naka['n'],
sig=naka['sig'](rgbr.mean()),
noise=naka['noise'],
scaling=naka['scaling'])
#rgbc = np.ones(rgbc.shape)*rgbc.mean() # test if eew ends up at origin
# calculate achromatic and color difference signals, A, a, b:
Aab = np.dot(MAab, rgbc.T).T
A, a, b = asplit(Aab)
a = ca * a
b = cb * b
# calculate colorfullness like signal M:
M = cM * ((a**2.0 + b**2.0)**0.5)
# calculate brightness Q:
Q = cA * (
A + cHK[0] * M**cHK[1]
) # last term is contribution of Helmholtz-Kohlrausch effect on brightness
# calculate saturation, s:
s = M / Q
S = s # make extra variable, jsut in case 'S' is called
# calculate amount of white, W:
W = 1 / (1.0 + cW[0] * (s**cW[1]))
# adjust Q for size (fov) of stimulus (matter of debate whether to do this before or after calculation of s or W, there was no data on s, M or W for different sized stimuli: after)
Q = Q * (fov / 10.0)**cfov
# calculate hue, h and Hue quadrature, H:
h = hue_angle(a, b, htype='deg')
if 'H' in outin:
H = hue_quadrature(h, unique_hue_data=unique_hue_data)
else:
H = None
# calculate cart. co.:
if 'aM' in outin:
aM = M * np.cos(h * np.pi / 180.0)
bM = M * np.sin(h * np.pi / 180.0)
if 'aS' in outin:
aS = s * np.cos(h * np.pi / 180.0)
bS = s * np.sin(h * np.pi / 180.0)
if 'aW' in outin:
aW = W * np.cos(h * np.pi / 180.0)
bW = W * np.sin(h * np.pi / 180.0)
if (outin != ['Q', 'as', 'bs']):
camout[i] = eval('ajoin((' + ','.join(outin) + '))')
else:
camout[i] = ajoin((Q, aS, bS))
elif direction == 'inverse':
# get Q, M and a, b depending on input type:
if 'aW' in outin:
Q, a, b = asplit(data[i])
Q = Q / (
(fov / 10.0)**cfov
) #adjust Q for size (fov) of stimulus back to that 10° ref
W = (a**2.0 + b**2.0)**0.5
s = (((1.0 / W) - 1.0) / cW[0])**(1.0 / cW[1])
M = s * Q
if 'aM' in outin:
Q, a, b = asplit(data[i])
Q = Q / (
(fov / 10.0)**cfov
) #adjust Q for size (fov) of stimulus back to that 10° ref
M = (a**2.0 + b**2.0)**0.5
if 'aS' in outin:
Q, a, b = asplit(data[i])
Q = Q / (
(fov / 10.0)**cfov
) #adjust Q for size (fov) of stimulus back to that 10° ref
s = (a**2.0 + b**2.0)**0.5
M = s * Q
if 'h' in outin:
Q, WsM, h = asplit(data[i])
Q = Q / (
(fov / 10.0)**cfov
) #adjust Q for size (fov) of stimulus back to that 10° ref
if 'W' in outin:
s = (((1.0 / WsM) - 1.0) / cW[0])**(1.0 / cW[1])
M = s * Q
elif 's' in outin:
M = WsM * Q
elif 'M' in outin:
M = WsM
# calculate achromatic signal, A from Q and M:
A = Q / cA - cHK[0] * M**cHK[1]
# calculate hue angle:
h = hue_angle(a, b, htype='rad')
# calculate a,b from M and h:
a = (M / cM) * np.cos(h)
b = (M / cM) * np.sin(h)
a = a / ca
b = b / cb
# create Aab:
Aab = ajoin((A, a, b))
# calculate rgbc:
rgbc = np.dot(invMAab, Aab.T).T
# decompress rgbc to (adapted) rgba :
rgba = naka_rushton(rgbc,
n=naka['n'],
sig=naka['sig'](rgbr.mean()),
noise=naka['noise'],
scaling=naka['scaling'],
direction='inverse')
# apply inverse von-kries cat with D = 1:
rgb = np.dot(np.diag((rgbb / rgbr)[0]), rgba.T).T
# convert rgb to lms to xyz:
lms = rgb / k * _CMF[cieobs]['K']
xyz = np.dot(Mlms2xyz, lms.T).T
camout[i] = xyz
camout = np.transpose(camout, axes=(1, 0, 2))
if camout.shape[1] == 1:
camout = np.squeeze(camout, axis=1)
return camout