ifcopenshell.api.root

Create, copy, or remove physical elements such as walls, doors, slabs, etc

This is one of the most used API modules and should be used any time you want to create, remove, copy, or change a physical or spatial element. See create_entity() to get started.

This module should also be used to create types. To then associate types with elements, see ifcopenshell.api.type.

Submodules

• ifcopenshell.api.root.copy_class
• ifcopenshell.api.root.create_entity
• ifcopenshell.api.root.reassign_class
• ifcopenshell.api.root.remove_product

Package Contents

ifcopenshell.api.root.copy_class(file: ifcopenshell.file, product: ifcopenshell.entity_instance) → ifcopenshell.entity_instance

Copies a product

The following relationships are also duplicated:

• The copy will have the same object placement coordinates as the original.

• The copy will have duplicated property sets, properties, and quantities

• The copy will have all nested distribution ports copied too

• The copy will be part of the same aggregate

• The copy will be contained in the same spatial structure

• The copy, if it is an occurrence, will have the same type

• Voids are duplicated too

• The copy will have the same material as the original. Parametric material set usages will be copied.

• The copy will be part of the same groups as the original.

Be warned that:

• Representations are _not_ copied. Copying representations is an expensive operation so for now the user is responsible for handling representations.

• Filled voids are not copied, as there is no guarantee that the filling will also be copied.

• Path connectivity is not copied, as there is no guarantee that the connections are still valid.

Parameters:

product – The IfcProduct to copy.

Returns:

The copied product

Return type:

ifcopenshell.entity_instance

Example:

# We have a wall
wall = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")

# And now we have two
wall_copy = ifcopenshell.api.root.copy_class(model, product=wall)

ifcopenshell.api.root.create_entity(file: ifcopenshell.file, ifc_class: str = 'IfcBuildingElementProxy', predefined_type: str | None = None, name: str | None = None) → ifcopenshell.entity_instance

Create a new rooted product

This is a critical function used to create almost any rooted product or product type. If you want to create walls, spaces, buildings, wall types, and so on, use this function.

Just specify the class you want to create, as well as the predefined type and name. It will handle the storage of the predefined type and check whether the predefined type is built-in or custom. It will also generate a valid GlobalId and store ownership history. It will also handle some edge cases for default validity where users might forget to populate some mandatory attributes. For example, doors must define an operation type but many people forget.

Parameters:

• ifc_class (str,optional) – Any rooted IFC class.

• predefined_type (str,optional) – Any built-in or user-defined predefined type that is applicable to that IFC class. For user-defined predefined types just enter in any value and the API will handle it automatically.

• name (str,optional) – The name of the new element.

Returns:

The newly created element based on the specified IFC class.

Return type:

ifcopenshell.entity_instance

Example:

# We have a project.
ifcopenshell.api.root.create_entity(model, ifc_class="IfcProject")

# We have a building.
ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuilding")

# We have a wall.
ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")

# We have a wall type.
ifcopenshell.api.root.create_entity(model, ifc_class="IfcWallType")

ifcopenshell.api.root.reassign_class(file: ifcopenshell.file, product: ifcopenshell.entity_instance, ifc_class: str = 'IfcBuildingElementProxy', predefined_type: str | None = None) → ifcopenshell.entity_instance

Changes the class of a product

If you ever created a wall then realised it’s meant to be something else, this function lets you change the IFC class whilst retaining all other geometry and relationships.

This is especially useful when dealing with poorly classified data from proprietary software with limited IFC capabilities.

If you are reassigning a type, the occurrence classes are also reassigned to maintain validity.

Vice versa, if you are reassigning an occurrence, the type is also reassigned in IFC4 and up. In IFC2X3, this may not occur if the type cannot be unambiguously derived, so you are required to manually check this.

Parameters:

• product (ifcopenshell.entity_instance) – The IfcProduct that you want to change the class of.

• ifc_class (str,optional) – The new IFC class you want to change it to.

• predefined_type (str,optional) – In case you want to change the predefined type too. User defined types are also allowed, just type what you want.

Returns:

The newly modified product.

Return type:

ifcopenshell.entity_instance

Example:

# We have a wall.
wall = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")

# Oh, did I say wall? I meant slab.
slab = ifcopenshell.api.root.reassign_class(model, product=wall, ifc_class="IfcSlab")

# Warning: this will crash since wall doesn't exist any more.
print(wall) # Kaboom.

ifcopenshell.api.root.remove_product(file: ifcopenshell.file, product: ifcopenshell.entity_instance) → None

Removes a product

This is effectively a smart delete function that not only removes a product, but also all of its relationships. It is always recommended to use this function to prevent orphaned data in your IFC model.

This is intended to be used for removing:

• IfcAnnotation

• IfcElement

• IfcElementType

• IfcSpatialElement

• IfcSpatialElementType

For example, geometric representations are removed. Placement coordinates are also removed. Properties are removed. Material, type, containment, aggregation, and nesting relationships are removed (but naturally, the materials, types, containers, etc themselves remain).

Parameters:

product (ifcopenshell.entity_instance) – The element to remove.

Returns:

None

Return type:

None

Example:

# We have a wall.
wall = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")

# No we don't.
ifcopenshell.api.root.remove_product(model, product=wall)