ifcopenshell.util.element

Module Contents

ifcopenshell.util.element.batch_remove_deep2(ifc_file: ifcopenshell.file) → None

Enable batch removal after running remove_deep2 using serialisation

See #944 and #3226. Removing elements in an IFC graph is slow as a lot of mappings need to be edited. In larger models (>100MB) and when removing many elements (>10000), it is faster to serialise the IFC, remove elements using string replacement, and then reload the modified serialised IFC.

The trade-off is that extra memory will be used, and string replacement only works with remove_deep2 where the removed elements have no inverses. In addition, transaction history will be lost, and any scripts using this method will have to refetch elements from the reloaded IFC and cannot rely on existing variables in memory.

Parameters:

ifc_file (ifcopenshell.file) – The IFC file object

Return type:

None

Example:

element1 = model.by_id(123)
element2 = model.by_id(456)

ifcopenshell.util.element.batch_remove_deep2(model)
ifcopenshell.util.element.remove_deep2(model, element2)

# Notice how we reload the model.
model = ifcopenshell.util.element.unbatch_remove_deep2(model)

print(element1) # Don't call element1!
ifcopenshell.util.element.copy(ifc_file: ifcopenshell.file, element: ifcopenshell.entity_instance) → ifcopenshell.entity_instance

Copy a single element. Any referenced elements are not copied.

GlobalIds are regenerated.

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file object

  • element (ifcopenshell.entity_instance) – The IFC element to copy

Returns:

The newly copied element

Return type:

ifcopenshell.entity_instance

ifcopenshell.util.element.copy_deep(ifc_file: ifcopenshell.file, element: ifcopenshell.entity_instance, exclude: list[str] | None = None, exclude_callback: Callable[[ifcopenshell.entity_instance], bool] | None = None, copied_entities: dict[int, ifcopenshell.entity_instance] | None = None) → ifcopenshell.entity_instance

Recursively copy an element and all of its directly related subelements.

GlobalIds are regenerated.

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file object

  • element (ifcopenshell.entity_instance) – The IFC element to copy

  • exclude (list[str],optional) – An optional list of strings of IFC class names to not copy. If any of the subelement is this class, it will not be copied and the original instance will be referenced.

  • exclude_callback (function,optional) – A callback to determine whether or not to exclude an entity or not. Returns True to exclude and False to exclude.

  • copied_entities (dict[int:ifcopenshell.entity_instance], optional) – A dictionary of IDs as keys and entities as values to reuse when coming across the same entity twice. This can typically be left as None.

Returns:

The newly copied element

Return type:

ifcopenshell.entity_instance

