ladybug_geometry.geometry3d.face module¶

Planar Face in 3D Space

class ladybug_geometry.geometry3d.face.Face3D(boundary, plane=None, holes=None, enforce_right_hand=True)[source]¶

Bases: Base2DIn3D

Planar Face in 3D space.

Parameters:

boundary – A list or tuple of Point3D objects representing the outer boundary vertices of the face.
plane – A Plane object indicating the plane in which the face exists. If None, the Plane normal will automatically be calculated by analyzing the input vertices and the origin of the plane will be the first vertex of the input vertices. Default: None.
holes – Optional list of lists with one list for each hole in the face. Each hole should be a list of at least 3 Point3D objects. If None, it will be assumed that there are no holes in the face. The boundary and holes are stored as separate lists of Point3Ds on the boundary and holes properties of this object. However, the vertices property will always contain all vertices across the shape. For a Face3D that has holes, it will trace out a single shape that turns inwards from the boundary to cut out the holes.
enforce_right_hand – Boolean to note whether a check should be run to ensure that input vertices are counterclockwise within the input plane, thereby enforcing the right-hand rule. By default, this is True and ensures that all Face3D objects adhere to the right-hand rule. It is recommended that this only be set to False in cases where you are certain that the input vertices are counter-clockwise within the input plane and you would like to avoid the extra unnecessary check.

Properties:

vertices
plane
boundary
holes
polygon2d
boundary_polygon2d
hole_polygon2d
triangulated_mesh2d
triangulated_mesh3d
boundary_segments
hole_segments
normal
min
max
center
perimeter
area
centroid
azimuth
altitude
tilt
is_clockwise
is_convex
is_self_intersecting
self_intersection_points
is_valid
has_holes
upper_left_corner
lower_left_corner
upper_right_corner
lower_right_corner
upper_left_counter_clockwise_vertices
lower_left_counter_clockwise_vertices
lower_right_counter_clockwise_vertices
upper_right_counter_clockwise_boundary
upper_left_counter_clockwise_boundary
lower_left_counter_clockwise_boundary
lower_right_counter_clockwise_boundary
upper_right_counter_clockwise_boundary

ToString()¶: Overwrite .NET ToString.

check_planar(tolerance, raise_exception=True)[source]¶

Check that all of the face’s vertices lie within the face’s plane.

This check is not done by default when creating the face since it is assumed that there is likely a check for planarity before the face is created (ie. in CAD software where the face likely originates from). This method is intended for quality control checking when the origin of face geometry is unknown or is known to come from a place where no planarity check was performed.

Parameters:

tolerance – The minimum distance between a given vertex and a the face’s plane at which the vertex is said to lie in the plane.
raise_exception – Boolean to note whether an exception should be raised if a vertex does not lie within the face’s plane. If True, an exception message will be given in such cases, which notes the non-planar vertex and its distance from the plane. If False, this method will simply return a False boolean if a vertex is found that is out of plane. Default is True to raise an exception.

Returns:

True if planar within the tolerance. False if not planar.

contour_by_distance_between(distance, direction_vector, flip_side, tolerance)[source]¶

Generate a list of LineSegment3D objects contouring the face.

Parameters:

distance – A number for the distance between each contour.
direction_vector – A Vector2D for the direction along which contours are generated. This 2D vector will be interpreted into a 3D vector within the plane of this Face. (0, 1) will usually generate horizontal contours in 3D space, (1, 0) will generate vertical contours, and (1, 1) will generate diagonal contours. Recommended value is Vector2D(0, 1).
flip_side – Boolean to note whether the side the contours start from should be flipped. Recommended value is is False to have contours start on top or right. Setting to True will start contours on the bottom or left.
tolerance – The minimum distance between coordinates that is considered meaningful. Will be used to remove any contours with a length less than the tolerance.

contour_by_number(contour_count, direction_vector, flip_side, tolerance)[source]¶

Generate a list of LineSegment3D objects contouring the face.

Parameters:

contour_count – A positive integer for the number of contours to generate over the face.
direction_vector – A Vector2D for the direction along which contours are generated. This 2D vector will be interpreted into a 3D vector within the plane of this Face. (0, 1) will usually generate horizontal contours in 3D space, (1, 0) will generate vertical contours, and (1, 1) will generate diagonal contours. Recommended value is Vector2D(0, 1).
flip_side – Boolean to note whether the side the contours start from should be flipped. Recommended value is False to have contours on top or right. Setting to True will start contours on the bottom or left.
tolerance – The minimum distance between coordinates that is considered meaningful. Will be used to remove any contours with a length less than the tolerance.

contour_fins_by_distance_between(distance, depth, offset, angle, contour_vector, flip_side, tolerance)[source]¶

Generate a list of Fac3D objects over this face (like louvers or fins).

Parameters:

