ifcopenshell.api.spatial.reference_structure

Module Contents

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

Denote that a list products is related to a list of spatial structures

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.

Parameters:

• products (list[ifcopenshell.entity_instance]) – The list of physical IfcElements that exists in the space.

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

Returns:

The IfcRelReferencedInSpatialStructure relationship instance or None if products was an empty list.

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

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, products=[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, products=[building], relating_object=site)
ifcopenshell.api.run("aggregate.assign_object", model, products=[storey], relating_object=building)
ifcopenshell.api.run("aggregate.assign_object", model, products=[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, products=[column], relating_structure=storey1)

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