ifcopenshell.api.geometry

Create geometric representations and assign them to elements

These functions support both the creation of arbitrary geometry as well as geometry that follows parametric rules (e.g. layered geometry or profiled geometry extrusions).

Submodules

Package Contents

ifcopenshell.api.geometry.add_axis_representation(file: ifcopenshell.file, context: ifcopenshell.entity_instance, axis: tuple[COORD, COORD]) → ifcopenshell.entity_instance

Adds a new axis representation

Certain objects are typically “axis-based”, such as walls, beams, and columns. This means you can represent them abstractly by simply drawing a single line either in 2D (such as for walls) or 3D (for beams and columns). Humans can understand this axis-based representation as being a simplification of a layered extrusion or a profile that is being extruded along that axis and joined to other elements.

Using an axis-based representation makes it easy for users and computers to analyse connectivity and spatial relationships, as well as makes it easy to parametrically edit these objects by simply stretching the start or end of the axis.

For now, only simple straight line axes are supported, represented by a start and end coordinate. The order is important. For walls, the start must be at the minimum local X ordinate, and the end at the maximum local X ordinate. For beams and columns, the start is at the minimum local Z ordinate, and the end of the maximum local Z ordinate. The first coordinate is the “start” and the second coordinate is the “end”. This stat and end is then used to determine any parametric junctions with other elements.

Using an axis-representation is optional, but highly recommended for “standard” representations of walls, beams, columns, and other structural members. A rule of thumb is that if you can draw it as a line on paper, you can probably represent it using an axis.

Parameters:

  • context (ifcopenshell.entity_instance) – The IfcGeometricRepresentationContext that the representation is part of. This must be either a Model/Axis/GRAPH_VIEW (3D) or Plan/Axis/GRAPH_VIEW (2D).

  • axis (list[list[float]]) – The axis, as a list of two coordinates, the coordinates being either a list of 2 or 3 float coordinates depending on whether the axis is 2D or 3D.

Returns:

The newly created IfcShapeRepresentation entity

Return type:

ifcopenshell.entity_instance

Example:

context = ifcopenshell.util.representation.get_context(model, "Plan", "Axis", "GRAPH_VIEW")
axis = ifcopenshell.api.geometry.add_axis_representation(model,
    context=context, axis=[(0.0, 0.0), (1.0, 0.0)])
ifcopenshell.api.geometry.add_boolean(file: ifcopenshell.file, first_item: ifcopenshell.entity_instance, second_items: list[ifcopenshell.entity_instance], operator: Literal['DIFFERENCE', 'INTERSECTION', 'UNION'] = 'DIFFERENCE') → list[ifcopenshell.entity_instance]

Adds a boolean operation to two or more representation items

If an IfcBooleanOperand is part of the top level items in an IfcShapeRepresentation, it will be removed from that level whilst being added to the IfcBooleanResult. This is because it is generally intuitive that an item is either participating in a boolean operation, or being an item in its own right, but not both.

However, if an IfcBooleanOperand is part of another boolean operation already, it will not be removed from the existing operation. A new operation will be created, and therefore it will participate in two operations.

This function protects against recursive booleans.

After a boolean operation is made, since the items of IfcShapeRepresentation may be modified, it is not guaranteed that the RepresentationType is still valid. After performing all your booleans, it is recommended to run ifcopenshell.api.geometry.validate_csg() to ensure correctness.

Parameters:

  • first_item – The IfcBooleanOperand that the operation is performed upon

  • second_items – The IfcBooleanOperands that the operation will be performed with, in the order given of the list.

  • operator – The type of boolean operation to perform

Returns:

A list of newly created IfcBooleanResult in the order of boolean operations (based on the order of second items). If nothing was created, the list will be empty.

ifcopenshell.api.geometry.add_footprint_representation(file, context: ifcopenshell.entity_instance, curves: list[ifcopenshell.entity_instance]) → ifcopenshell.entity_instance
ifcopenshell.api.geometry.add_mesh_representation(file: ifcopenshell.file, context: ifcopenshell.entity_instance, vertices: list[COORD_3D], edges: list[tuple[int, int]] = None, faces: list[list[int]] = None, cooridnate_offset: COORD_3D | None = None, unit_scale: float | None = None, force_faceted_brep: bool = False) → ifcopenshell.entity_instance
ifcopenshell.api.geometry.add_profile_representation(file: ifcopenshell.file, context: ifcopenshell.entity_instance, profile: ifcopenshell.entity_instance, depth: float = 1.0, cardinal_point: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] = 5, clippings: list[ifcopenshell.util.data.Clipping | dict[str, Any]] | None = None, placement_zx_axes: tuple[VECTOR_3D | None, VECTOR_3D | None] = (None, None)) → ifcopenshell.entity_instance
ifcopenshell.api.geometry.add_shape_aspect(file: ifcopenshell.file, name: str, items: list[ifcopenshell.entity_instance], representation: ifcopenshell.entity_instance, part_of_product: ifcopenshell.entity_instance, description: str | None = None) → ifcopenshell.entity_instance