distance – A number for the approximate distance between each contour.
depth – A number for the depth to extrude the fins.
offset – A number for the distance to offset fins from this face. Recommended value is 0 for no offset.
angle – A number for the for an angle to rotate the fins in radians. Recommended value is 0 for no rotation.
contour_vector – A Vector2D for the direction along which contours are generated. This 2D vector will be interpreted into a 3D vector within the plane of this Face. (0, 1) will usually generate horizontal contours in 3D space, (1, 0) will generate vertical contours, and (1, 1) will generate diagonal contours. Recommended value is Vector2D(0, 1).
flip_side – Boolean to note whether the side the fins start from should be flipped. Recommended value is False to have contours start on top or right. Setting to True will start contours on the bottom or left.
tolerance – The minimum distance between coordinates that is considered meaningful. Will be used to remove any contours with a length less than the tolerance.

contour_fins_by_number(fin_count, depth, offset, angle, contour_vector, flip_side, tolerance)[source]¶

Generate a list of Fac3D objects over this face (like louvers or fins).

Parameters:

fin_count – A positive integer for the number of fins to generate.
depth – A number for the depth to extrude the fins.
offset – A number for the distance to offset fins from this face. Recommended value is 0 for no offset.
angle – A number for the for an angle to rotate the fins in radians. Recommended value is 0 for no rotation.
contour_vector – A Vector2D for the direction along which contours are generated. This 2D vector will be interpreted into a 3D vector within the plane of this Face. (0, 1) will usually generate horizontal contours in 3D space, (1, 0) will generate vertical contours, and (1, 1) will generate diagonal contours. Recommended value is Vector2D(0, 1).
flip_side – Boolean to note whether the side the fins start from should be flipped. Recommended value is False to have contours start on top or right. Setting to True will start contours on the bottom or left.
tolerance – The minimum distance between coordinates that is considered meaningful. Will be used to remove any contours with a length less than the tolerance.

coplanar_difference(faces, tolerance, angle_tolerance)[source]¶

Subtract one or more coplanar Face3D from this Face3D.

Note that, when the faces are not coplanar or they do not overlap, a list with only the original face will be returned.

Parameters:

faces – A list of Face3D for which will be subtracted from this Face3D.
tolerance – The minimum difference between X, Y and Z values at which vertices are considered distinct from one another.
angle_tolerance – The max angle in radians that the plane normals can differ from one another in order for them to be considered coplanar.

Returns:

A List of Face3D representing the original Face3D with the input faces subtracted from it.

static coplanar_intersection(face1, face2, tolerance, angle_tolerance)[source]¶

Boolean Intersection two coplanar Face3D with one another.

Parameters:

face1 – A Face3D for the first face that will be intersected with the second face.
face2 – A Face3D for the second face that will be intersected with the first face.
tolerance – The minimum difference between X, Y and Z values at which vertices are considered distinct from one another.
angle_tolerance – The max angle in radians that the plane normals can differ from one another in order for them to be considered coplanar.

Returns:

A list of Face3D for the Intersection of the two input Face3D. When the faces are not coplanar or they do not overlap, None will be returned.

static coplanar_split(face1, face2, tolerance, angle_tolerance)[source]¶

Split two coplanar Face3D with one another (ensuring matching overlapped area)

When the faces are not coplanar or they do not overlap, the original faces will be returned.

Parameters:

face1 – A Face3D for the first face that will be split with the second face.
face2 – A Face3D for the second face that will be split with the first face.
tolerance – The minimum difference between X, Y and Z values at which vertices are considered distinct from one another.
angle_tolerance – The max angle in radians that the plane normals can differ from one another in order for them to be considered coplanar.

Returns:

A tuple with two elements

face1_split: A list of Face3D for the split version of the input face1.
face2_split: A list of Face3D for the split version of the input face2.

static coplanar_union(face1, face2, tolerance, angle_tolerance)[source]¶

Boolean Union two coplanar Face3D with one another.

Parameters:

face1 – A Face3D for the first face that will be unioned with the second face.
face2 – A Face3D for the second face that will be unioned with the first face.
tolerance – The minimum difference between X, Y and Z values at which vertices are considered distinct from one another.
angle_tolerance – The max angle in radians that the plane normals can differ from one another in order for them to be considered coplanar.

Returns:

A single Face3D for the Union of the two input Face3D. When the faces are not coplanar or they do not overlap, None will be returned.

static coplanar_union_all(faces, tolerance, angle_tolerance)[source]¶

Boolean Union several coplanar Face3D together.

Note that this method does not perform any check for whether the input faces overlap before it performs the unioning operation. So it is recommended that the Face3D.group_by_coplanar_overlap method be run before using this method to union each group together.

Parameters:

faces – A list of Face3D that will be unioned together.
tolerance – The minimum difference between X, Y and Z values at which vertices are considered distinct from one another.
angle_tolerance – The max angle in radians that the plane normals can differ from one another in order for them to be considered coplanar.

Returns:

A list of Face3D for the Union of all the input Face3D. When the faces are not coplanar, None will be returned.

duplicate()¶: Get a copy of this object.

