<< User Guide

xeokit SDK: White Paper

1. Introduction
2. Resource Links
3. Use Cases
4. Features
5. Viewing AEC Models
6. Code Modules
7. Usage Examples
- 7.1. Example: View an IFC Model and Hide All IfcSpaces

1. Introduction

The xeokit SDK is an open-source toolkit for real-time 3D visualization in web-based Architecture, Engineering, and Construction (AEC) applications. Key features include:

Smooth interaction with large 3D models using double-precision coordinates to prevent floating-point errors.
A powerful rendering engine provided by the Viewer module, supporting multiple canvases, object interaction, and customizable effects.
A Scene module that manages 3D geometries, materials, and model structure.
A Data module that integrates semantic metadata for querying and analysis.

This document details the SDK’s architecture, rendering techniques, and applications in web-based visualization.

2. Resource Links

Essential resources to help you get started with xeokit SDK:

Examples – Interactive demos showcasing SDK features.
Model Viewer – Explore test models from various AEC formats.
Source Code – Open-source repository under the AGPL3 license.
API Documentation – Detailed API reference generated with TypeDoc.
User Guide – Guides for effective SDK use.
Releases – Latest updates and version history.
NPM Package – Install the SDK via NPM.

3. Use Cases

The xeokit SDK supports a wide range of AEC industry use cases:

3.1. BIM Model Visualization

Load and view IFC, glTF, and other 3D formats in your web browser.
Efficiently visualize large-scale BIM models with optimized rendering.
Overlay and compare federated models for project coordination.

3.2. Web-Based BIM Collaboration

Supports BCF (BIM Collaboration Format) for issue tracking and annotations.
Enables real-time collaboration with shared 3D views.
Manages object properties and metadata via the Data module.

3.3. GIS and LiDAR Integration

Ensures precise geospatial alignment using double-precision coordinates.
Overlays AEC models with point clouds (supports LAS/LAZ).
Ideal for visualizing large-scale infrastructure accurately.

3.4. Interactive Model Analysis

Perform sectioning, slicing, and x-ray views for in-depth analysis.
Use custom materials and rendering effects for enhanced visualization.
Employ collision detection to verify model integrity.

3.5. Web-Based Digital Twin Applications

Integrate real-time IoT data with BIM models for facility management.
Visualize historical and predictive asset maintenance.
Provide interactive dashboards featuring embedded 3D model viewers.

3.6. AEC Model Conversion and Processing

Convert between BIM formats with built-in importers/exporters.
Pre-convert models to XKT /XGF formats for optimal performance.
Process semantic relationships for structured querying.

3.7. Custom Web-Based 3D Applications

Develop custom visualization tools using the xeokit Viewer.
Embed high-performance 3D models into web dashboards.
Create multi-view 3D interfaces for enhanced user experience.

4. Features

Key features of the xeokit SDK include:

Advanced AEC Graphics Toolkit: Build, load, convert, export, view, and interact with 3D models.
Multi-Model Viewing: Simultaneously display multiple federated models.
Multi-Format Support: Handles IFC, glTF, LAS/LAZ, CityJSON, XKT, XGF, .BIM, and more.
Multi-Canvas Support: Configure different view canvases independently.
Double-Precision Coordinates: Ensure precise geospatial model placement.
Optimized Loading: Pre-conversion to XGF format speeds up performance.
High-Performance Rendering: Built for complex AEC models.
Interactive Effects: Slice, x-ray, highlight, colorize and select objects.
BCF Collaboration: Interoperate with other BIM software through BCF viewpoints.
Natively TypeScript: Leverages strongly-typed components and clear API contracts.

5. Viewing AEC Models

The xeokit SDK supports viewing various AEC file formats through multiple import pipelines.

The best pipeline to use depends on the source format and file size.

The table below outlines the recommended pipeline based on format and data size. Smaller files can be loaded directly into the xeokit Viewer while medium/large files should be preconverted to a more compact format, such as to XGF, for optimal performance. The links on the right take you to the tutorials for the selected pipelines.

Model Format	File Size	Load Directly vs. Preconvert	Recommended Articles
IFC	0MB - 10MB	Load Directly	Viewing IFC using IFCLoader
	0MB - 10MB	Preconvert	Viewing IFC using xeoconvert and XGFLoader
	10MB - 100MB	Preconvert	Viewing IFC using xeoconvert and GLTFLoader Viewing IFC using ifc2gltf2xgf
	100MB - 2GB	Preconvert	Viewing IFC using ifc2gltf2xgf
