ladybug_geometry.geometry3d.mesh module

3D Mesh

class ladybug_geometry.geometry3d.mesh.Mesh3D(vertices, faces, colors=None)

Bases: MeshBase

3D Mesh object.

Parameters:

• vertices – A list or tuple of Point3D objects for vertices.

• faces – A list of tuples with each tuple having either 3 or 4 integers. These integers correspond to indices within the list of vertices.

• colors – An optional list of colors that correspond to either the faces of the mesh or the vertices of the mesh. Default is None.

Properties:

• vertices

• faces

• colors

• is_color_by_face

• min

• max

• center

• area

• face_areas

• face_centroids

• face_area_centroids

• face_vertices

• face_normals

• vertex_normals

• vertex_connected_faces

• face_edges

• edges

• naked_edges

• internal_edges

• non_manifold_edges

ToString()

Overwrite .NET ToString.

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Create a Mesh3D from a dictionary.

Parameters:

data – A python dictionary in the following format

{
    "type": "Mesh3D",
    "vertices": [(0, 0, 0), (10, 0, 0), (0, 10, 0)],
    "faces": [(0, 1, 2)],
    "colors": [{"r": 255, "g": 0, "b": 0}]
}

classmethod from_face_vertices(faces, purge=True)

Create a mesh from a list of faces with each face defined by Point3Ds.

Parameters:

• faces – A list of faces with each face defined as a list of 3 or 4 Point3D.

• purge – A boolean to indicate if duplicate vertices should be shared between faces. Default is True to purge duplicate vertices, which can be slow for large lists of faces but results in a higher-quality mesh with a smaller size in memory. Note that vertices are only considered duplicate if the coordinate values are equal to one another within floating point tolerance. To remove duplicate vertices within a specified tolerance other than floating point, the from_purged_face_vertices method should be used instead.

classmethod from_mesh2d(mesh_2d, plane=None)

Create a Mesh3D from a Mesh2D and a Plane in which the mesh exists.

Parameters:

• mesh_2d – A Mesh2D object.

• plane – A Plane object to represent the plane in which the Mesh2D exists within 3D space. If None, the WorldXY plane will be used.

classmethod from_obj(file_path)

Create a Mesh3D from an OBJ file.

Parameters:

file_path – Path to an OBJ file as a text string.

classmethod from_purged_face_vertices(faces, tolerance)

Create a mesh from a list of faces with each face defined by Point3Ds.

This method is slower than ‘from_face_vertices’ but will result in a mesh with fewer vertices and a smaller size in memory. This method is similar to using the ‘purge’ option in ‘from_face_vertices’ but will result in more shared vertices since it uses a tolerance to check equivalent vertices rather than comparing within floating point tolerance.

Parameters:

• faces – A list of faces with each face defined as a list of 3 or 4 Point3D.

• tolerance – A number for the minimum difference between coordinate values at which point vertices are considered equal to one another.

classmethod from_stl(file_path)

Create a Mesh3D from 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.

height_field_mesh(values, domain)

Get a Mesh3D that has faces or vertices offset according to a list of values.

Parameters:

• values – A list of values that has a length matching the number of faces or vertices in this mesh.

• domain – A tuple or list of two numbers for the upper and lower distances that the mesh vertices should be offset. (ie. (0, 3))

static join_meshes(meshes)

Join an array of Mesh3Ds into a single Mesh3D.

Parameters:

meshes – An array of meshes to be joined into one.

Returns:

A single Mesh3D object derived from the input meshes.

move(moving_vec)

Get a mesh that has been moved along a vector.

Parameters:

moving_vec – A Vector with the direction and distance to move the mesh.

offset_mesh(distance)

Get a Mesh3D that has been offset from this one by a certain difference.

Effectively, this method moves each mesh vertex along the vertex normal by the offset distance.

Parameters:

distance – A number for the distance to offset the mesh.

reflect(normal, origin)

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

Parameters:

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

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

remove_faces(pattern)

Get a version of this mesh where faces are removed according to a pattern.

Parameters:

pattern – A list of boolean values denoting whether a face should remain in the mesh (True) or be removed from the mesh (False). The length of this list must match the number of this mesh’s faces.

Returns:

A tuple with two elements.

• new_mesh: A mesh where the faces have been removed according to the input pattern.

• vertex_pattern: A list of boolean values that corresponds to the original mesh vertices noting whether the vertex is in the new mesh (True) or has been removed from the new mesh (False).

remove_faces_only(pattern)

Get a version of this mesh where faces are removed and vertices are unaltered.

This is faster than the Mesh3D.remove_faces method but will likely result a lower-quality mesh where several vertices exist in the mesh that are not referenced by any face. This may be preferred if pure speed of removing faces is a priority over smallest size of the mesh in memory.