static extract_all_from_stl(file_path)[source]¶

Get a list of Face3Ds imported from all of the triangles in an STL file.

Parameters:: file_path – Path to an STL file as a text string. The STL file can be in either ASCII or binary format.

extract_rectangle(tolerance)[source]¶

Extract top and bottom line segments of a rectangle within this Face.

This method will only return geometry if:

There are no holes in the face.
The face is not parallel to the World XY plane.
There are two parallel edges to this face, which are either oriented horizontally or vertically.
There must be enough overlap between these edges for a rectangle to be drawn between them.

If this Face does not satisfy this criteria, None will be returned.

Parameters:

tolerance – The maximum difference between point values for them to be considered a part of a rectangle.

Returns:

A tuple with three elements

bottom_edge: A LineSegment3D representing the bottom of the rectangle.
top_edge: A LineSegment3D representing the top of the rectangle.
other_faces: A list of Face3D objects for the parts of this face not included in the rectangle. The length of this list will be between 0 (if this face is already rectangular) and 2 (if there are non- rectangular geometries on either side of the rectangle.)

flip()[source]¶: Get a face with a flipped direction from this one.

classmethod from_array(point_array)[source]¶

Create a Face3D from a nested array of vertex coordinates.

Parameters:: point_array – A nested array of arrays where each sub-array represents a loop of the Face3D. The first array is the boundary and subsequent arrays represent holes in the Face3D. point arrays. Each sub-array is composed of arrays that each have a length of 3 and denote 3D points that define the face.

classmethod from_dict(data)[source]¶

Create a Face3D from a dictionary.

Parameters:: data – A python dictionary in the following format

{
    "type": "Face3D",
    "boundary": [(0, 0, 0), (10, 0, 0), (0, 10, 0)],
    "plane": {"n": (0, 0, 1), "o": (0, 0, 0), "x": (1, 0, 0)},
    "holes": [[(2, 2, 0), (5, 2, 0), (2, 5, 0)]]
}

classmethod from_extrusion(line_segment, extrusion_vector)[source]¶

Initialize Face3D by extruding a line segment.

Initializing a face this way has the added benefit of having its properties quickly computed.

Parameters:

line_segment – A LineSegment3D to be extruded.
extrusion_vector – A vector denoting the direction and distance to extrude the line segment.

classmethod from_punched_geometry(base_face, sub_faces)[source]¶

Create a face with holes punched in it from sub-faces.

Parameters:

base_face – A Face3D that acts as a parent to the sub_faces, completely encircling them.
sub_faces – A list of Face3D objects that will be punched into the base_face. These faces must lie completely within the base_face for the result to be valid. The is_sub_face() method can be used to check sub_faces before they are input here.

classmethod from_rectangle(base, height, base_plane=None)[source]¶

Initialize Face3D from rectangle parameters (base + height) and a base plane.

Initializing a face this way has the added benefit of having its properties quickly computed.

Parameters:

base – A number indicating the length of the base of the rectangle.
height – A number indicating the length of the height of the rectangle.
base_plane – A Plane object in which the rectangle will be created. The origin of this plane will be the lower left corner of the rectangle and the X and Y axes will form the sides. Default is the world XY plane.

classmethod from_regular_polygon(side_count, radius=1, base_plane=None)[source]¶

Initialize Face3D from regular polygon parameters and a base_plane.

Parameters:

side_count – An integer for the number of sides on the regular polygon. This number must be greater than 2.
radius – A number indicating the distance from the polygon’s center where the vertices of the polygon will lie. The default is set to 1.
base_plane – A Plane object for the plane in which the face exists. The origin of this plane will be used as the center of the polygon. If None, the default will be the WorldXY plane.

get_left_right_vertical_edges(tolerance)[source]¶

Get left and right vertical edges of this Face if they exist.

Parameters:: tolerance – The maximum difference between the x any y values of the start and end coordinates at which an edge is considered vertical.
Returns:: (left_edge, right_edge) with each as LineSegment3D if they exist. Left in this case is defined as the edge with the lower X coordinates. Result will be None if vertical edges do not exist.

get_top_bottom_horizontal_edges(tolerance)[source]¶

Get top and bottom horizontal edges of this Face if they exist.

Parameters:: tolerance – The maximum difference between the z values of the start and end coordinates at which an edge is considered horizontal.
Returns:: (bottom_edge, top_edge) with each as LineSegment3D if they exist. None if they do not exist.

static group_by_coplanar_overlap(faces, tolerance)[source]¶

Group coplanar Face3Ds depending on whether they overlap one another.

This is useful as a pre-step before running Face3D.coplanar_union() in order to assess whether union-ing is necessary and to ensure that it is only performed among the necessary groups of faces.

This method will return the minimal number of overlapping polygon groups thanks to a recursive check of whether groups can be merged.

Parameters:

faces – A list of Face3D to be grouped by their overlapping.
tolerance – The minimum distance from the edge of a neighboring Face3D at which a point is considered to overlap with that Face3D.

