Thatopen Core Web Ifc

web-ifc Engine: Direct WASM IFC Parser

Overview

web-ifc is the WASM-powered IFC parsing engine beneath the ThatOpen component stack. It reads and writes IFC files at native speed in browser and Node.js environments. The central class is IfcAPI.

• Package: web-ifc (npm)
• Source: https://github.com/ThatOpen/engine_web-ifc
• Environments: Browser, Node.js (single-threaded and multi-threaded WASM)
• License: MPL-2.0

When using ThatOpen components (@thatopen/components), you rarely call web-ifc directly — the IfcLoader component wraps it. Use this skill when you need low-level IFC access, custom geometry extraction, or bulk property queries outside the component framework.

Critical Warnings

1. ALWAYS call Init() before any other method (except SetWasmPath). Every method silently fails or throws without WASM initialization.
2. ALWAYS call CloseModel(modelID) when done — each open model holds significant WASM heap memory. Forgetting this causes memory leaks that crash browser tabs.
3. ALWAYS use .size() and .get(i) for Vector<T> access — NEVER use array indexing ([]). WASM vectors are not JavaScript arrays.
4. ALWAYS call Dispose() when the IfcAPI instance is no longer needed — this releases the entire WASM module.
5. NEVER create multiple IfcAPI instances — one instance handles multiple models. Extra instances waste memory by loading duplicate WASM modules.
6. Vertex format is 6 floats per vertex: [x, y, z, nx, ny, nz] — position followed by normal. ALWAYS account for this interleaved layout when extracting geometry.
7. All 4x4 matrices are column-major (16 floats) — directly compatible with THREE.Matrix4.fromArray().

Quick Start

import * as WebIFC from "web-ifc";

const ifcApi = new WebIFC.IfcAPI();
ifcApi.SetWasmPath("/wasm/");       // MUST be called before Init()
await ifcApi.Init();

const data = new Uint8Array(buffer); // from fetch or fs.readFile
const modelID = ifcApi.OpenModel(data);

// Query walls
const wallIDs = ifcApi.GetLineIDsWithType(modelID, WebIFC.IFCWALL);
for (let i = 0; i < wallIDs.size(); i++) {
  const wall = ifcApi.GetLine(modelID, wallIDs.get(i));
  console.log(wall.Name?.value);
}

// Get geometry
const mesh = ifcApi.GetFlatMesh(modelID, wallIDs.get(0));

// Get coordination matrix
const matrix = ifcApi.GetCoordinationMatrix(modelID);

ifcApi.CloseModel(modelID); // ALWAYS free memory

Initialization

SetWasmPath(path: string, absolute?: boolean): void

Sets the directory containing WASM files. MUST be called before Init(). The directory MUST contain web-ifc.wasm (and web-ifc-mt.wasm for multi-threaded mode).

ifcApi.SetWasmPath("/static/wasm/");                         // relative
ifcApi.SetWasmPath("https://cdn.example.com/wasm/", true);   // absolute URL

NEVER hardcode a version in the WASM path — ALWAYS match the installed web-ifc npm version.

Init(customLocateFileHandler?, forceSingleThread?): Promise<void>

Initializes the WASM module. MUST be awaited before calling any other API method.

await ifcApi.Init();                        // default (auto-detect threading)
await ifcApi.Init(undefined, true);         // force single-threaded
await ifcApi.Init((path, prefix) => "/custom/" + path); // custom file locator

Dispose(): void

Releases the entire WASM module and all resources. Call when the IfcAPI instance is no longer needed.

Model Lifecycle

LoaderSettings

