ladybug_geometry.geometry3d.polyface module

Object with Multiple Planar Faces in 3D Space

class ladybug_geometry.geometry3d.polyface.Polyface3D(vertices, face_indices, edge_information=None)[source]

Bases: Base2DIn3D

Object with Multiple Planar Faces in 3D Space. Includes solids and polyhedra.

Parameters:

  • vertices – A list of Point3D objects representing the vertices of this PolyFace.

  • face_indices – A list of lists with one list for each face of the polyface. Each face list must contain at least one tuple of integers corresponding to indices within the vertices list. Additional tuples of integers may follow this one such that the first tuple denotes the boundary of the face while each subsequent tuple denotes a hole in the face.

  • edge_information –

    Optional edge information, which will speed up the creation of the Polyface object if it is available but should be left as None if it is unknown. If None, edge_information will be computed from the vertices and face_indices inputs. Edge information should be formatted as a dictionary with two keys as follows:

    • ’edge_indices’: An array objects that each contain two integers. These integers correspond to indices within the vertices list and each tuple represents a line segment for an edge of the polyface.

    • ’edge_types’: An array of integers for each edge that parallels the edge_indices list. An integer of 0 denotes a naked edge, an integer of 1 denotes an internal edge. Anything higher is a non-manifold edge.

Properties:

  • vertices

  • faces

  • edges

  • naked_edges

  • internal_edges

  • non_manifold_edges

  • face_indices

  • edge_indices

  • edge_types

  • min

  • max

  • center

  • area

  • volume

  • is_solid

ToString()

Overwrite .NET ToString.

does_intersect_line_ray_exist(line_ray)[source]

Boolean for whether an intersection exists between the input Line3D or Ray3D.

Parameters:

line_ray – A Line3D or Ray3D object for which intersection will be evaluated.

Returns:

True if an intersection exists. False if it does not exist.

duplicate()

Get a copy of this object.

classmethod from_box(width, depth, height, base_plane=None)[source]

Initialize Polyface3D from parameters describing a box.

Initializing a polyface this way has the added benefit of having its faces property quickly calculated.

Parameters:

  • width – A number for the width of the box (in the X direction).

  • depth – A number for the depth of the box (in the Y direction).

  • height – A number for the height of the box (in the Z direction).

  • base_plane – A Plane object from which to generate the box. If None, default is the WorldXY plane.

classmethod from_dict(data)[source]

Create a Face3D from a dictionary.

Parameters:

data – A python dictionary in the following format

{
    "type": "Polyface3D",
    "vertices": [(0, 0, 0), (10, 0, 0), (10, 10, 0), (0, 10, 0)],
    "face_indices": [[(0, 1, 2)], [(3, 0, 1)]],
    "edge_information": {
        "edge_indices":[(0, 1), (1, 2), (2, 0), (2, 3), (3, 0)],
        "edge_types":[0, 0, 1, 0, 0]
    }
}
classmethod from_faces(faces, tolerance)[source]

Initialize Polyface3D from a list of Face3D objects.

Note that the Polyface3D.faces property of the resulting polyface will have an order of faces that matches the order input to this classmethod.

Parameters:

  • faces – A list of Face3D objects representing the boundary of this Polyface.

  • tolerance – The maximum difference between x, y, and z values at which the vertex of two adjacent faces is considered the same.

classmethod from_offset_face(face, offset)[source]

Initialize a solid Polyface3D from a Face3D offset along its normal.

The resulting polyface will always be offset in the direction of the face normal.

When a polyface is initialized this way, the first face of the Polyface3D.faces will always be the input face used to create the object, the last face will be the offset version of the face, and all other faces will form the extrusion connecting the two.

Parameters:

  • face – A Face3D to serve as a base for the polyface.

  • offset – A number for the distance to offset the face to make a solid.

static get_outward_faces(faces, tolerance)[source]

Turn a list of faces forming a solid into one where they all point outward.

Note that, if the input faces do not form a closed solid, there may be some output faces that are not pointing outward. However, if the gaps in the combined solid are within the input tolerance, this should not be an issue.

Also, note that this method runs automatically for any solid polyface (meaning every solid polyface automatically has outward-facing faces). So there is no need to rerun this method for faces from a solid polyface.

Parameters:

  • faces – A list of Face3D objects that together form a solid.

  • tolerance – Optional tolerance for the permissable size of gap between faces at which point the faces are considered to have a single edge.

Returns:

outward_faces – A list of the input Face3D objects that all point outwards (provided the input faces form a solid).

intersect_line_ray(line_ray)[source]

Get the intersections between this polyface and the input Line3D or Ray3D.

Parameters:

line_ray – A Line3D or Ray3D object for which intersection will be computed.

Returns:

A list of Point3D for the intersection. Will be an empty list if no intersection exists.

intersect_plane(plane)[source]

Get the intersection between this polyface and the input plane.

Parameters:

plane – A Plane object for which intersection will be computed.

Returns:

List of LineSegment3D objects for the intersection. Will be an empty list if no intersection exists.

is_point_inside(point, test_vector=Vector3D(1.00, 0.00, 0.00))[source]

Test whether a Point3D lies inside or outside the polyface.