Returns:

A list of lists where each sub-list represents a group of Face3Ds that all overlap with one another.

intersect_line_ray(line_ray)[source]¶

Get the intersection between this face and the input LineSegment3D or Ray3D.

Parameters:: line_ray – A LineSegment3D or Ray3D object for which intersection will be computed.
Returns:: Point3D for the intersection. Will be None if no intersection exists.

intersect_plane(plane)[source]¶

Get the intersection between this face 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 None if no intersection exists.

is_centered_adjacent(face, tolerance)[source]¶

Check whether a given face is centered adjacent with this Face.

Centered adjacency is defined as sharing the same center point as this face and being next to one another to within the tolerance.

This is useful for identifying matching faces when you want to quickly solve for adjacency and you are not concerned about false positives in cases where one face does not perfectly match the other in terms of vertex ordering.

Parameters:

face – Another face for which centered adjacency will be tested.
tolerance – The minimum difference between the coordinate values of two centers at which they can be considered centered adjacent.

Returns:

True if centered adjacent. False if not centered adjacent.

is_coplanar(face, tolerance)[source]¶

Check whether a this face is coplanar with another given tolerance.

This method will only evaluate the distance between the other face’s vertices and this face’s plane so it does not rely on a check based on angle tolerance.

Parameters:

face – A neighboring Face3D for which co-planarity will be checked.
tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent.

Returns:

True if the face is coplanar with this one. False if it is not.

is_geometrically_equivalent(face, tolerance)[source]¶

Check whether a given face is geometrically equivalent to this Face.

Geometrical equivalence is defined as being coplanar with this face, having the same number of vertices, and having each vertex map-able between the faces. Clockwise relationships do not have to match nor does the normal direction of the face. However, all other properties must be matching to within the input tolerance.

This is useful for identifying matching surfaces when solving for adjacency and you need to ensure that two faces match perfectly in their area and vertices. Note that you may also want to use the remove_colinear_vertices() method on input faces before using this method in order to count faces with the same non-colinear vertices as geometrically equivalent.

Parameters:

face – Another face for which geometric equivalency will be tested.
tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered geometrically equivalent.

Returns:

True if geometrically equivalent. False if not geometrically equivalent.

is_horizontal(tolerance)[source]¶

Check whether a this face is horizontal within a given tolerance.

Parameters:: tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent.
Returns:: True if the face is horizontal. False if it is not.

is_overlapping(face, tolerance)[source]¶

Check whether a this face overlaps with another given tolerance.

Overlapping faces must not only be coplanar but they also have overlapping polygons when evaluated within the same plane. Note that, if the face is a sub-face of this one, this method will return True.

Parameters:

face – A neighboring Face3D for which overlaps will be checked.
tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent.

Returns:

True if the face is overlapping with this one. False if it is not.

is_point_on_face(point, tolerance)[source]¶

Check whether a given point is on this face.

This includes both a check to be sure that the point is in the plane of this face and a check to ensure that point lies in the boundary of the face.

Parameters:

point – A Point3D to evaluate whether it lies on the face.
tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent.

Returns:

True if the point is on the face. False if it is not.

is_sub_face(face, tolerance, angle_tolerance)[source]¶

Check whether a given face is a sub-face of this face.

Sub-faces will lie in the same plane as this one and have all of their vertices completely within the boundary of this face.

This is useful for identifying whether a given sub-face (ie. a window or door) can be assigned as a child to this face.

Parameters:

face – Another face for which sub-face equivalency will be tested.
tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent.
angle_tolerance – The max angle in radians that the plane normals can differ from one another in order for them to be considered coplanar.

Returns:

True if it can be a valid sub-face. False if it is not a valid sub-face.

static join_coplanar_faces(faces, tolerance)[source]¶

Join a list of coplanar Face3Ds together to get as few as possible.

Note that this method does not perform any boolean union operations on the input faces. It will only join the objects together along shared edges.

Parameters:

faces – A list of Face3D objects to be joined together. These should all be coplanar but they do not need to have their colinear vertices removed or be intersected for matching segments along which they are joined.
tolerance – The maximum difference between values at which point vertices are considered to be the same.

Returns:

A list of Face3Ds for the minimum number joined together.

static merge_faces_to_holes(faces, tolerance)[source]¶

Take of list of Face3Ds and merge any sub-faces into the others as holes.

This is particularly useful when translating 2D Polygons back into a 3D space and it is unknown whether certain polygons represent holes in the others.

Parameters:

faces – A list of Face3D which will be merged into fewer faces with any sub-faces represented as holes.
tolerance – The tolerance to be used for evaluating sub-faces.

mesh_grid(x_dim, y_dim=None, offset=None, flip=False, generate_centroids=True)[source]¶

Get a gridded Mesh3D over this face.

This method generates a mesh grid over the domain of the face and then removes any vertices that do not lie within it.

