Bonsai Impl Clash

Bonsai Clash Detection Implementation

> Version: Bonsai v0.8.x | IfcClash (from IfcOpenShell v0.8.x) | Blender 4.2.0+ | Python 3.11 > Module path: bonsai.bim.module.clash — NEVER blenderbim.bim.module.clash > Engine: IfcClash — frontend for FCL (Flexible Collision Library)

Critical Warnings

1. ALWAYS save IFC files to disk BEFORE running clash detection. IfcClash reads files from disk, NOT from Blender's in-memory model.
2. ALWAYS define BOTH Group A and Group B in every clash set, even for intra-model checks (e.g., structural vs. MEP in the same file).
3. ALWAYS use filter_groups to limit clash scope. Unfiltered detection on large models produces excessive runtime and noise.
4. ALWAYS use bim.smart_clash_group for result sets exceeding 50 clashes. Manual review of hundreds of individual clashes is impractical.
5. NEVER expect real-time clash checking. Clash detection is a batch operation — there is NO live monitoring.
6. NEVER use collision mode with allow_touching=True for detecting hard overlaps — this generates false positives where elements share surfaces. Use intersection mode instead.
7. ALWAYS specify an output path (.bcf or .json) before executing clash detection.
8. ALWAYS use bonsai.* imports. NEVER use blenderbim.* — renamed in 2024 (v0.8.0+).

---

Decision Tree: Clash Detection Mode Selection

What type of geometric conflict are you detecting?
│
├── Physical overlap (pipe through wall, duct through beam)?
│   └── Use mode = "intersection"
│       └── tolerance = 0.001 (1mm) for architectural
│       └── tolerance = 0.0001 (0.1mm) for mechanical
│
├── Surface contact (elements touching)?
│   └── Use mode = "collision"
│       └── allow_touching = False (default) for strict contact detection
│       └── allow_touching = True ONLY when surface sharing is acceptable
│
└── Proximity clearance (maintenance access, fire safety)?
    └── Use mode = "clearance"
        └── clearance = required_distance_in_meters
        └── Example: clearance = 0.3 for 300mm maintenance gap

Decision Tree: Output Format Selection

What will you do with clash results?
│
├── Share with external stakeholders (Navisworks, Solibri, BIMcollab)?
│   └── Export as .bcf
│       └── Each clash becomes a BCF topic with viewpoint
│       └── Set should_create_clash_snapshots = True for visual context
│
├── Programmatic analysis or custom reporting?
│   └── Export as .json
│       └── Contains coordinates, GlobalIds, distances
│       └── Parseable by any JSON library
│
└── Internal review within Bonsai?
    └── Export as .json
        └── Load with bim.select_ifc_clash_results
        └── Navigate clashes in 3D viewport

---

Essential Patterns

Pattern 1: Define a Clash Set

# Bonsai v0.8.x: Create and configure a clash set
import bpy

props = bpy.context.scene.BIMClashProperties

# Create a new clash set
bpy.ops.bim.add_clash_set()
clash_set = props.clash_sets[props.active_clash_set_index]

# Set detection mode
clash_set.mode = "intersection"    # "intersection" | "collision" | "clearance"
clash_set.tolerance = 0.002        # Default: 0.002m (2mm)

# Add Group A source
bpy.ops.bim.add_clash_source(group="a")
clash_set.a[0].name = "/path/to/structural.ifc"
clash_set.a[0].mode = "i"  # "a"=all, "i"=include filtered, "e"=exclude filtered

# Add Group B source
bpy.ops.bim.add_clash_source(group="b")
clash_set.b[0].name = "/path/to/mep.ifc"
clash_set.b[0].mode = "i"

Pattern 2: Run Clash Detection

# Bonsai v0.8.x: Execute clash detection
import bpy

props = bpy.context.scene.BIMClashProperties

# Set output path BEFORE execution
props.export_path = "/path/to/results.json"

# Execute clash detection
bpy.ops.bim.execute_ifc_clash()

# For BCF output with snapshots
props.should_create_clash_snapshots = True
props.export_path = "/path/to/results.bcf"
bpy.ops.bim.execute_ifc_clash()

Pattern 3: Review Clash Results

# Bonsai v0.8.x: Load and navigate clash results
import bpy

props = bpy.context.scene.BIMClashProperties

# Load results from JSON file
props.clash_results_path = "/path/to/results.json"
bpy.ops.bim.select_ifc_clash_results()

# Navigate to a specific clash (highlights pair, positions viewport)
bpy.ops.bim.select_clash(index=0)

