Module Contents#

class ifcopenshell.api.spatial.reference_structure.Usecase(file, product=None, relating_structure=None)#

Denote that a product is related to a spatial structure

This is similar to ifcopenshell.api.spatial.assign_container, except that containment can only occur between a product and a single spatial structure element. This is fine if a wall is on level 1, but not appropriate if you have a multistorey column on multiple levels, or a door with a to and from space, or a stair going from one floor to another floor. This is where spatial referencing is used.

Typically, the product will be contained in the lowermost, constructed first, or primarily accessible space. For a multistorey column or stair, the column or stair will therefore be contained in the lowermost storey. Then, any other storeys will be referenced.

Referencing is non-hierarchical, so a door may be referenced in multiple spaces simultaneously.

  • product (ifcopenshell.entity_instance.entity_instance) – The physical IfcElement that exists in the space.

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


The IfcRelReferencedInSpatialStructure relationship instance

Return type



project = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcProject")
site = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcSite")
building = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuilding")
storey1 = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuildingStorey")
storey2 = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuildingStorey")
storey3 = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuildingStorey")

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

# The site has a building, the building has a storey, and the storey has a space
ifcopenshell.api.run("aggregate.assign_object", model, product=building, relating_object=site)
ifcopenshell.api.run("aggregate.assign_object", model, product=storey, relating_object=building)
ifcopenshell.api.run("aggregate.assign_object", model, product=space, relating_object=storey)

# Create a column, this column spans 3 storeys
column = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWall")

# The column is contained in the lowermost storey
ifcopenshell.api.run("spatial.assign_container", model, product=column, relating_structure=storey1)

# And referenced in the others
ifcopenshell.api.run("spatial.reference_structure", model, product=column, relating_structure=storey2)
ifcopenshell.api.run("spatial.reference_structure", model, product=column, relating_structure=storey3)