Note that the x_dim and y_dim refer to dimensions within the X and Y coordinate system of this faces’s plane. So rotating this plane will result in rotated grid cells.

Parameters:

x_dim – The x dimension of the grid cells as a number.
y_dim – The y dimension of the grid cells as a number. Default is None, which will assume the same cell dimension for y as is set for x.
offset – A number for how far to offset the grid from the base face. Default is None, which will not offset the grid at all.
flip – Set to True to have the mesh normals reversed from the direction of this face and to have the offset input move the mesh in the opposite direction from this face’s normal.
generate_centroids – Set to True to have the face centroids generated alongside the grid of vertices, which is much faster than having them generated upon request as they typically are. However, if you have no need for the face centroids, you would save time and memory by setting this to False. Default is True.

move(moving_vec)[source]¶

Get a face that has been moved along a vector.

Parameters:: moving_vec – A Vector3D with the direction and distance to move the face.

non_planar_vertices(tolerance)[source]¶

Get a tuple of Point3D for any vertices that lie outside the face’s plane.

This will be an empty tuple when the Face3D is planar and it is recommended that the Face3D.check_planar method be used before calling this one.

Parameters:: tolerance – The minimum distance between a given vertex and a the face’s plane at which the vertex is said to lie in the plane.

pole_of_inaccessibility(tolerance)[source]¶

Get the pole of inaccessibility for the Face3D.

The pole of inaccessibility is the most distant internal point from the Face3D outline. It is not to be confused with the centroid, which represents the “center of mass” of the shape and may be outside of the Face3D if the shape is concave. The poly of inaccessibility is useful for optimal placement of a text label on the Face3D.

Parameters:: tolerance – The precision to which the pole of inaccessibility will be computed.

polygon_in_face(sub_face, origin=None, flip=False)[source]¶

Get a Polygon2D for a sub_face within the plane of this Face3D.

Note that there is no check within this method to determine whether the the sub_face is coplanar with this Face3D or is fully bounded by it. So the is_sub_face method should be used to evaluate this before using this method.

Parameters:

sub_face – A Face3D for which a Polygon2D in the plane of this Face3D will be returned.
origin – An optional Point3D to set the origin of the plane in which the sub_face will be evaluated. Plugging in values like the Face’s lower_left_corner can standardize the geometry rules for the resulting polygon. If None, this face’s own plane will be used. (Default: None).
flip – Boolean to note whether the x-axis of the plane should be flipped when translating this the sub_face vertices.

project_point(point)[source]¶

Project a Point3D onto this face.

Note that this method does a check to see if the point can be projected to within this face’s boundary. If all that is needed is a point projected into the plane of this face, the Plane.project_point() method should be used with this face’s plane property.

Parameters:: point – A Point3D object to project.
Returns:: Point3D for the point projected onto this face. Will be None if the point cannot be projected to within the boundary of the face.

reflect(normal, origin)[source]¶

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

Parameters:

normal – A Vector3D representing the normal vector for the plane across which the face will be reflected. THIS VECTOR MUST BE NORMALIZED.
origin – A Point3D representing the origin from which to reflect.

remove_colinear_vertices(tolerance)[source]¶

Get a version of this face without colinear or duplicate vertices.

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

remove_duplicate_vertices(tolerance)[source]¶

Get a version of this face without duplicate vertices.

Parameters:: tolerance – The minimum distance between a two vertices at which they are considered co-located or duplicated.

rotate(axis, angle, origin)[source]¶

Rotate a face 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 face rotated counterclockwise in the world XY plane by a certain 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 face by a factor from an origin point.

Parameters:

factor – A number representing how much the face 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).

split_through_holes()[source]¶

Get this Face3D split through its holes to get Face3D without holes.

This method attempts to return the minimum number of non-holed shapes that are needed to represent the original Face3D. If this fails, the result will be derived from a triangulated shape. If getting a minimum number of constituent Face3D is not important, it is more efficient to just use all of the triangles in Face3D.triangulated_mesh3d instead of the result of this method.

Returns:: A list of Face3D without holes that together form a geometric representation of this Face3D. If this Face3D has no holes a list with a single Face3D is returned.

split_with_line(line, tolerance)[source]¶

Split this face into two or more Face3D given a LineSegment3D.

If the input line is found to not exist in the plane of this Face3D or it does not intersect this Face3D in a manner that splits it into two or more pieces, None will be returned.

Parameters:

line – A LineSegment3D object in the plane of this Face3D, which will be used to split it into two or more pieces.
tolerance – The maximum difference between point values for them to be considered distinct from one another.

Returns:

A list of Face3D for the result of splitting this Face3D with the input line. Will be None if the line is not in the plane of the Face3D or if it does not split the Face3D into two or more pieces.

split_with_lines(lines, tolerance)[source]¶

Split this face into two or more Face3D given multiple LineSegment3D.