Adds a shape aspect to items that are part of a representation and product

Existing shape aspects will be reused where possible. If the items already belong to another shape aspect with a different name, this relationship will be purged.

Warning: it is not possible to add a shape aspect to types (i.e. IfcRepresentationMap) in IFC2X3.

Parameters:

  • name – The name of the shape aspect. This is case sensitive.

  • items – IfcRepresentationItems that will be assigned to this aspect.

  • representation – The IfcShapeRepresentation that the items are in.

  • part_of_product – The IfcRepresentationMap or IfcProductDefinitionShape that the representation is in.

  • description – A description to set for the shape aspect. It’s usually not necessary.

Returns:

The IfcShapeAspect

ifcopenshell.api.geometry.add_slab_representation(file: ifcopenshell.file, context: ifcopenshell.entity_instance, depth: float = 0.2, direction_sense: str = 'POSITIVE', offset: float = 0.0, x_angle: float = 0.0, clippings: list[ifcopenshell.util.data.Clipping | dict[str, Any]] | None = None, polyline: list[tuple[float, float]] | None = None) → ifcopenshell.entity_instance

Add a geometric representation for a slab.

Parameters:

  • context – The IfcGeometricRepresentationContext for the representation, only Model/Body/MODEL_VIEW type of representations are currently supported.

  • depth – The slab depth, in meters.

  • x_angle – The slope angle along the slab’s X-axis, in radians.

  • clippings – List of planes that define clipping half space solids. Clippings can be Clipping objects or dictionaries of arguments for Clipping.parse.

Returns:

IfcShapeRepresentation.

Example:

context = ifcopenshell.util.representation.get_context(ifc_file, "Model", "Body", "MODEL_VIEW")
clippings = [ifcopenshell.util.data.Clipping(location=(0.0, 0.0, 0.1), normal=(0.0, 0.0, 1.0),)]
representation = ifcopenshell.api.geometry.add_slab_representation(ifc_file, context, depth=0.2, clippings=clippings)
ifcopenshell.api.geometry.assign_representation(ifc_file, product=element, representation=representation)
ifcopenshell.api.geometry.add_wall_representation(file: ifcopenshell.file, context: ifcopenshell.entity_instance, length: float = 1.0, height: float = 3.0, direction_sense: str = 'POSITIVE', offset: float = 0.0, thickness: float = 0.2, x_angle: float = 0.0, clippings: list[ifcopenshell.util.data.Clipping | dict[str, Any]] | None = None, booleans: list[ifcopenshell.entity_instance] | None = None) → ifcopenshell.entity_instance

Add a geometric representation for a wall.

Parameters:

  • context – The IfcGeometricRepresentationContext for the representation, only Model/Body/MODEL_VIEW type of representations are currently supported.

  • length – The length of the wall in meters.

  • height – The height of the wall in meters.

  • offset – The base offset distance of the wall from the origin.

  • thickness – The thickness of the wall in meters.

  • x_angle – The slope angle along the wall’s X-axis, in radians.

  • clippings – List of clipping definitions. Clippings can be Clipping objects or dictionaries of arguments for Clipping.parse.

  • booleans – List of any existing IfcBooleanResults.

Returns:

IfcShapeRepresentation.

ifcopenshell.api.geometry.assign_representation(file: ifcopenshell.file, product: ifcopenshell.entity_instance, representation: ifcopenshell.entity_instance) → None
ifcopenshell.api.geometry.connect_element(file: ifcopenshell.file, relating_element: ifcopenshell.entity_instance, related_element: ifcopenshell.entity_instance, description: str | None = None) → ifcopenshell.entity_instance
ifcopenshell.api.geometry.connect_path(file: ifcopenshell.file, relating_element: ifcopenshell.entity_instance, related_element: ifcopenshell.entity_instance, relating_connection: str = 'NOTDEFINED', related_connection: str = 'NOTDEFINED', description: str | None = None) → ifcopenshell.entity_instance
ifcopenshell.api.geometry.create_2pt_wall(file: ifcopenshell.file, element: ifcopenshell.entity_instance, context: ifcopenshell.entity_instance, p1: tuple[float, float], p2: tuple[float, float], elevation: float, height: float, thickness: float, is_si: bool = True) → ifcopenshell.entity_instance

