ifcopenshell.api.spatial.assign_container

Module Contents

ifcopenshell.api.spatial.assign_container.assign_container(file: ifcopenshell.file, products: list[ifcopenshell.entity_instance], relating_structure: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Assigns products to be contained hierarchically in a space

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. See ifcopenshell.api.aggregate.assign_object for more details about aggregation.

The IfcProject will be “decomposed” into spatial structure elements. These are virtual spaces like stes, buildings, storeys, and spaces (i.e. rooms). You can’t physically touch these spaces, but you can touch the products contained within these spaces.

To state that a product is contained in a space, you will use a “containment” relationship. Containment is a very common relationship used to create the hierarchical spatial decomposition tree. For example, you might say that “This wall is on the third building storey”, or “this table is in the living room space”.

The distinguishing factor between aggregation and containment is that aggregation occurs between objects of the same type (e.g. a large space is made up of smaller spaces), whereas containment is between two different types: explicitly saying that a physical product exists within a virtual space.

Containment is critical in construction management, to know which objects are in which spaces, as often you would divide your construction schedule into storey by storey, or zone by zone. Containment is also critical in facility management, as it indicates through which space equipment may be accessed for maintenance purposes.

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.

Parameters:

• products (list[ifcopenshell.entity_instance]) – A list of physical IfcElements existing in the space.

• relating_structure – The IfcSpatialStructureElement element, such as IfcBuilding, IfcBuildingStorey, or IfcSpace that the element exists in.

Returns:

The IfcRelContainedInSpatialStructure 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")
site = ifcopenshell.api.root.create_entity(model, ifc_class="IfcSite")
building = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuilding")
storey = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuildingStorey")
space = ifcopenshell.api.root.create_entity(model, ifc_class="IfcSpace")

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

# The site has a building, the building has a storey, and the storey has a space
ifcopenshell.api.aggregate.assign_object(model, products=[building], relating_object=site)
ifcopenshell.api.aggregate.assign_object(model, products=[storey], relating_object=building)
ifcopenshell.api.aggregate.assign_object(model, products=[space], relating_object=storey)

# Create a wall and furniture
wall = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")
furniture = ifcopenshell.api.root.create_entity(model, ifc_class="IfcFurniture")

# The wall is in the storey, and the furniture is in the space
ifcopenshell.api.spatial.assign_container(model, products=[wall], relating_structure=storey)
ifcopenshell.api.spatial.assign_container(model, products=[furniture], relating_structure=space)