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, minsamp=0)

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, featurefunc=<function amax>, features=1, weightfunc=<function amax>, t0=0.00390625, t1=0.0625)

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)

• featurefunc (func, optional) – takes detail array as an argument, shape: (features,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.

• features (int, optional) – number of values evaluated for detail

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

scene information

Type

raytraverse.scene.Scene

t0

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

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

accuracy

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

sampler type

Type

str

weights

holds weights for self.draw

Type

np.array

featurefunc

func takes weights and axis=0 argument to reduce detail

weightfunc

func takes weights and axis=1 argument to reduce output from engine when engine produces more features than sampler needs

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

Sensor

class raytraverse.sampler.Sensor(engine, dirs=(0.0, 0.0, 1.0), offsets=(0.0, 0.0, 0.0), name='sensor', sunview=False)

Bases: object

for use as engine in area sampler, holds collection of multiple sensor directions and offsets

Parameters

• engine (craytraverse.renderer.Rennderer) – fully initialized renderer class instance

• dirs (Sequence, optional) – array like shape (N, 3) sensor directions

• offsets (Sequence, optional) – array like shape (N, 3) offsets from sample position to include (for example mulitple z-heights)

• sunview (bool, optional) – NOT IMPLEMENTED if True, dirs are treated as candidate reflection normals, a value of (0, 0, 0) is prepended to hold the direct view.

property nproc

run(*args, **kwargs)

alias for call, for consistency with SamplerPt classes for nested dimensions of evaluation

stack_rays(r)

ISamplerArea

class raytraverse.sampler.ISamplerArea(scene, engine, accuracy=1.0, nlev=3, jitter=True, edgemode='constant', t0=0.1, t1=0.9, **kwargs)

Bases: SamplerArea

wavelet based area sampling class using Sensor as engine

Parameters

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

• engine (raytraverse.sampler.Sensor) – renderer

• 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’

srcn

number of sources return per vector by run

Type

int

run(mapper, plotp=False, **kwargs)

adapively sample an area defined by mapper

Parameters

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

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

• kwargs – passed to self.run()

Return type

raytraverse.lightplane.SensorPlaneKD

repeat(guide, stype)

repeat the sampling of a guide SensorPlane (to match all points)

Parameters

• guide (LightPlaneKD) –

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

Return type

raytraverse.lightfield.SensorPlaneKD

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

ISamplerSuns

class raytraverse.sampler.ISamplerSuns(scene, engine, accuracy=1.0, nlev=3, jitter=True, areakwargs=None, t0=0.05, t1=0.125)

Bases: SamplerSuns

wavelet based sun position sampling class

Parameters

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

• engine (raytraverse.sampler.Sensor) – with 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.

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, **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

• kwargs – passed to self.run()

Return type

raytraverse.lightlplane.LightPlaneKD

SamplerSuns

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

Bases: 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.

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 (Union[raytraverse.lightfield.LightPlaneKD, Bool]) – 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()

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

idxvecs()

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'), t0=0.1, t1=0.9, **kwargs)

Bases: 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)

ub = 100

upper bound for drawing from pdf

metricclass

raytraverse.evaluate.BaseMetricSet

metricset

iterable

features

int:

property edgemode

sampling_scheme(mapper)

calculate sampling scheme

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

adapively sample an area defined by mapper

Parameters

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

• specguide (Union[None, bool, str]) –

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

• kwargs – passed to self.run()

Return type

raytraverse.lightlplane.LightPlaneKD

repeat(guide, stype)

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

Parameters

• guide (LightPlaneKD) –

• stype (str) – 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

idxvecs()

SamplerPt

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

Bases: 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)

• features (int, optional) – number of values evaluated for detail

• 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()

srcn

number of sources return per vector by run

Type

int

idres

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, position 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()

Return type

LightPointKD

repeat(guide, stype)

SkySamplerPt

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

Bases: 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

SunSamplerPt

class raytraverse.sampler.SunSamplerPt(scene, engine, sun, sunbin, nlev=6, stype='sun', **kwargs)

Bases: 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

sun position x,y,z

Type

np.array

run(point, posidx, specguide=None, **kwargs)

sample a single point, position 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()

Return type

LightPointKD

SunSamplerPtView

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

Bases: 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, position 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()

Return type

LightPointKD

ImageSampler

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

Bases: 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', color=False, **kwargs)

Bases: ImageSampler

ub = 1

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

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

sample a single point, position 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()

Return type

LightPointKD