# Access clash data
clash_set = props.clash_sets[props.active_clash_set_index]
for i, clash in enumerate(clash_set.clashes):
    print(f"Clash {i}: {clash.a_name} vs {clash.b_name}")
    print(f"  A GlobalId: {clash.a_global_id}")
    print(f"  B GlobalId: {clash.b_global_id}")
    print(f"  Type: {clash.clash_type}")

# Remove clash visualization overlay
bpy.ops.bim.hide_clash()

Pattern 4: Use IfcClash Standalone (Without Bonsai)

# IfcClash standalone: Bonsai v0.8.x / IfcOpenShell v0.8.x
import ifcclash
import json
import logging

# Configure settings
settings = ifcclash.ClashSettings()
settings.output = "/path/to/results.json"
settings.logger = logging.getLogger("IfcClash")
settings.logger.setLevel(logging.INFO)

# Define clash sets
clash_sets = [
    {
        "name": "Structural vs MEP",
        "a": [{"file": "/path/to/structural.ifc", "mode": "i", "selector": "IfcBeam"}],
        "b": [{"file": "/path/to/mep.ifc", "mode": "i", "selector": "IfcFlowSegment"}],
        "tolerance": 0.001,
        "mode": "intersection",
    }
]

# Run clash detection
clasher = ifcclash.Clasher(settings)
clasher.clash_sets = clash_sets
clasher.clash()
clasher.export()

---

Common Operations

Filter Configuration

Element filters control which elements participate in clash detection. Each ClashSource has a mode and optional filter_groups:

| Filter Mode | Value | Behavior | |-------------|-------|----------| | All Elements | "a" | Include every element from the IFC file | | Include | "i" | Include ONLY elements matching the selector/filter | | Exclude | "e" | Include all elements EXCEPT those matching the selector/filter |

Standalone IfcClash selector syntax uses IFC class names as filters:

{
    "file": "/path/to/model.ifc",
    "mode": "i",
    "selector": "IfcWall"
}

Bonsai UI filter groups use BIMFilterGroup collections on ClashSource.filter_groups for more granular control (filter by class, property, attribute).

Smart Grouping

Smart grouping clusters spatially proximate clashes using the OPTICS algorithm to reduce noise and identify systemic patterns:

# Bonsai v0.8.x: Smart clash grouping
import bpy

props = bpy.context.scene.BIMClashProperties

# Set maximum clustering distance (meters, default: 3)
props.smart_clash_grouping_max_distance = 3

# Run grouping (requires clash_results_path to be set)
bpy.ops.bim.smart_clash_group()

# Load smart groups for the active clash set
bpy.ops.bim.load_smart_groups_for_active_clash_set()

# Navigate to a specific group (selects all elements, frames viewport)
bpy.ops.bim.select_smart_group(group_index=0)

# Access group data
for group in props.smart_clash_groups:
    print(f"Group {group.number}: {len(group.global_ids)} elements")

BCF Integration

Clash results integrate directly with BCF (BIM Collaboration Format) for issue tracking:

# Bonsai v0.8.x: Clash-to-BCF workflow
import bpy

props = bpy.context.scene.BIMClashProperties

# Step 1: Run clash detection with BCF output
props.export_path = "/path/to/clashes.bcf"
props.should_create_clash_snapshots = True
bpy.ops.bim.execute_ifc_clash()

# Step 2: Load BCF results in Bonsai BCF panel
bpy.ops.bim.load_bcf_project(filepath="/path/to/clashes.bcf")

# Each clash becomes a BCF topic containing:
# - Viewpoint positioned at the clash location
# - Component references for both clashing elements (GlobalIds)
# - Metadata: clash type, severity classification

Export and Import Clash Set Configurations

# Bonsai v0.8.x: Save/restore clash set definitions
import bpy

# Export current clash set configuration to JSON
bpy.ops.bim.export_clash_sets()

# Import clash set configuration from JSON
bpy.ops.bim.import_clash_sets()

Clash Visualization in 3D Viewport

The ClashDecorator renders clash points as a viewport overlay:

• Two colored points at P1 and P2 (clash contact endpoints)
• Connecting line between P1 and P2 (when points differ)
• Text label at midpoint with clash identification
• Colors configurable via addon preferences (selected/unselected/special)
• Uses GPU shaders (UNIFORM_COLOR, POLYLINE_UNIFORM_COLOR)

# Bonsai v0.8.x: Clash visualization properties
props = bpy.context.scene.BIMClashProperties

# P1 and P2 coordinates (set by select_clash operator)
print(f"P1: {tuple(props.p1)}")
print(f"P2: {tuple(props.p2)}")
print(f"Label: {props.active_clash_text}")

---