Create a wall between two points (p1 and p2). A shortcut for geometry.add_wall_representation.

Parameters:

  • element – Wall IFC element.

  • context – IfcGeometricRepresentationContext for the representation. only Model/Body/MODEL_VIEW type of representations are currently supported.

  • p1 – The starting point (x, y) of the wall.

  • p2 – The ending point (x, y) of the wall.

  • elevation – The base elevation (z-coordinate) for the wall.

  • height – The height of the wall.

  • thickness – The thickness of the wall.

  • is_si – If True, provided arguments units are treated as SI (meters). If False, values are converted from project units to SI.

Returns:

IfcShapeRepresentation.

ifcopenshell.api.geometry.disconnect_element(file: ifcopenshell.file, relating_element: ifcopenshell.entity_instance, related_element: ifcopenshell.entity_instance) → None
ifcopenshell.api.geometry.disconnect_path(file: ifcopenshell.file, element: ifcopenshell.entity_instance | None = None, connection_type: str | None = None, relating_element: ifcopenshell.entity_instance | None = None, related_element: ifcopenshell.entity_instance | None = None) → None

There are two options to use this API method: - provide element (connected from) and connection_type that should be disconnected. - provide connected elements to disconnect explicitly: relating_element (connected from) and related_element (connected to)

ifcopenshell.api.geometry.edit_object_placement(file: ifcopenshell.file, product: ifcopenshell.entity_instance, matrix: NPArrayOfFloats | None = None, is_si: bool = True, should_transform_children: bool = False) → ifcopenshell.entity_instance
ifcopenshell.api.geometry.map_representation(file: ifcopenshell.file, representation: ifcopenshell.entity_instance) → ifcopenshell.entity_instance
ifcopenshell.api.geometry.remove_boolean(file: ifcopenshell.file, item: ifcopenshell.entity_instance) → None

Removes a boolean operation without deleting the operands

The first operand will replace the boolean result itself, and the second operand will be reset as a top level representation item.

This may affect the Items of IfcShapeRepresentation, so it is recommended to run ifcopenshell.api.geometry.validate_type() after all boolean modifications are complete.

Parameters:

item – This may either be an IfcBooleanResult or an IfcRepresentationItem that is participating in one or more boolean results (in which case all are removed).

ifcopenshell.api.geometry.remove_representation(file: ifcopenshell.file, representation: ifcopenshell.entity_instance, should_keep_named_profiles: bool = True) → None

Remove a representation.

Also purges representation items and their related elements like IfcStyledItem, tessellated facesets colours and UV map.

By default, named profiles are assumed to be significant (i.e. curated as part of a profile library) and will not be removed.

Parameters:

  • representation – IfcRepresentation to remove. Note that it’s expected that IfcRepresentation won’t be in use before calling this method (in such elements as IfcProductRepresentation, IfcShapeAspect) otherwise representation won’t be removed.

  • should_keep_named_profiles – If true, named profile defs will not be removed as they are assumed to be significant.

ifcopenshell.api.geometry.unassign_representation(file: ifcopenshell.file, product: ifcopenshell.entity_instance, representation: ifcopenshell.entity_instance) → None
ifcopenshell.api.geometry.validate_type(file: ifcopenshell.file, representation: ifcopenshell.entity_instance, preferred_item: ifcopenshell.entity_instance | None = None) → bool

Validates the RepresentationType of an IfcShapeRepresentation

A shape representation has to identify its geometry using the RepresentationType attribute. For example, if it holds tessellated geometry, it should store “Tessellation” as its RepresentationType.

This function checks whether or not the RepresentationType is valid. This is a wrapper around ifcopenshell.util.representation.guess_type(). It will then set RepresentationType to the most appropriate value, or return False otherwise. In addition, it also attempts to reconcile otherwise invalid CSG geometry by unioning all remaining top level items to existing boolean results.

Parameters:

  • representation – The IfcShapeRepresentation with Items

  • preferred_item – If the type is expected to be a CSG, this will be the preferred item to union all remaining items to. If no preferred item is provided, the first boolean result will be chosen.

Returns:

True if the representation type was set and it is a valid combination, or False otherwise.