ifcopenshell.api.aggregate

Aggregates is the concept of breaking down larger wholes into smaller parts.

For example, spatial elements such as sites are broken down into one or more buildings, and a building is broken down into storeys. Another example is for physical elements, such as how a wall is made out of members and coverings.

Submodules

• ifcopenshell.api.aggregate.assign_object
• ifcopenshell.api.aggregate.unassign_object

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:

Union[ifcopenshell.entity_instance, None]

Example:

project = ifcopenshell.api.root.create_entity(model, ifc_class="IfcProject")
element = ifcopenshell.api.root.create_entity(model, ifc_class="IfcSite")
subelement = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuilding")

# The project contains a site (note that project aggregation is a special case in IFC)
ifcopenshell.api.aggregate.assign_object(model, products=[element], relating_object=project)

# The site has a building
ifcopenshell.api.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.root.create_entity(model, ifc_class="IfcSite")
subelement1 = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuilding")
subelement2 = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuilding")
ifcopenshell.api.aggregate.assign_object(model, products=[subelement1], relating_object=element)
ifcopenshell.api.aggregate.assign_object(model, products=[subelement2], relating_object=element)
# nothing is returned
ifcopenshell.api.aggregate.unassign_object(model, products=[subelement1])
# nothing is returned, relationship is removed
ifcopenshell.api.aggregate.unassign_object(model, products=[subelement2])