Workflow: Complete Clash Detection Pipeline

1. Prepare Models
   ├── Save all IFC files to disk
   └── Verify file paths are absolute

2. Define Clash Sets
   ├── bpy.ops.bim.add_clash_set()
   ├── Configure mode (intersection/collision/clearance)
   ├── Set tolerance/clearance values
   ├── Add Group A sources with filters
   └── Add Group B sources with filters

3. Execute Detection
   ├── Set export_path (.json or .bcf)
   ├── Set should_create_clash_snapshots (for BCF)
   └── bpy.ops.bim.execute_ifc_clash()

4. Review Results
   ├── Load results: bpy.ops.bim.select_ifc_clash_results()
   ├── Navigate: bpy.ops.bim.select_clash(index=N)
   └── Hide overlay: bpy.ops.bim.hide_clash()

5. Group and Analyze
   ├── bpy.ops.bim.smart_clash_group()
   ├── bpy.ops.bim.load_smart_groups_for_active_clash_set()
   └── bpy.ops.bim.select_smart_group(group_index=N)

6. Report (optional)
   ├── BCF export for external collaboration
   └── JSON export for programmatic analysis

---

Operator Quick Reference

| Operator | bl_idname | Purpose | |----------|-----------|---------| | AddClashSet | bim.add_clash_set | Create new clash set | | RemoveClashSet | bim.remove_clash_set | Delete clash set by index | | AddClashSource | bim.add_clash_source | Add IFC source to group (a/b) | | RemoveClashSource | bim.remove_clash_source | Remove source from group | | SelectClashSource | bim.select_clash_source | File picker for IFC source | | ExecuteIfcClash | bim.execute_ifc_clash | Run clash detection engine | | SelectIfcClashResults | bim.select_ifc_clash_results | Load clash results from JSON | | SelectClash | bim.select_clash | Navigate to individual clash | | HideClash | bim.hide_clash | Remove clash visualization | | SmartClashGroup | bim.smart_clash_group | Group clashes by proximity | | LoadSmartGroupsForActiveClashSet | bim.load_smart_groups_for_active_clash_set | Load saved smart groups | | SelectSmartGroup | bim.select_smart_group | Select elements in smart group | | ExportClashSets | bim.export_clash_sets | Export configuration to JSON | | ImportClashSets | bim.import_clash_sets | Import configuration from JSON | | SelectClashResults | bim.select_clash_results | Set clash results file path | | SelectSmartGroupedClashesPath | bim.select_smart_grouped_clashes_path | Set smart groups file path |

---

Property Reference

BIMClashProperties (on bpy.context.scene)

| Property | Type | Default | Description | |----------|------|---------|-------------| | clash_sets | Collection[ClashSet] | — | All defined clash sets | | active_clash_set_index | Int | 0 | Currently selected clash set | | active_clash_index | Int | 0 | Currently selected clash | | export_path | String | "" | Output path for .bcf or .json | | clash_results_path | String | "" | Path to loaded results file | | should_create_clash_snapshots | Bool | False | Generate BCF viewpoint snapshots | | smart_clash_groups | Collection[SmartClashGroup] | — | Grouped clash results | | active_smart_group_index | Int | 0 | Currently selected smart group | | smart_clash_grouping_max_distance | Int | 3 | Max clustering distance (meters) | | p1 | FloatVector | (0,0,0) | First clash contact point | | p2 | FloatVector | (0,0,0) | Second clash contact point | | active_clash_text | String | "" | Label text for active clash |

---

Dependencies

• bonsai-core-architecture — Three-layer architecture, IfcStore, operator pattern
• bonsai-syntax-elements — IFC element access via tool.Ifc, entity↔object mapping

Reference Links

• [Complete API Signatures](references/methods.md) — All method signatures for Bonsai clash module and IfcClash engine
• [Working Code Examples](references/examples.md) — End-to-end clash detection workflow examples
• [Anti-Patterns](references/anti-patterns.md) — What NOT to do when implementing clash detection

Sources

• Bonsai source: src/bonsai/bonsai/bim/module/clash/ (operators, props, UI, decorator)
• Bonsai source: src/bonsai/bonsai/tool/clash.py (tool layer implementation)
• IfcClash source: src/ifcclash/ifcclash/ifcclash.py (engine)
• IfcClash docs: https://docs.ifcopenshell.org/ifcclash.html
• Bonsai docs: https://docs.bonsaibim.org

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Blender-Bonsai-ifcOpenshell-Sverchok-Claude-Skill-Package
• License: MIT
• Homepage: https://github.com/OpenAEC-Foundation

Install and usage instructions live in the source repository linked above.