bonsai-impl-bcf

name	bonsai-impl-bcf
description	Use when working with BIM Collaboration Format (BCF) files in Bonsai -- creating topics, adding viewpoints, managing comments, or importing/exporting BCF files (v2.1 and v3.0). Prevents the common mistake of creating viewpoints without proper camera snapshots or missing element references. Covers BCF issue tracking integration with IFC elements. Keywords: BCF, BIM Collaboration Format, viewpoint, topic, comment, clash report, issue tracking, BCF v2.1, BCF v3.0, collaboration, share issues, report problem in model, BIM issue.
license	MIT
compatibility	Designed for Claude Code. Requires Blender with Bonsai addon.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

BCF Workflows in Bonsai

Version: Bonsai v0.8.x | Blender 4.2.0+ | Python 3.11 Module path: bonsai.bim.module.bcf — NEVER blenderbim.bim.module.bcf BCF versions: v2.1 and v3.0 (via bcf.bcfxml library bundled with IfcOpenShell) Dependencies: bonsai-core-architecture, bonsai-syntax-elements

Critical Warnings

1. ALWAYS set scene.BCFProperties.author to a valid email BEFORE creating topics or comments. Default "[e-mail]" is a placeholder — replace it.
2. ALWAYS use BcfStore.get_bcfxml() to access BCF data. NEVER access BcfStore.bcfxml directly — get_bcfxml() handles lazy initialization and path resolution.
3. ALWAYS call bpy.ops.bim.save_bcf_project() to persist changes. BCF modifications are in-memory only until saved.
4. NEVER mix BCF v2.1 and v3.0 operations on the same project. The version is set at creation/load time and MUST remain consistent.
5. ALWAYS ensure an active camera exists before calling bpy.ops.bim.add_bcf_viewpoint(). The operator polls for an active scene camera.
6. NEVER assume viewpoint coordinates match the loaded IFC model coordinates. Viewpoint activation applies georeference offset corrections.
7. ALWAYS use bonsai.* imports. NEVER use blenderbim.* — renamed in 2024 (v0.8.0+).
8. BCF v3.0 REQUIRES non-empty status and type fields on topics. These are optional in v2.1 but mandatory in v3.0.

---

Architecture Overview

The BCF module diverges from Bonsai's standard core/tool/operator pattern. At v0.8.x, most domain logic lives directly in operators rather than in a separate core/bcf.py. The tool/bcf.py provides version-agnostic helper methods for topic data access.

+----------------------------------------------------------+
|  DELIVERY LAYER  — bim/module/bcf/                        |
|  operator.py (30+ operators), prop.py, ui.py              |
+----------------------------------------------------------+
|  TOOL LAYER      — tool/bcf.py                            |
|  Version-agnostic getters/setters for topic data          |
+----------------------------------------------------------+
|  DATA LAYER      — bcfstore.py (BcfStore singleton)       |
|  Class-level singleton wrapping bcf.bcfxml.BcfXml         |
+----------------------------------------------------------+
|  LIBRARY         — bcf.v2.bcfxml / bcf.v3.bcfxml          |
|  BCF-XML parser bundled with IfcOpenShell                 |
+----------------------------------------------------------+

Key singleton: BcfStore manages BCF data as a class-level singleton. Only ONE BCF project is loaded at a time. Access via BcfStore.get_bcfxml().

Properties access: bpy.context.scene.BCFProperties (or tool.Bcf.get_bcf_props()) holds all BCF UI state.

---

Decision Tree: BCF Workflow Selection