Using this method is distinct from looping over Face3D.split_with_line in that this method will resolve cases where multiple segments branch out from nodes in a network of input lines. So, if three line segments meet at a point in the middle of this Face3D and each extend past the edges of this Face3D, this method can split the Face3D in 3 parts whereas looping over the Face3D.split_with_line will not do this given that each individual segment cannot split the Face3D.

If the input lines together do not intersect this Face3D in a manner that splits it into two or more pieces, None will be returned.

Parameters:

lines – A list of LineSegment3D objects in the plane of this Face3D, which will be used to split it into two or more pieces.
tolerance – The maximum difference between point values for them to be considered distinct from one another.

Returns:

A list of Face3D for the result of splitting this Face3D with the input lines. Will be None if the line is not in the plane of the Face3D or if it does not split the Face3D into two or more pieces.

split_with_polyline(polyline, tolerance)[source]¶

Split this face into two or more Face3D given an open Polyline3D.

If the input polyline is found to not exist in the plane of this Face3D, or the polyline is self-intersecting (or closed), or it does not intersect this Face3D in a manner that splits it into two or more pieces, None will be returned.

Note that, if you wish to use an operation similar to this method but with a closed Polyline3D (effectively another Face3D), then the Face3D.coplanar_split() method should be used instead of this method.

Parameters:

polyline – A Polyline3D object in the plane of this Face3D, which will be used to split it into two or more pieces.
tolerance – The maximum difference between point values for them to be considered distinct from one another.

Returns:

A list of Face3D for the result of splitting this Face3D with the input polyline. Will be None if the polyline is not in the plane of the Face3D, or the polyline intersects itself (or is closed), or if it does not split the Face3D into two or more pieces.

sub_faces_by_dimension_rectangle(sub_rect_height, sub_rect_width, sill_height, horizontal_separation, tolerance)[source]¶

Get a list of rectangular faces within this Face3D.

Note that this method will only yield results if there is a rectangle to be extracted from this Face3D’s geometry.

Parameters:

sub_rect_height – A number for the target height of the output rectangles.
sub_rect_width – A number for the target width of the output rectangles.
sill_height – A number for the target height above the bottom edge of the rectangle to start the sub-rectangles. If the sub_rect_height is too large for the sill_height to fit within the rectangle, the sub_rect_height will take precedence.
horizontal_separation – A number for the target separation between individual sub-rectangle center lines. If this number is larger than the parent rectangle base, only one sub-rectangle will be produced.
tolerance – The maximum difference between point values for them to be considered a part of a rectangle.

Returns:

A list of Face3D objects for sub faces.

sub_faces_by_ratio(ratio)[source]¶

Get a list of faces with a combined area equal to ratio times this face area.

All sub faces will lie inside the boundaries of this face and will have the same normal as this face.

Parameters:: ratio – A number between 0 and 1 for the ratio between the area of the sub faces and the area of this face.
Returns:: A list of Face3D objects for sub faces.

sub_faces_by_ratio_gridded(ratio, x_dim, y_dim=None)[source]¶

Get a list of faces with a combined area equal to ratio times this face area.

All sub faces will lie inside the boundaries of this face and have the same normal as this face.

Sub faces will be arranged in a grid derived from this face’s plane property. Because the x_dim and y_dim refer to dimensions within the X and Y coordinate system of this faces’s plane, rotating this plane will result in rotated grid cells.

If the x_dim and/or y_dim are too large for this face, this method will return essentially the same result as the sub_faces_by_ratio method.

Parameters:

ratio – A number between 0 and 1 for the ratio between the area of the sub faces and the area of this face.
x_dim – The x dimension of the grid cells as a number.
y_dim – The y dimension of the grid cells as a number. Default is None, which will assume the same cell dimension for y as is set for x.

Returns:

A list of Face3D objects for sub faces.

sub_faces_by_ratio_rectangle(ratio, tolerance)[source]¶

Get a list of faces with a combined area equal to ratio times this face area.

This function is virtually equivalent to the sub_faces_by_ratio method but a check will be performed to see if any rectangles can be pulled out of this face’s geometry. This tends to make the result a bit cleaner, especially for concave faces that have rectangles (like L-shaped faces).

Parameters:

ratio – A number between 0 and 1 for the ratio between the area of the sub faces and the area of this face.
tolerance – The maximum difference between point values for them to be considered a part of a rectangle.

Returns:

A list of Face3D objects for sub faces. If there is a rectangle in this shape, the scaled rectangle will be the first item in this list.

sub_faces_by_ratio_sub_rectangle(ratio, sub_rect_height, sill_height, horizontal_separation, vertical_separation, tolerance)[source]¶

Get a list of faces with a combined area equal to ratio times this face area.

This function is virtually equivalent to the sub_faces_by_ratio_rectangle method but any rectangles that are found will be broken down into sub-rectangles using the other inputs (sub_rect_height, sill_height, horizontal_separation, vertical_separation). This allows for the creation of a wide array of rectangular sub-face geometries.

Parameters:

