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=32, nlev=5, 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 sqrt of samples per hemisphere)

• nlev (int, optional) – number of levels to sample (eeach lvl doubles idres)

• 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 sqrt of samples per hemisphere (or view angle)

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, nlev=6, 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

sunpos = None

sun position x,y,z

Type

np.array

run(point, posidx, 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

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