# Bonsai Impl Clash

> >

- **Type:** Skill
- **Install:** `agentstack add skill-impertio-studio-blender-bonsai-ifcopenshell-sverchok-claude-skill-package-bonsai-impl-clash`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Impertio-Studio](https://agentstack.voostack.com/s/impertio-studio)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** https://github.com/Impertio-Studio/Blender-Bonsai-ifcOpenshell-Sverchok-Claude-Skill-Package/tree/main/skills/bonsai/impl/bonsai-impl-clash
- **Website:** https://github.com/OpenAEC-Foundation

## Install

```sh
agentstack add skill-impertio-studio-blender-bonsai-ifcopenshell-sverchok-claude-skill-package-bonsai-impl-clash
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```python
# 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

```python
# 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

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

```python
# 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:

```json
{
    "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:

```python
# 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:

```python
# 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

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

```python
# 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](https://github.com/Impertio-Studio)
- **Source:** [Impertio-Studio/Blender-Bonsai-ifcOpenshell-Sverchok-Claude-Skill-Package](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-impertio-studio-blender-bonsai-ifcopenshell-sverchok-claude-skill-package-bonsai-impl-clash
- Seller: https://agentstack.voostack.com/s/impertio-studio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.