ladybug.viewsphere module

Class to subdivide the sphere and hemisphere for view-based and radiation studies.

class ladybug.viewsphere.ViewSphere[source]

Bases: object

Class for subdividing the sphere and hemisphere for view-based studies.

Note

[1] Tregenza, Peter. (1987). Subdivision of the sky hemisphere for luminance measurements. Lighting Research & Technology - LIGHTING RES TECHNOL. 19. 13-14. 10.1177/096032718701900103.

Properties:

  • tregenza_dome_vectors

  • tregenza_sphere_vectors

  • tregenza_dome_mesh

  • tregenza_dome_mesh_high_res

  • tregenza_sphere_mesh

  • tregenza_solid_angles

  • reinhart_dome_vectors

  • reinhart_sphere_vectors

  • reinhart_dome_mesh

  • reinhart_sphere_mesh

  • reinhart_solid_angles

dome_patch_weights(division_count=1)[source]

Get a list of numbers corresponding to the area weight of each dome patch.

Parameters:

division_count – A positive integer for the number of times that the original Tregenza patches are subdivided. (Default: 1).

Returns:

A list of numbers with a value for each patch that corresponds to the area of that patch. The average value of all the patches is equal to 1.

dome_patches(division_count=1, subdivide_in_place=False)[source]

Get Vector3Ds and a corresponding Mesh3D for a dome.

Parameters:

  • division_count – A positive integer for the number of times that the original Tregenza patches are subdivided. 1 indicates that the original Tregenza patches will be used, 2 indicates the Reinhart patches will be used, and so on. (Default: 1).

  • subdivide_in_place – A boolean to note whether patches should be subdivided according to the extension of Tregenza’s original logic through the Reinhart method (False) or they should be simply divided into 4 in place (True). The latter is useful for making higher resolution Mesh visualizations of an inherently low-resolution dome.

Returns:

A tuple with two elements

  • patch_mesh: A ladybug_geometry Mesh3D that represents the dome at the input division_count. There is one quad face per patch except for the last circular patch, which is represented by a number of triangles equal to division_count * 6.

  • patch_vectors: A list of ladybug_geometry Vector3D with one vector per patch. These will align with the faces of the patch_mesh up until the last circular patch, which will have a single vector for the several triangular faces. All vectors are unit vectors.

dome_radial_patch_weights(azimuth_count=72, altitude_count=18)[source]

Get a list of numbers corresponding to the area weight of each dome patch.

Parameters:

  • azimuth_count – A positive integer for the number of times that the horizontal circle will be subdivided into azimuth patches. (Default: 72).

  • altitude_count – A positive integer for the number of times that the dome quarter-circle will be subdivided into altitude patches. (Default: 18).

Returns:

A list of numbers with a value for each patch that corresponds to the area of that patch. The average value of all the patches is equal to 1.

dome_radial_patches(azimuth_count=72, altitude_count=18)[source]

Get Vector3Ds and a corresponding Mesh3D for a a radial dome.

Parameters:

  • azimuth_count – A positive integer for the number of times that the horizontal circle will be subdivided into azimuth patches. (Default: 72).

  • altitude_count – A positive integer for the number of times that the dome quarter-circle will be subdivided into altitude patches. (Default: 18).

Returns:

A tuple with two elements

  • patch_mesh: A ladybug_geometry Mesh3D that represents the patches at the input azimuth_count and altitude_count.

  • patch_vectors: A list of ladybug_geometry Vector3D with one vector per mesh face. These will align with the faces of the patch_mesh. All vectors are unit vectors.

dome_view_mesh(center_point=Point3D(0.00, 0.00, 0.00), radius=1, azimuth_count=72, altitude_count=18)[source]

Get a mesh of a horizontal circle with vertices coordinated with view_vectors.

Parameters:

  • center_point – A Point3D for the center of the mesh. (Default: (0, 0, 0)).

  • radius – A number for the radius of the circle. (Default: 1).

  • azimuth_count – An integer greater than or equal to 3, which notes the number of horizontal orientations to be evaluated on the dome. (Default: 72).

  • altitude_count – An integer greater than or equal to 3, which notes the number of vertical orientations to be evaluated on the dome. (Default: 18).

Returns:

A tuple with two elements

  • dome_mesh: A ladybug_geometry Mesh3D that represents the hemispherical view dome at the input azimuth_count and altitude_count.

  • view_vecs: A list of ladybug_geometry Vector3D with one vector per mesh vertex.

static fin_pattern(plane_normal, left_fin_angle, right_fin_angle, view_vectors)[source]

Get booleans for whether a view vectors are blocked by left and right fins.

Parameters:

  • plane_normal – A Vector3D for the normal of the plane.

  • left_fin_angle – A number between 0 and 90 for the projection angle of a fin on the left side in degrees.

  • right_fin_angle – A number between 0 and 90 for the projection angle of a fin on the right side in degrees.

  • view_vectors – A list of view vectors which will be evaluated to determine if they are blocked by the plane or not.