glTF	Small	Load Directly	Viewing glTF using GLTFLoader
glTF	Medium / Large	Preconvert	Viewing glTF using xeoconvert and XGFLoader
.BIM	Small	Load Directly	Viewing .BIM using DotBIMLoader
.BIM	Medium / Large	Preconvert	Viewing .BIM using xeoconvert and XGFLoader
CityJSON	All Sizes	Load Directly	Viewing CityJSON using CityJSONLoader
LAS/LAZ	All Sizes	Load Directly	Viewing LAS/LAZ using LASLoader
XKT	All Sizes	Load Directly	Viewing XKT using XKTLoader
XGF	All Sizes	Load Directly	Viewing XGF using XGFLoader

6. Code Modules

The xeokit SDK is built with a modular design for maximum flexibility and scalability in both browser and Node.js environments. It follows best practices such as:

Main modules include:

Scene – Manages 3D model objects.
Data – Provides a searchable entity-relationship data model.
Viewer – Enables interactive 3D model visualization.
Importers/Exporters – Load and export various AECO formats.
Converters – CLI tools to convert models to an optimized format.
BCF Support – Tools for BIM collaboration.
Collision Detection – Utilities for frustum culling, ray-picking, etc.
Utilities – Core functionalities like math operations and 3D graphics.

6.1. Scene Module

The Scene module (Scene ) represents the model using a scene graph that holds 3D objects, geometries, and materials. This scene graph is agnostic of the viewer and operates on both the browser and NodeJS platforms. It can be used to create models, convert between model formats, and provide content for the SDK's model viewer.

Module	Description
`@xeokit/sdk/scene`	Handles model geometries, materials, and more.

6.2. Viewer Modules

The Viewer module (Viewer ) offers a high-performance 3D viewer for browsers with a pluggable rendering strategy (WebGL/WebGPU). It allows for:

Simultaneous visualization of multiple models.
Creation of multiple canvases with customizable elements (lights, section planes, annotations).

Module	Description
`@xeokit/sdk/viewer`	Main browser-based model Viewer
`@xeokit/sdk/cameracontrol`	Interactive camera control
`@xeokit/sdk/cameraflight`	Animates camera transitions
`@xeokit/sdk/webglrenderer`	WebGL rendering implementation
`@xeokit/sdk/treeview`	HTML tree widget for model hierarchy
`@xeokit/sdk/locale`	Localization service for Viewer

6.3. Data Module

The Data module (Data ) implements an entity-relationship graph to manage model semantics (entities, properties, relationships). It is agnostic of the viewer and scene.

Module	Description
`@xeokit/sdk/data`	Manages model semantic data

6.4. Model Importer and Exporter Modules

These functions allow you to import and export model representations and semantic data in various AECO formats, either in Node.js (for file conversion) or in the browser.

Module	Description
`@xeokit/sdk/xgf`	Handles import/export of XKT
`@xeokit/sdk/dotbim`	Handles import/export of .BIM
`@xeokit/sdk/gltf`	Imports glTF
`@xeokit/sdk/las`	Imports LAS/LAZ
`@xeokit/sdk/cityjson`	Imports CityJSON
`@xeokit/sdk/webifc`	Imports IFC

6.5. Model Converter Modules

Command-line tools to convert various model formats into the SDK’s optimized XGF format.

Module	Description
`@xeokit/sdk/cityjson2xgf`	Converts CityJSON to XGF
`@xeokit/sdk/dotbim2xgf`	Converts .BIM to XGF
`@xeokit/sdk/gltf2xgf`	Converts glTF to XGF
`@xeokit/sdk/ifc2gltf2xgf`	Converts IFC output to XGF
`@xeokit/sdk/las2xgf`	Converts LAS/LAZ to XGF
`@xeokit/sdk/ifc2xgf`	Converts IFC to XGF

6.6. BCF Support Module

These functions allow sharing viewer state as industry-standard BCF Viewpoints for collaboration.

Module	Description
`@xeokit/sdk/bcf`	Load and export BCF

6.7. Collision Detection Modules

Collision detection utilities support functions like frustum culling, ray-picking, and marquee selection.

Module	Description
`@xeokit/sdk/kdtree2`	2D k-d tree search and collision tests
`@xeokit/sdk/kdtree3`	3D k-d tree search and collision tests
`@xeokit/sdk/pick`	Object selection using rays and boundaries

6.8. Utility Library Modules

A collection of low-level utility libraries used throughout the SDK.

