raytraverse.sampler¶
draw¶
wavelet and associated probability functions.
- raytraverse.sampler.draw.get_detail(data, *args, mode='reflect', cval=0.0)[source]¶
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)[source]¶
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 max>, features=1, weightfunc=<function max>, t0=0.00390625, t1=0.0625)[source]¶
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:
- 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
- run(mapper, name, levels, plotp=False, log='err', pfish=True, **kwargs)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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¶
ISamplerArea¶
- class raytraverse.sampler.ISamplerArea(scene, engine, accuracy=1.0, nlev=3, jitter=True, edgemode='constant', t0=0.1, t1=0.9, **kwargs)[source]¶
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)[source]¶
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)[source]¶
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:
ISamplerSuns¶
- class raytraverse.sampler.ISamplerSuns(scene, engine, accuracy=1.0, nlev=3, jitter=True, areakwargs=None, t0=0.05, t1=0.125)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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
- get_existing_run(skymapper, areamapper)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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
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)[source]¶
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¶
- run(mapper, specguide=None, plotp=False, **kwargs)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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
SamplerPt¶
- class raytraverse.sampler.SamplerPt(scene, engine, idres=32, nlev=5, accuracy=1.0, srcn=1, stype='generic', features=1, samplerlevel=0, **kwargs)[source]¶
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
- run(point, posidx, mapper=None, lpargs=None, **kwargs)[source]¶
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:
SkySamplerPt¶
- class raytraverse.sampler.SkySamplerPt(scene, engine, **kwargs)[source]¶
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)[source]¶
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)[source]¶
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:
SunSamplerPtView¶
- class raytraverse.sampler.SunSamplerPtView(scene, engine, sun, sunbin, **kwargs)[source]¶
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)[source]¶
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:
ImageSampler¶
- class raytraverse.sampler.ImageSampler(scene, vm=None, scalefac=None, method='linear', color=False, uv=False, **kwargs)[source]¶
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, uv=False, **kwargs)[source]¶
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)[source]¶
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: