Bonsai Spatial Structure Syntax

Version: Bonsai v0.8.x | Blender 4.2.0+ | Python 3.11 Module path: bonsai.* — NEVER blenderbim.* Source files: core/spatial.py, tool/spatial.py, bim/module/spatial/

Critical Warnings

1. ALWAYS use bonsai.* imports. NEVER use blenderbim.* — renamed in 2024 (v0.8.0+).
2. ALWAYS build spatial hierarchy via IfcRelAggregates using ifcopenshell.api.run("aggregate.assign_object", ...). NEVER create spatial elements without connecting them to the hierarchy.
3. ALWAYS use ifcopenshell.api.run("spatial.assign_container", ...) to place physical elements in spatial containers. NEVER set containment via direct attribute manipulation.
4. ALWAYS pass products as a list (v0.8+ breaking change): products=[wall], NOT product=wall.
5. NEVER delete IfcProject — it is the root of every IFC model. Bonsai operators enforce this constraint.
6. ALWAYS set a default container (typically IfcBuildingStorey) before creating elements. Use bpy.ops.bim.set_default_container(container=storey_id).
7. NEVER assign an element to multiple containers via IfcRelContainedInSpatialStructure — an element can only be contained in ONE spatial structure. Use IfcRelReferencedInSpatialStructure for multi-storey references.
8. ALWAYS use ifcopenshell.api.run("root.create_entity", ...) to create spatial elements. NEVER use model.create_entity() — it skips GlobalId generation and ownership assignment.

IFC Spatial Hierarchy