raytraverse.mapper¶

Mapper¶

class raytraverse.mapper.Mapper(dxyz=(0.0, 0.0, 1.0), sf=(1, 1), bbox=((0, 0), (1, 1)), aspect=None, name='mapper', origin=(0, 0, 0), jitterrate=1.0)[source]¶

Bases: object

translate between world and normalized UV space. do not use directly, instead use an inheriting class.

Parameters

sf (tuple np.array, optional) – scale factor for each axis (array of length(2)
bbox (tuple np.array, optional) – bounding box for mapper shape (2, 2)
name (str, optional) – used for output file naming

property aspect¶

property dxyz¶: (float, float, float) central view direction

property bbox¶

bounding box of view

Type: np.array of shape (2,2)

view2world(xyz)[source]¶: rotate vectors from view direction to world Z

world2view(xyz)[source]¶: rotate vectors from world Z to view direction

xyz2uv(xyz)[source]¶: transform from world xyz space to mapper UV space

uv2xyz(uv, stackorigin=False)[source]¶: transform from mapper UV space to world xyz

idx2uv(idx, shape, jitter=True)[source]¶

Parameters

idx (flattened index) –
shape – the shape to unravel into
jitter (bool, optional) – randomly offset coordinates within grid

Returns

uv – uv coordinates

Return type

np.array

static uv2idx(uv, shape)[source]¶

xyz2vxy(xyz)[source]¶: transform from world xyz to view image space (2d)

vxy2xyz(xy, stackorigin=False)[source]¶: transform from view image space (2d) to world xyz

framesize(res)[source]¶

pixels(res, jitter=0.0)[source]¶: generate pixel coordinates for image space

pixelrays(res, jitter=0.0)[source]¶: world xyz coordinates for pixels in view image space

ray2pixel(xyz, res, integer=True)[source]¶: world xyz to pixel coordinate

pixel2ray(pxy, res)[source]¶: pixel coordinate to world xyz vector

pixel2omega(pxy, res)[source]¶: pixel area

in_view(vec, indices=True)[source]¶: generate mask for vec that are in the field of view

header(**kwargs)[source]¶

init_img(res=512, jitter=0.0, **kwargs)[source]¶

Initialize an image array with vectors and mask

Parameters

res (int, optional) – image array resolution
jitter (float, optional) – pixel jitter rate
kwargs – passed to self.header

Returns

img (np.array) – zero array of shape (res, res)
vecs (np.array) – direction vectors corresponding to each pixel (img.size, 3)
mask (np.array) – indices of flattened img that are in view

mask2 (np.array None) –

if ViewMapper has inverse, mask for opposite view, usage:

add_to_img(img, vecs[mask], mask)
add_to_img(img[res:], vecs[res:][mask2], mask2

header (str)

add_vecs_to_img(img, v, channels=(1, 0, 0), grow=0, **kwargs)[source]¶

plot(xyz, outf, res=1000, grow=1, **kwargs)[source]¶

AngularMixin¶

class raytraverse.mapper.angularmixin.AngularMixin[source]¶

Bases: object

includes overrides of transformation functions for angular type mapper classes. Inherit before raytraverse.mapper.Mapper eg:

NewMapper(AngularMixin, Mapper)

initialization of NewMapper must include declarations of:

self._viewangle = viewangle
self._chordfactor = chordfactor
self._ivm = ivm

xyz2uv(xyz)[source]¶: transform from world xyz space to mapper UV space

uv2xyz(uv, stackorigin=False)[source]¶: transform from mapper UV space to world xyz

xyz2vxy(xyz)[source]¶: transform from world xyz to view image space (2d)

vxy2xyz(xy, stackorigin=False)[source]¶: transform from view image space (2d) to world xyz

static framesize(res)[source]¶

pixelrays(res)[source]¶: world xyz coordinates for pixels in view image space

pixel2omega(pxy, res)[source]¶: pixel solid angle

in_view(vec, indices=True, tol=0.0)[source]¶: generate mask for vec that are in the field of view (up to 180 degrees) if view aspect is 2, only tests against primary view direction

header(pt=(0, 0, 0), **kwargs)[source]¶

init_img(res=512, pt=(0, 0, 0), features=1, **kwargs)[source]¶

Initialize an image array with vectors and mask

Parameters

res (int, optional) – image array resolution
pt (tuple, optional) – view point for image header

Returns

img (np.array) – zero array of shape (res*self.aspect, res)
vecs (np.array) – direction vectors corresponding to each pixel (img.size, 3)
mask (np.array) – indices of flattened img that are in view
mask2 (np.array None) – if features > 1, use mask 2 fro color images
header (str)

add_vecs_to_img(img, v, channels=(1, 0, 0), grow=0, fisheye=True, mask=None)[source]¶

property viewangle¶: view angle

property ivm¶: viewmapper for opposite view direction (in case of 360 degree view

ctheta(vec)[source]¶: cos(theta) (dot product) between view direction and vec

radians(vec)[source]¶: angle in radians betweeen vieew direction and vec

degrees(vec)[source]¶: angle in degrees betweeen vieew direction and vec

ViewMapper¶

class raytraverse.mapper.ViewMapper(dxyz=(0.0, 1.0, 0.0), viewangle=360.0, name='view', origin=(0, 0, 0), jitterrate=0.5)[source]¶

Bases: AngularMixin, Mapper

translate between world direction vectors and normalized UV space for a given view angle. pixel projection yields equiangular projection

Parameters

dxyz (tuple, optional) – central view direction
viewangle (float, optional) – if < 180, the horizontal and vertical view angle, if greater, view becomes 360,180

property aspect¶

property dxyz¶: (float, float, float) central view direction

idx2uv(idx, shape, jitter=True)[source]¶

Parameters

idx (flattened index) –
shape – the shape to unravel into
jitter (bool, optional) – randomly offset coordinates within grid

Returns

uv – uv coordinates

Return type

np.array

SkyMapper¶

class raytraverse.mapper.SkyMapper(loc=None, skyro=0.0, sunres=9, name='suns', jitterrate=0.5)[source]¶

Bases: AngularMixin, Mapper

translate between world direction vectors and normalized UV space for a given view angle. pixel projection yields equiangular projection

Parameters

loc (any, optional) –
can be a number of formats:
1. either a numeric iterable of length 3 (lat, lon, mer) where lat is +west and mer is tz*15 (matching gendaylit).
2. an array (or tsv file loadable with np.loadtxt) of shape (N,3), (N,4), or (N,5):
  2 elements: alt, azm (angles in degrees)
  
  3 elements: dx,dy,dz of sun positions
  
  4 elements: alt, azm, dirnorm, diffhoriz (angles in degrees)
  
  5 elements: dx, dy, dz, dirnorm, diffhoriz.
3. path to an epw or wea formatted file
4. None (default) all possible sun positions are considered self.in_solarbounds always returns True
in the case of a geo location, sun positions are considered valid when in the solar transit for that location. for candidate options, sun positions are drawn from this set (with one randomly chosen from all candidates within bin.
skyro (float, optional) – counterclockwise sky-rotation in degrees (equivalent to clockwise project north rotation)
sunres (float, optional) – initial sampling resolution for suns
name (str, optional) –

property skyro¶

property loc¶

property solarbounds¶

property candidates¶

in_solarbounds(xyz, level=0, include='any')[source]¶

for checking if src direction is in solar transit

Parameters

xyz (np.array) – source directions
level (int) – for determining patch size, 2**level resolution from sunres
include ({'center', 'all', 'any'}, optional) – boundary test condition. ‘center’ tests uv only, ‘all’ requires for corners of box centered at uv to be in, ‘any’ requires atleast one corner. ‘any’ is the least restrictive and ‘all’ is the most, but with increasing levels ‘any’ will exclude more positions while ‘all’ will exclude less (both approaching ‘center’ as level -> N)

Returns

result – Truth of ray.src within solar transit

Return type

np.array

shape(level=0)[source]¶

solar_grid(jitter=True, level=0, masked=True)[source]¶

generate a grid of solar positions

Parameters

jitter (bool, optional) – if None, use the instance default, if True jitters point samples within stratified grid
level (int, optional) – sets the resolution of the grid as a power of 2 from sunress
masked (bool, optional) – apply in_solarbounds to suns before returning

Returns

shape (N, 3)

Return type

np.array

PlanMapper¶

class raytraverse.mapper.PlanMapper(area, ptres=1.0, rotation=0.0, zheight=None, name='plan', jitterrate=0.5, autorotate=False, autogrid=None)[source]¶

Bases: Mapper

translate between world positions on a horizontal plane and normalized UV space for a given view angle. pixel projection yields a parallel plan projection

Parameters

area (str np.array, optional) – radiance scene geometry defining a plane to sample, tsv file of points to generate bounding box, or np.array of points.
ptres (float, optional) – resolution for considering points duplicates, border generation (1/2) and add_grid(). updateable
rotation (float, optional) – positive Z rotation for point grid alignment
zheight (float, optional) – override calculated zheight
name (str, optional) – plan mapper name used for output file naming
jitterrate (float, optional) – proportion of cell to jitter within
autorotate (bool, optional) – if true set rotation based on long axis of area geometry
autogrid (int, optional) – if given, autoset ptres based on this minimum number of points at level 0 along the minimum dimemsion (width or height)

ptres¶

point resolution for area look ups and grid

Type: float

property dxyz¶: (float, float, float) central view point

property rotation¶

ccw rotation (in degrees) for point grid on plane

Type: float

property bbox¶

boundary frame for translating between coordinates [[xmin ymin zmin] [xmax ymax zmax]]

Type: np.array

update_bbox(plane, level=0, updatez=True)[source]¶: handle bounding box generation from plane or points

uv2xyz(uv, stackorigin=False)[source]¶: transform from mapper UV space to world xyz

in_view_uv(uv, indices=True, **kwargs)[source]¶

in_view(vec, indices=True)[source]¶

check if point is in boundary path

Parameters

vec (np.array) – xyz coordinates, shape (N, 3)
indices (bool, optional) – return indices of True items rather than boolean array

Returns

mask – boolean array, shape (N,)

Return type

np.array

header(**kwargs)[source]¶

borders()[source]¶: world coordinate vertices of planmapper boundaries

property boundary¶

bbox_vertices(offset=0, close=False)[source]¶

shape(level=0)[source]¶

point_grid(jitter=True, level=0, masked=True, snap=None)[source]¶

generate a grid of points

Parameters

jitter (bool, optional) – if None, use the instance default, if True jitters point samples within stratified grid
level (int, optional) – sets the resolution of the grid as a power of 2 from ptres
masked (bool, optional) – apply in_view to points before returning
snap (int, optional) – level to snap samples to when jitter=False should be > level

Returns

shape (N, 3)

Return type

np.array

point_grid_uv(jitter=True, level=0, masked=True, snap=None)[source]¶

add a grid of UV coordinates

Parameters

jitter (bool, optional) – if None, use the instance default, if True jitters point samples within stratified grid
level (int, optional) – sets the resolution of the grid as a power of 2 from ptres
masked (bool, optional) – apply in_view to points before returning
snap (int, optional) – level to snap samples to when jitter=False should be > level

Returns

shape (N, 2)

Return type

np.array

MaskedPlanMapper¶

class raytraverse.mapper.MaskedPlanMapper(pm, valid, level)[source]¶

Bases: PlanMapper

translate between world positions on a horizontal plane and normalized UV space for a given view angle. pixel projection yields a parallel plan projection

Parameters

pm (raytraverse.mapper.PlanMapper) – the source mapper to copy
valid (np.array) – a list of valid points used to make a mask, grid cells not represented by one of valid will be masked
level (int, optional) – the level at which to grid the valid candidates

update_mask(valid, level)[source]¶

in_view_uv(uv, indices=True, usemask=True)[source]¶