raytraverse.sampler

draw

wavelet and associated probability functions.

raytraverse.sampler.draw.get_detail(data, *args, mode='reflect', cval=0.0)

convolve a set of kernels with data. computes the sum of the absolute values of each convolution.

Parameters

• data (np.array) – source data (atleast 2D), detail calculated over last 2D

• args (np.array) – filters

• mode (str) – signal extension mode (passed to scipy.ndimage.convolve)

• cval (float) – constant value (passed to scipy.ndimage.convolve, used when mode=’constant’)

Returns

detail_array – 1d array of detail coefficients (row major order) matching size of data

Return type

np.array

raytraverse.sampler.draw.from_pdf(pdf, threshold, lb=0.5, ub=4)

generate choices from a numeric probability distribution

Parameters

• pdf (np.array) – 1-d array of weights

• threshold (float) – the threshold used to determine the number of choices to draw given by pdf > threshold

• lb (float, optional) – values below threshold * lb will be excluded from candidates (lb must be in (0,1)

• ub (float, optional) – the maximum weight is set to ub*threshold, meaning all values in pdf >= to ub*threshold have an equal chance of being selected. in cases where extreme values are much higher than moderate values, but 100% sampling of extreme areas should be avoided, this value should be lower, such as when a region is sampled at a very high resolution ( as is the case with directional sampling). On the other hand, set this value higher for sampling schemes with a low final resolution (like area sampling). If ub <= 1, then a deterministic choice is made, returning the idx of all values in pdf > threshold.

Returns

idx – an index array of choices, size varies.

Return type

np.array

BaseSampler

class raytraverse.sampler.BaseSampler(scene, engine, accuracy=1.0, stype='generic', samplerlevel=0)

Bases: object

wavelet based sampling class this is a virutal class that holds the shared sampling methods across directional, area, and sunposition samplers. subclasses are named as: {Source}Sampler{SamplingRange}, for instance:

• SamplerPt: virtual base class for sampling directions from a point

  • SkySamplerPt: sampling directions from a point with a sky patch source.

  • SunSamplerPt: sampling directions from a point with a single sun source

  • SunSamplerPtView: sampling the view from a point of the sun

  • ImageSampler: (re)sampling a fisheye image, useful for testing

• SamplerArea: sampling points on a horizontal planar area with any source type

• SamplerSuns: sampling sun positions (with nested area sampler)

Parameters

• scene (raytraverse.scene.Scene) – scene class containing geometry and formatter compatible with engine

• engine – has a run() method

• accuracy (float, optional) – parameter to set threshold at sampling level relative to final level threshold (smaller number will increase sampling, default is 1.0)

• stype (str, optional) – sampler type (prefixes output files)

t0 = 0.00390625

initial sampling threshold coefficient this value times the accuracy parameter is passed to raytraverse.sampler.draw.from_pdf() at level 0 (usually not used)

t1 = 0.0625

final sampling threshold coefficient this value times the accuracy parameter is passed to raytraverse.sampler.draw.from_pdf() at final level, intermediate sampling levels are thresholded by a linearly interpolated between t0 and t1

lb = 0.25

lower bound for drawing from pdf passed to raytraverse.sampler.draw.from_pdf()

ub = 8

upper bound for drawing from pdf passed to raytraverse.sampler.draw.from_pdf()

scene = None

scene information

Type

raytraverse.scene.Scene

accuracy = None

accuracy parameter some subclassed samplers may apply a scale factor to normalize threshold values depending on source brightness (see for instance ImageSampler and SunSamplerPt)

Type

float

stype = None

sampler type

Type

str

weights = None

holds weights for self.draw

Type

np.array

property levels

sampling scheme

Getter

Returns the sampling scheme

Setter

Set the sampling scheme

Type

np.array

sampling_scheme(*args)

calculate sampling scheme

run(mapper, name, levels, plotp=False, log='err', pfish=True, **kwargs)

trigger a sampling run. subclasses should return a LightPoint/LightField from the executed object state (first call this method with super().run(…)

Parameters

• mapper (raytraverse.mapper.Mapper) – mapper to sample

• name (str) – output name

• levels (np.array) – the sampling scheme

• plotp (bool, optional) – plot weights, detail and vectors for each level

• log (str, optional) – whether to log level sampling rates can be ‘scene’, ‘err’ or None ‘scene’ - logs to Scene log file ‘err’ - logs to stderr anything else - does not log incremental progress

• pfish (bool, optional) – if True and plotp, use fisheye projection for detail/weight/vector images.

• kwargs – unused

draw(level)

draw samples based on detail calculated from weights

Returns

• pdraws (np.array) – index array of flattened samples chosen to sample at next level

• p (np.array) – computed probabilities

sample_to_uv(pdraws, shape)

generate samples vectors from flat draw indices

Parameters

• pdraws (np.array) – flat index positions of samples to generate

• shape (tuple) – shape of level samples

Returns

• si (np.array) – index array of draws matching samps.shape

• vecs (np.array) – sample vectors

sample(vecs)

call rendering engine to sample rays

Parameters

vecs (np.array) – sample vectors (subclasses can choose which to use)

Returns

lum – array of shape (N,) to update weights

Return type

np.array

detailfunc = 'wav'

filter banks for calculating detail choices:

‘haar’: [[1 -1]]/2, [[1] [-1]]/2, [[1, 0] [0, -1]]/2

‘wav’: [[-1 2 -1]] / 2, [[-1] [2] [-1]] / 2, [[-1 0 0] [0 2 0] [0 0 -1]] / 2

SamplerSuns

class raytraverse.sampler.SamplerSuns(scene, engine, accuracy=1.0, nlev=3, jitter=True, ptkwargs=None, areakwargs=None, metricset='avglum', 'loggcr')

Bases: raytraverse.sampler.basesampler.BaseSampler

wavelet based sun position sampling class

Parameters

• scene (raytraverse.scene.Scene) – scene class containing geometry and formatter compatible with engine

• engine (raytraverse.renderer.Rtrace) – initialized renderer instance (with scene loaded, no sources)

• accuracy (float, optional) – parameter to set threshold at sampling level relative to final level threshold (smaller number will increase sampling, default is 1.0)

• nlev (int, optional) – number of levels to sample

• jitter (bool, optional) – jitter samples

• ptkwargs (dict, optional) – kwargs for raytraveerse.sampler.SunSamplerPt initialization

• areakwargs (dict, optional) – kwargs for raytravrse.sampler.SamplerArea initialization

• metricset (iterable, optional) – subset of samplerarea.metric set to use for sun detail calculation.

t0 = 0.05

initial sampling threshold coefficient

t1 = 0.125

final sampling threshold coefficient

ub = 8

upper bound for drawing from pdf

sampling_scheme(mapper)

calculate sampling scheme

get_existing_run(skymapper, areamapper)

check for file conflicts before running/overwriting parameters match call to run

Parameters

• skymapper (raytraverse.mapper.SkyMapper) – the mapping for drawing suns

• areamapper (raytraverse.mapper.PlanMapper) – the mapping for drawing points

Returns

conflicts –

a tuple of found conflicts (None for each if no conflicts:

• suns: np.array of sun positions in vfile

• ptfiles: existing point files

Return type

tuple

run(skymapper, areamapper, specguide=None, recover=True, **kwargs)

adaptively sample sun positions for an area (also adaptively sampled)

Parameters

• skymapper (raytraverse.mapper.SkyMapper) – the mapping for drawing suns

• areamapper (raytraverse.mapper.PlanMapper) – the mapping for drawing points

• specguide (raytraverse.lightfield.LightPlaneKD) – sky source lightfield to use as specular guide for sampling

• recover (continue run on top of existing files, if false, overwrites) – previous run.

• kwargs – passed to self.run()

Returns

Return type

raytraverse.lightlplane.LightPlaneKD

draw(level)

draw on condition of in_solarbounds from skymapper. In this way all solar positions are presented to the area sampler, but the area sampler is initialized with a weighting to sample only where there is variance between sun position. this keeps the subsampling of area and solar position independent.

Returns

• pdraws (np.array) – index array of flattened samples chosen to sample at next level

• p (np.array) – computed probabilities

sample_to_uv(pdraws, shape)

generate samples vectors from flat draw indices

Parameters

• pdraws (np.array) – flat index positions of samples to generate

• shape (tuple) – shape of level samples

Returns

• si (np.array) – index array of draws matching samps.shape

• vecs (np.array) – sample vectors

sample(vecs)

call rendering engine to sample rays

Parameters

vecs (np.array) – sample vectors

Returns

lum – array of shape (N,) to update weights

Return type

np.array

SamplerArea

class raytraverse.sampler.SamplerArea(scene, engine, accuracy=1.0, nlev=3, jitter=True, edgemode='constant', metricclass=<class 'raytraverse.evaluate.samplingmetrics.SamplingMetrics'>, metricset=('avglum', 'loggcr', 'xpeak', 'ypeak'), metricfunc=<function amax>, **kwargs)

Bases: raytraverse.sampler.basesampler.BaseSampler

wavelet based area sampling class

Parameters

• scene (raytraverse.scene.Scene) – scene class containing geometry and formatter compatible with engine

• engine (raytraverse.sampler.SamplerPt) – point sampler

• accuracy (float, optional) – parameter to set threshold at sampling level relative to final level threshold (smaller number will increase sampling, default is 1.0)

• nlev (int, optional) – number of levels to sample

• jitter (bool, optional) – jitter samples

• edgemode ({‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’}, optional) – default: ‘constant’, if ‘constant’ value is set to -self.t1, so edge is always seen as detail. Internal edges (resulting from PlanMapper borders) will behave like ‘nearest’ for all options except ‘constant’

• metricclass (raytraverse.evaluate.BaseMetricSet, optional) – the metric calculator used to compute weights

• metricset (iterable, optional) – list of metrics (must be recognized by metricclass. metrics containing “lum” will be normalized to 0-1)

• metricfunc (func, optional) – takes detail array as an argument, shape: (len(metricset),N, M) and an axis=0 keyword argument, returns shape (N, M). could be np.max, np.sum np.average or us custom function following the same pattern.

t0 = 0.1

initial sampling threshold coefficient

t1 = 0.9

final sampling threshold coefficient

ub = 100

upper bound for drawing from pdf

metricclass = None

raytraverse.evaluate.BaseMetricSet

metricset = None

iterable

features = None

int:

sampling_scheme(mapper)

calculate sampling scheme

run(mapper, name=None, specguide=None, plotp=False, find_reflections=False, **kwargs)

adapively sample an area defined by mapper

Parameters

• mapper (raytraverse.mapper.PlanMapper) – the pointset to build/run

• name (str, optional) –

• specguide (raytraverse.lightfield.LightPlaneKD) – sky source lightfield to use as specular guide for sampling (used by engine of type raytraverse.sampler.SunSamplerPt)

• plotp (bool, optional) – plot weights, detail and vectors for each level

• find_reflections (bool, optional) – write file for zone with potential reflection normals

• kwargs – passed to self.run()

Returns

Return type

raytraverse.lightlplane.LightPlaneKD

reflection_search(vecs, res=5)

repeat(guide, stype)

repeat the sampling of a guide LightPlane (to match all rays)

Parameters

• guide (LightPlaneKD) –

• stype (str, optional) – alternate stype name for samplerpt. raises a ValueError if it matches the guide.

draw(level)

draw samples based on detail calculated from weights

Returns

• pdraws (np.array) – index array of flattened samples chosen to sample at next level

• p (np.array) – computed probabilities

sample_to_uv(pdraws, shape)

generate samples vectors from flat draw indices

Parameters

• pdraws (np.array) – flat index positions of samples to generate

• shape (tuple) – shape of level samples

Returns

• si (np.array) – index array of draws matching samps.shape

• vecs (np.array) – sample vectors

sample(vecs)

call rendering engine to sample rays

Parameters

vecs (np.array) – sample vectors (subclasses can choose which to use)

Returns

lum – array of shape (N,) to update weights

Return type

np.array

SamplerPt

class raytraverse.sampler.SamplerPt(scene, engine, idres=5, fdres=9, accuracy=1.0, srcn=1, stype='generic', bands=1, samplerlevel=0, **kwargs)

Bases: raytraverse.sampler.basesampler.BaseSampler

wavelet based sampling class for direction rays from a point

Parameters

• scene (raytraverse.scene.Scene) – scene class containing geometry and formatter compatible with engine

• engine (raytraverse.renderer.Renderer) – should inherit from raytraverse.renderer.Renderer

• idres (int, optional) – initial direction resolution (as log2(res))

• fdres (int, optional) – final directional resolution given as log2(res)

• accuracy (float, optional) – parameter to set threshold at sampling level relative to final level threshold (smaller number will increase sampling, default is 1.0)

• srcn (int, optional) – number of sources return per vector by run

• stype (str, optional) – sampler type (prefixes output files)

• srcdef (str, optional) – path or string with source definition to add to scene

• plotp (bool, optional) – show probability distribution plots at each level (first point only)

• bands (int, optional) – number of spectral bands returned by the engine

• engine_args (str, optional) – command line arguments used to initialize engine

• nproc (int, optional) – number of processors to give to the engine, if None, uses os.cpu_count()

bands = None

number of spectral bands / channels returned by renderer based on given renderopts (user ensures these agree).

Type

int

srcn = None

number of sources return per vector by run

Type

int

idres = None

initial direction resolution (as log2(res))

Type

int

sampling_scheme(a)

calculate sampling scheme

run(point, posidx, mapper=None, lpargs=None, **kwargs)

sample a single point, poisition index handles file naming

Parameters

• point (np.array) – point to sample

• posidx (int) – position index

• mapper (raytraverse.mapper.ViewMapper) – view direction to sample

• lpargs (dict, optional) – keyword arguments forwarded to LightPointKD construction

• kwargs – passed to BaseSampler.run()

Returns

Return type

LightPointKD

repeat(guide, stype)

SkySamplerPt

class raytraverse.sampler.SkySamplerPt(scene, engine, **kwargs)

Bases: raytraverse.sampler.samplerpt.SamplerPt

sample contributions from the sky hemisphere according to a square grid transformed by shirley-chiu mapping using rcontrib.

Parameters

• scene (raytraverse.scene.Scene) – scene class containing geometry, location and analysis plane scene: str, optional (required if not reload) space separated list of radiance scene files (no sky) or octree

• engine (raytraverse.renderer.Rcontrib) – initialized rendering instance

sample(vecs)

call rendering engine to sample rays

Parameters

vecs (np.array) – sample vectors (subclasses can choose which to use)

Returns

lum – array of shape (N,) to update weights

Return type

np.array

SunSamplerPt

class raytraverse.sampler.SunSamplerPt(scene, engine, sun, sunbin, speclevel=9, fdres=10, slimit=0.01, maxspec=0.2, stype='sun', **kwargs)

Bases: raytraverse.sampler.samplerpt.SamplerPt

sample contributions from direct suns.

Parameters

• scene (raytraverse.scene.Scene) – scene class containing geometry, location and analysis plane

• engine (raytraverse.renderer.Rtrace) – initialized renderer instance (with scene loaded, no sources)

• sun (np.array) – shape 3, sun position

• sunbin (int) – sun bin

• speclevel (int, optional) – at this sampling level, pdf is made from brightness of sky sampling rather than progressive variance to look for fine scale specular highlights, this should be atleast 1 level from the end and the resolution of this level should be smaller than the size of the source

• slimit (float, optional) – the minimum value in the specular guide considered as a potential specular reflection source, in the case of low vlt glazing, this value should be reduced.

• maxspec (float, optional) – the maximum value inn the specular guide considered as a specular reflection source. above this value it is assumed that these are direct view rays to the source so are not sampled. in the case of low vlt glazing, this value should be reduced. In mixed (high-low) vlt scenes the specular guide will either over sample (including direct views) or under sample (miss specular reflections) depending on this setting.

specidx = None

index of level at which brightness sampling occurs

Type

int

sunpos = None

sun position x,y,z

Type

np.array

run(point, posidx, vm=None, plotp=False, specguide=None, **kwargs)

sample a single point, poisition index handles file naming

Parameters

• point (np.array) – point to sample

• posidx (int) – position index

• mapper (raytraverse.mapper.ViewMapper) – view direction to sample

• lpargs (dict, optional) – keyword arguments forwarded to LightPointKD construction

• kwargs – passed to BaseSampler.run()

Returns

Return type

LightPointKD

draw(level)

draw samples based on detail calculated from weights

Returns

pdraws – index array of flattened samples chosen to sample at next level

Return type

np.array

SunSamplerPtView

class raytraverse.sampler.SunSamplerPtView(scene, engine, sun, sunbin, **kwargs)

Bases: raytraverse.sampler.samplerpt.SamplerPt

sample view rays to a source.

Parameters

• scene (raytraverse.scene.Scene) – scene class containing geometry, location and analysis plane

• sun (np.array) – the direction to the source

• sunbin (int) – index for naming

ub = 1

deterministic sample draws

run(point, posidx, vm=None, plotp=False, log=None, **kwargs)

sample a single point, poisition index handles file naming

Parameters

• point (np.array) – point to sample

• posidx (int) – position index

• mapper (raytraverse.mapper.ViewMapper) – view direction to sample

• lpargs (dict, optional) – keyword arguments forwarded to LightPointKD construction

• kwargs – passed to BaseSampler.run()

Returns

Return type

LightPointKD

ImageSampler

class raytraverse.sampler.ImageSampler(scene, vm=None, scalefac=None, method='linear', **kwargs)

Bases: raytraverse.sampler.samplerpt.SamplerPt

sample image (for testing algorithms).

Parameters

• scene (raytraverse.scene.ImageScene) – scene class containing image file information

• scalefac (float, optional) – by default set to the average of non-zero pixels in the image used to establish sampling thresholds similar to contribution based samplers

DeterministicImageSampler

class raytraverse.sampler.DeterministicImageSampler(scene, vm=None, scalefac=None, method='linear', **kwargs)

Bases: raytraverse.sampler.imagesampler.ImageSampler

ub = 1

run(point, posidx, mapper=None, lpargs=None, **kwargs)

sample a single point, poisition index handles file naming

Parameters

• point (np.array) – point to sample

• posidx (int) – position index

• mapper (raytraverse.mapper.ViewMapper) – view direction to sample

• lpargs (dict, optional) – keyword arguments forwarded to LightPointKD construction

• kwargs – passed to BaseSampler.run()

Returns

Return type

LightPointKD