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¶
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)