Parameters:

pattern – A list of boolean values denoting whether a face should remain in the mesh (True) or be removed from the mesh (False). The length of this list must match the number of this mesh’s faces.

Returns:

new_mesh – A mesh where the faces have been removed according to the input pattern.

remove_vertices(pattern)

Get a version of this mesh where vertices are removed according to a pattern.

Parameters:

pattern – A list of boolean values denoting whether a vertex should remain in the mesh (True) or be removed from the mesh (False). The length of this list must match the number of this mesh’s vertices.

Returns:

A tuple with two elements.

• new_mesh: A mesh where the vertices have been removed according to the input pattern.

• face_pattern: A list of boolean values that corresponds to the original mesh faces noting whether the face is in the new mesh (True) or has been removed from the new mesh (False).

rotate(axis, angle, origin)

Rotate a mesh 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 point will be rotated.

rotate_xy(angle, origin)

Get a mesh rotated counterclockwise in the XY plane by a certain angle.

Parameters:

• angle – An angle for rotation in radians.

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

scale(factor, origin=None)

Scale a mesh by a factor from an origin point.

Parameters:

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

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

to_dict()

Get Mesh3D as a dictionary.

to_obj(folder, name, include_colors=True, include_normals=False, triangulate_quads=False, include_mtl=False)

Write the Mesh3D to an ASCII OBJ file.

Parameters:

• folder – A text string for the directory where the OBJ will be written.

• name – A text string for the name of the OBJ file.

• include_colors – Boolean to note whether the Mesh3D colors should be included in the OBJ file. (Default: True).

• include_normals – Boolean to note whether the vertex normals should be included in the OBJ file. (Default: False).

• triangulate_quads – Boolean to note whether quad faces should be triangulated upon export to OBJ. This may be needed for certain software platforms that require the mesh to be composed entirely of triangles (eg. Radiance). (Default: False).

• include_mtl – Boolean to note whether an .mtl file should be automatically generated next to the .obj file in the output folder. All materials in the mtl file will be diffuse white, with the assumption that these will be customized later. (Default: False).

to_stl(folder, name=None)

Write the Mesh3D to an ASCII STL file.

Parameters:

• folder – A text string for the directory where the STL will be written.

• name – A text string for the name of the STL file.

property area

The area of the entire mesh.

property center

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

property colors

Get or set a list of colors for the mesh. Will be None if no colors assigned.

property edges

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

Note that this method will return only the unique edges in the mesh without any duplicates. This is sometimes desirable but can take a lot of time to compute for large meshes. For a faster property, use face_edges.

property face_area_centroids

Tuple of face area centroids that aligns the faces property.

These Point3Ds are are the area centroids of the faces, which come from considering the surface of each quad face as having constant density.

The area centroid is more intensive to compute compared to the vertex centroid available through the face_centroids property. Moreover, the area centroid is equal to the vertex centroid for triangles and fairly close to the vertex centroid for convex quad faces with moderate aspect ratios. Therefore, this property is most useful when working with meshes containing concave quad faces or quads with extreme aspect ratios.

property face_areas

A tuple of face areas that parallels the faces property.

property face_centroids

Tuple of face centroids that aligns the faces property.

These Point3Ds are are the vertex centroids of the faces, which come from considering each quad face as being empty but having equal mass at each vertex.

Because such vertex centroids are computed as the mean of the coordinate values, they are fast to compute and a good property to use when generating test points that align large meshes predominantly containing triangles and/or convex quad faces. For meshes containing concave quad faces, the face_area_centroids may produce a more desirable result.

property face_edges

List of polylines with one Polyline3D for each face.

This is faster to compute compared to the edges and results in effectively the same type of wireframe visualization.

property face_normals

Tuple of Vector3D objects for all face normals.

property face_vertices

Tuple of mesh faces with each face defined as a tuple of Point3Ds.

property faces

Tuple of all faces in the mesh.

property internal_edges

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

Internal edges are shared between two faces in the mesh.

property is_color_by_face

Boolean for whether colors are face-by-face (True) or vertex-by-vertex (False)

When colors are assigned to the mesh, this property is linked to the colors and cannot be set. However, when no colors are assigned, it can be set because it affects how the mesh is translated to external interfaces. In such cases, this property notes whether the mesh will be translated in a format that can accept face-by-face colors. Default is False when no colors are assigned.

property max

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

property min

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

property naked_edges

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

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

property non_manifold_edges

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

Non-manifold edges are shared between three or more faces.

property vertex_connected_faces

Tuple with a tuple for each vertex that lists the indexes of connected faces.

property vertex_normals

Tuple of Vector3D objects for all vertex normals.

property vertices

Tuple of all vertices in this geometry.