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 – 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 – 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

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_door_representation(file: ifcopenshell.file, *, context: ifcopenshell.entity_instance, overall_height: float | None = None, overall_width: float | None = None, operation_type: DOOR_TYPE = 'SINGLE_SWING_LEFT', lining_properties: DoorLiningProperties | dict[str, Any] | None = None, panel_properties: DoorPanelProperties | dict[str, Any] | None = None, part_of_product: ifcopenshell.entity_instance | None = None, unit_scale: float | None = None) → ifcopenshell.entity_instance | None

Add a geometric representation for a door.

units in usecase_settings expected to be in ifc project units

Parameters:

  • context – IfcGeometricRepresentationContext for the representation.

  • overall_height – Overall door height. Defaults to 2m.

  • overall_width – Overall door width. Defaults to 0.9m.

  • operation_type – Type of the door. Defaults to SINGLE_SWING_LEFT.

  • lining_properties – DoorLiningProperties or a dictionary to create one. See DoorLiningProperties description for details.

  • panel_properties – DoorPanelProperties or a dictionary to create one. See DoorPanelProperties description for details.

  • unit_scale – The unit scale as calculated by ifcopenshell.util.unit.calculate_unit_scale. If not provided, it will be automatically calculated for you.

Returns:

IfcShapeRepresentation for a door.

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[ifcopenshell.util.shape_builder.SequenceOfVectors], edges: list[list[tuple[int, int]]] | None = None, faces: list[list[list[int]]] = None, coordinate_offset: ifcopenshell.util.shape_builder.VectorType | None = None, unit_scale: float | None = None, force_faceted_brep: bool = False) → ifcopenshell.entity_instance

Add a mesh representation.

Vertices, edges, and faces are given in the form of: [item1, item2, item3, ...]. Each itemN is a sublist representing data for a separate IfcRepresentationItem to add.

You can provide either edges or faces, no need to provide both. But currently edges argument is not supported.

Parameters:

  • context – The IfcGeometricRepresentationContext for the representation.

  • vertices – A list of coordinates. where itemN = [(0., 0., 0.), (1., 1., 1.), (x, y, z), ...]

  • edges – A list of edges, represented by vertex index pairs where itemN = [(0, 1), (1, 2), (v1, v2), ...]

  • faces – A list of polygons, represented by vertex indices. where itemN = [(0, 1, 2), (5, 4, 2, 3), (v1, v2, v3, ... vN), ...]

  • coordinate_offset – Optionally apply a vector offset to all coordinates. In project units.

  • unit_scale –

    Scale factor for vertices units.

    If omitted, it is assumed that vertices are in SI units.

    If other value is provided vertices coords will be divided by unit_scale.

  • force_faceted_brep – Force using IfcFacetedBreps instead of IfcPolygonalFaceSets.

Returns:

IfcShapeRepresentation.

ifcopenshell.api.geometry.add_profile_representation(file: ifcopenshell.file, context: ifcopenshell.entity_instance, profile: ifcopenshell.entity_instance, depth: float = 1.0, cardinal_point: CardinalPoint | None = 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

Add profile representation.

Parameters:

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

  • profile – The IfcProfileDef to extrude.

  • depth – The depth of the extrusion in meters.

  • cardinal_point – The cardinal point of the profile.

  • clippings – A list of planes that define clipping half space solids. Planes are defined either by Clipping objects or by dictionaries of arguments for Clipping.parse.

  • placement_zx_axes – A tuple of two vectors that define the placement of the profile. The first vector is the Z axis, the second vector is the X axis.

Returns:

IfcShapeRepresentation.

ifcopenshell.api.geometry.add_railing_representation(file: ifcopenshell.file, *, context: ifcopenshell.entity_instance, railing_type: Literal['WALL_MOUNTED_HANDRAIL'] = 'WALL_MOUNTED_HANDRAIL', railing_path: ifcopenshell.util.shape_builder.SequenceOfVectors, use_manual_supports: bool = False, support_spacing: float | None = None, railing_diameter: float | None = None, clear_width: float | None = None, terminal_type: TERMINAL_TYPE = '180', height: float | None = None, looped_path: bool = False, unit_scale: float | None = None) → ifcopenshell.entity_instance

Units are expected to be in IFC project units.

Parameters:

  • context – IfcGeometricRepresentationContext for the representation.

  • railing_type – Type of the railing. Defaults to “WALL_MOUNTED_HANDRAIL”.

  • railing_path – A list of points coordinates for the railing path, coordinates are expected to be at the top of the railing, not at the center. If not provided, default path [(0, 0, 1), (1, 0, 1), (2, 0, 1)] (in meters) will be used

  • use_manual_supports – If enabled, supports are added on every vertex on the edges of the railing path. If disabled, supports are added automatically based on the support spacing. Default to False.

  • support_spacing – Distance between supports if automatic supports are used. Defaults to 1m.

  • railing_diameter – Railing diameter. Defaults to 50mm.

  • clear_width – Clear width between the railing and the wall. Defaults to 40mm.

  • terminal_type – type of the cap. Defaults to “180”.

  • height – defaults to 1m

  • looped_path – Whether to end the railing on the first point of railing_path. Defaults to False.

  • unit_scale – The unit scale as calculated by ifcopenshell.util.unit.calculate_unit_scale. If not provided, it will be automatically calculated for you.

Returns:

IfcShapeRepresentation for a railing.

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 | ifcopenshell.entity_instance] | 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.add_window_representation(file: ifcopenshell.file, *, context: ifcopenshell.entity_instance, overall_height: float | None = None, overall_width: float | None = None, partition_type: WINDOW_TYPE = 'SINGLE_PANEL', lining_properties: WindowLiningProperties | dict[str, Any] | None = None, panel_properties: list[WindowPanelProperties | dict[str, Any]] | None = None, part_of_product: ifcopenshell.entity_instance | None = None, unit_scale: float | None = None) → ifcopenshell.entity_instance

