raytraverse.mapper

SkyMapper

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

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

     1. 2 elements: alt, azm (angles in degrees)

     2. 3 elements: dx,dy,dz of sun positions

     3. 4 elements: alt, azm, dirnorm, diffhoriz (angles in degrees)

     4. 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')

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)

solar_grid(jitter=True, level=0, masked=True)

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)

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. if area is a radiance scene, or a 3d array of points, vertices are used to directly define the borders of the planmapper. if the array is 2d (or loaded from a tsv) points are used to generate an offset (see ptres) convexhull. points are stored as candidates for use as a static point sampler (jitter=false and level=0).

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

handle bounding box generation from plane or points

uv2xyz(uv, stackorigin=False)

transform from mapper UV space to world xyz

in_view_uv(uv, indices=True, **kwargs)

in_view(vec, indices=True)

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)

borders()

world coordinate vertices of planmapper boundaries

property boundary

bbox_vertices(offset=0, close=False)

shape(level=0)

point_grid(jitter=True, level=0, masked=True, snap=None)

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)

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)

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)

in_view_uv(uv, indices=True, usemask=True)