Use when developing Bonsai (formerly BlenderBIM) extensions, scripting BIM workflows in Blender, or understanding the Bonsai addon architecture. Prevents the common mistake of using ifcopenshell.open() to access the model instead of tool.Ifc.get() which gives the live Bonsai IFC file. Covers native IFC workflow, bpy.ops.bim.* operators, BIM property panels, and the relationship between Blender objects and IFC entities. Keywords: Bonsai, BlenderBIM, tool.Ifc.get(), bpy.ops.bim, native IFC, addon architecture, IFC-backed properties, BIM authoring, how does Bonsai work, Bonsai internals, Bonsai API.
Use when developing Bonsai (formerly BlenderBIM) extensions, scripting BIM workflows in Blender, or understanding the Bonsai addon architecture. Prevents the common mistake of using ifcopenshell.open() to access the model instead of tool.Ifc.get() which gives the live Bonsai IFC file. Covers native IFC workflow, bpy.ops.bim.* operators, BIM property panels, and the relationship between Blender objects and IFC entities. Keywords: Bonsai, BlenderBIM, tool.Ifc.get(), bpy.ops.bim, native IFC, addon architecture, IFC-backed properties, BIM authoring, how does Bonsai work, Bonsai internals, Bonsai API.
Key principle: Core NEVER imports bpy. All Blender-specific code lives in Tool implementations. This keeps business logic independently testable.
Module Structure Pattern
Every functional area follows a three-part split:
Sub-layer
Location
Purpose
UI (delivery)
bim/module/<name>/ui.py, operator.py, prop.py
Panels, operators, properties
Core (abstract)
core/<name>.py
Use-case flow, no Blender imports
Tool (concrete)
tool/<name>.py
Blender + IFC implementation
Module File Structure
File
Purpose
__init__.py
Package init
operator.py
bpy.types.Operator subclasses (bpy.ops.bim.*)
prop.py
bpy.types.PropertyGroup subclasses
ui.py
Panel draw() methods
data.py
Cached/computed UI data (refresh patterns)
decorator.py
bpy.types.SpaceView3D draw callbacks (overlays)
gizmo.py
bpy.types.Gizmo / GizmoGroup subclasses
Registered Modules (~51-56)
Bonsai registers approximately 51-56 functional modules, each corresponding to an IFC domain area:
aggregate alignment attribute bcf boundary
brick bsdd cad clash classification
constraint context cost covering csv
debug demo diff document drawing
fm geometry georeference gis ifcgit
layer library material nest owner
patch profile project pset pset_template
qto resource search sequence spatial
structural style system tester type
unit void web
Demo Module: Reference Implementation
The demo module (bim/module/demo/) is a heavily commented reference implementation for new contributors. It demonstrates the full module pattern including all optional files. Enable it in bonsai/bim/__init__.py.
The @interface Decorator Pattern
core/tool.py defines tool interfaces using the @interface decorator — a design-by-contract enforcement mechanism:
Need IFC data from Blender object?
|
+--> Use tool.Ifc.get_entity(obj)
|
+--> Returns entity_instance? --> Access .GlobalId, .Name, .is_a()
+--> Returns None? --> Object is not linked to IFC
Need Blender object from IFC entity?
|
+--> Use tool.Ifc.get_object(entity)
|
+--> Returns bpy.types.Object? --> Manipulate via Blender API
+--> Returns None? --> Entity has no Blender representation
Need to run IFC API command?
|
+--> Inside Bonsai (bpy available)?
| +--> Use tool.Ifc.run("module.command", **kwargs)
|
+--> Standalone (no bpy)?
+--> Use ifcopenshell.api.run("module.command", ifc_file, **kwargs)
Native IFC Workflow
The IFC file IS the document. There is NO import/export step.
Action
What Happens
Create new project
Empty ifcopenshell.file created in memory
Open IFC file
ifcopenshell.open() loads directly into IfcStore
Create element
IFC entity created + Blender mesh generated + bidirectional link
Modify element
IFC graph updated via ifcopenshell.api + Blender mesh regenerated
Save project
model.write(path) — writes live IFC directly to disk
File Conventions
Bonsai native files: .ifc (saves directly to IFC, NOT .blend)
Bonsai registers BIMObjectProperties on every Blender object:
# Key property: ifc_definition_id
obj.BIMProperties.ifc_definition_id # int: IFC entity step ID (0 = not linked)
Property modifications in Blender UI panels are synced to IFC via pset.edit_pset(). NEVER assume modifying a Blender property alone updates the IFC data.
IfcOpenShell API Integration
Bonsai uses three abstraction levels for IFC operations:
Level
Module
Use When
Core
ifcopenshell.file
Low-level entity creation/read
Utility
ifcopenshell.util.*
Data extraction, conversions
API
ifcopenshell.api.run()
ALL mutations (ALWAYS use this)
Preferred: ifcopenshell.api.run()
# ALWAYS use the API for mutations: maintains IFC graph integrity
wall = ifcopenshell.api.run("root.create_entity", model,
ifc_class="IfcWall", name="Wall-001")
# NEVER modify attributes directly# wall.Name = "Bad" # WRONG: bypasses relationship management
Blender Registration
# bonsai/__init__.py (schematic)
bl_info = {
"name": "Bonsai",
"version": (0, 8, 4),
"blender": (4, 2, 0),
"category": "System",
}
defregister():
register_classes(classes)
for mod in modules.values():
mod.register()
bpy.types.Scene.BIMProperties = PointerProperty(type=BIMProperties)
defunregister():
for mod inreversed(list(modules.values())):
mod.unregister()
unregister_classes(classes)
IfcSverchok Integration (use_bonsai_file)
IfcSverchok (Sverchok's IFC bridge) can operate on Bonsai's active IFC file instead of its own transient SvIfcStore:
Toggle: use_bonsai_file on SvIfcCreateProject node
When enabled: SvIfcStore.get_file() returns tool.Ifc.get() (Bonsai's live IFC)
Effect: Sverchok node tree writes IFC entities directly into Bonsai's model
Dependency: Bonsai addon MUST be enabled and have an active IFC project loaded
Warning: Undo/redo with simultaneous Sverchok + Bonsai modifications can crash. Save before combining.
Refer to: sverchok-impl-ifcsverchok
Source Code Paths (IfcOpenShell Monorepo)
Component
Path
Bonsai root
src/bonsai/bonsai/
IfcStore
src/bonsai/bonsai/bim/ifc.py
Tool classes
src/bonsai/bonsai/tool/
Core functions
src/bonsai/bonsai/core/
Module operators/UI
src/bonsai/bonsai/bim/module/
Interface definitions
src/bonsai/bonsai/core/tool.py
Demo module
src/bonsai/bonsai/bim/module/demo/
IfcOpenShell API
src/ifcopenshell-python/ifcopenshell/api/
References
methods.md — Complete API signatures for tool.*, IfcStore, core functions
examples.md — Working code examples for common Bonsai operations