units in usecase_settings expected to be in ifc project units

Parameters:

  • context – IfcGeometricRepresentationContext for the representation.

  • overall_height – Overall window height. Defaults to 0.9m.

  • overall_width – Overall window width. Defaults to 0.6m.

  • partition_type – Type of the window. Defaults to SINGLE_PANEL.

  • lining_properties – WindowLiningProperties or a dictionary to create one. See WindowLiningProperties description for details.

  • panel_properties – A list of WindowPanelProperties or dictionaries to create one. See WindowPanelProperties description for details.

  • unit_scale – The unit scale as calculated by ifcopenshell.util.unit.calculate_unit_scale. If not provided, it will be automatically calculated for you.

Returns:

IfcShapeRepresentation for a window.

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.connect_wall(file: ifcopenshell.file, wall1: ifcopenshell.entity_instance, wall2: ifcopenshell.entity_instance, is_atpath: bool = False) → ifcopenshell.entity_instance | None
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

Changes the object placement matrix of an element

The placement matrix is a 4x4 matrix describing the location and orientation of an element in 3D. See https://docs.ifcopenshell.org/ifcopenshell-python/geometry_creation.html#object-placements for more details.

This only supports local placements. Grid and linear placements are not supported.

Parameters:

  • matrix – A 4x4 matrix in numpy. If left blank, it is the identity matrix (equivalent to np.eye(4)).

  • is_si – If True, the matrix is given in SI units. If false, in project units.

  • should_transform_children – A child element is a nested element, opening, filling, etc. If true, child elements will move along with the parent. If false, child elements will stay where they are. Because most placements in IFC are relative, this means that if a child moves, we actually don’t change their placement.

Returns:

The new or updated IfcLocalPlacement entity

ifcopenshell.api.geometry.map_representation(file: ifcopenshell.file, representation: ifcopenshell.entity_instance) → ifcopenshell.entity_instance
ifcopenshell.api.geometry.regenerate_wall_representation(file: ifcopenshell.file, wall: ifcopenshell.entity_instance, length: float = 1.0, height: float = 1.0, angle: float | None = None) → ifcopenshell.entity_instance

Regenerate the body representation of a wall taking into account connections.

IFC defines how a standard (case) wall should behave that has a material layer set and connections to other walls using IfcRelConnectsPathElements. This function will regenerate the body geometry of a wall taking into account the notches, butts, mitres, etc in the wall due to connections with other walls.

A standard wall has a 2D axis line as well as parameters defined in terms of layer thicknesses and priorities. The body geometry is defined as a 2D XY profile which is extruded in the +Z direction. For this function to work, a wall must have these defined and the project must have an axis and body representation context.

For non-sloped walls, a 2D profile is generated and extruded in the +Z direction. The profile may be a composite profile, if the wall is split due to wall joins along the path of the wall that protrude all the way through the wall.

For sloped walls, a basic rectangular 2D profile is extruded, and then additional extrusions are generated for each connection that boolean difference the base extrusion.

This will also update the axis line representation (e.g. trim the axis line to any connections).

The wall’s object placement will also be updated such that the placement is equivalent to the axis line’s start point (which therefore becomes (0.0, 0.0)). This is a logical, consistent, and useful placement coordinate (especially for apps that can pivot using this point).

All this functionality relies on the Plan/Axis/GRAPH_VIEW representation context. It will be created if it does not exist.

Parameters:

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

  • length – If the wall doesn’t have an axis length, this is the default length in SI units.

  • height – If the wall doesn’t already have a height, this is the default height in SI units.

  • angle – If the wall doesn’t already have a slope, this is the default angle in radians. Left as none or 0 defines no slope.

Returns:

The newly generated body IfcShapeRepresentation

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.