def dot23(A,B, keepdims = False):
"""
Dot product of a 2-d ndarray with a (N x K x L) 3-d ndarray
using einsum().
Args:
:A:
| ndarray (.shape = (M,N))
:B:
| ndarray (.shape = (N,K,L))
Returns:
:returns:
| ndarray (.shape = (M,K,L))
"""
if (len(A.shape)==2) & (len(B.shape)==3):
dotAB = np.einsum('ij,jkl->ikl',A,B)
if (len(B.shape)==3) & (keepdims == True):
dotAB = np.expand_dims(dotAB,axis=1)
elif (len(A.shape)==2) & (len(B.shape)==2):
dotAB = np.einsum('ij,jk->ik',A,B)
if (len(B.shape)==2) & (keepdims == True):
dotAB = np.expand_dims(dotAB,axis=1)
return dotAB
def np3dT(data): # keep last axis the same
"""
Make a tuple, list or numpy array at least a 3d numpy array and transposed
first 2 axes.
Args:
:data:
| tuple, list, ndarray
Returns:
:returns:
| ndarray with .ndim >= 3 and with first two axes
transposed (axis=3 is kept the same).
"""
if isinstance(
data, np.ndarray
): # assume already atleast_3d when nd.array (user has to ensure input is an array)
if (len(data.shape) >= 3):
return data.transpose((1, 0, 2))
else:
return np.expand_dims(np.atleast_2d(data), axis=0).transpose(
(1, 0, 2))
else:
return np.expand_dims(np.atleast_2d(np.aray(data)), axis=0).transpose(
(1, 0, 2))
def todim(x, tshape, add_axis=1, equal_shape=False):
"""
Expand x to dims that are broadcast-compatable with shape of another array.
Args:
:x:
| ndarray
:tshape:
| tuple with target shape
:add_axis:
| 1, optional
| Determines where in x.shape an axis should be added
:equal_shape:
| False or True, optional
| True: expand :x: to identical dimensions (speficied by :tshape:)
Returns:
:returns:
| ndarray broadcast-compatable with tshape.
"""
if x is None:
return np.broadcast_arrays(x, np.ones(tshape))[0]
else:
x = np2d(x)
sx = x.shape
lsx = len(sx)
ltshape = len(tshape)
if (sx == tshape):
pass
else:
if ((lsx == 1) | (sx == (1, tshape[-1])) |
(sx == (tshape[-1], 1))):
if (sx == (tshape[-1], 1)):
x = x.T
if lsx != ltshape:
x = np.expand_dims(x, 0)
elif (lsx == 2):
if (ltshape == 3):
sd = np.setdiff1d(tshape, sx, assume_unique=True)
if len(sd) == 0:
ax = add_axis
else:
ax = np.where(tshape == sd)[0][0]
x = np.expand_dims(x, ax)
else:
raise Exception(
"todim(x,tshape): dimensions do not match for 2d arrays."
)
else:
raise Exception(
"todim(x,tshape): no matching dimensions between 3d x and tshape."
)
if equal_shape == False:
return x
else:
return np.ones(
tshape) * x #make dims of x equal to those of a (tshape)
def broadcast_shape(data,target_shape = None, expand_2d_to_3d = None, axis0_repeats = None, axis1_repeats = None):
"""
Broadcasts shapes of data to a target_shape.
| Useful for block/vector calc. when numpy fails to broadcast correctly.
Args:
:data:
| ndarray
:target_shape:
| None or tuple with requested shape, optional
| - None: returns unchanged :data:
:expand_2d_to_3d:
| None (do nothing) or ..., optional
| If ndim == 2, expand from 2 to 3 dimensions
:axis0_repeats:
| None or number of times to repeat axis=0, optional
| - None: keep axis=0 same size
:axis1_repeats:
| None or number of times to repeat axis=1, optional
| - None: keep axis=1 same size
Returns:
:returns:
| reshaped ndarray
"""
data = np2d(data)
# expand shape along axis (useful for some functions that allow block-calculations when the data is only 2d )
if (expand_2d_to_3d is not None) & (len(data.shape) == 2):
data = np.expand_dims(data, axis = expand_2d_to_3d)
if target_shape is not None:
dshape = data.shape
if dshape != target_shape:
axis_of_v3 = len(target_shape)-1
if (dshape[0] != target_shape[0]): # repeat along axis 0
if axis0_repeats is None:
axis0_repeats = (target_shape[0]-dshape[0] + 1)
data = np.repeat(data,axis0_repeats,axis = 0)
if (len(target_shape)>2) & (len(data.shape)==2): # repeat along axis 1, create axis if necessary
data = np.expand_dims(data,axis = axis_of_v3-1) # axis creation
dshape = data.shape
if (dshape[1] != target_shape[1]):
if axis1_repeats is None:
axis1_repeats = (target_shape[1]-dshape[1] + 1) # repititon
data = np.repeat(data,axis1_repeats,axis = 1)
for i in range(2):
if (data.shape[i] > 1) & (data.shape[i] != target_shape[i]):
raise Exception('broadcast_shape(): Cannot match dim of data with target: data.shape[i]>1 & ... != target.shape[i]')
return data
def np3d(data):
"""
Make a tuple, list or numpy array at least a 3d numpy array.
Args:
:data:
| tuple, list, ndarray
Returns:
:returns:
| ndarray with .ndim >= 3
"""
if isinstance(data, np.ndarray):# assume already atleast_3d when nd.array (user has to ensure input is an array)
if (len(data.shape)>=3):
return data
else:
return np.expand_dims(np.atleast_2d(data),axis=0)
else:
return np.expand_dims(np.atleast_2d(np.array(data)),axis=0)
def spd_to_mcri(SPD, D=0.9, E=None, Yb=20.0, out='Rm', wl=None):
"""
Calculates the MCRI or Memory Color Rendition Index, Rm
Args:
:SPD:
| ndarray with spectral data (can be multiple SPDs,
first axis are the wavelengths)
:D:
| 0.9, optional
| Degree of adaptation.
:E:
| None, optional
| Illuminance in lux
| (used to calculate La = (Yb/100)*(E/pi) to then calculate D
| following the 'cat02' model).
| If None: the degree is determined by :D:
| If (:E: is not None) & (:Yb: is None): :E: is assumed to contain
the adapting field luminance La (cd/m²).
:Yb:
| 20.0, optional
| Luminance factor of background. (used when calculating La from E)
| If None, E contains La (cd/m²).
:out:
| 'Rm' or str, optional
| Specifies requested output (e.g. 'Rm,Rmi,cct,duv')
:wl:
| None, optional
| Wavelengths (or [start, end, spacing]) to interpolate the SPDs to.
| None: default to no interpolation
Returns:
:returns:
| float or ndarray with MCRI Rm for :out: 'Rm'
| Other output is also possible by changing the :out: str value.
References:
1. `K.A.G. Smet, W.R. Ryckaert, M.R. Pointer, G. Deconinck, P. Hanselaer,(2012)
“A memory colour quality metric for white light sources,”
Energy Build., vol. 49, no. C, pp. 216–225.
<http://www.sciencedirect.com/science/article/pii/S0378778812000837>`_
"""
SPD = np2d(SPD)
if wl is not None:
SPD = spd(data=SPD, interpolation=_S_INTERP_TYPE, kind='np', wl=wl)
# unpack metric default values:
avg, catf, cieobs, cri_specific_pars, cspace, ref_type, rg_pars, sampleset, scale = [
_MCRI_DEFAULTS[x] for x in sorted(_MCRI_DEFAULTS.keys())
]
similarity_ai = cri_specific_pars['similarity_ai']
Mxyz2lms = cspace['Mxyz2lms']
scale_fcn = scale['fcn']
scale_factor = scale['cfactor']
sampleset = eval(sampleset)
# A. calculate xyz:
xyzti, xyztw = spd_to_xyz(SPD, cieobs=cieobs['xyz'], rfl=sampleset, out=2)
if 'cct' in out.split(','):
cct, duv = xyz_to_cct(xyztw,
cieobs=cieobs['cct'],
out='cct,duv',
mode='lut')
# B. perform chromatic adaptation to adopted whitepoint of ipt color space, i.e. D65:
if catf is not None:
Dtype_cat, F, Yb_cat, catmode_cat, cattype_cat, mcat_cat, xyzw_cat = [
catf[x] for x in sorted(catf.keys())
]
# calculate degree of adaptationn D:
if E is not None:
if Yb is not None:
La = (Yb / 100.0) * (E / np.pi)
else:
La = E
D = cat.get_degree_of_adaptation(Dtype=Dtype_cat, F=F, La=La)
else:
Dtype_cat = None # direct input of D
if (E is None) and (D is None):
D = 1.0 # set degree of adaptation to 1 !
if D > 1.0: D = 1.0
if D < 0.6: D = 0.6 # put a limit on the lowest D
# apply cat:
xyzti = cat.apply(xyzti,
cattype=cattype_cat,
catmode=catmode_cat,
xyzw1=xyztw,
xyzw0=None,
xyzw2=xyzw_cat,
D=D,
mcat=[mcat_cat],
Dtype=Dtype_cat)
xyztw = cat.apply(xyztw,
cattype=cattype_cat,
catmode=catmode_cat,
xyzw1=xyztw,
xyzw0=None,
xyzw2=xyzw_cat,
D=D,
mcat=[mcat_cat],
Dtype=Dtype_cat)
# C. convert xyz to ipt and split:
ipt = xyz_to_ipt(
xyzti, cieobs=cieobs['xyz'], M=Mxyz2lms
) #input matrix as published in Smet et al. 2012, Energy and Buildings
I, P, T = asplit(ipt)
# D. calculate specific (hue dependent) similarity indicators, Si:
if len(xyzti.shape) == 3:
ai = np.expand_dims(similarity_ai, axis=1)
else:
ai = similarity_ai
a1, a2, a3, a4, a5 = asplit(ai)
mahalanobis_d2 = (a3 * np.power((P - a1), 2.0) + a4 * np.power(
(T - a2), 2.0) + 2.0 * a5 * (P - a1) * (T - a2))
if (len(mahalanobis_d2.shape) == 3) & (mahalanobis_d2.shape[-1] == 1):
mahalanobis_d2 = mahalanobis_d2[:, :, 0].T
Si = np.exp(-0.5 * mahalanobis_d2)
# E. calculate general similarity indicator, Sa:
Sa = avg(Si, axis=0, keepdims=True)
# F. rescale similarity indicators (Si, Sa) with a 0-1 scale to memory color rendition indices (Rmi, Rm) with a 0 - 100 scale:
Rmi = scale_fcn(np.log(Si), scale_factor=scale_factor)
Rm = np2d(scale_fcn(np.log(Sa), scale_factor=scale_factor))
# G. calculate Rg (polyarea of test / polyarea of memory colours):
if 'Rg' in out.split(','):
I = I[
...,
None] #broadcast_shape(I, target_shape = None,expand_2d_to_3d = 0)
a1 = a1[:, None] * np.ones(
I.shape
) #broadcast_shape(a1, target_shape = None,expand_2d_to_3d = 0)
a2 = a2[:, None] * np.ones(
I.shape
) #broadcast_shape(a2, target_shape = None,expand_2d_to_3d = 0)
a12 = np.concatenate(
(a1, a2), axis=2
) #broadcast_shape(np.hstack((a1,a2)), target_shape = ipt.shape,expand_2d_to_3d = 0)
ipt_mc = np.concatenate((I, a12), axis=2)
nhbins, normalize_gamut, normalized_chroma_ref, start_hue = [
rg_pars[x] for x in sorted(rg_pars.keys())
]
Rg = jab_to_rg(ipt,
ipt_mc,
ordered_and_sliced=False,
nhbins=nhbins,
start_hue=start_hue,
normalize_gamut=normalize_gamut)
if (out != 'Rm'):
return eval(out)
else:
return Rm
def cam18sl(data, datab = None, Lb = [100], 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 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,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._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)
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, k, naka, unique_hue_data = [parameters[x] for x in sorted(parameters.keys())]
# precomputations:
Mlms2xyz = np.linalg.inv(_CMF['2006_10']['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 = '2006_10', 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 = '2006_10', 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 = '2006_10', relative = False)
datar = datab.copy()
# 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':
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.nan*np.ones(dshape)
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 = '2006_10', relative = False)
xyzr = spd_to_xyz(np.vstack((datar[0], datar[i+1:i+2,:])), cieobs = '2006_10', relative = False)
else:
xyzb = datab[i:i+1,:]
xyzr = datar[i:i+1,:]
lmsb = np.dot(_CMF['2006_10']['M'],xyzb.T).T # convert to l,m,s
rgbb = (lmsb / _CMF['2006_10']['K']) * k # convert to rho, gamma, beta
#lmsr = np.dot(_CMF['2006_10']['M'],xyzr.T).T # convert to l,m,s
#rgbr = (lmsr / _CMF['2006_10']['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 = '2006_10', relative = False)
elif (inputtype == 'xyz'):
xyz = data[i]
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
# 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
# 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','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 = (((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['2006_10']['K']
xyz = np.dot(Mlms2xyz,lms.T).T
camout[i] = xyz
if camout.shape[0] == 1:
camout = np.squeeze(camout,axis = 0)
return camout
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.nan * np.ones(dshape)
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 hue_quadrature(h, unique_hue_data=None):
"""
Get hue quadrature H from hue h.
Args:
:h:
| float or ndarray [(N,) or (N,1)] with hue data in degrees (!).
:unique_hue data:
| None or dict, optional
| - None: defaults to:
| {'hues': 'red yellow green blue red'.split(),
| 'i': np.arange(5.0),
| 'hi':[20.14, 90.0, 164.25,237.53,380.14],
| 'ei':[0.8,0.7,1.0,1.2,0.8],
| 'Hi':[0.0,100.0,200.0,300.0,400.0]}
| - dict: user specified unique hue data
| (same structure as above)
Returns:
:H:
| ndarray of Hue quadrature value(s).
"""
if unique_hue_data is None:
unique_hue_data = {
'hues': 'red yellow green blue red'.split(),
'i': np.arange(5.0),
'hi': [20.14, 90.0, 164.25, 237.53, 380.14],
'ei': [0.8, 0.7, 1.0, 1.2, 0.8],
'Hi': [0.0, 100.0, 200.0, 300.0, 400.0]
}
changed_number_to_array = False
if isinstance(h, float) | isinstance(h, int):
h = np.atleast_1d(h)
changed_number_to_array = True
squeezed = False
if h.ndim > 1:
if (h.shape[0] == 1):
h = np.squeeze(h, axis=0)
squeezed = True
hi = unique_hue_data['hi']
Hi = unique_hue_data['Hi']
ei = unique_hue_data['ei']
h[h < hi[0]] += 360.0
h_tmp = np.atleast_2d(h)
if h_tmp.shape[0] == 1:
h_tmp = h_tmp.T
h_hi = np.repeat(h_tmp, repeats=len(hi), axis=1)
hi_h = np.repeat(np.atleast_2d(hi), repeats=h.shape[0], axis=0)
d = (h_hi - hi_h)
d[d < 0] = 1000.0
p = d.argmin(axis=1)
p[p == (len(hi) - 1)] = 0 # make sure last unique hue data is not selected
H = np.array([
Hi[pi] + (100.0 * (h[i] - hi[pi]) / ei[pi]) /
((h[i] - hi[pi]) / ei[pi] + (hi[pi + 1] - h[i]) / ei[pi + 1])
for (i, pi) in enumerate(p)
])
if changed_number_to_array:
H = H[0]
if squeezed:
H = np.expand_dims(H, axis=0)
return H
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.nan*np.ones(dshape)
# 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