ifcopenshell.api.aggregate¶
Aggregates are the concept of breaking down larger wholes into smaller parts.
One common use is spatial elements, such as how a site has multiple buildings, and a building has multiple storeys. Another is for regular elements, such as how a wall is made out of members and coverings.
Submodules¶
Package Contents¶
- ifcopenshell.api.aggregate.assign_object(file: ifcopenshell.file, products: list[ifcopenshell.entity_instance], relating_object: ifcopenshell.entity_instance) ifcopenshell.entity_instance | None¶
Assigns object as an aggregate to the products
All physical IFC model elements must be part of a hierarchical tree called the “spatial decomposition”, where large things are made up of smaller things. This tree always begins at an “IfcProject” and is then broken down using “decomposition” relationships, of which aggregation is the first relationship you will use.
Typically used when you want to describe how large spaces are made up of smaller spaces. For example large spatial elements (e.g. sites, buidings) can be made out of smaller spatial elements (e.g. storeys, spaces).
The largest space (typically the IfcSite) can then be aggregated in a project. It is requirement for all spatial structures to be directly or indirectly aggregated back to the IfcProject to create a hierarchy of spaces.
The other common usecase is when larger physical products are made up of smaller physical products. For example, a stair might be made out of a flight, a landing, a railing and so on. Or a wall might be made out of stud members, and coverings.
As a product may only have a single location in the “spatial decomposition” tree, assigning an aggregate relationship will remove any previous aggregation, containment, or nesting relationships it may have.
IFC placements follow a convention where the placement is relative to its parent in the spatial hierarchy. If your product has a placement, its placement will be recalculated to follow this convention.
- Parameters:
products – The list of parts of the aggregate, typically of IfcElement or IfcSpatialStructureElement subclass
relating_object (ifcopenshell.entity_instance) – The whole of the aggregate, typically an IfcElement or IfcSpatialStructureElement subclass
- Returns:
The IfcRelAggregate relationship instance or None if products was empty list.
- Return type:
Example:
project = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcProject") element = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcSite") subelement = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuilding") # The project contains a site (note that project aggregation is a special case in IFC) ifcopenshell.api.run("aggregate.assign_object", model, products=[element], relating_object=project) # The site has a building ifcopenshell.api.run("aggregate.assign_object", model, products=[subelement], relating_object=element)
- ifcopenshell.api.aggregate.unassign_object(file: ifcopenshell.file, products: list[ifcopenshell.entity_instance]) None¶
Unassigns products from their aggregate
A product (i.e. a smaller part of a whole) may be aggregated into zero or one larger space or element. This function will remove that aggregation relationship.
As all physical IFC model elements must be part of a hierarchical tree called the “spatial decomposition”, using this function will remove the product from that tree. This is a dangerous operation and may result in the product no longer being visible in IFC applications.
If the product is not part of an aggregation relationship, nothing will happen.
- Parameters:
products – The list of parts of the aggregate, typically of IfcElements or IfcSpatialStructureElement subclass
- Returns:
None
- Return type:
None
Example:
element = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcSite") subelement1 = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuilding") subelement2 = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuilding") ifcopenshell.api.run("aggregate.assign_object", model, products=[subelement1], relating_object=element) ifcopenshell.api.run("aggregate.assign_object", model, products=[subelement2], relating_object=element) # nothing is returned ifcopenshell.api.run("aggregate.unassign_object", model, products=[subelement1]) # nothing is returned, relationship is removed ifcopenshell.api.run("aggregate.unassign_object", model, products=[subelement2])