Module	Description
`@xeokit/sdk/components`	Core component types
`@xeokit/sdk/constants`	Constants used throughout the SDK
`@xeokit/sdk/utils`	Core utility functions
`@xeokit/sdk/basictypes`	Basic semantic data type constants
`@xeokit/sdk/ifctypes`	IFC data type constants
`@xeokit/sdk/math/math`	Math definitions and constants
`@xeokit/sdk/boundaries`	Boundary math functions
`@xeokit/sdk/compression`	Geometry compression utilities
`@xeokit/sdk/curves`	Spline curves math library
`@xeokit/sdk/procgen`	Procedural geometry generation
`@xeokit/sdk/matrix`	Matrix and vector math utilities
`@xeokit/sdk/rtc`	Relative-to-center (RTC) coordinate math
`@xeokit/sdk/webglutils`	WebGL utility functions
`@xeokit/sdk/ktx2`	Compressed texture support

7. Usage Examples

7.1. Example: Viewing IFC using IFCLoader

How to use IFCLoader to view an IFC model in the browser with a xeokit web viewer.

Click to load

Viewing IFC using IFCLoader

HTML

Create an HTML page in index.html that contains a canvas element:


<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Viewing IFC using IFCLoader</title>
    <style>
        body {
            background-color: white;
            overflow: hidden;
            margin: 0;
            user-select: none;
        }

        #demoCanvas {
            width: 100%;
            height: 100%;
            position: absolute;
            background: white;
            border: 0;
        }
    </style>
</head>
<body>
<canvas id="demoCanvas"></canvas>
</body>
<script type="module" src="./index.js"></script>
</html>

JavaScript

Then create JavaScript in index.js to create the Viewer and view our converted model.

The steps in the JavaScript are as follows:

1. Import the SDK from a bundle built for these examples

import * as xeokit from "../../js/xeokit-demo-bundle.js";
import {DemoHelper} from "../../js/DemoHelper.js";

2. Create an IFCLoader to load IFC files

const ifcLoader = new xeokit.ifc.IFCLoader();

3. Create a Scene to hold geometry and materials

const scene = new xeokit.scene.Scene();

4. Create a Data to hold semantic data

const data = new xeokit.data.Data();

5. Create a WebGLRenderer to use the browser's WebGL graphics API for rendering

const renderer = new xeokit.webglrenderer.WebGLRenderer({});

6. Create a Viewer that will use the WebGLRenderer to draw the Scene

const viewer = new xeokit.viewer.Viewer({
    id: "demoViewer",
    scene,
    renderer
});

7. Give the Viewer a single View to render the Scene in our HTML canvas element

const view = viewer.createView({
    id: "demoView",
    elementId: "demoCanvas"
});

8. Arrange the View's Camera

view.camera.eye = [-6.01, 4.85, 9.11];
view.camera.look = [3.93, -2.65, -12.51];
view.camera.up = [0.12, 0.95, -0.27];

9. Add a CameraControl to interactively control the View's Camera with keyboard, mouse and touch input

new xeokit.cameracontrol.CameraControl(view, {});

10. Create a SceneModel to hold our model's geometry and materials

const sceneModel = scene.createModel({
    id: "demoModel"
});

11. Ignore the DemHelper

const demoHelper = new DemoHelper({
    viewer,
    data
});
demoHelper
    .init()
    .then(() => {

12. Create a DataModel to hold semantic data for our model

        const dataModel = data.createModel({
            id: "demoModel"
        });

13. Load our IFC data into the SceneModel and DataModel

        fetch(`../../models/Minimal_IFC4/ifc/model.ifc`)
            .then(response => {
                response
                    .arrayBuffer()
                    .then(fileData => {
                        ifcLoader.load({
                            fileData,
                            sceneModel,
                            dataModel
                        }).then(() => { // IFC file loaded

14. Build the SceneModel. The IFC model now appears in our Viewer.

                            sceneModel.build();

15. Build the DataModel. The DataModel and the Data will then contain DataObject , Relationship and PropertySet components that represent the IFC data as an entity-relationship graph.

                            dataModel.build();

16. Using the searchObjects function, query the Data for all the IfcMember elements within a given IfcBuildingStorey .

                            const resultObjectIds = [];
                            const result = xeokit.data.searchObjects(data, {
                                startObjectId: "38aOKO8_DDkBd1FHm_lVXz",
                                includeObjects: [xeokit.ifctypes.IfcMember],
                                includeRelated: [xeokit.ifctypes.IfcRelAggregates],
                                resultObjectIds
                            });

17. Check if the query was valid.

                            if (typeof result === xeokit.core.SDKError) {
                                console.error(result);
                                return;
                            }

18. If the query succeeded, go ahead and mark whatever objects we found as selected. In this case, it will set the window frames as selected in the View.

                            view.setObjectsSelected(resultObjectIds, true);
                            demoHelper.finished();
                        }).catch(e => {
                            console.error(e);
                        });
                    });
            });
    });