What BCF operation do you need?
│
├── Start a new BCF project?
│   └── bpy.ops.bim.new_bcf_project()
│       ├── Set props.bcf_version = "2" (v2.1) or "3" (v3.0) FIRST
│       └── Sets up empty BcfXml in BcfStore
│
├── Load an existing BCF file?
│   └── bpy.ops.bim.load_bcf_project(filepath="/path/to/file.bcf")
│       └── Auto-detects version, populates BcfStore + topics
│
├── Create/manage issues?
│   ├── Add topic: bpy.ops.bim.add_bcf_topic()
│   ├── Edit topic: bpy.ops.bim.edit_bcf_topic()
│   ├── View topic: bpy.ops.bim.view_bcf_topic(topic_guid="...")
│   └── Remove topic: bpy.ops.bim.remove_bcf_topic(guid="...")
│
├── Add visual context to an issue?
│   ├── Capture viewpoint: bpy.ops.bim.add_bcf_viewpoint()
│   ├── Restore viewpoint: bpy.ops.bim.activate_bcf_viewpoint()
│   └── Remove viewpoint: bpy.ops.bim.remove_bcf_viewpoint()
│
├── Add discussion to an issue?
│   ├── Add comment: bpy.ops.bim.add_bcf_comment()
│   ├── Edit comment: bpy.ops.bim.edit_bcf_comment()
│   └── Remove comment: bpy.ops.bim.remove_bcf_comment(comment_guid="...")
│
├── Attach documents/references?
│   ├── Reference link: bpy.ops.bim.add_bcf_reference_link()
│   ├── Document ref: bpy.ops.bim.add_bcf_document_reference()
│   ├── BIM snippet: bpy.ops.bim.add_bcf_bim_snippet()
│   └── Header file: bpy.ops.bim.add_bcf_header_file()
│
├── Save BCF to disk?
│   └── bpy.ops.bim.save_bcf_project(filepath="/path/to/output.bcf")
│
└── Close BCF project?
    └── bpy.ops.bim.unload_bcf_project()

---

Essential Patterns

Pattern 1: BCF Project Lifecycle

# Bonsai v0.8.x: Complete BCF project lifecycle
import bpy

props = bpy.context.scene.BCFProperties

# Step 1: Set author (REQUIRED before any topic/comment creation)
props.author = "[e-mail]"

# Step 2: Choose BCF version and create project
props.bcf_version = "3"  # "2" for v2.1, "3" for v3.0
bpy.ops.bim.new_bcf_project()

# Step 3: Work with topics, viewpoints, comments...
# (see patterns below)

# Step 4: Save to disk
bpy.ops.bim.save_bcf_project(filepath="/path/to/issues.bcf")

# Step 5: Unload when done
bpy.ops.bim.unload_bcf_project()

Pattern 2: Load Existing BCF File

# Bonsai v0.8.x: Load and inspect BCF file
import bpy

# Load BCF file (auto-detects v2.1 or v3.0)
bpy.ops.bim.load_bcf_project(filepath="/path/to/issues.bcf")

# Access loaded data
props = bpy.context.scene.BCFProperties
print(f"Project: {props.name}")
print(f"Version: BCF v{props.bcf_version}")
print(f"Topics: {len(props.topics)}")

# Iterate topics
for topic in props.topics:
    print(f"  [{topic.status}] {topic.title} (GUID: {topic.name})")

Pattern 3: Create Topic with Metadata

# Bonsai v0.8.x: Create and configure a BCF topic
import bpy

props = bpy.context.scene.BCFProperties
props.author = "[e-mail]"

# Create topic
bpy.ops.bim.add_bcf_topic()

# Get the newly created topic (last in list)
topic = props.topics[props.active_topic_index]

# Set metadata
topic.title = "MEP clash at Level 2 corridor"
topic.type = "Error"
topic.status = "Open"
topic.priority = "Critical"
topic.assigned_to = "[e-mail]"
topic.description = "HVAC duct intersects structural beam at grid B-4."

# Persist changes to the BCF data structure
bpy.ops.bim.edit_bcf_topic()

Pattern 4: Capture Viewpoint with Camera Snapshot

# Bonsai v0.8.x: Capture viewpoint for active topic
import bpy

# PREREQUISITE: Active camera MUST exist
if bpy.context.scene.camera is None:
    raise RuntimeError("Set an active camera before capturing a viewpoint.")

# Position camera at the issue location
camera = bpy.context.scene.camera
camera.location = (10.0, -5.0, 3.0)
camera.rotation_euler = (1.22, 0.0, 0.78)

# Capture viewpoint (records camera state + element visibility + snapshot)
bpy.ops.bim.add_bcf_viewpoint()
# This operator:
# 1. Reads camera position/orientation from active scene camera
# 2. Records component visibility and selection state
# 3. Renders a PNG snapshot via bpy.ops.render.opengl()
# 4. Stores clipping planes if present

Pattern 5: Add Comments to a Topic

# Bonsai v0.8.x: Add comments to the active BCF topic
import bpy

props = bpy.context.scene.BCFProperties
props.author = "[e-mail]"

# Set comment text
props.comment = "Duct routing needs to be lowered by 200mm to clear beam."