ratio – A number between 0 and 1 for the ratio between the area of the sub faces and the area of this face.
sub_rect_height – A number for the target height of the output sub- rectangles. Note that, if the ratio is too large for the height, the ratio will take precedence and the sub-rectangle height will be larger than this value.
sill_height – A number for the target height above the bottom edge of the rectangle to start the sub-rectangles. Note that, if the ratio is too large for the height, the ratio will take precedence and the sub-rectangle height will be smaller than this value.
horizontal_separation – A number for the target separation between individual sub-rectangle center lines. If this number is larger than the parent rectangle base, only one sub-rectangle will be produced.
vertical_separation – An optional number to create a single vertical separation between top and bottom sub-rectangles. The default is 0 for no separation.
tolerance – The maximum difference between point values for them to be considered a part of a rectangle.

Returns:

A list of Face3D objects for sub faces. If there is a rectangle in this shape, the scaled rectangle will be the first item in this list.

static sub_rects_from_rect_dimensions(base_plane, parent_base, parent_height, sub_rect_height, sub_rect_width, sill_height, horizontal_separation)[source]¶

Get a list of rectangular Face3D objects from dimensions and parameters.

All of the resulting Face3D objects lie within a parent rectangle defined by the parent_base, parent_height, and base_plane.

Parameters:

base_plane – A Plane object in which the rectangle exists. The origin of this plane will be the lower left corner of the rectangle and the X and Y axes will form the sides.
parent_base – A number indicating the length of the base of the parent rectangle.
parent_height – A number indicating the length of the height of the parent rectangle.
sub_rect_height – A number for the target height of the output rectangles.
sub_rect_width – A number for the target width of the output rectangles.
sill_height – A number for the target height above the bottom edge of the rectangle to start the sub-rectangles. If the sub_rect_height is too large for the sill_height to fit within the rectangle, the sub_rect_height will take precedence.
horizontal_separation – A number for the target separation between individual sub-rectangle center lines. If this number is larger than the parent rectangle base, only one sub-rectangle will be produced.

Returns:

A list of Face3D objects for sub faces.

static sub_rects_from_rect_ratio(base_plane, parent_base, parent_height, ratio, sub_rect_height, sill_height, horizontal_separation, vertical_separation=0)[source]¶

Get a list of rectangular Face3D objects using an area ratio and parameters.

All of the resulting Face3D objects lie within a parent rectangle defined by the parent_base, parent_height, and base_plane. The combined area of the resulting rectangles is equal to the area of the larger rectangle multiplied by the input ratio. This method is particularly useful for generating rectangular window surfaces.

Parameters:

base_plane – A Plane object in which the rectangle exists. The origin of this plane will be the lower left corner of the rectangle and the X and Y axes will form the sides.
parent_base – A number indicating the length of the base of the parent rectangle.
parent_height – A number indicating the length of the height of the parent rectangle.
ratio – A number between 0 and 1 for the ratio between the area of the sub rectangle faces and the area of this face.
sub_rect_height – A number for the target height of the output sub- rectangles. Note that, if the ratio is too large for the height, the ratio will take precedence and the sub-rectangle height will be larger than this value.
sill_height – A number for the target height above the bottom edge of the rectangle to start the sub-rectangles. Note that, if the ratio is too large for the height, the ratio will take precedence and the sub-rectangle height will be smaller than this value.
horizontal_separation – A number for the target separation between individual sub-rectangle center lines. If this number is larger than the parent rectangle base, only one sub-rectangle will be produced.
vertical_separation – An optional number to create a single vertical separation between top and bottom sub-rectangles. The default is 0 for no separation.

Returns:

A list of Face3D objects for sub faces.

to_array()[source]¶

Get Face3D as a nested list of tuples where each sub-tuple represents loop.

The first loop is always the outer boundary and successive loops represent holes in the face (if they exist). Each sub-tuple is composed of tuples that each have a length of 3 and denote 3D points that define the face.

to_dict(include_plane=True, enforce_upper_left=False)[source]¶

Get Face3D as a dictionary.

Parameters:

include_plane – Set to True to include the Face3D plane in the dictionary, which will preserve the underlying orientation of the face plane. Default True.
enforce_upper_left – Set to True to ensure that the boundary vertices all start from the upper-left corner. This takes extra time to compute but ensures that the vertices in the dictionary are directly usable in an EnergyPlus simulations. Default: False.

HOLE_VERTEX_THRESHOLD = 400¶

property altitude¶: Get the altitude of the Face3D. Between Pi/2 (up) and -Pi/2 (down).

property area¶: The area of the face.

property azimuth¶

Get the azimuth of the Face3D (between 0 and 2 * Pi).

This will be zero if the Face3D is perfectly horizontal.

property boundary¶

Tuple of vertices on the boundary of this face.

For most Face3D objects, this will be identical to the vertices property. However, when the Face3D has holes within it, this property stores the outer boundary of the shape.

property boundary_polygon2d¶

