ifcopenshell.api.spatial

Assign spatial relationships such as when an element is in a space

Physical elements (walls, doors, etc) may be contained in or reference spatial elements (spaces, storeys, buildings, etc).

Submodules

• ifcopenshell.api.spatial.assign_container
• ifcopenshell.api.spatial.dereference_structure
• ifcopenshell.api.spatial.reference_structure
• ifcopenshell.api.spatial.unassign_container

Package Contents

ifcopenshell.api.spatial.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)

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

Dereferences a list of products and space

Parameters:

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

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

Returns:

None

Return type:

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")
storey1 = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuildingStorey")
storey2 = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuildingStorey")
storey3 = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuildingStorey")

# 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 column, this column spans 3 storeys
column = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")

# The column is contained in the lowermost storey
ifcopenshell.api.spatial.assign_container(model, products=[column], relating_structure=storey1)

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

# Actually, it only goes up to storey 2.
ifcopenshell.api.spatial.dereference_structure(model, products=[column], relating_structure=storey3)

ifcopenshell.api.spatial.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.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")
storey1 = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuildingStorey")
storey2 = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuildingStorey")
storey3 = ifcopenshell.api.root.create_entity(model, ifc_class="IfcBuildingStorey")

# 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 column, this column spans 3 storeys
column = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")

# The column is contained in the lowermost storey
ifcopenshell.api.spatial.assign_container(model, products=[column], relating_structure=storey1)

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

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

Unassigns a container from products.

Parameters:

product (list[ifcopenshell.entity_instance]) – A list of IfcProducts to remove the containment from.

Returns:

None

Return type:

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")

# 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)

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

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

# Not anymore!
ifcopenshell.api.spatial.unassign_container(model, products=[wall])