# Optionally link to active viewpoint
props.has_related_viewpoint = True  # Links comment to current viewpoint

# Create comment
bpy.ops.bim.add_bcf_comment()

Pattern 6: Activate (Restore) a Viewpoint

# Bonsai v0.8.x: Restore a saved viewpoint
import bpy

props = bpy.context.scene.BCFProperties
topic = props.active_topic

# Viewpoints are accessed via the topic's viewpoints enum
# Activate the currently selected viewpoint
bpy.ops.bim.activate_bcf_viewpoint()
# This restores:
# - Camera position and orientation
# - Component visibility/selection state
# - Clipping planes
# - Applies georeference offset correction

# To activate a specific viewpoint by GUID:
bpy.ops.bim.activate_bcf_viewpoint(viewpoint_guid="abc-123-def-456")

---

BCF Version Differences

Feature	BCF v2.1	BCF v3.0
props.bcf_version value	"2"	"3"
Topic status field	Optional	REQUIRED (edit fails without it)
Topic type field	Optional	REQUIRED (edit fails without it)
Document storage	Per-topic (TopicDocumentReference)	Global registry (bcfxml.documents)
API support	No	Yes (OpenCDE compliant)
Data model module	bcf.v2.model	bcf.v3.model
BcfXml class	bcf.v2.bcfxml.BcfXml	bcf.v3.bcfxml.BcfXml

Version Detection

# Bonsai v0.8.x: Detecting BCF version at runtime
from bonsai.bim.module.bcf.bcfstore import BcfStore

bcfxml = BcfStore.get_bcfxml()
if bcfxml is None:
    raise RuntimeError("No BCF project loaded.")

version_id = bcfxml.version.version_id or ""
is_v2 = version_id.startswith("2")
is_v3 = version_id.startswith("3")

---

Common Operations

Import BCF from External Tool

# Bonsai v0.8.x: Load BCF from Solibri, Navisworks, etc.
import bpy

# Load external BCF file
bpy.ops.bim.load_bcf_project(filepath="/path/to/coordination.bcf")

props = bpy.context.scene.BCFProperties

# Iterate all topics
for i, topic in enumerate(props.topics):
    print(f"Topic {i}: [{topic.status}] {topic.title}")

    # View topic to load its details
    bpy.ops.bim.view_bcf_topic(topic_guid=topic.name)

    # Load comments for this topic
    bpy.ops.bim.load_bcf_comments(topic_guid=topic.name)
    for comment in topic.comments:
        print(f"  Comment by {comment.author}: {comment.comment}")

Export BCF for External Tools

# Bonsai v0.8.x: Save BCF for sharing with other BIM tools
import bpy

# Save current BCF project
bpy.ops.bim.save_bcf_project(filepath="/path/to/export.bcf")

# Save to same path (overwrite)
bpy.ops.bim.save_bcf_project(save_current_bcf=True)

Link BCF Topic to IFC Elements

# Bonsai v0.8.x: Reference IFC elements in BCF viewpoint
import bpy
import bonsai.tool as tool

model = tool.Ifc.get()
if model is None:
    raise RuntimeError("No IFC project loaded.")

# Select the clashing elements in Blender viewport
bpy.ops.object.select_all(action='DESELECT')

# Find elements by GlobalId and select them
for global_id in ["2O2Fr$t4X7Zf8NOew3FLOH", "1kTvXnbbzEWu00n_qpFOat"]:
    entity = model.by_guid(global_id)
    obj = tool.Ifc.get_object(entity)
    if obj:
        obj.select_set(True)

# Capture viewpoint: selected elements are recorded as BCF components
bpy.ops.bim.add_bcf_viewpoint()

Clash Detection to BCF Workflow

# Bonsai v0.8.x: Convert clash results to BCF issues
import bpy

# Step 1: Run clash detection with BCF output
bpy.ops.bim.execute_ifc_clash()
# Save output as .bcf file when prompted

# Step 2: Load the clash BCF into BCF panel
bpy.ops.bim.load_bcf_project(filepath="/path/to/clashes.bcf")

# Each clash becomes a BCF topic with:
# - Viewpoint at clash location
# - Component references for both clashing elements
# - Metadata about clash type and severity

Attach Documents and References

# Bonsai v0.8.x: Add reference links and documents to a topic
import bpy