interface LoaderSettings {
  COORDINATE_TO_ORIGIN?: boolean;    // translate model to origin (recommended)
  USE_FAST_BOOLS?: boolean;          // faster but less accurate boolean ops
  CIRCLE_SEGMENTS_LOW?: number;      // tessellation for small curves
  CIRCLE_SEGMENTS_MEDIUM?: number;   // tessellation for medium curves
  CIRCLE_SEGMENTS_HIGH?: number;     // tessellation for large curves
  BOOL_ABORT_THRESHOLD?: number;     // timeout (ms) for boolean operations
  MEMORY_LIMIT?: number;             // WASM memory limit in bytes
}

ALWAYS use COORDINATE_TO_ORIGIN: true for models with large world coordinates — prevents floating-point precision issues in rendering.

Data Queries

Core Query Methods

GetLine Parameters

NEVER use flatten: true on large models without limiting scope — it recursively resolves every reference and causes severe performance degradation.

Schema & Type Information

Geometry Extraction

Single-Element Geometry

const flatMesh = ifcApi.GetFlatMesh(modelID, expressID);

for (let i = 0; i < flatMesh.geometries.size(); i++) {
  const pg = flatMesh.geometries.get(i);
  const geom = ifcApi.GetGeometry(modelID, pg.geometryExpressID);
  const verts = ifcApi.GetVertexArray(geom.GetVertexData(), geom.GetVertexDataSize());
  const indices = ifcApi.GetIndexArray(geom.GetIndexData(), geom.GetIndexDataSize());

  // verts: Float32Array — 6 floats per vertex [x, y, z, nx, ny, nz]
  // indices: Uint32Array — triangle indices
  // pg.color: { x, y, z, w } — RGBA (w = alpha)
  // pg.flatTransformation: number[] — 4x4 column-major transform matrix
}

Geometry Streaming (Memory-Efficient)

ALWAYS prefer streaming over LoadAllGeometry for models with more than a few hundred elements.

Callback signature: (mesh: FlatMesh, index: number, total: number) => void

Coordination & Transforms

Properties Helper

The ifcApi.properties object provides high-level async methods for property queries.

The spatial structure returns a tree: { expressID, type, children: [...] }.

GUID Utilities

ALWAYS call CreateIfcGuidToExpressIdMapping first if performing many GUID lookups — it builds an index that makes subsequent calls faster.

Writing Data

After modifications, use SaveModel(modelID) to serialize back to IFC format.

Logging

import { LogLevel } from "web-ifc";
ifcApi.SetLogLevel(LogLevel.LOG_LEVEL_OFF);    // silent (recommended for production)
ifcApi.SetLogLevel(LogLevel.LOG_LEVEL_ERROR);  // errors only
ifcApi.SetLogLevel(LogLevel.LOG_LEVEL_DEBUG);  // verbose debugging

Key Types

See references/methods.md for complete type definitions.

Common IFC Type Constants

import {
  // Structural
  IFCWALL, IFCWALLSTANDARDCASE, IFCSLAB, IFCBEAM, IFCCOLUMN,
  // Openings
  IFCDOOR, IFCWINDOW, IFCOPENINGELEMENT,
  // Building elements
  IFCROOF, IFCSTAIR, IFCFURNISHINGELEMENT,
  // Spatial hierarchy
  IFCPROJECT, IFCSITE, IFCBUILDING, IFCBUILDINGSTOREY, IFCSPACE,
  // Properties & relations
  IFCPROPERTYSET, IFCPROPERTYSINGLEVALUE,
  IFCRELDEFINESBYPROPERTIES, IFCRELCONTAINEDINSPATIALSTRUCTURE,
  IFCRELAGGREGATES, IFCRELVOIDSELEMENT,
} from "web-ifc";

References

• references/methods.md — Complete IfcAPI method signatures and type definitions
• references/examples.md — Full working examples: init, load, query, geometry, properties
• references/anti-patterns.md — Common failures: WASM init, memory leaks, Vector access

Sources

• GitHub: https://github.com/ThatOpen/engine_web-ifc
• Docs: https://thatopen.github.io/engine_web-ifc/docs/
• npm: https://www.npmjs.com/package/web-ifc