Returns:

A list of booleans for whether each of the view vectors are blocked by the fins (True) or not (False).

horizontal_circle_view_mesh(center_point=Point3D(0.00, 0.00, 0.00), radius=1, azimuth_count=72)[source]

Get a mesh of a horizontal circle with vertices coordinated with view_vectors.

Parameters:

  • center_point – A Point3D for the center of the mesh. (Default: (0, 0, 0)).

  • radius – A number for the radius of the circle. (Default: 1).

  • azimuth_count – A positive integer greater than or equal to 3 for the number of times that the horizontal circle will be subdivided into vertices. (Default: 72).

Returns:

A tuple with two elements

  • circle_mesh: A ladybug_geometry circular Mesh3D that represents the horizontal view at the input azimuth_count.

  • view_vecs: A tuple of ladybug_geometry Vector3D with one vector per mesh vertex. The first vertex of the circle_mesh is the center and each one after that is coordinated with the vector here.

horizontal_radial_patch_weights(offset_angle=30, division_count=1)[source]

Get a list of numbers corresponding to the area weight of each radial patch.

Parameters:

  • offset_angle – A number between 0 and 90 for the angle offset from the horizontal plane at which vectors will be included. Vectors both above and below this angle will be included (Default: 30).

  • division_count – A positive integer for the number of times that the original Tregenza patches are subdivided. (Default: 1).

Returns:

A list of numbers with a value for each patch that corresponds to the area of that patch. The average value of all the patches is equal to 1.

horizontal_radial_patches(offset_angle=30, division_count=1, subdivide_in_place=False)[source]

Get Vector3Ds within a certain angle offset from the horizontal plane.

Parameters:

  • offset_angle – A number between 0 and 90 for the angle offset from the horizontal plane at which vectors will be included. Vectors both above and below this angle will be included (Default: 30 for the rough vertical limit of human peripheral vision).

  • division_count – A positive integer for the number of times that the original Tregenza patches are subdivided. 1 indicates that the original Tregenza patches will be used, 2 indicates the Reinhart patches will be used, and so on. (Default: 1).

  • subdivide_in_place – A boolean to note whether patches should be subdivided according to the extension of Tregenza’s original logic through the Reinhart method (False) or they should be simply divided into 4 in place (True).

Returns:

A tuple with two elements

  • patch_mesh: A ladybug_geometry Mesh3D that represents the patches at the input division_count. There is one quad face per patch.

  • patch_vectors: A list of ladybug_geometry Vector3D with one vector per patch. These will align with the faces of the patch_mesh. All vectors are unit vectors.

horizontal_radial_vectors(vector_count)[source]

Get perfectly horizontal Vector3Ds radiating outward in a circle.

Parameters:

vector_count – An integer for the number of vectors to generate in the horizontal plane. This can align with any of the dome or sphere patches by setting this to 30 * division_count.

Returns:

A list of ladybug_geometry horizontal Vector3D radiating outward in a circle. All vectors are unit vectors.

horizontal_radial_view_mesh(center_point=Point3D(0.00, 0.00, 0.00), radius=1, offset_angle=30, azimuth_count=72, altitude_count=6)[source]

Get a mesh of a radial circle with vertices coordinated with view_vectors.

Parameters:

  • center_point – A Point3D for the center of the mesh. (Default: (0, 0, 0)).

  • radius – A number for the radius of the circle. (Default: 1).

  • offset_angle – A number between 0 and 90 for the angle offset from the horizontal plane at which vectors will be included. Vectors both above and below this angle will be included (Default: 30).

  • azimuth_count – A positive integer greater than or equal to 3 for the number of times that the horizontal circle will be subdivided into vertices. (Default: 72).

  • altitude_count – An integer greater than or equal to 1, which notes the number of vertical orientations at which the altitude will be evaluated. (Default: 18).

Returns:

A tuple with two elements

  • radial_mesh: A ladybug_geometry Mesh3D that represents the horizontal radial view at the input azimuth_count and altitude_count.

  • view_vecs: A list of ladybug_geometry Vector3D with one vector per mesh vertex. The first vertex of the radial_mesh is the center and each one after that is coordinated with the vector here.

static orientation_pattern(plane_normal, view_vectors)[source]

Get booleans for whether view vectors are blocked by a plane.

Parameters:

  • plane_normal – A Vector3D for the normal of the plane.

  • view_vectors – A list of view vectors which will be evaluated to determine if they are blocked by the plane or not.

Returns:

A tuple with two values.

  • mask_pattern – A list of booleans for whether each of the view vectors are blocked by the plane (True) or not (False).

  • angles – A list of angles in radians for the angle between the plane normal and each view vector.

static overhang_pattern(plane_normal, overhang_angle, view_vectors)[source]

Get booleans for whether a view vectors are blocked by a overhang.

