ifcopenshell.util.shape

Module Contents

ifcopenshell.util.shape.get_area(geometry: ifcopenshell.geom.ShapeType) → float

Calculates the surface area of the geometry

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The surface area.

Return type:

float

ifcopenshell.util.shape.get_area_vf(vertices: numpy.typing.NDArray[numpy.float64], faces: numpy.typing.NDArray[numpy.int32]) → float

Calculates the surface area given a list of vertices and triangulated faces

Parameters:

  • vertices – A list of 3D vertices, such as returned from get_vertices.

  • faces – A list of faces, such as returned from get_faces.

Type:

np.array[iterable[float]]

Type:

np.array[iterable[int]]

Returns:

The surface area.

Return type:

float

ifcopenshell.util.shape.get_bbox(vertices: Iterable[VECTOR_3D]) → tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

Gets the bounding box of vertices

Parameters:

vertices – An iterable of vertices

Type:

iterable

Returns:

The bounding box value represented as a tuple of two numpy arrays. The first holds the bottom left corner and the second holds the top right. E.g. (np.array([minx, miny, minz]), np.array([maxx, maxy, maxz]))

Return type:

tuple[np.array[float]]

ifcopenshell.util.shape.get_bbox_centroid(geometry: ifcopenshell.geom.ShapeType) → tuple[float, float, float]

Calculates the bounding box centroid of the geometry

The centroid is in local coordinates relative to the object’s placement.

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

A tuple representing the XYZ centroid

Return type:

tuple[float, float, float]

ifcopenshell.util.shape.get_bottom_elevation(geometry: ifcopenshell.geom.ShapeType) → float

Gets the lowest local Z ordinate of the geometry

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The Z value

Return type:

float

ifcopenshell.util.shape.get_edges(geometry: ifcopenshell.geom.ShapeType) → numpy.typing.NDArray[numpy.int32]

Get all the edges as a numpy array

Results are a nested numpy array e.g. [[e1v1, e1v2], [e2v1, e2v2], …]

Note that although geometry always holds triangulated faces, edges will represent the original tessellation or BRep’s faces, which may be quads or ngons.

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

A numpy array listing all the edges. Each edge is a numpy array with two vertex indices.

Return type:

np.array[np.array[int]]

ifcopenshell.util.shape.get_element_bbox_centroid(element: ifcopenshell.entity_instance, geometry) → numpy.typing.NDArray[numpy.float64]

Calculates the element’s bounding box centroid

The centroid is in global coordinates. Note that if you have the shape, it is more efficient to use get_shape_bbox_centroid.

Parameters:

  • element – The element occurrence

  • geometry (geometry) – Geometry output calculated by IfcOpenShell

Type:

ifcopenshell.entity_instance

Returns:

A tuple representing the XYZ centroid

Return type:

npt.NDArray[np.float64]

ifcopenshell.util.shape.get_element_bottom_elevation(element: ifcopenshell.entity_instance, geometry: ifcopenshell.geom.ShapeType) → float

Gets the lowest global Z ordinate of the element

Note that if you have the shape, it is more efficient to use get_shape_bottom_elevation.

Parameters:

  • element – The element occurrence

  • geometry (geometry) – Geometry output calculated by IfcOpenShell

Type:

ifcopenshell.entity_instance

Returns:

The Z value

Return type:

float

ifcopenshell.util.shape.get_element_top_elevation(element: ifcopenshell.entity_instance, geometry: ifcopenshell.geom.ShapeType) → float

Gets the highest global Z ordinate of the element

Note that if you have the shape, it is more efficient to use get_shape_top_elevation.

Parameters:

  • element – The element occurrence

  • geometry (geometry) – Geometry output calculated by IfcOpenShell

Type:

ifcopenshell.entity_instance

Returns:

The Z value

Return type:

float

ifcopenshell.util.shape.get_element_vertices(element: ifcopenshell.entity_instance, geometry: ifcopenshell.geom.ShapeType) → numpy.typing.NDArray[numpy.float64]

Get the element’s vertices as a numpy array

Vertices are in global coordinates. Note that if you have the shape, it is more efficient to use get_shape_vertices.

Results are a nested numpy array e.g. [[v1x, v1y, v1z], [v2x, v2y, v2z], …]

Parameters:

  • element – The element occurrence

  • geometry (geometry) – Geometry output calculated by IfcOpenShell

Type:

ifcopenshell.entity_instance

Returns:

A numpy array listing all the vertices. Each vertex is a numpy array with XYZ coordinates.

Return type:

np.array[np.array[float]]