ifcopenshell.util.element.get_aggregate(element: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Retrieves the aggregate parent of an element.

Parameters:

element (ifcopenshell.entity_instance) – The IFC element

Returns:

The aggregate of the element

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

element = file.by_type("IfcBeam")[0]
aggregate = ifcopenshell.util.element.get_aggregate(element)
ifcopenshell.util.element.get_components(element: ifcopenshell.entity_instance, include_ports=False) → list[ifcopenshell.entity_instance]

Retrieves the components of an element that have an nest relationship.

For nested ports, see ifcopenshell.util.system.

Parameters:

  • element – The IFC element

  • include_ports (bool,optional) – Default as False. Set to true if you also want to get ports.

Returns:

The components of the element

Return type:

list[ifcopenshell.entity_instance]

Example:

element = file.by_type("IfcElementAssembly")[0]
components = ifcopenshell.util.element.get_components(element)
ifcopenshell.util.element.get_contained(element: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Retrieves the contained elements of spatial element.

Parameters:

element (ifcopenshell.entity_instance) – The IFC element

Returns:

The parts of the element

Return type:

list[ifcopenshell.entity_instance]

Example:

element = file.by_type("IfcBuildingStorey")[0]
elements = ifcopenshell.util.element.get_contained(element)
ifcopenshell.util.element.get_container(element: ifcopenshell.entity_instance, should_get_direct: bool = False, ifc_class: str | None = None) → ifcopenshell.entity_instance | None

Retrieves the spatial structure container of an element.

Parameters:

  • element (ifcopenshell.entity_instance) – The IFC element

  • should_get_direct (bool) – If True, a result is only returned if the element is directly contained in a spatial structure element. If False, an indirect spatial container may be returned, such as if an element is a part of an aggregate, and then if that aggregate is contained in a spatial structure element.

  • ifc_class (str, optional) – Optionally filter the type of container you’re after. For example, you may be after the storey, not a space.

Returns:

The direct or indirect container of the element or None.

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

element = file.by_type("IfcWall")[0]
container = ifcopenshell.util.element.get_container(element)
ifcopenshell.util.element.get_decomposition(element: ifcopenshell.entity_instance, is_recursive=True) → list[ifcopenshell.entity_instance]

Retrieves all subelements of an element based on the spatial decomposition hierarchy. This includes all subspaces and elements contained in subspaces, parts of an aggreate, all openings, and all fills of any openings.

Parameters:

element (ifcopenshell.entity_instance) – The IFC element

Returns:

The decomposition of the element

Return type:

list[ifcopenshell.entity_instance]

Example:

element = file.by_type("IfcProject")[0]
decomposition = ifcopenshell.util.element.get_decomposition(element)
ifcopenshell.util.element.get_elements_by_layer(ifc_file: ifcopenshell.file, layer: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Get all the elements that are used by a presentation layer

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file

  • layer (ifcopenshell.entity_instance) – The IfcPresentationLayerAssignment layer

Returns:

The elements using the geometric representation

Return type:

list[ifcopenshell.entity_instance]

ifcopenshell.util.element.get_elements_by_material(ifc_file: ifcopenshell.file, material: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Retrieves the elements related to a material.

This includes elements using the material as part of a material set or set usage.

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file

  • material (ifcopenshell.entity_instance) – The IFC Material entity

Returns:

A list of elements using the to the material

Return type:

list[ifcopenshell.entity_instance]

Example:

material = file.by_type("IfcMaterial")[0]
elements = ifcopenshell.util.element.get_elements_by_material(file, material)
ifcopenshell.util.element.get_elements_by_representation(ifc_file: ifcopenshell.file, representation: ifcopenshell.entity_instance) → set[ifcopenshell.entity_instance]

Gets all elements using a geometric representation

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file

  • representation (ifcopenshell.entity_instance) – The IfcShapeRepresentation representation

Returns:

The elements using the geometric representation

Return type:

set[ifcopenshell.entity_instance]

Example:

representation = file.by_type("IfcShapeRepresentation")[0]
elements = ifcopenshell.util.element.get_elements_by_representation(file, representation)
ifcopenshell.util.element.get_elements_by_style(ifc_file: ifcopenshell.file, style: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Retrieves the elements whose geometric representation uses a style

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file

  • style (ifcopenshell.entity_instance) – The IfcPresentationStyle entity

Returns:

The elements related to the style

Return type:

list[ifcopenshell.entity_instance]

Example:

style = file.by_type("IfcSurfaceStyle")[0]
elements = ifcopenshell.util.element.get_elements_by_style(file, style)
ifcopenshell.util.element.get_filled_void(element: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

If the element is filling a void, get the void

Examples include windows and doors which fill a opening inside a wall.

Parameters:

element (ifcopenshell.entity_instance) – The building element, typically a window or door

Returns:

The IfcOpeningElement that it is filling

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

window = file.by_type("IfcWindow")[0]
opening = ifcopenshell.util.element.get_filled_void(window)
ifcopenshell.util.element.get_grouped_by(element: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Retrieves all subelements of an element based on the group.

Parameters:

element (ifcopenshell.entity_instance) – IfcGroup entity

Returns:

All subelements of the group

Return type:

list[ifcopenshell.entity_instance]

Example:

element = file.by_type("IfcGroup")[0]
subelements = ifcopenshell.util.element.get_grouped_by(element)
ifcopenshell.util.element.get_groups(element: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Retrieves the groups of an element.

Parameters:

element – The IFC element

Returns:

List of IfcGroups element is assigned to.

Return type:

list[ifcopenshell.entity_instance]

Example:

wall = file.by_type("IfcWall")[0]
group = ifcopenshell.util.element.get_groups(element)[0]
ifcopenshell.util.element.get_layers(ifc_file: ifcopenshell.file, element: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Get the CAD layers that an element is part of

An element may have portions or all of its geometry assigned to a traditional CAD presentation layer.

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file object

  • element (ifcopenshell.entity_instance) – The IFC element to interrogate

Returns:

A list of IfcPresentationLayerAssignment

Return type:

list[ifcopenshell.entity_instance]

Example:

element = ifcopenshell.by_type("IfcWall")[0]
layers = ifcopenshell.util.element.get_layers(element)
ifcopenshell.util.element.get_material(element: ifcopenshell.entity_instance, should_skip_usage=False, should_inherit=True) → ifcopenshell.entity_instance | None

Gets the material of the element

The material may be a single material, material set (layered, profiled, or constituent), or a material set usage.

Parameters:

  • element (ifcopenshell.entity_instance) – The element to get the material of.

  • should_skip_usage (bool) – If set to True, if the material is a material set usage, the material set itself will be returned. Useful if you don’t care about occurrence usage parameters. If False, the usage will be returned.

  • should_inherit (bool) – If True, any inherited materials from associated types will be considered.

Returns:

The associated material of the element or None.

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

element = ifcopenshell.by_type("IfcWall")[0]
material = ifcopenshell.util.element.get_material(element)
ifcopenshell.util.element.get_materials(element: ifcopenshell.entity_instance, should_inherit: bool = True) → list[ifcopenshell.entity_instance]

Gets individual materials of an element

If the element has a material set, the individual materials of that set are returned as a list.

Parameters:

  • element (ifcopenshell.entity_instance) – The element to get the materials of.

  • should_inherit – If True, any inherited materials from associated types will be considered.

Returns:

The associated materials of the element.

Return type:

list[ifcopenshell.entity_instance]

Example:

element = ifcopenshell.by_type("IfcWall")[0]
materials = ifcopenshell.util.element.get_materials(element)
ifcopenshell.util.element.get_nest(element: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Retrieves the nest parent of an element.

Parameters:

element (ifcopenshell.entity_instance) – The IFC element

Returns:

The nested whole of the element

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

element = file.by_type("IfcBeam")[0]
aggregate = ifcopenshell.util.element.get_nest(element)
ifcopenshell.util.element.get_parent(element: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Get the parent in the spatial heirarchy

IFC features a spatial hierarchy tree of all objects. Each spatial element or physical element must be located inside this hierarchy exactly once.

The top level parent of this tree is the IfcProject, which has no parent.

All children may have parent-child relationships of one of the following types:

  • Spatial containment: a physical object is located in a space

  • Aggregation: a physical object is broken up into parts, or a spatial location is split into sub locations

  • Nesting: components are attached to a host parent

  • Filling: the physical element fills an opening, such as a window filling a hole

  • Voiding: the opening voids another physical element, such as a hole in a wall

Parameters:

element (ifcopenshell.entity_instance) – Any physical or spatial element in the tree

Returns:

Its parent. This must exist for any valid file, or None if we’ve reached the IfcProject.

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

element = file.by_type("IfcWall")[0]
parent = ifcopenshell.util.element.get_parent(element)
ifcopenshell.util.element.get_parts(element: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Retrieves the parts of an element that have an aggregation relationship.

Parameters:

element (ifcopenshell.entity_instance) – The IFC element

Returns:

The parts of the element

Return type:

list[ifcopenshell.entity_instance]

Example:

element = file.by_type("IfcElementAssembly")[0]
parts = ifcopenshell.util.element.get_parts(element)
ifcopenshell.util.element.get_predefined_type(element: ifcopenshell.entity_instance) → str

Retrieves the PrefefinedType attribute of an element.

If the predefined type is user defined, the custom type (such as object type, element type, or process type depending on the class) is returned instead. Predefined types from the associated type element are also considered first.

Parameters:

element (ifcopenshell.entity_instance) – The IFC Element entity

Returns:

The predefined type of the element

Return type:

str

Example:

element = ifcopenshell.by_type("IfcWall")[0]
predefined_type = ifcopenshell.util.element.get_predefined_type(element)
ifcopenshell.util.element.get_properties(properties: list[ifcopenshell.entity_instance], verbose: Literal[False] = False) → dict[str, Any]
ifcopenshell.util.element.get_properties(properties: list[ifcopenshell.entity_instance], verbose: Literal[True]) → dict[str, dict[str, Any]]
ifcopenshell.util.element.get_property(properties: list[ifcopenshell.entity_instance], name: str, verbose: Literal[False] = False) → Any
ifcopenshell.util.element.get_property(properties: list[ifcopenshell.entity_instance], name: str, verbose: Literal[True]) → dict[str, Any]
ifcopenshell.util.element.get_property_definition(definition: ifcopenshell.entity_instance | None, prop: None = None, verbose=False) → dict[str, Any]
ifcopenshell.util.element.get_property_definition(definition: ifcopenshell.entity_instance | None, prop: str, verbose=False) → Any
ifcopenshell.util.element.get_property_definition(definition: None, prop: None = None, verbose: bool = False) → None

if prop name is not provided in prop, will return dict of all available properties otherwise will return the value of the specified prop.

ifcopenshell.util.element.get_pset(element: ifcopenshell.entity_instance, name: str, prop: str | None = None, psets_only: bool = False, qtos_only: bool = False, should_inherit: bool = True, verbose: bool = False) → Any | dict[str, Any]

Retrieve a single property set or single property

This is more efficient than ifcopenshell.util.element.get_psets if you know exactly which property set and property you are after.

If should_inherit is true, the pset “id” only refers to the ID of the occurrence, not the type’s pset.

Parameters:

  • element (ifcopenshell.entity_instance) – The IFC Element entity

  • name (str) – The name of the pset

  • prop (str,optional) – The name of the property

  • psets_only (bool,optional) – Default as False. Set to true if only property sets are needed.

  • qtos_only (bool,optional) – Default as False. Set to true if only quantities are needed.

  • should_inherit (bool,optional) – Default as True. Set to false if you don’t want to inherit property sets from the Type.

Returns:

A dictionary of property names and values, or a single value if a property is specified.

Return type:

Union[Any, dict[str, Any]]

Example:

element = ifc_file.by_type("IfcWall")[0]
psets_and_qtos = ifcopenshell.util.element.get_pset(element, "Pset_WallCommon")
ifcopenshell.util.element.get_psets(element: ifcopenshell.entity_instance, psets_only=False, qtos_only=False, should_inherit=True, verbose=False) → dict[str, dict[str, Any]]

Retrieve property sets, their related properties’ names & values and ids.

If should_inherit is true, the pset “id” only refers to the ID of the occurrence, not the type’s pset.

Parameters:

  • element (ifcopenshell.entity_instance) – The IFC Element entity

  • psets_only (bool,optional) – Default as False. Set to true if only property sets are needed.

  • qtos_only (bool,optional) – Default as False. Set to true if only quantities are needed.

  • should_inherit (bool,optional) – Default as True. Set to false if you don’t want to inherit property sets from the Type.

  • verbose (bool,optional) – More detailed prop values, defaults to False.

Returns:

Key, value pair of psets’ names and their properties’ names & values

Return type:

dict[str, dict[str, Any]]

Example:

element = ifc_file.by_type("IfcWall")[0]
psets = ifcopenshell.util.element.get_psets(element, psets_only=True)
qsets = ifcopenshell.util.element.get_psets(element, qtos_only=True)
psets_and_qtos = ifcopenshell.util.element.get_psets(element)
ifcopenshell.util.element.get_quantities(quantities: list[ifcopenshell.entity_instance], verbose: Literal[False] = False) → dict[str, Any]
ifcopenshell.util.element.get_quantities(quantities: list[ifcopenshell.entity_instance], verbose: Literal[True]) → dict[str, dict[str, Any]]
ifcopenshell.util.element.get_quantity(quantities: list[ifcopenshell.entity_instance], name: str, verbose: Literal[False] = False) → Any
ifcopenshell.util.element.get_quantity(quantities: list[ifcopenshell.entity_instance], name: str, verbose: Literal[True]) → dict[str, Any]
ifcopenshell.util.element.get_referenced_elements(reference: ifcopenshell.entity_instance) → set[ifcopenshell.entity_instance]

Get all elements with assigned reference

Parameters:

reference (ifcopenshell.entity_instance) – IfcExternalReference/IfcExternalInformation subtype reference

Returns:

The elements with assigned reference

Return type:

set[ifcopenshell.entity_instance]

Example:

reference = file.by_type("IfcClassificationReference")[0]
elements = ifcopenshell.util.element.get_referenced_elements(reference)
ifcopenshell.util.element.get_referenced_structures(element: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Retreives a list of referenced spatial elements

Typically useful for multistorey elements, such as columns or facade elements, or elements that span multiple spaces or in-between spaces, such as stairs, doors, etc.

Parameters:

element (ifcopenshell.entity_instance) – The IFC element

Returns:

A list of IfcSpatialElement

Return type:

list[ifcopenshell.entity_instance]

Example:

element = file.by_type("IfcWall")[0]
print(ifcopenshell.util.element.get_referenced_structures(element))
ifcopenshell.util.element.get_shape_aspects(element: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Get element’s shape aspects.

Parameters:

element – IfcProduct or IfcTypeProduct.

Returns:

The associated shape aspects of the element.

Example:

element = ifcopenshell.by_type("IfcWall")[0]
shape_aspect = ifcopenshell.util.element.get_shape_aspects(element)
ifcopenshell.util.element.get_structure_referenced_elements(structure: ifcopenshell.entity_instance) → set[ifcopenshell.entity_instance]

Retreives a set of elements referenced by a structure

Parameters:

structure – IfcSpatialElement

Returns:

A set of referenced elements, IfcSpatialReferenceSelect

Return type:

set[ifcopenshell.entity_instance]

Example:

element = file.by_type("IfcBuildingStorey")[0]
print(ifcopenshell.util.element.get_structure_referenced_elements(element))
ifcopenshell.util.element.get_styles(element: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Retrieves the styles used in an element’s representation.

Styles may be retreived from the material or the body representation.

Parameters:

element (ifcopenshell.entity_instance) – The element to get the styles of.

Returns:

A list of surface styles

Return type:

list[ifcopenshell.entity_instance]

Example:

wall = file.by_type("IfcWall")[0]
styles = ifcopenshell.util.element.get_styles(wall)
ifcopenshell.util.element.get_type(element: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Retrieves the construction type element of an element occurrence.

Note: get_type(type_element) == type_element.

Parameters:

element – The element occurrence

Type:

ifcopenshell.entity_instance

Returns:

The related type element

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

element = ifcopenshell.by_type("IfcWall")[0]
element_type = ifcopenshell.util.element.get_type(element)
ifcopenshell.util.element.get_types(type: ifcopenshell.entity_instance) → list[ifcopenshell.entity_instance]

Get all the occurrences of a type element

Parameters:

type (ifcopenshell.entity_instance) – The type element

Returns:

A list of occurrences of that type

Return type:

list[ifcopenshell.entity_instance]

Example:

element_type = ifcopenshell.by_type("IfcWallType")[0]
walls = ifcopenshell.util.element.get_types(element_type)
ifcopenshell.util.element.get_voided_element(element: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

For an opening, get the building element that the opening is voiding

For all valid models, this should never return None.

Parameters:

element (ifcopenshell.entity_instance) – The IfcOpeningElement

Returns:

The building element, such as a wall or slab

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

opening = file.by_type("IfcOpeningElement")[0]
element = ifcopenshell.util.element.get_voided_element(opening)
ifcopenshell.util.element.has_element_reference(value: Any, element: ifcopenshell.entity_instance) → bool
ifcopenshell.util.element.remove_deep(ifc_file: ifcopenshell.file, element: ifcopenshell.entity_instance) → None

Recursively purges a subgraph safely.

Do not use, use remove_deep2() instead.

ifcopenshell.util.element.remove_deep2(ifc_file: ifcopenshell.file, element: ifcopenshell.entity_instance, also_consider: list[ifcopenshell.entity_instance] = [], do_not_delete: list[ifcopenshell.entity_instance] = []) → None

Recursively purges a subgraph safely, starting at an element

This should always be used instead of remove_deep. See #1812. The start element must have no inverses. The subgraph to be purged is calculated using all forward relationships determined by the traverse() function.

The deletion process starts at element and traverses forward through the subgraph. Each subelement is checked for any inverses outside the subgraph. If there are no inverses outside, it may be safely purged. If there are inverses that aren’t part of this subgraph, that subelement, and all of its subelements (i.e. that entire branch of subelements) will not be deleted as it is used elsewhere.

For simple subgraphs, traverse() is sufficient to fully represent all related subelements. When it isn’t, the also_consider argument may be used. These are typically inverses futher down the subelement chain.

Note that remove_deep2 will _not_ remove elements in also_consider. Instead, it is only used as a consideration for whether or not an element has all inverses fully contained in the subgraph.

The do_not_delete argument contains all elements that may be part of the subgraph but are protected from deletion.

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file object

  • also_consider (list[ifcopenshell.entity_instance], optional) – elements to also consider as a part of a subgraph

  • do_not_delete (list[ifcopenshell.entity_instance], optional) – elements to protect from deletion

  • element (ifcopenshell.entity_instance) – The starting element that defines the subgraph

ifcopenshell.util.element.replace_attribute(element: ifcopenshell.entity_instance, old: Any, new: Any) → None
ifcopenshell.util.element.unbatch_remove_deep2(ifc_file: ifcopenshell.file) → ifcopenshell.file

Finish removing elements batched from remove_deep2 using string replacement

See documentation for batch_remove_deep2.

Parameters:

ifc_file (ifcopenshell.file) – The IFC file object

Returns:

A newly loaded file with the elements removed.

Return type:

ifcopenshell.file

ifcopenshell.util.element.MATERIAL_TYPE
ifcopenshell.util.element.REFERENCE_TYPES: dict[str, ReferenceData]
ifcopenshell.util.element.ReferenceData