Parameters:

  • plane_normal – A Vector3D for the normal of the plane.

  • overhang_angle – A number between 0 and 90 for the projection angle of an overhang in degrees.

  • view_vectors – A list of view vectors which will be evaluated to determine if they are blocked by the plane or not.

Returns:

A list of booleans for whether each of the view vectors are blocked by the overhang (True) or not (False).

sphere_patch_weights(division_count=1)[source]

Get a list of numbers corresponding to the area weight of each sphere patch.

Parameters:

division_count – A positive integer for the number of times that the original Tregenza patches are subdivided. (Default: 1).

Returns:

A list of numbers with a value for each patch that corresponds to the area of that patch. The average value of all the patches is equal to 1.

sphere_patches(division_count=1, subdivide_in_place=False)[source]

Get Vector3Ds and a corresponding Mesh3D for a sphere.

Parameters:

  • division_count – A positive integer for the number of times that the original Tregenza patches are subdivided. 1 indicates that the original Tregenza patches will be used, 2 indicates the Reinhart patches will be used, and so on. (Default: 1).

  • subdivide_in_place – A boolean to note whether patches should be subdivided according to the extension of Tregenza’s original logic through the Reinhart method (False) or they should be simply divided into 4 in place (True). The latter is useful for making higher resolution Mesh visualizations of an inherently low-resolution dome.

Returns:

A tuple with two elements

  • patch_mesh: A ladybug_geometry Mesh3D that represents the sphere at the input division_count. There is one quad face per patch except for the last circular patch of each hemisphere, which is represented by a number of triangles equal to division_count * 6.

  • patch_vectors: A list of ladybug_geometry Vector3D with one vector per patch. These will align with the faces of the patch_mesh except for the two circular patches, which will have a single vector for the several triangular faces. All vectors are unit vectors.

sphere_view_mesh(center_point=Point3D(0.00, 0.00, 0.00), radius=1, azimuth_count=72, altitude_count=18)[source]

Get a mesh of a sphere with vertices coordinated with view_vectors.

Parameters:

  • center_point – A Point3D for the center of the mesh. (Default: (0, 0, 0)).

  • radius – A number for the radius of the sphere. (Default: 1).

  • azimuth_count – An integer greater than or equal to 3, which notes the number of horizontal orientations to be evaluated on the sphere. (Default: 72).

  • altitude_count – An integer greater than or equal to 3, which notes the number of vertical orientations to be evaluated on the sphere. (Default: 18).

Returns:

A tuple with two elements

  • sphere_mesh: A ladybug_geometry Mesh3D that represents the view sphere at the input azimuth_count and altitude_count.

  • view_vecs: A list of ladybug_geometry Vector3D with one vector per mesh vertex.

REINHART_COEFFICIENTS = (0.0113221971, 0.0111894547, 0.0109255262, 0.0105335058, 0.0125224872, 0.0117312774, 0.0108025291, 0.00974713106, 0.011436609, 0.00974295956, 0.0119026242, 0.00905126163, 0.0121875626, 0.00612971396, 0.00921483254)
REINHART_PATCHES_PER_ROW = (60, 60, 60, 60, 48, 48, 48, 48, 36, 36, 24, 24, 12, 12)
TREGENZA_COEFFICIENTS = (0.0435449227, 0.0416418006, 0.0473984151, 0.0406730411, 0.0428934136, 0.0445221864, 0.0455168385, 0.0344199465)
TREGENZA_PATCHES_PER_ROW = (30, 30, 24, 24, 18, 12, 6)
property reinhart_dome_mesh

An Mesh3D representing the Reinhart sky dome.

There is one quad face per patch except for the last circular patch, which is represented by 12 triangles.

property reinhart_dome_vectors

An array of 577 vectors representing the Reinhart sky dome.

property reinhart_solid_angles

Get a list of solid angles that align with the reinhart_dome_vectors.

property reinhart_sphere_mesh

An Mesh3D representing a Reinhart sphere.

There is one quad face per patch except for the two circular patches, which are each represented by 12 triangles.

property reinhart_sphere_vectors

An array of 1154 vectors representing a sphere of Reinhart vectors.

property tregenza_dome_mesh

An Mesh3D representing the Tregenza sky dome.

There is one quad face per patch except for the last circular patch, which is represented by 6 triangles.

property tregenza_dome_mesh_high_res

An high-resolution Mesh3D representing the Tregenza sky dome.

Each patch is represented by a 3x3 set of quad faces except for the last circular patch, which is represented by 18 triangles.

property tregenza_dome_vectors

An array of 145 vectors representing the Tregenza sky dome.

property tregenza_solid_angles

Get a list of solid angles that align with the tregenza_dome_vectors.

property tregenza_sphere_mesh

An Mesh3D representing a Tregenza sphere.

There is one quad face per patch except for the two circular patches, which are each represented by 6 triangles.

property tregenza_sphere_vectors

An array of 290 vectors representing a sphere of Tregenza vectors.