Open BIM Components

To initialize a basic 3D scene, you need to instantiate the OBC.Components manager, create a World via the Worlds component, and then define the scene, renderer, and camera. Finally, call components.init() to activate the system.

This example demonstrates creating a navigable 3D scene containing a single cube.

import * as THREE from "three";
import * as OBC from "@thatopen/components"; // Note: Import path depends on your setup

const container = document.getElementById("container")!;

// 1. Initialize the main components manager
const components = new OBC.Components();

// 2. Access the Worlds component to manage 3D environments
const worlds = components.get(OBC.Worlds);

// 3. Create a new world with specific implementations for Scene, Camera, and Renderer
const world = worlds.create<
  OBC.SimpleScene,
  OBC.SimpleCamera,
  OBC.SimpleRenderer
>();

// 4. Assign the implementations to the world
world.scene = new OBC.SimpleScene(components);
world.renderer = new OBC.SimpleRenderer(components, container);
world.camera = new OBC.SimpleCamera(components);

// 5. Initialize the components system
components.init();

// 6. Add content to the scene using standard Three.js objects
const material = new THREE.MeshLambertMaterial({ color: "#6528D7" });
const geometry = new THREE.BoxGeometry();
const cube = new THREE.Mesh(geometry, material);
world.scene.three.add(cube);

// 7. Finalize scene setup
world.scene.setup();

// 8. Configure camera view
world.camera.controls.setLookAt(3, 3, 3, 0, 0, 0);

The Classifier component allows you to group items from different models based on specific criteria (classifications and groups). It uses an internal DataMap to organize these groups and provides methods to aggregate items via queries, relations, or specific IFC structures like building storeys.

Key workflows include:

• Aggregating by Query: Use aggregateItems to find items matching a query and register them into a classification group using a callback.
• Aggregating by Relations: Use aggregateItemRelations to group items based on their relationships (e.g., ContainsElements).
• Finding Intersections: Use find to retrieve the intersection of items that belong to multiple classification groups across different classifications.
• IFC Specifics: Use byIfcBuildingStorey to automatically classify items by their parent building storey.

// Example: Aggregating items by a query
await classifier.aggregateItems(
  "MyClassification",
  { categories: [/Wall/] },
  {
    aggregationCallback: (item, register) => {
      // 'register' associates the item's name with its local ID
      register(item.Name.value, item._localId.value);
    }
  }
);

// Example: Finding items that satisfy multiple classifications
const intersection = await classifier.find({
  "ClassificationA": ["Group1"],
  "ClassificationB": ["Group2"]
});

The OrthoPerspectiveCamera is a high-level camera component that extends SimpleCamera. It provides seamless switching between orthographic and perspective projections and supports multiple navigation modes like Orbit, First Person, and Plan (2D floor plan) navigation. It uses camera-controls internally to manage user interactions.

Key Features

• Projection Switching: Managed via the projection property (a ProjectionManager).
• Navigation Modes: Switch between predefined modes like Orbit, FirstPerson, and Plan using the .set(modeId) method.
• Auto-fitting: Use the .fit(meshes) method to automatically adjust the camera view to encompass specific meshes or the entire scene.
• User Input Control: Enable or disable user interaction via .setUserInput(active).

// Example setup (assuming components is initialized)
const camera = new OrthoPerspectiveCamera(components);

// Switch to First Person mode
camera.set("FirstPerson");

// Switch to Orbit mode
camera.set("Orbit");

// Fit the camera to specific meshes
await camera.fit(myMeshesArray);

// Disable user interaction
camera.setUserInput(false);

The Views class manages a collection of 2D sections (views) within a 3D environment. It allows you to create views based on vectors, planes, IFC storeys, or bounding box elevations. The component handles camera state management, ensuring that when you open a view, the world's camera switches to the view's camera, and when you close it, the camera can automatically restore its previous pose.

Key features:

• Automatic Camera Restoration: If restoreCameraOnClose is true, the component snapshots the active camera's controls state before opening a view and restores it when the view is closed.
• Input Routing: It automatically manages CameraControls.enabled to ensure only the active view's camera responds to user input, preventing navigation in one view from affecting others.
• View Lifecycle: Views are stored in a DataMap called list. Opening a view in a specific World will automatically close any other currently open view in that same world.

// Example of creating and opening a view
const views = components.get(Views);

// Create a view at a specific point with a specific normal
const myView = views.create(
  new THREE.Vector3(0, 1, 0), // normal
  new THREE.Vector3(0, 0, 0)  // point
);

// Open the view
views.open(myView.id);

// Later, close the view to return to the default world camera
views.close(myView.id);

Callout annotations are managed through a state machine and persisted as CalloutAnnotation objects.

Data Structures

• CalloutAnnotation: The committed data for an annotation, including uuid, center, halfW, halfH, elbow (the bend point), extensionEnd (the text anchor), text, and the style name.
• CalloutAnnotationData: An editable version of the annotation (all fields except uuid).

State Machine (CalloutAnnotationState)

The annotation creation follows a specific lifecycle:

1. awaitingCenter: Waiting for the user to click the enclosure centre.
2. awaitingRadius: User defines halfW and halfH by moving the cursor.
3. awaitingElbow: User clicks to place the bend in the extension line.
4. awaitingExtension: User clicks to place the extension endpoint.
5. enteringText: Geometry is set; the system waits for a SUBMIT_TEXT event.
6. committed: The annotation is finalized.