Thatopen Syntax Ifc Loading

IFC Loading: IfcLoader & IfcImporter

Overview

IFC loading in ThatOpen converts IFC files into the internal Fragments binary format for high-performance 3D rendering. There are two approaches:

1. IfcLoader (high-level, @thatopen/components) — The standard component for loading IFC files in a ThatOpen application. Wraps web-ifc and handles WASM setup, conversion to fragments, and scene integration.
2. IfcImporter (low-level, @thatopen/fragments) — Direct fragment conversion without the component framework. Useful for server-side processing, Web Workers, or custom pipelines.

The time-consuming part is the IFC-to-Fragments conversion, not the actual fragment loading. ALWAYS convert once and store the Fragments binary for fast reloading.

Critical Rules

1. ALWAYS call setup() before load() — IfcLoader implements Configurable. Calling load() before setup() causes WASM initialization failures.
2. ALWAYS match WASM path version to installed web-ifc version — A version mismatch between the WASM files and the web-ifc npm package causes silent parsing failures or crashes.
3. NEVER hardcode a web-ifc version in the WASM path without checking package.json — the installed version may differ.
4. ALWAYS initialize FragmentsManager before loading IFC — Call fragmentsManager.init(workerURL) before any IFC loading to enable fragment processing.
5. ALWAYS pass IFC data as Uint8Array — The load() method does not accept ArrayBuffer, string, or File objects directly.
6. NEVER skip disposal — Call components.dispose() on teardown. IfcLoader holds a webIfc: IfcAPI instance that allocates WASM heap memory.

IfcLoader Component

Setup

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

const components = new OBC.Components();

// Create world (scene, camera, renderer)
const worlds = components.get(OBC.Worlds);
const world = worlds.create();
world.scene = new OBC.SimpleScene(components);
world.renderer = new OBC.SimpleRenderer(components, container);
world.camera = new OBC.OrthoPerspectiveCamera(components);

// Initialize FragmentsManager with worker
const fragmentsManager = components.get(OBC.FragmentsManager);
fragmentsManager.init(workerURL);

// Get and configure IfcLoader
const ifcLoader = components.get(OBC.IfcLoader);
await ifcLoader.setup();  // uses autoSetWasm (default: true)

WASM Configuration

Two approaches for WASM path configuration:

Automatic (default):

await ifcLoader.setup();  // autoSetWasm: true (default)
// Automatically resolves WASM path from the web-ifc package

Manual (CDN or custom path):

await ifcLoader.setup({
  autoSetWasm: false,
  wasm: {
    path: "https://unpkg.com/web-ifc@0.0.77/",
    absolute: true,
  },
});

Manual (local files):

await ifcLoader.setup({
  autoSetWasm: false,
  wasm: {
    path: "/static/wasm/",
    absolute: false,
  },
});

When using a local path, the directory MUST contain web-ifc.wasm (and web-ifc-mt.wasm for multi-threaded mode). Copy these from node_modules/web-ifc/.

Loading IFC Files

// Fetch IFC file as ArrayBuffer, convert to Uint8Array
const response = await fetch("/models/building.ifc");
const buffer = await response.arrayBuffer();
const data = new Uint8Array(buffer);

// Load into the viewer
const model = await ifcLoader.load(data, true, "MyBuilding");

// Add to scene
world.scene.three.add(model.object);

load() Parameters

• Set coordinate: true when loading multiple models that must align spatially.
• Set coordinate: false for single-model scenarios or when manual positioning is needed.

readIfcFile(): Low-Level Access

const modelID = await ifcLoader.readIfcFile(data);
// Now access raw web-ifc API:
const line = ifcLoader.webIfc.GetLine(modelID, expressID);
ifcLoader.cleanUp();  // ALWAYS clean up after raw access

Use readIfcFile() when you need raw web-ifc queries without full fragment conversion.

IfcFragmentSettings

The settings property on IfcLoader controls loading behavior.

web-ifc LoaderSettings (via settings.webIfc)

Use COORDINATE_TO_ORIGIN: true for models with large real-world coordinates to prevent floating-point precision issues.

Configuring Settings After Setup

await ifcLoader.setup();

// Modify web-ifc settings before loading
ifcLoader.settings.webIfc.COORDINATE_TO_ORIGIN = true;
ifcLoader.settings.webIfc.USE_FAST_BOOLS = true;

Events

Customizing Default Imports

Use onIfcImporterInitialized to modify which IFC entity types are converted:

ifcLoader.onIfcImporterInitialized.add((importer) => {
  // Add a category that is not imported by default
  importer.classes.elements.add(WEBIFC.IFCSPACE);

  // Remove a category to save memory
  importer.classes.elements.delete(WEBIFC.IFCFURNISHINGELEMENT);
});

By default, IfcLoader imports common building elements (walls, slabs, beams, columns, doors, windows, roofs, stairs, etc.) but excludes some categories like IFCSPACE and IFCOPENINGELEMENT for performance. Use this event to customize the import set.

IfcImporter (Low-Level, @thatopen/fragments)

IfcImporter operates at the fragments level without requiring the component framework. Use it for server-side conversion, Web Worker pipelines, or when you need fine-grained control.

import { IfcImporter } from "@thatopen/fragments";

const importer = new IfcImporter();

// Configure WASM
importer.wasm.path = "https://unpkg.com/web-ifc@0.0.77/";
importer.wasm.absolute = true;

// Process IFC file → Fragments binary
const fragmentsData = await importer.process(ifcData);  // Uint8Array in, Uint8Array out

IfcImporter Properties

IfcImporter Methods

Fragment Conversion Workflow

The recommended production pattern: convert once, store fragments, reload fast.

// Step 1: Convert IFC → FragmentsModel (slow, one-time)
const model = await ifcLoader.load(data, true, "Building");
world.scene.three.add(model.object);

// Step 2: Export to Fragments binary (fast serialization)
const fragmentsData = model.export();  // Uint8Array

// Step 3: Store the binary (IndexedDB, server, file system)
await saveToStorage("building.frg", fragmentsData);

// Step 4: Reload from Fragments binary (fast, skips IFC parsing)
const stored = await loadFromStorage("building.frg");
const reloaded = fragmentsManager.load(stored);
world.scene.three.add(reloaded.object);

This workflow avoids re-parsing IFC on every page load. The Fragments binary format loads orders of magnitude faster than IFC conversion.

Relationship to Other Skills

References

• references/methods.md — Complete IfcLoader and IfcImporter API signatures
• references/examples.md — Working examples: basic load, CDN WASM, IfcImporter, fragment workflow
• references/anti-patterns.md — Common failures: WASM misconfig, version mismatch, missing setup

Sources

• API docs: https://docs.thatopen.com/api/@thatopen/components/classes/IfcLoader
• Tutorial: https://docs.thatopen.com/Tutorials/Components/Core/IfcLoader
• GitHub: https://github.com/ThatOpen/engine_components
• IfcImporter: https://docs.thatopen.com/api/@thatopen/fragments/classes/IfcImporter