raytraverse.lightfield

LightField

class raytraverse.lightfield.LightField(scene, vecs, pm, src)

Bases: object

collection of light data with KDtree structure for spatial query

Parameters

• scene (raytraverse.scene.BaseScene) –

• vecs (np.array str) – the vectors used to organizing the child data as array or file shape (N,3) or (N,4) if 3, indexed from 0

• pm (raytraverse.mapper.PlanMapper) –

• src (str) – name of source group.

property samplelevel

the level at which the vec was sampled (all zero if not provided upon initialization

property vecs

indexing vectors (such as position, sun positions, etc.)

property data

light data

property kd

kdtree for spatial queries built on demand

property omega

solid angle or area

query(vecs)

return the index and distance of the nearest point to each of points

Parameters

vecs (np.array) – shape (N, 3) vectors to query.

Returns

• i (np.array) – integer indices of closest ray to each query

• d (np.array) – distance from query to point in spacemapper.

query_ball(pts, dist=1.0)

return set of vectors within a distance

Parameters

• pts (np.array) – shape (N, 3) vectors to query.

• dist (int float) – radius

Returns

i – if vecs is a single vector, a list of indices within radius. if vecs is a set of points an array of lists, one for each is returned.

Return type

list np.array

evaluate(*args, **kwargs)

LightPlaneKD

class raytraverse.lightfield.LightPlaneKD(scene, vecs, pm, src)

Bases: raytraverse.lightfield.lightfield.LightField

collection of lightpoints with KDtree structure for positional query

property data

LightPointSet

property omega

represeentative area of each point

Getter

Returns array of areas

Setter

sets areas

Type

np.array

evaluate(skyvec, points=None, vm=None, metricclass=<class 'raytraverse.evaluate.metricset.MetricSet'>, metrics=None, mask=True, **kwargs)

make_image(outf, vals, res=1024, interp=False, showsample=False)

make an image from precomputed values for every point in LightPlane

Parameters

• outf (str) – the file to write

• vals (np.array) – shape (len(self.points),) the values computed for each point

• res (int, optional) – image resolution (the largest dimension

• interp (bool, optional) – apply linear interpolation, points outside convex hull of results fall back to nearest

• showsample (bool, optionaal) – color pixel at sample location red

direct_view(res=512, showsample=True, vm=None, area=False, metricclass=<class 'raytraverse.evaluate.metricset.MetricSet'>, metrics=('avglum', ), interp=False)

create a summary image of lightplane showing samples and areas

add(lf2, src=None, calcomega=True, write=False, compress=False)

add light planes of distinct sources together

DayLightPlaneKD

class raytraverse.lightfield.DayLightPlaneKD(scene, vecs, pm, src, includesky=True)

Bases: raytraverse.lightfield.lightfield.LightField

collection of lightplanes with KDtree structure for sun position query

Parameters

• scene (raytraverse.scene.BaseScene) –

• vecs (np.array str) – suns as array or file shape (N,3), (N,4) or (N,5) if 3, indexed from 0

• pm (raytraverse.mapper.PlanMapper) –

• src (str) – name of sun sources group.

property samplelevel

the level at which the vec was sampled (all zero if not provided upon initialization

property vecs

indexing vectors (sx, sy, sz, px, py, pz)

property data

LightPlaneSet

property kd

kdtree for spatial queries built on demand

property skyplane

LightPlaneKD of sky results

query(vecs)

return the index and distance of the nearest vec to each of vecs

Parameters

vecs (np.array) – shape (N, 6) vectors to query.

Returns

• i (np.array) – integer indices of closest ray to each query

• d (np.array) – distance from query to point, positional distance is normalized by the average chord-length between leveel 0 sun samples divided by the PlanMapper ptres * sqrt(2).

add_indirect_to_suns(skyplanedirect, srcprefix='i_', overwrite=False)

Parameters

• skyplanedirect (DayLightPlaneKD) – a skyplane with matching ray samples to self.skyplane (use SamplerArea.repeat) representing the direct contribution from sky patches.

• overwrite (bool, optional) – overwrite output

• srcprefix (str, optional) – if inplace is False, the prefix to add to the source names

Returns

self if inplace is True, else a new DaylightPlaneKD

Return type

DayLightPlaneKD

make_images(skydata, points, vm, viewangle=180.0, res=512, interp=False, prefix='img', namebyindex=False)

see namebyindex for file naming conventions

Parameters

• skydata (raytraverse.sky.Skydata) –

• points (np.array) – shape (N, 3)

• vm (Union[raytraverse.mapper.ViewMapper, np.array]) – either a predefined ViewMapper (used for all points) or an array of view directions (will use a 180 degree view angle when initializing ViewMapper)

• viewangle (float, optional) – view opening for sensor (0-180,360) when vm is given as an array of view directions.

• res (int, optional) – image resolution

• interp (bool, optional) – interpolate image

• prefix (str, optional) – prefix for output file naming

• namebyindex (bool, optional) – if False (default), names images by: <prefix>_sky-<row>_pt-<x>_<y>_<z>_vd-<dx>_<dy>_<dz>.hdr if True, names images by: <prefix>_sky-<row>_pt-<pidx>_vd-<vidx>.hdr, where pidx, vidx are refer to the order of points, and vm.

Returns

Return type

np.array of out_files shape (skiees, points, views)

evaluate(skydata, points, vm, viewangle=180.0, metricclass=<class 'raytraverse.evaluate.metricset.MetricSet'>, metrics=None, datainfo=False, srconly=False, **kwargs)

apply sky data and view queries to daylightplane to return metrics parallelizes and optimizes run order.

Parameters

• skydata (raytraverse.sky.Skydata) –

• points (np.array) – shape (N, 3)

• vm (Union[raytraverse.mapper.ViewMapper, np.array]) – either a predefined ViewMapper (used for all points) or an array of view directions (will use ‘viewangle’ when initializing ViewMapper)

• viewangle (float, optional) – view opening for sensor (0-180,360) when vm is given as an array of view directions, note that for illuminance based metrics, a value of 360 may not make sense as values behind will be negative.

• metricclass (raytraverse.evaluate.BaseMetricSet, optional) –

• metrics (Sized, optional) –

• srconly (bool, optional) – sun only calculations

• datainfo (Union[Sized[str], bool], optional) – include information about source data as additional metrics. Valid values include: [“sun_pt_err”, “sun_pt_bin”, “sky_pt_err”, “sky_pt_bin”, “sun_err”, “sun_bin”]. If True, includes all. “err” is distance from queried vector to actual. “bin” is the unraveled idx of source vector at a 500^2 resolution of the mapper. order is ignored, info is always in order listed above after the last metric.

Returns

Return type

raytraverse.lightfield.LightResult

LightResult

class raytraverse.lightfield.LightResult(data, *axes)

Bases: object

a dense representation of lightfield data analyzed for a set of metrics

this class handles writing and loading results to disk as binary data and intuitive result extraction and reshaping for downstream visualisation and analysis using one of the “pull” methods. axes are indexed both numerically and names for increased transparency and ease of use.

Parameters

• data (np.array str) – multidimensional array of result data or file path to saved LightResule

• axes (Sequence[raytraverse.lightfield.ResultAxis]) – axis information

property data

property axes

property names

static load(file)

write(file, compressed=True)

pull(*axes, aindices=None, findices=None, order=None)

arrange and extract data slices from result.

DaylightPlaneKD.evaluate constructs a light result with these axes:

0. sky

1. point

2. view

3. metric

Parameters

• axes (Union[int, str]) – the axes (by name or integer index) to maintain and order the returned result (where axes will be the last N axes of result)

• aindices (Sequence[array_like], optional) – sequence of returned axis indices, up to one per each of axes to return a subset of data along these axes.

• findices (Sequence, optional) – sequence of indices or slices for pre-flattened axes to be flattened. give in order matching “order”

• order (Sequence) – the remainder of the axes in the order in which they should be arranged prior to flattening. by default uses their original order in self.data

Returns

• result (np.array) – the result array, will have 1+len(axes) dims, with the shaped determined by axis size and any indices argument.

• labels (Sequence) – list of labels for each axis, for flattened axes will be a tuple of broadcast axis labels.

• names (Sequence) – list of strings of returned axis names

print(col, aindices=None, findices=None, order=None, header=True, rowlabel=True, file=None)

first calls pull and then prints result to file

pull2pandas(ax1, ax2, **kwargs)

returns a list of dicts suitable for initializing pandas.DataFrames

Parameters

• ax1 (Union[int, str]) – the output row axis

• ax2 (Union[int, str]) – the output column axis

• kwargs (dict) – additional parameters for self.pull()

Returns

• panda_args (Sequence[dict]) –

  list of keyword arguments for initializing a pandas DataFrame:

  frames = [pandas.DataFrame(**kw) for kw in panda_args]
  

  keys are [‘data’, ‘index’, ‘columns’]

• frame_info (Sequence[dict]) –

  information for each data frame keys:

  • name: the summary name of the frame, a concatenation of the flattened axes (for example: “point_view” implies the frame is extracted for a particular point and view direction)

  • item: the values of the frame from each of the flatten axes (for example: for a name “point_view” this item = [(x, y, z), (vx, vy, vz)]

  • axis0: the name of the row axis (for example: “sky”)

  • axis1: the name of thee column axis (for example: “metric”)