A Polygon2D of the face boundary in the 2D space of the face’s plane.

Note that this does not include any holes in the face. Just the outer boundary.

property boundary_segments¶

Tuple of all line segments bordering the face.

Note that this does not include segments for any holes in the face. Just the outer boundary.

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

property centroid¶

The centroid of the face as a Point3D (aka. center of mass).

Note that the centroid is more time consuming to compute than the center (or the middle point of the face bounding box). So the center might be preferred over the centroid if you just need a rough point for the middle of the face.

property has_holes¶: Boolean noting whether the face has holes within it.

property hole_polygon2d¶: A list of Polygon2D for the face holes in the 2D space of the face’s plane.

property hole_segments¶

Tuple with a tuple of line segments for each hole in the face.

This will be None if there are no holes in the face.

property holes¶

Tuple with one tuple of vertices for each hole within this face.

This property will be None when the face has no holes in it.

property is_clockwise¶

Boolean for whether the face vertices and boundary are in clockwise order.

Note that all Face3D objects should have counterclockwise vertices (meaning that this property should always be False). This property exists largely for testing / debugging purposes.

property is_convex¶

Boolean noting whether the face is convex (True) or non-convex (False).

Note that any face with holes will be automatically considered non-convex since the underlying polygon_2d is always non-convex in this case.

property is_self_intersecting¶

Boolean noting whether the face has self-intersecting edges.

Note that this property is relatively computationally intense to obtain compared to properties like area and is_convex. Also, most CAD programs forbid geometry with self-intersecting edges. So it is recommended that this property only be used in quality control scripts where the origin of the geometry is unknown.

property is_valid¶

Boolean noting whether the face is valid (having a non-zero area).

Note that faces are still considered valid if they have out-of-plane vertices, self-intersecting edges, or duplicate/colinear vertices. The check_planar method can be used to detect if there are out-of-plane vertices. The is_self_intersecting property identifies self-intersecting edges, and the remove_colinear_vertices method will remove duplicate/colinear vertices.

property lower_left_corner¶: Get the vertex in the lower-left corner of the face’s bounding box.

property lower_left_counter_clockwise_boundary¶

Get face boundary starting from the lower left and moving counterclockwise.

Horizontal faces will treat the positive Y axis as up. All other faces treat the positive Z axis as up.

property lower_left_counter_clockwise_vertices¶

Get face vertices starting from the lower left and moving counterclockwise.

Horizontal faces will treat the positive Y axis as up. All other faces treat the positive Z axis as up.

property lower_right_corner¶: Get the vertex in the lower-right corner of the face’s bounding box.

property lower_right_counter_clockwise_boundary¶

Get face boundary starting from the lower left and moving counterclockwise.

Horizontal faces will treat the positive Y axis as up. All other faces treat the positive Z axis as up.

property lower_right_counter_clockwise_vertices¶

Get face vertices starting from the lower left and moving counterclockwise.

Horizontal faces will treat the positive Y axis as up. All other faces treat the positive Z axis as up.

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 normal¶: Normal vector for the plane in which the face exists.

property perimeter¶: The perimeter of the face. This includes the length of holes in the face.

property plane¶: Tuple of all vertices in this face.

property polygon2d¶

A Polygon2D of this face in the 2D space of the face’s plane.

Note that this is a single polygon object even when there are holes in the face since such a polygon can be made by drawing a line from the holes to the outer boundary.

property self_intersection_points¶

A tuple of Point3Ds for the locations where the Face3D intersects itself.

This will be an empty tuple if the Face3D is not self-intersecting and it is generally recommended that the Face3D.is_self_intersecting property be checked before using this property.

property tilt¶: Get the tilt of the Face3D. Between 0 (up) and Pi (down).

property triangulated_mesh2d¶: A triangulated Mesh2D in the 2D space of the face’s plane.

property triangulated_mesh3d¶: A triangulated Mesh3D of this face.

property upper_left_corner¶: Get the vertex in the upper-left corner of the face’s bounding box.

property upper_left_counter_clockwise_boundary¶

Get face boundary starting from the upper left and moving counterclockwise.

Horizontal faces will treat the positive Y axis as up. All other faces treat the positive Z axis as up.

property upper_left_counter_clockwise_vertices¶

Get face vertices starting from the upper left and moving counterclockwise.

Horizontal faces will treat the positive Y axis as up. All other faces treat the positive Z axis as up.

property upper_right_corner¶: Get the vertex in the upper-right corner of the face’s bounding box.

property upper_right_counter_clockwise_boundary¶

Get face boundary starting from the lower left and moving counterclockwise.

Horizontal faces will treat the positive Y axis as up. All other faces treat the positive Z axis as up.

property upper_right_counter_clockwise_vertices¶

Get face vertices starting from the lower left and moving counterclockwise.

Horizontal faces will treat the positive Y axis as up. All other faces treat the positive Z axis as up.

property vertices¶

Tuple of all vertices in this face.

Note that, in the case of a face 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.