ifcopenshell.util.shape.get_extrusions(element: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Gets all extruded area solids used to define an element’s model body geometry

Parameters:

element – The element occurrence

Type:

ifcopenshell.entity_instance

Returns:

A list of extrusion representation items

Return type:

list[ifcopenshell.entity_instance]

ifcopenshell.util.shape.get_faces(geometry: ifcopenshell.geom.ShapeType) → numpy.typing.NDArray[numpy.int32]

Get all the faces as a numpy array

Faces are always triangulated. If the shape is a BRep and you want to get the original untriangulated output, refer to get_edges.

Results are a nested numpy array e.g. [[f1v1, f1v2, f1v3], [f2v1, f2v2, f2v3], …]

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

A numpy array listing all the faces. Each face is a numpy array with three vertex indices.

Return type:

np.array[np.array[int]]

ifcopenshell.util.shape.get_footprint_area(geometry: ifcopenshell.geom.ShapeType, axis: AXIS_LITERAL = 'Z', direction: VECTOR_3D | None = None) → float

Calculates the total footprint (i.e. projected) surface area visible from along an axis

This is typically useful for calculating footprint areas. For example, you might want to calculate the top-down footprint area of a slab, ignoring slopes in the slab.

Surfaces do not need to be exactly perpendicular in the direction of the specified axis. A surface is counted so long as it is visible from that axis.

Note that this calculates the 2D projected area, not the actual surface area. If you want the actual area, use get_side_area.

Parameters:

  • geometry (geometry) – Geometry output calculated by IfcOpenShell

  • axis (iterable[float],optional) – Either X, Y, or Z. Defaults to Z.

  • direction – An XYZ iterable (e.g. (0., 0., 1.)). If a direction vector is specified, this overrides the axis argument.

Returns:

The surface area.

Return type:

float

ifcopenshell.util.shape.get_footprint_perimeter(geometry: ifcopenshell.geom.ShapeType) → float

Calculates the footprint perimeter of the geometry

All faces with a negative Z normal are considered and the distance of all perimeter edges are totaled.

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The perimeter length

Return type:

float

ifcopenshell.util.shape.get_max_side_area(geometry: ifcopenshell.geom.ShapeType) → float

Returns the maximum X, Y, or Z side area

See get_side_area() for how side area is calculated.

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The maximum surface area from either the X, Y, or Z axis.

Return type:

float

ifcopenshell.util.shape.get_max_xy(geometry: ifcopenshell.geom.ShapeType) → float

Gets the maximum X or Y length of the geometry

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The maximum possible value out of the X and Y dimension

Return type:

float

ifcopenshell.util.shape.get_max_xyz(geometry: ifcopenshell.geom.ShapeType) → float

Gets the maximum X, Y, or Z length of the geometry

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The maximum possible value out of the X, Y, and Z dimension

Return type:

float

ifcopenshell.util.shape.get_min_xyz(geometry: ifcopenshell.geom.ShapeType) → float

Gets the minimum X, Y, or Z length of the geometry

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The minimum possible value out of the X, Y, and Z dimension

Return type:

float

ifcopenshell.util.shape.get_outer_surface_area(geometry: ifcopenshell.geom.ShapeType) → float

Calculates the outer surface area (i.e. all sides except for top and bottom)

This is typically useful for calculating painted areas of beams which exclude the end faces (at the minimum and maximum local Z).

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The surface area.

Return type:

float

ifcopenshell.util.shape.get_profiles(element: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Gets all 2D profiles used in the definition of a parametric shape

Profiles may be retrieved either from material profile sets or from swept solid extrusions. This is useful for later doing 2D take-off from profiles.

Parameters:

element – The element occurrence

Type:

ifcopenshell.entity_instance

Returns:

A list of profiles

Return type:

list[ifcopenshell.entity_instance]

ifcopenshell.util.shape.get_representation_item_ids(geometry: ifcopenshell.geom.ShapeType) → numpy.typing.NDArray[numpy.int32]

Get representation item ids for the geometry faces.

ifcopenshell.util.shape.get_shape_bbox_centroid(shape: ifcopenshell.geom.ShapeType, geometry: ifcopenshell.geom.ShapeType) → numpy.typing.NDArray[numpy.float64]

Calculates the shape’s bounding box centroid

The centroid is in global coordinates. Note that if you do not have the shape, you can use get_element_bbox_centroid.

Parameters:

  • shape (shape) – Shape output calculated by IfcOpenShell

  • geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

A tuple representing the XYZ centroid

Return type:

npt.NDArray[np.float64]

ifcopenshell.util.shape.get_shape_bottom_elevation(shape: ifcopenshell.geom.ShapeType, geometry: ifcopenshell.geom.ShapeType) → float

Gets the lowest global Z ordinate of the shape

If you do not have the shape, you can use get_element_bottom_elevation instead.

Parameters:

  • shape (shape) – Shape output calculated by IfcOpenShell

  • geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The Z value

Return type:

float

ifcopenshell.util.shape.get_shape_matrix(shape: ifcopenshell.geom.ShapeElementType) → MatrixType

Formats the transformation matrix of a shape as a 4x4 numpy array

Parameters:

shape (shape) – Shape output calculated by IfcOpenShell

Returns:

A 4x4 numpy array representing the transformation matrix

Return type:

MatrixType

ifcopenshell.util.shape.get_shape_top_elevation(shape: ifcopenshell.geom.ShapeType, geometry: ifcopenshell.geom.ShapeType) → float

Gets the highest global Z ordinate of the shape

If you do not have the shape, you can use get_element_top_elevation instead.

Parameters:

  • shape (shape) – Shape output calculated by IfcOpenShell

  • geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The Z value

Return type:

float

ifcopenshell.util.shape.get_shape_vertices(shape: ifcopenshell.geom.ShapeType, geometry: ifcopenshell.geom.ShapeType) → numpy.typing.NDArray[numpy.float64]

Get the shape’s vertices as a numpy array

Vertices are in global coordinates. If you do not have the shape, you can use get_element_vertices.

Results are a nested numpy array e.g. [[v1x, v1y, v1z], [v2x, v2y, v2z], …]

Parameters:

  • shape (shape) – Shape output calculated by IfcOpenShell

  • geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

A numpy array listing all the vertices. Each vertex is a numpy array with XYZ coordinates.

Return type:

np.array[np.array[float]]

ifcopenshell.util.shape.get_side_area(geometry: ifcopenshell.geom.ShapeType, axis: AXIS_LITERAL = 'Y', direction: VECTOR_3D | None = None) → float

Calculates the total surface area of surfaces that are visible from the specified axis

This is typically useful for calculating elevational areas. For example, you might want to calculate the side area of a wall (i.e. only one side, not both).

Surfaces do not need to be exactly perpendicular in the direction of the specified axis. A surface is counted so long as it is visible from that axis.

Note that this calculates the actual area, not the projected 2D area. If you want the projected area, use get_footprint_area.

Parameters:

  • geometry (geometry) – Geometry output calculated by IfcOpenShell

  • axis (str) – Either X, Y, or Z. Defaults to Y, which is used for standard walls.

Returns:

The surface area.

Return type:

float

ifcopenshell.util.shape.get_top_elevation(geometry: ifcopenshell.geom.ShapeType) → float

Gets the highest local Z ordinate of the geometry

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The Z value

Return type:

float

ifcopenshell.util.shape.get_total_edge_length(geometry: ifcopenshell.geom.ShapeType) → float

Calculates the total length of edges in a given geometry.

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The total length of all edges in the geometry.

Return type:

float

ifcopenshell.util.shape.get_vert_centroid(geometry: ifcopenshell.geom.ShapeType) → tuple[float, float, float]

Calculates the average vertex centroid of the geometry

The centroid is in local coordinates relative to the object’s placement.

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

A tuple representing the XYZ centroid

Return type:

tuple[float, float, float]

ifcopenshell.util.shape.get_vertices(geometry: ifcopenshell.geom.ShapeType) → numpy.typing.NDArray[numpy.float64]

Get all the vertices as a numpy array

Vertices are in local coordinates.

Results are a nested numpy array e.g. [[v1x, v1y, v1z], [v2x, v2y, v2z], …]

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

A numpy array listing all the vertices. Each vertex is a numpy array with XYZ coordinates.

Return type:

np.array[np.array[float]]

ifcopenshell.util.shape.get_volume(geometry: ifcopenshell.geom.ShapeType) → float

Calculates the total internal volume of a geometry

Volumes of non-manifold geometry will be unpredictable.

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The volume in m3

Return type:

float

ifcopenshell.util.shape.get_x(geometry: ifcopenshell.geom.ShapeType) → float

Calculates the X length of the geometry

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The X dimension

Return type:

float

ifcopenshell.util.shape.get_y(geometry: ifcopenshell.geom.ShapeType) → float

Calculates the Y length of the geometry

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The Y dimension

Return type:

float

ifcopenshell.util.shape.get_z(geometry: ifcopenshell.geom.ShapeType) → float

Calculates the Z length of the geometry

Parameters:

geometry (geometry) – Geometry output calculated by IfcOpenShell

Returns:

The Z dimension

Return type:

float

ifcopenshell.util.shape.is_x(value: float, x: float, tolerance: float | None = None) → bool

Checks whether a value is equivalent to X given a tolerance

Parameters:

  • value (float) – Input value

  • x (float) – The value to compare to

  • tolerance (float) – The tolerance to use. Defaults to 1e-6.

Returns:

True or false

Return type:

bool

ifcopenshell.util.shape.AXIS_LITERAL
ifcopenshell.util.shape.MatrixType

npt.NDArray[np.float64]

ifcopenshell.util.shape.VECTOR_3D
ifcopenshell.util.shape.tol = 1e-06