raytraverse.evaluate¶
BaseMetricSet¶
-
class
raytraverse.evaluate.
BaseMetricSet
(vec, omega, lum, vm, metricset=None, scale=179.0, omega_as_view_area=True, guth=True, warnings=False, **kwargs)[source]¶ Bases:
object
object for calculating metrics based on a view direction, and rays consisting on direction, solid angle and luminance information
by encapsulating these calculations within a class, metrics with redundant calculations can take advantage of cached results, for example dgp does not need to recalculate illuminance when it has been directly requested. all metrics can be accessed as properties (and are calculated just in time) or the object can be called (no arguments) to return a np.array of all metrics defined in “metricset”
- Parameters
vm (raytraverse.mapper.ViewMapper) – the view direction
vec (np.array) – (N, 3) directions of all rays in view
omega (np.array) – (N,) solid angle of all rays in view
lum (np.array) – (N,) luminance of all rays in view (multiplied by “scale”)
metricset (list, optional) – keys of metrics to return, same as property names
scale (float, optional) – scalefactor for luminance
omega_as_view_area (bool, optional) – take sum(omega) as view area. if false corrects omega to vm.area
warnings (bool, optional) – if False, suppresses numpy warnings (zero div, etc…) when accessed via __call__
kwargs – additional arguments that may be required by additional properties
-
allmetrics
= ['illum', 'avglum', 'loggcr', 'gcr', 'pwgcr', 'logpwgcr', 'density', 'avgraylum', 'pwavglum', 'maxlum']¶
-
safe2sum
= {'avglum', 'density', 'illum'}¶
-
defaultmetrics
= ['illum', 'avglum', 'loggcr']¶ available metrics (and the default return set)
-
classmethod
check_metrics
(metrics, raise_error=False)[source]¶ returns list of valid metric names from argument if raise_error is True, raises an Atrribute Error
-
classmethod
check_safe2sum
(metrics)[source]¶ checks if list if metrics is safe to compute for seperate sources before adding
-
property
vec
¶
-
property
lum
¶
-
property
omega
¶
-
property
ctheta
¶ cos angle between ray and view
-
property
radians
¶ angle between ray and view
-
property
pos_idx
¶
-
property
pweight
¶
-
property
pweighted_area
¶
-
property
illum
¶ illuminance
-
property
avglum
¶ average luminance
-
property
maxlum
¶ average luminance
-
property
pwavglum
¶ position weighted average luminance
-
property
avgraylum
¶ average luminance (not weighted by omega
-
property
gcr
¶ a unitless measure of relative contrast defined as the average of the squared luminances divided by the average luminance squared
-
property
pwgcr
¶ a unitless measure of relative contrast defined as the average of the squared luminances divided by the average luminance squared weighted by a position index
-
property
logpwgcr
¶ a unitless measure of relative contrast defined as the log of gcr
-
property
loggcr
¶ a unitless measure of relative contrast defined as the log of gcr
-
property
density
¶
MultiLumMetricSet¶
-
class
raytraverse.evaluate.
MultiLumMetricSet
(vec, omega, lum, vm, metricset=None, scale=179.0, omega_as_view_area=True, **kwargs)[source]¶ Bases:
raytraverse.evaluate.basemetricset.BaseMetricSet
object for calculating metrics based on a view direction, and rays consisting on direction, solid angle and luminance information
by encapsulating these calculations within a class, metrics with redundant calculations can take advantage of cached results, for example dgp does not need to recalculate illuminance when it has been directly requested. all metrics can be accessed as properties (and are calculated just in time) or the object can be called (no arguments) to return a np.array of all metrics defined in “metricset”
- Parameters
vm (raytraverse.mapper.ViewMapper) – the view direction
vec (np.array) – (N, 3) directions of all rays in view
omega (np.array) – (N,) solid angle of all rays in view
lum (np.array) – (N, M) luminance of all rays in view (multiplied by “scale”)
metricset (list, optional) – keys of metrics to return, same as property names
scale (float, optional) – scalefactor for luminance
kwargs – additional arguments that may be required by additional properties
-
property
illum
¶ illuminance
-
property
avglum
¶ average luminance
-
property
avgraylum
¶ average luminance (not weighted by omega)
-
property
gcr
¶ a unitless measure of relative contrast defined as the average of the squared luminances divided by the average luminance squared
MetricSet¶
-
class
raytraverse.evaluate.
MetricSet
(vec, omega, lum, vm, metricset=None, scale=179.0, threshold=2000.0, guth=True, tradius=30.0, omega_as_view_area=False, lowlight=False, **kwargs)[source]¶ Bases:
raytraverse.evaluate.basemetricset.BaseMetricSet
object for calculating metrics based on a view direction, and rays consisting on direction, solid angle and luminance information
by encapsulating these calculations within a class, metrics with redundant calculations can take advantage of cached results, for example dgp does not need to recalculate illuminance when it has been directly requested. all metrics can be accessed as properties (and are calculated just in time) or the object can be called (no arguments) to return a np.array of all metrics defined in “metricset”
- Parameters
vm (raytraverse.mapper.ViewMapper) – the view direction
vec (np.array) – (N, 3) directions of all rays in view
omega (np.array) – (N,) solid angle of all rays in view
lum (np.array) – (N,) luminance of all rays in view (multiplied by “scale”)
metricset (list, optional) – keys of metrics to return, same as property names
scale (float, optional) – scalefactor for luminance
threshold (float, optional) – threshold for glaresource/background similar behavior to evalglare ‘-b’ paramenter. if greater than 100 used as a fixed luminance threshold. otherwise used as a factor times the task luminance (defined by ‘tradius’)
guth (bool, optional) – if True, use Guth for the upper field of view and iwata for the lower if False, use Kim
tradius (float, optional) – radius in degrees for task luminance calculation
kwargs – additional arguments that may be required by additional properties
-
defaultmetrics
= ['illum', 'avglum', 'loggcr', 'ugp', 'dgp']¶ available metrics (and the default return set)
-
allmetrics
= ['illum', 'avglum', 'loggcr', 'gcr', 'pwgcr', 'logpwgcr', 'density', 'avgraylum', 'pwavglum', 'maxlum', 'ugp', 'dgp', 'tasklum', 'backlum', 'dgp_t1', 'log_gc', 'dgp_t2', 'ugr', 'threshold', 'pwsl2', 'view_area', 'backlum_true', 'srcillum', 'srcarea', 'maxlum']¶
-
safe2sum
= {'avglum', 'density', 'illum', 'pwsl2', 'srcillum'}¶
-
property
src_mask
¶ boolean mask for filtering source/background rays
-
property
task_mask
¶
-
property
sources
¶ vec, omega, lum of rays above threshold
-
property
background
¶ vec, omega, lum of rays below threshold
-
property
source_pos_idx
¶
-
property
threshold
¶ threshold for glaresource/background similar behavior to evalglare ‘-b’ paramenter
-
property
pwsl2
¶ position weighted source luminance squared, used by dgp, ugr, etc sum(Ls^2*omega/Ps^2)
-
property
srcillum
¶ source illuminance
-
property
srcarea
¶ total source area
-
property
maxlum
¶ peak luminance
-
property
backlum
¶ average background luminance CIE estimate (official for some metrics)
-
property
backlum_true
¶ average background luminance mathematical
-
property
tasklum
¶ average task luminance
-
property
dgp
¶
-
property
dgp_t1
¶
-
property
log_gc
¶
-
property
dgp_t2
¶
-
property
ugr
¶
-
property
ugp
¶ //dx.doi.org/10.1016/j.buildenv.2016.08.005
- Type
http
FieldMetric¶
-
class
raytraverse.evaluate.
FieldMetric
(vec, omega, lum, vm=None, scale=1.0, npts=360, close=True, sigma=0.05, omega_as_view_area=True, **kwargs)[source]¶ Bases:
raytraverse.evaluate.basemetricset.BaseMetricSet
calculate metrics on full spherical point clouds rather than view based metrics.
- Parameters
vec (np.array) – (N, 3) directions of all rays
omega (np.array) – (N,) solid angle of all rays
lum (np.array) – (N,) luminance of all rays (multiplied by “scale”)
metricset (list, optional) – keys of metrics to return, same as property names
scale (float, optional) – scalefactor for luminance
npts (int, optional) – for equatorial metrics, the number of points to interpolate
close (bool, optional) – include npts+1 duplicate to draw closed curve
sigma (float, optional) – scale parameter of gaussian for kernel estimated metrics
omega_as_view_area (bool, optional) – set to true when vectors either represent a whole sphere or a subset that does not match the viewmapper. if False, corrects boundary omega to properly trim to correct size.
kwargs – additional arguments that may be required by additional properties
-
property
tp
¶ vectors in spherical coordinates
-
property
phi
¶ interpolated output phi values
-
property
eq_xyz
¶ interpolated output xyz vectors
-
property
avg
¶ overall vector (with magnitude)
-
property
peak
¶ overall vector (with magnitude)
-
property
eq_lum
¶ luminance along an interpolated equator with a bandwidth=sigma
-
property
eq_density
¶ ray density along an interpolated equator
-
property
eq_illum
¶ illuminiance along an interpolated equator
-
property
eq_gcr
¶ cosine weighted gcr along an interpolated equator
-
property
eq_loggc
¶
-
property
eq_dgp
¶
SamplingMetrics¶
-
class
raytraverse.evaluate.
SamplingMetrics
(vec, omega, lum, vm, scale=1.0, peakthreshold=0.0, lmin=0, gcrnorm=8, **kwargs)[source]¶ Bases:
raytraverse.evaluate.basemetricset.BaseMetricSet
default metricset for areasampler
-
defaultmetrics
= ['avglum', 'loggcr', 'xpeak', 'ypeak']¶ available metrics (and the default return set)
-
allmetrics
= ['avglum', 'loggcr', 'xpeak', 'ypeak']¶
-
property
peakvec
¶ average vector (with magnitude) for peak rays
-
property
xpeak
¶ x-component of avgvec as positive number (in range 0-1)
-
property
ypeak
¶ y-component of avgvec as positive number (in range 0-1)
-
property
loggcr
¶ log of global contrast ratio
-
PositionIndex¶
-
class
raytraverse.evaluate.
PositionIndex
(guth=True)[source]¶ Bases:
object
calculate position index according to guth/iwata or kim
- Parameters
guth (bool) – if True, use Guth for the upper field of view and iwata for the lower if False, use Kim
-
positions
(vm, vec)[source]¶ calculate position indices for a set of vectors
- Parameters
vm (raytraverse.mapper.ViewMapper) – the view/analysis point, should have 180 degree field of view
vec (np.array) – shape (N,3) the view vectors to calculate
- Returns
posidx – shape (N,) the position indices
- Return type
np.array
retina¶
-
raytraverse.evaluate.retina.
hpsf
(x, fwhm=0.183333)[source]¶ estimate of human eye point-spread function
from: Yang, Yr., Wanek, J. & Shahidi, M. Representing the retinal line spread shape with mathematical functions. J. Zhejiang Univ. Sci. B 9, 996–1002 (2008). https://doi.org/10.1631/jzus.B0820184
-
raytraverse.evaluate.retina.
blur_sun
(omega, lmax, lmin=279.33, fwhm=0.183333)[source]¶ calculate source correction to small bright source
returned value should be multiplied by omega and divides luminance
- Parameters
omega (Union[float, np.array]) – solid angle in steradians of source
lmax (Union[float, np.array]) – maximum radiance in source (cd/m^2)/179
lmin (Union[float, np.array], optional) – minimum radiance value to gather after spread (mimic peak extraction of evalglare, but note the different units (cd/m^2)/179
fwhm (Union[float, np.array], optional) – full width half max of Lorentzian curve (radius in degrees) default is 11 arcmin.
- Returns
correction factor – value should be multiplied by omega and divides luminance
- Return type
Union[float, np.array]
-
raytraverse.evaluate.retina.
rgcf_density_on_meridian
(deg, mi)[source]¶ retinal ganlgion cell field density along a meridian as a functional best fit.
the field density accounts for the input region of the ganglion cell to account for displaced ganglion cells. This value is estimate from cone density and the inferred density of midget ganglion cells. see Watson (2014) for important caveats.
- Parameters
deg (np.array) – eccentricity in degrees along merdian
mi (int) – meridian index. [0, 1, 2, 3] for Temporal, Superior, Nasal, Inferior.
- Returns
1d array of retinal ganglion cell density along a merdian
- Return type
np.array
-
raytraverse.evaluate.retina.
rgc_density_on_meridian
(deg, mi)[source]¶ retinal ganglion cell density along a merdian as a linear interpolation between non-zero measurements
As opposed to the field density this estimate the actual location of ganglion cells, which could be important to consider for intrinsically photosensitive cells. These are (partially?) responsible for pupillary response. However, even iprgc (may?) receive signals from rods/cones
- Parameters
deg (np.array) – eccentricity in degrees along merdian
mi (int) – meridian index. [0, 1, 2, 3] for Temporal, Superior, Nasal, Inferior.
- Returns
1d array of retinal ganglion cell density along a merdian
- Return type
np.array
-
raytraverse.evaluate.retina.
rgcf_density_xy
(xy, func=<function rgcf_density_on_meridian>)[source]¶ interpolate density between meridia, selected by quadrant
- Parameters
xy (np.array) – xy visual field coordinates on a disk in degrees (eccentricity 0-90 from fovea)
func (callable) – density function along a meridian, takes r in degrees and an axes index: [0, 1, 2, 3] for Temporal, Superior, Nasal, Inferior.
- Returns
1d array of single eye densities
- Return type
np.array
-
raytraverse.evaluate.retina.
binocular_density
(xy, func=<function rgcf_density_on_meridian>)[source]¶ average denisty between both eyes.
- Parameters
xy (np.array) – xy visual field coordinates on a disk (eccentricity 0-1 from fovea)
func (callable) – density function along a meridian, takes r in degrees and an axes index: [0, 1, 2, 3] for Temporal, Superior, Nasal, Inferior. coordinates are for the visual field.
- Returns
1d array of average binocular densities
- Return type
np.array
-
raytraverse.evaluate.retina.
rgcf_density
(xy)[source]¶ retinal ganglion cell field density
- Parameters
xy (np.array) – xy visual field coordinates on a disk (eccentricity 0-1 from fovea)
- Returns
1d array retinal ganglion cell field density according to model by Watson
- Return type
np.array
-
raytraverse.evaluate.retina.
rgc_density
(xy)[source]¶ retinal ganglion cell density (includes displaced ganglion cells)
- Parameters
xy (np.array) – xy visual field coordinates on a disk (eccentricity 0-1 from fovea)
- Returns
1d array retinal ganglion cell density according to measurements by Curcio
- Return type
np.array