Thatopen Impl Bcf

ThatOpen BCF & Viewpoints

Overview

This skill covers BIM Collaboration Format (BCF) support in @thatopen/components: the BCFTopics component for issue tracking and the Viewpoints component for 3D scene state capture. BCF enables structured communication about BIM model issues between different tools.

Version: @thatopen/components 3.3.x Prerequisites: thatopen-impl-viewer (world setup), thatopen-core-architecture Dependencies: jszip (BCF zip), fast-xml-parser (BCF XML)

Component Overview

BCFTopics

Setup

ALWAYS call setup() with configuration before creating or importing topics:

import * as OBC from "@thatopen/components";

const bcfTopics = components.get(OBC.BCFTopics);
bcfTopics.setup({
  version: "3",
  author: "user@example.com",
  types: new Set(["Issue", "Request", "Comment"]),
  statuses: new Set(["Active", "Resolved", "Closed"]),
  priorities: new Set(["Critical", "Major", "Normal", "Minor"]),
  labels: new Set(["Architecture", "Structure", "MEP"]),
  stages: new Set(["Design", "Construction", "Handover"]),
  users: new Set(["user@example.com", "reviewer@example.com"]),
});

BCFTopicsConfig

Strict Mode

When strict: true, all Topic property setters validate against the configured extensions. Setting topic.type = "Unknown" throws if "Unknown" is not in config.types. When strict: false (default), any value is accepted.

Properties

Events

Methods

Computed Getters

Topic

Properties

Topic References (stored as GUIDs)

Topic Methods

set() vs Direct Assignment

Direct property assignment updates internally without triggering events. Use set() to broadcast changes for reactive UI updates:

// Silent update — no events fired
topic.title = "Updated Title";

// Reactive update — listeners notified
topic.set({ title: "Updated Title", status: "Resolved" });

Comment

Document References

Two types of document references stored in bcfTopics.documents:

// Internal (embedded in BCF zip)
{ type: "internal", fileName: "report.pdf", data: Uint8Array, description?: string }

// External (URL reference)
{ type: "external", url: "https://...", description?: string }

Viewpoints

Setup

const viewpoints = components.get(OBC.Viewpoints);
viewpoints.world = world; // REQUIRED — default world for viewpoint creation

Properties

Methods

Viewpoint Instance

Each Viewpoint captures a complete 3D scene state:

Viewpoint Methods

BCF Version Differences

ALWAYS set config.version before exporting. The serialization format of viewpoints and markup XML differs between versions.

BCF Import/Export Workflow

Export

// Export all topics
const blob = await bcfTopics.export();

// Export specific topics
const selectedTopics = [...bcfTopics.list.values()].filter(t => t.status === "Active");
const blob = await bcfTopics.export(selectedTopics);

// Download in browser
const url = URL.createObjectURL(blob);
const link = document.createElement("a");
link.href = url;
link.download = "issues.bcf";
link.click();
URL.revokeObjectURL(url);

Import

// From file input
const input = document.createElement("input");
input.type = "file";
input.accept = ".bcf,.bcfzip";
input.addEventListener("change", async () => {
  const file = input.files?.[0];
  if (!file) return;
  const data = new Uint8Array(await file.arrayBuffer());
  const { topics, viewpoints } = await bcfTopics.load(data);
  console.log(`Imported ${topics.length} topics, ${viewpoints.length} viewpoints`);
});
input.click();

Linking Viewpoints to Topics

ALWAYS link viewpoints to topics using GUIDs, not object references:

const viewpoint = viewpoints.create();
viewpoint.title = "Clash at Level 2";
await viewpoint.updateCamera();
viewpoint.takeSnapshot();

const topic = bcfTopics.create({
  title: "Steel beam clashes with duct",
  type: "Issue",
  priority: "Critical",
});
topic.viewpoints.add(viewpoint.guid);

Auto-linking on Creation

viewpoints.list.onItemSet.add(({ value: vp }) => {
  const topic = bcfTopics.create();
  topic.viewpoints.add(vp.guid);
});

IDSSpecifications Overview

The IDSSpecifications component in @thatopen/components provides Information Delivery Specification (IDS) validation. IDS is a buildingSMART standard for specifying information requirements on BIM models.

This component is exported from the openbim module alongside BCFTopics. For detailed IDS usage, refer to the ThatOpen documentation.

Complete Setup Pattern

import * as OBC from "@thatopen/components";

// 1. Get components
const bcfTopics = components.get(OBC.BCFTopics);
const viewpoints = components.get(OBC.Viewpoints);

// 2. Configure BCFTopics (REQUIRED before create/load/export)
bcfTopics.setup({
  version: "3",
  author: "user@example.com",
  types: new Set(["Issue", "Request", "Comment"]),
  statuses: new Set(["Active", "Resolved", "Closed"]),
  priorities: new Set(["Critical", "Major", "Normal", "Minor"]),
  labels: new Set(["Architecture", "Structure", "MEP"]),
  stages: new Set(["Design", "Construction"]),
  users: new Set(["user@example.com"]),
  strict: false,
});

// 3. Set viewpoints world (REQUIRED before creating viewpoints)
viewpoints.world = world;

// 4. Create topic with viewpoint
const viewpoint = viewpoints.create();
await viewpoint.updateCamera();
viewpoint.takeSnapshot();

const topic = bcfTopics.create({
  title: "Coordination issue at grid A-3",
  type: "Issue",
  priority: "Major",
  assignedTo: "user@example.com",
  description: "Steel column interferes with HVAC duct routing",
});
topic.viewpoints.add(viewpoint.guid);
topic.createComment("Please review and propose resolution");

Critical Rules

1. ALWAYS call bcfTopics.setup() before creating, loading, or exporting topics. Without setup, the author field is empty and extensions are not configured.
2. ALWAYS set viewpoints.world before creating viewpoints. Camera capture and snapshot require a valid world reference.
3. ALWAYS set config.version to "2.1" or "3" before exporting. An empty version string produces invalid BCF output.
4. ALWAYS link viewpoints to topics via topic.viewpoints.add(guid), not by storing object references. GUIDs prevent memory leaks.
5. ALWAYS call updateCamera() after creating a viewpoint to capture the current camera state. New viewpoints have no camera data by default.
6. NEVER skip setup() and rely on defaults. All config sets start empty, meaning strict mode would reject every value.
7. NEVER assume imported BCF files specify a version. Use fallbackVersionOnImport to handle version-less files.
8. NEVER mix BCF version strings: use "2.1" or "3" (not "3.0").
9. NEVER store Topic or Viewpoint object references in external data structures. Use GUIDs from topic.guid / viewpoint.guid and look up via bcfTopics.list.get(guid) / viewpoints.list.get(guid).
10. NEVER forget to call dispose() or components.dispose() on cleanup. BCFTopics and Viewpoints hold DataMaps that must be freed.

Reference Files

• references/methods.md — BCFTopics, Viewpoints, Topic, Comment full API reference
• references/examples.md — Create topic, import/ export BCF, viewpoints integration examples
• references/anti-patterns.md — Wrong BCF version, missing config, memory leaks

Source Verification

All API signatures verified against:

• GitHub: ThatOpen/engine_components main branch (packages/core/src/openbim/BCFTopics/, packages/core/src/core/Viewpoints/)
• npm: @thatopen/components@3.3.3
• Research: docs/research/vooronderzoek-thatopen.md (Section 7)