ifcopenshell.util.element#

Module Contents#

ifcopenshell.util.element.batch_remove_deep2(ifc_file)#

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.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, element)#

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

GlobalIds are regenerated.

Parameters
Returns

The newly copied element

Return type

ifcopenshell.entity_instance.entity_instance

ifcopenshell.util.element.copy_deep(ifc_file, element, exclude=None, exclude_callback=None, copied_entities=None)#

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

GlobalIds are regenerated.

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

  • element (ifcopenshell.entity_instance.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.entity_instance]) – 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.entity_instance

ifcopenshell.util.element.get_aggregate(element)#

Retrieves the aggregate parent of an element.

Parameters

element – The IFC element

Returns

The aggregate of the element

Example:

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

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

Example:

element = file.by_type("IfcElementAssembly")[0]
components = ifcopenshell.util.element.get_components(element)
ifcopenshell.util.element.get_container(element, should_get_direct=False, ifc_class=None)#

Retrieves the spatial structure container of an element.

Parameters
  • element (ifcopenshell.entity_instance.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) – 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.

Example:

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

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.entity_instance) – The IFC element

Returns

The decomposition of the element

Return type

list[ifcopenshell.entity_instance.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, layer)#

Get all the elements that are used by a presentation layer

Parameters
Returns

The elements using the geometric representation

Return type

list[ifcopenshell.entity_instance.entity_instance]

ifcopenshell.util.element.get_elements_by_material(ifc_file, material)#

Retrieves the elements related to a material.

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

Parameters
Returns

A list of elements using the to the material

Return type

list[ifcopenshell.entity_instance.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, representation)#

Gets all elements using a geometric representation

Parameters
Returns

The elements using the geometric representation

Return type

list[ifcopenshell.entity_instance.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, style)#

Retrieves the elements whose geometric representation uses a style

Parameters
Returns

The elements related to the style

Return type

list[ifcopenshell.entity_instance.entity_instance]

Example:

style = file.by_type("IfcSurfaceStyle")[0]
elements = ifcopenshell.util.element.get_elements_by_style(file, style)
ifcopenshell.util.element.get_grouped_by(element)#

Retrieves all subelements of an element based on the group.

Parameters

element – The IFC element

Returns

All subelements of the group

Example:

element = file.by_type("IfcGroup")[0]
subelements = ifcopenshell.util.element.get_grouped_by(element)
ifcopenshell.util.element.get_layers(ifc_file, element)#

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
Returns

A list of IfcPresentationLayerAssignment

Return type

list[ifcopenshell.entity_instance.entity_instance]

Example:

element = ifcopenshell.by_type("IfcWall")[0]
layers = ifcopenshell.util.element.get_layers(element)
ifcopenshell.util.element.get_material(element, should_skip_usage=False, should_inherit=True)#

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

Return type

ifcopenshell.entity_instance.entity_instance

Example:

element = ifcopenshell.by_type("IfcWall")[0]
material = ifcopenshell.util.element.get_material(element)
ifcopenshell.util.element.get_materials(element, should_inherit=True)#

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
Returns

The associated materials of the element.

Return type

list[ifcopenshell.entity_instance.entity_instance]

Example:

element = ifcopenshell.by_type("IfcWall")[0]
materials = ifcopenshell.util.element.get_materials(element)
ifcopenshell.util.element.get_nest(element)#

Retrieves the nest parent of an element.

Parameters

element – The IFC element

Returns

The nested whole of the element

Example:

element = file.by_type("IfcBeam")[0]
aggregate = ifcopenshell.util.element.get_nest(element)
ifcopenshell.util.element.get_parts(element)#

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

Parameters

element – The IFC element

Returns

The parts of the element

Example:

element = file.by_type("IfcElementAssembly")[0]
parts = ifcopenshell.util.element.get_parts(element)
ifcopenshell.util.element.get_predefined_type(element)#

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.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, verbose=False)#
ifcopenshell.util.element.get_property(properties, name, verbose=False)#
ifcopenshell.util.element.get_property_definition(definition, prop=None, verbose=False)#
ifcopenshell.util.element.get_pset(element, name, prop=None, psets_only=False, qtos_only=False, should_inherit=True, verbose=False)#

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

dict

Example:

element = ifcopenshell.by_type("IfcWall")[0]
psets_and_qtos = ifcopenshell.util.element.get_pset(element, "Pset_WallCommon")
ifcopenshell.util.element.get_psets(element, psets_only=False, qtos_only=False, should_inherit=True, verbose=False)#

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

Returns

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

Return type

dict

Example:

element = ifcopenshell.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, verbose=False)#
ifcopenshell.util.element.get_quantity(quantities, name, verbose=False)#
ifcopenshell.util.element.get_referenced_structures(element)#

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.entity_instance) – The IFC element

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]#

Gets element shape aspects

Parameters

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

Returns

The associated shape aspects of the element.

Return type

list[ifcopenshell.entity_instance.entity_instance]

Example:

element = ifcopenshell.by_type("IfcWall")[0]
shape_aspect = ifcopenshell.util.element.get_shape_aspects(element)
ifcopenshell.util.element.get_styles(element)#

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.entity_instance) – The element to get the styles of.

Returns

A list of surface styles

Return type

list[ifcopenshell.entity_instance.entity_instance]

Example:

wall = file.by_type("IfcWall")[0]
styles = ifcopenshell.util.element.get_styles(wall)
ifcopenshell.util.element.get_type(element)#

Retrieves the construction type element of an element occurrence

Parameters

element – The element occurrence

Type

ifcopenshell.entity_instance.entity_instance

Returns

The related type element

Return type

ifcopenshell.entity_instance.entity_instance

Example:

element = ifcopenshell.by_type("IfcWall")[0]
element_type = ifcopenshell.util.element.get_type(element)
ifcopenshell.util.element.get_types(type)#

Get all the occurrences of a type element

Parameters

type (ifcopenshell.entity_instance.entity_instance) – The type element

Returns

A list of occurrences of that type

Return type

list[ifcopenshell.entity_instance.entity_instance]

Example:

element_type = ifcopenshell.by_type("IfcWallType")[0]
walls = ifcopenshell.util.element.get_types(element_type)
ifcopenshell.util.element.has_element_reference(value, element)#
ifcopenshell.util.element.remove_deep(ifc_file, element)#

Recursively purges a subgraph safely.

Do not use, use remove_deep2() instead.

ifcopenshell.util.element.remove_deep2(ifc_file, element, also_consider=[], do_not_delete=[])#

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
ifcopenshell.util.element.replace_attribute(element, old, new)#
ifcopenshell.util.element.unbatch_remove_deep2(ifc_file)#

Finish removing elements batched from remove_deep2 using string replacement

See documentation for batch_remove_deep2.

Parameters

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

Returns

A newly loaded file with the elements removed.

Return type

ifcopenshell.file.file