props = bpy.context.scene.BCFProperties

# Add a reference link (URL)
props.reference_link = "https://project.example.com/issues/MEP-042"
bpy.ops.bim.add_bcf_reference_link()

# Add a document reference
props.document_reference = "/path/to/specification.pdf"
props.document_reference_description = "MEP specification section 4.2"
bpy.ops.bim.add_bcf_document_reference()

# Add a BIM snippet (IFC fragment for context)
props.bim_snippet_reference = "/path/to/fragment.ifc"
props.bim_snippet_type = "IfcSharedBuildingElements"
props.bim_snippet_schema = "IFC4"
bpy.ops.bim.add_bcf_bim_snippet()

Add Labels and Related Topics

# Bonsai v0.8.x: Organize topics with labels and relations
import bpy

props = bpy.context.scene.BCFProperties

# Add labels to active topic
props.label = "MEP"
bpy.ops.bim.add_bcf_label()
props.label = "Structural"
bpy.ops.bim.add_bcf_label()

# Add related topic (requires another topic to exist)
# related_topic is an EnumProperty listing other topics
bpy.ops.bim.add_bcf_related_topic()

Extract Embedded Files

# Bonsai v0.8.x: Extract files embedded in BCF topics
import bpy

# Extract a header file by index
bpy.ops.bim.extract_bcf_file(entity_type="HEADER_FILE", index=0)

# Extract BIM snippet
bpy.ops.bim.extract_bcf_file(entity_type="BIM_SNIPPET", index=0)

# Extract document reference
bpy.ops.bim.extract_bcf_file(entity_type="DOCUMENT_REFERENCE", index=0)

---

BcfStore Singleton

The BcfStore class (at bonsai.bim.module.bcf.bcfstore) manages BCF session state:

from bonsai.bim.module.bcf.bcfstore import BcfStore

# Get the active BCF project (lazy-loads from props.bcf_file)
bcfxml = BcfStore.get_bcfxml()

# Set BCF data explicitly
BcfStore.set(bcfxml, filepath)

# Load by filepath (triggers lazy load on next get_bcfxml())
BcfStore.set_by_filepath("/path/to/file.bcf")

# Unload BCF session
BcfStore.unload_bcfxml()

Key behavior:

• get_bcfxml() calls bcf.bcfxml.load(filepath) from props.bcf_file on first access
• set() auto-detects BCF version from bcfxml.version.version_id and updates props.bcf_version
• Silently handles load exceptions (e.g., permission denied) — check return value for None
• Resolves relative paths against the .blend file directory

---

BCFProperties Quick Reference

Access via bpy.context.scene.BCFProperties:

Property	Type	Purpose
author	str	Author email — REQUIRED before creating topics/comments
bcf_version	enum	"2" (v2.1) or "3" (v3.0)
bcf_file	str	Path to loaded BCF file
name	str	Project name
topics	Collection[BcfTopic]	All loaded topics
active_topic_index	int	Currently selected topic index
comment	str	Input field for new comment text
has_related_viewpoint	bool	Link new comment to active viewpoint
reference_link	str	Input field for reference link URL
label	str	Input field for label text

Computed property: props.active_topic returns BcfTopic at active_topic_index or None.

---

Drag-and-Drop Support

Bonsai registers BCFFileHandlerOperator with bl_file_extensions = ".bcf", enabling drag-and-drop import of BCF files directly into Blender. The handler calls bim.load_bcf_project with the dropped file path.

---

Reference Links

• BCF API Methods — Complete operator signatures and BcfStore API
• Working Examples — End-to-end BCF workflow examples
• Anti-Patterns — What NOT to do when implementing BCF workflows

Dependencies

• bonsai-core-architecture — Three-layer architecture, IfcStore, operator execution pattern
• bonsai-syntax-elements — IFC element access for linking BCF issues to IFC entities

Sources

• Bonsai BCF source: src/bonsai/bonsai/bim/module/bcf/ (operator.py, prop.py, bcfstore.py)
• Bonsai BCF tool: src/bonsai/bonsai/tool/bcf.py
• BCF library: bcf.v2.bcfxml / bcf.v3.bcfxml (bundled with IfcOpenShell)
• Bonsai Documentation: https://docs.bonsaibim.org
• IfcOpenShell GitHub: https://github.com/IfcOpenShell/IfcOpenShell