Note that, if this polyface is not solid, the result will always be False.

Parameters:

  • point – A Point3D for which the inside/outside relationship will be tested.

  • test_vector – Optional vector to set the direction in which intersections with the polyface faces will be evaluated to determine if the point is inside. Default is the X-unit vector.

Returns:

A boolean denoting whether the point lies inside (True) or outside (False).

merge_overlapping_edges(tolerance, angle_tolerance)[source]

Get this object with overlapping naked edges merged into single internal edges

This can be used to determine if a polyface is truly solid since this check is not performed by default when the Polyface3D is created from_faces. In the default test of edge conditions, overlapping colinear edges are considered naked when the could be interpreted a single internal edge such as the case below:

 |           1          |
A|______________________|C
 |          B|          |
 |           |          |
 |     2     |     3    |

If Face 1 only has edge AC and not two separate edges for AB and BC, the creation of the polyface will yield naked edges for AC, AB, and BC, meaning the shape would not be considered solid when it might actually be so. This merge_overlapping_edges method overcomes this by replacing the entire set of 3 naked edges above a single internal edge running from A to C.

Parameters:

  • tolerance – The minimum distance between a vertex and the boundary segments at which point the vertex is considered colinear.

  • angle_tolerance – The max angle in radians that vertices are allowed to differ from one another in order to consider them colinear.

move(moving_vec)[source]

Get a polyface that has been moved along a vector.

Parameters:

moving_vec – A Vector3D with the direction and distance to move the polyface.

static overlapping_bounding_boxes(polyface1, polyface2, tolerance)[source]

Check if the bounding boxes of two polyfaces overlap within a tolerance.

This is particularly useful as a check before performing computationally intense processes between two polyfaces like intersection or checking for adjacency. Checking the overlap of the bounding boxes is extremely quick given this method’s use of the Separating Axis Theorem.

Parameters:

  • polyface1 – The first polyface to check.

  • polyface2 – The second polyface to check.

  • tolerance – Distance within which two points are considered to be co-located.

reflect(normal, origin)[source]

Get a polyface reflected across a plane with the input normal and origin.

Parameters:

  • normal – A Vector3D representing the normal vector for the plane across which the polyface will be reflected. THIS VECTOR MUST BE NORMALIZED.

  • origin – A Point3D representing the origin from which to reflect.

rotate(axis, angle, origin)[source]

Rotate a polyface by a certain angle around an axis and origin.

Right hand rule applies: If axis has a positive orientation, rotation will be clockwise. If axis has a negative orientation, rotation will be counterclockwise.

Parameters:

  • axis – A Vector3D axis representing the axis of rotation.

  • angle – An angle for rotation in radians.

  • origin – A Point3D for the origin around which the object will be rotated.

rotate_xy(angle, origin)[source]

Get a polyface rotated counterclockwise in the world XY plane by an angle.

Parameters:

  • angle – An angle in radians.

  • origin – A Point3D for the origin around which the object will be rotated.

scale(factor, origin=None)[source]

Scale a polyface by a factor from an origin point.

Parameters:

  • factor – A number representing how much the polyface should be scaled.

  • origin – A Point3D representing the origin from which to scale. If None, it will be scaled from the World origin (0, 0, 0).

to_dict(include_edge_information=True)[source]

Get Polyface3D as a dictionary.

Parameters:

include_edge_information – Set to True to include the edge_information in the dictionary, which will allow for fast initialization when it is de-serialized. Default True.

property area

The total surface area of the polyface.

property center

A Point3D for the center of the bounding box around this geometry.

property edge_indices

Tuple of edge tuples with integers corresponding to indices of vertices.

property edge_information

Dictionary with keys edge_indices, edge_types and corresponding properties.

property edge_types

Tuple of integers for each edge that denotes the type of edge.

0 denotes a naked edge, 1 denotes an internal edge, and anything higher is a non-manifold edge.

property edges

“Tuple of all edges in this polyface as LineSegment3D objects.

property face_indices

Tuple of face tuples with integers corresponding to indices of vertices.

property faces

Tuple of all Face3D objects making up this polyface.

property internal_edges

“Tuple of all internal edges in this polyface as LineSegment3D objects.

Internal edges are shared between two faces in the polyface.

property is_solid

A boolean to note whether the polyface is solid (True) or is open (False).

Note that all solid polyface objects will have faces pointing outwards.

property max

A Point3D for the maximum bounding box vertex around this geometry.

property min

A Point3D for the minimum bounding box vertex around this geometry.

property naked_edges

“Tuple of all naked edges in this polyface as LineSegment3D objects.

Naked edges belong to only one face in the polyface (they are not shared between faces).

property non_manifold_edges

“Tuple of all non-manifold edges in this polyface as LineSegment3D objects.

Non-manifold edges are shared between three or more faces and are therefore not allowed in solid polyfaces.

property vertices

Tuple of all vertices in this polyface.

Note that, in the case of a polyface with holes, some vertices will be repeated since this property effectively traces out a single boundary around the whole shape, winding inward to cut out the holes.

property volume

The volume enclosed by the polyface.

Note that, if this polyface is not solid (with all face normals pointing outward), the value of this property will not be valid.