Viewer plugin that loads models from xeokit's optimized .XKT format.

[Run this example]

Overview

• XKTLoaderPlugin is the most efficient way to load high-detail models into xeokit.
• An .XKT file is a single BLOB containing a model, compressed using geometry quantization and pako.
• Supports double-precision coordinates.
• Supports compressed textures.
• Set the position, scale and rotation of each model as you load it.
• Filter which IFC types get loaded.
• Configure initial default appearances for IFC types.
• Set a custom data source for .XKT and IFC metadata files.
• Option to load multiple copies of the same model, without object ID clashes.

Creating .XKT Files and Metadata

We have several sways to convert your files into XKT. See these tutorials for more info:

• Converting Models to XKT with convert2xkt - how to convert various file formats (glTF, IFC, CityJSON, LAS/LAZ...) to XKT using our nodejs-based converter.
• Converting IFC Models to XKT using 3rd-Party Open Source Tools - how to convert IFC files to XKT using 3rd-party open source CLI tools.

Scene representation

When loading a model, XKTLoaderPlugin creates an Entity that represents the model, which will have Entity#isModel set true and will be registered by Entity#id in Scene#models. The XKTLoaderPlugin also creates an Entity for each object within the model. Those Entities will have Entity#isObject set true and will be registered by Entity#id in Scene#objects.

Metadata

Since XKT V8, model metadata is included in the XKT file. If the XKT file has metadata, then loading it creates model metadata components within the Viewer, namely a MetaModel corresponding to the model Entity, and a MetaObject for each object Entity.

Each MetaObject has a MetaObject#type, which indicates the classification of its corresponding Entity. When loading metadata, we can also configure XKTLoaderPlugin with a custom lookup table of initial values to set on the properties of each type of Entity. By default, XKTLoaderPlugin uses its own map of default colors and visibilities for IFC element types.

For XKT versions prior to V8, we provided the metadata to XKTLoaderPlugin as an accompanying JSON file to load. We can still do that for all XKT versions, and for XKT V8+ it will override any metadata provided within the XKT file.

Usage

In the example below we'll load the Schependomlaan model from a .XKT file.

This will create a bunch of Entitys that represents the model and its objects, along with a MetaModel and MetaObjects that hold their metadata.

Since this model contains IFC types, the XKTLoaderPlugin will set the initial appearance of each object Entity according to its IFC type in XKTLoaderPlugin#objectDefaults.

Read more about this example in the user guide on Viewing BIM Models Offline.

• [Run example]

import {Viewer, XKTLoaderPlugin} from "xeokit-sdk.es.js";

//------------------------------------------------------------------------------------------------------------------
// 1. Create a Viewer,
// 2. Arrange the camera
//------------------------------------------------------------------------------------------------------------------

// 1
const viewer = new Viewer({
     canvasId: "myCanvas",
     transparent: true
});

// 2
viewer.camera.eye = [-2.56, 8.38, 8.27];
viewer.camera.look = [13.44, 3.31, -14.83];
viewer.camera.up = [0.10, 0.98, -0.14];

//------------------------------------------------------------------------------------------------------------------
// 1. Create a XKTLoaderPlugin,
// 2. Load a building model and JSON IFC metadata
//------------------------------------------------------------------------------------------------------------------

// 1
const xktLoader = new XKTLoaderPlugin(viewer);

// 2
const model = xktLoader.load({          // Returns an Entity that represents the model
    id: "myModel",
    src: "./models/xkt/Schependomlaan.xkt",
    edges: true
});

model.on("loaded", () => {

    //--------------------------------------------------------------------------------------------------------------
    // 1. Find metadata on the third storey
    // 2. Select all the objects in the building's third storey
    // 3. Fit the camera to all the objects on the third storey
    //--------------------------------------------------------------------------------------------------------------

    // 1
    const metaModel = viewer.metaScene.metaModels["myModel"];       // MetaModel with ID "myModel"
    const metaObject
         = viewer.metaScene.metaObjects["0u4wgLe6n0ABVaiXyikbkA"];  // MetaObject with ID "0u4wgLe6n0ABVaiXyikbkA"

    const name = metaObject.name;                                   // "01 eerste verdieping"
    const type = metaObject.type;                                   // "IfcBuildingStorey"
    const parent = metaObject.parent;                               // MetaObject with type "IfcBuilding"
    const children = metaObject.children;                           // Array of child MetaObjects
    const objectId = metaObject.id;                                 // "0u4wgLe6n0ABVaiXyikbkA"
    const objectIds = viewer.metaScene.getObjectIDsInSubtree(objectId);   // IDs of leaf sub-objects
    const aabb = viewer.scene.getAABB(objectIds);                   // Axis-aligned boundary of the leaf sub-objects

    // 2
    viewer.scene.setObjectsSelected(objectIds, true);

    // 3
    viewer.cameraFlight.flyTo(aabb);
});

// Find the model Entity by ID
model = viewer.scene.models["myModel"];

// Destroy the model
model.destroy();

Loading XKT files containing textures

XKTLoaderPlugin uses a KTX2TextureTranscoder to load textures in XKT files (XKT v10+). An XKTLoaderPlugin has its own default KTX2TextureTranscoder, configured to load the Basis Codec from the CDN. If we wish, we can override that with our own KTX2TextureTranscoder instance that's configured to load the Codec locally.

In the example below, we'll create a Viewer and add an XKTLoaderPlugin configured with a KTX2TextureTranscoder that finds the Codec in our local file system. Then we'll use the XKTLoaderPlugin to load an XKT file that contains KTX2 textures, which the plugin will transcode using its KTX2TextureTranscoder.

We'll configure our KTX2TextureTranscoder to load the Basis Codec from a local directory. If we were happy with loading the Codec from our CDN (ie. our app will always have an Internet connection) then we could just leave out the KTX2TextureTranscoder altogether, and let the XKTLoaderPlugin use its internal default KTX2TextureTranscoder, which is configured to load the Codec from the CDN. We'll stick with loading our own Codec, in case we want to run our app without an Internet connection.

• [Run this example]

const viewer = new Viewer({
    canvasId: "myCanvas",
    transparent: true
});

viewer.camera.eye = [-2.56, 8.38, 8.27];
viewer.camera.look = [13.44, 3.31, -14.83];
viewer.camera.up = [0.10, 0.98, -0.14];

const textureTranscoder = new KTX2TextureTranscoder({
    viewer,
    transcoderPath: "https://cdn.jsdelivr.net/npm/@xeokit/xeokit-sdk/dist/basis/" // <------ Path to Basis Universal transcoder
});

const xktLoader = new XKTLoaderPlugin(viewer, {
    textureTranscoder // <<------------- Transcodes KTX2 textures in XKT files
});

const sceneModel = xktLoader.load({
    id: "myModel",
    src: "./HousePlan.xkt" // <<------ XKT file with KTX2 textures
});

Transforming

We have the option to rotate, scale and translate each .XKT model as we load it.

This lets us load multiple models, or even multiple copies of the same model, and position them apart from each other.

In the example below, we'll scale our model to half its size, rotate it 90 degrees about its local X-axis, then translate it 100 units along its X axis.

xktLoader.load({
     src: "./models/xkt/Duplex.ifc.xkt",
     rotation: [90,0,0],
     scale: [0.5, 0.5, 0.5],
     position: [100, 0, 0]
});

Including and excluding IFC types

We can also load only those objects that have the specified IFC types.

In the example below, we'll load only the objects that represent walls.

const model2 = xktLoader.load({
    id: "myModel2",
    src: "./models/xkt/OTCConferenceCenter.xkt",
    includeTypes: ["IfcWallStandardCase"]
});

We can also load only those objects that don't have the specified IFC types.

In the example below, we'll load only the objects that do not represent empty space.

const model3 = xktLoader.load({
    id: "myModel3",
    src: "./models/xkt/OTCConferenceCenter.xkt",
    excludeTypes: ["IfcSpace"]
});

Configuring initial IFC object appearances

We can specify the custom initial appearance of loaded objects according to their IFC types.

This is useful for things like:

• setting the colors to our objects according to their IFC types,
• automatically hiding IfcSpace objects, and
• ensuring that IfcWindow objects are always transparent.
  In the example below, we'll load a model, while configuring IfcSpace elements to be always initially invisible, and IfcWindow types to be always translucent blue.

const myObjectDefaults = {

     IfcSpace: {
         visible: false
     },
     IfcWindow: {
         colorize: [0.337255, 0.303922, 0.870588], // Blue
         opacity: 0.3
     },

     //...

     DEFAULT: {
         colorize: [0.5, 0.5, 0.5]
     }
};

const model4 = xktLoader.load({
     id: "myModel4",
     src: "./models/xkt/Duplex.ifc.xkt",
     objectDefaults: myObjectDefaults // Use our custom initial default states for object Entities
});

When we don't customize the appearance of IFC types, as just above, then IfcSpace elements tend to obscure other elements, which can be confusing.

It's often helpful to make IfcSpaces transparent and unpickable, like this:

const xktLoader = new XKTLoaderPlugin(viewer, {
   objectDefaults: {
       IfcSpace: {
           pickable: false,
           opacity: 0.2
       }
   }
});

Alternatively, we could just make IfcSpaces invisible, which also makes them unpickable:

const xktLoader = new XKTLoaderPlugin(viewer, {
   objectDefaults: {
       IfcSpace: {
           visible: false
       }
   }
});

Configuring a custom data source

By default, XKTLoaderPlugin will load .XKT files and metadata JSON over HTTP.

In the example below, we'll customize the way XKTLoaderPlugin loads the files by configuring it with our own data source object. For simplicity, our custom data source example also uses HTTP, using a couple of xeokit utility functions.

import {utils} from "xeokit-sdk.es.js";

class MyDataSource {

     constructor() {
     }

     // Gets metamodel JSON
     getMetaModel(metaModelSrc, ok, error) {
         console.log("MyDataSource#getMetaModel(" + metaModelSrc + ", ... )");
         utils.loadJSON(metaModelSrc,
             (json) => {
                 ok(json);
             },
             function (errMsg) {
                 error(errMsg);
             });
     }

     // Gets the contents of the given .XKT file in an arraybuffer
     getXKT(src, ok, error) {
         console.log("MyDataSource#getXKT(" + xKTSrc + ", ... )");
         utils.loadArraybuffer(src,
             (arraybuffer) => {
                 ok(arraybuffer);
             },
             function (errMsg) {
                 error(errMsg);
             });
     }
}

const xktLoader2 = new XKTLoaderPlugin(viewer, {
      dataSource: new MyDataSource()
});

const model5 = xktLoader2.load({
     id: "myModel5",
     src: "./models/xkt/Duplex.ifc.xkt"
});

Loading multiple copies of a model, without object ID clashes

Sometimes we need to load two or more instances of the same model, without having clashes between the IDs of the equivalent objects in the model instances.

As shown in the example below, we do this by setting XKTLoaderPlugin#globalizeObjectIds true before we load our models.

• [Run example]

xktLoader.globalizeObjectIds = true;

const model = xktLoader.load({
     id: "model1",
     src: "./models/xkt/Schependomlaan.xkt"
});

const model2 = xktLoader.load({
   id: "model2",
   src: "./models/xkt/Schependomlaan.xkt"
});

For each Entity loaded by these two calls, Entity#id and MetaObject#id will get prefixed by the ID of their model, in order to avoid ID clashes between the two models.

An Entity belonging to the first model will get an ID like this:

myModel1#0BTBFw6f90Nfh9rP1dlXrb

The equivalent Entity in the second model will get an ID like this:

myModel2#0BTBFw6f90Nfh9rP1dlXrb

Now, to update the visibility of both of those Entities collectively, using Scene#setObjectsVisible, we can supply just the IFC product ID part to that method:

myViewer.scene.setObjectVisibilities("0BTBFw6f90Nfh9rP1dlXrb", true);

The method, along with Scene#setObjectsXRayed, Scene#setObjectsHighlighted etc, will internally expand the given ID to refer to the instances of that Entity in both models.

We can also, of course, reference each Entity directly, using its globalized ID:

myViewer.scene.setObjectVisibilities("myModel1#0BTBFw6f90Nfh9rP1dlXrb", true);

We can also provide an HTTP URL to the XKT file:

const sceneModel = xktLoader.load({
  manifestSrc: "https://xeokit.github.io/xeokit-sdk/assets/models/models/xkt/Schependomlaan.xkt",
  id: "myModel",
});

Loading a model from a manifest of XKT files

The ifc2gltf tool from Creoox, which converts IFC files into glTF geometry and JSON metadata files, has the option to split its output into multiple pairs of glTF and JSON files, accompanied by a JSON manifest that lists the files.

To integrate with that option, the convert2xkt tool, which converts glTF geometry and JSON metadata files into XKT files, also has the option to batch-convert the glTF+JSON files in the manifest, in one invocation.

When we use this option, convert2xkt will output a bunch of XKT files, along with a JSON manifest file that lists those XKT files.

Working down the pipeline, the XKTLoaderPlugin has the option batch-load all XKT files listed in that manifest into a xeokit Viewer in one load operation, combining the XKT files into a single SceneModel and MetaModel.

You can learn more about this conversion and loading process, with splitting, batch converting and batch loading, in this tutorial.

To show how to use XKTLoaderPlugin to load a manifest of XKT files, let's imagine that we have a set of such XKT files. As described in the tutorial, they were converted by ifc2gltf from an IFC file into a set of glTF+JSON files, that were then converted by convert2xkt into this set of XKT files and a manifest, as shown below.

./
├── model_1.xkt
├── model_2.xkt
├── model_3.xkt
├── model_4..xkt
└── model.xkt.manifest.json

The model.xkt.manifest.json XKT manifest would look something like this:

{
  "inputFile": null,
  "converterApplication": "convert2xkt",
  "converterApplicationVersion": "v1.1.9",
  "conversionDate": "10-08-2023- 02-05-01",
  "outputDir": null,
  "xktFiles": [
    "model_1.xkt",
    "model_2.xkt",
    "model_3.xkt",
    "model_4.xkt"
  ]
}

Now, to load all those XKT files into a single SceneModel and MetaModel in one operation, we pass a path to the XKT manifest to XKTLoaderPlugin.load, as shown in the example below:

• [Run example]

import {
  Viewer,
  XKTLoaderPlugin,
  TreeViewPlugin,
} from "xeokit-sdk.es.js";

constviewer = new Viewer({
  canvasId: "myCanvas"
});

viewer.scene.camera.eye = [26.54, 29.29, 36.20,];
viewer.scene.camera.look = [-23.51, -8.26, -21.65,];
viewer.scene.camera.up = [-0.2, 0.89, -0.33,];

const xktLoader = new XKTLoaderPlugin(viewer);

const sceneModel = xktLoader.load({
  manifestSrc: "model.xkt.manifest.json",
  id: "myModel",
});

const metaModel = viewer.metaScene.metaModels[sceneModel.id];

// Then when we need to, we can destroy the SceneModel
// and MetaModel in one shot, like so:

sceneModel.destroy();
metaModel.destroy();

The main advantage here, of splitting IFC files like this within the conversion and import pipeline, is to reduce the memory pressure on each of the ifc2gltf, convert2xkt and XKTLoaderPlugin components. They work much reliably (and faster) when processing smaller files (eg. 20MB) than when processing large files (eg. 500MB), where they have less trouble allocating the system memory they need for conversion and parsing.

We can also provide an HTTP URL to the manifest:

const sceneModel = xktLoader.load({
  manifestSrc: "https://xeokit.github.io/xeokit-sdk/assets/models/xkt/v10/split/Karhumaki-Bridge/model.xkt.manifest.json",
  id: "myModel",
});

We can also provide the manifest as parameter object:

const sceneModel = xktLoader.load({
  id: "myModel",
  manifest: {
  inputFile: "assets/models/gltf/Karhumaki/model.glb.manifest.json",
  converterApplication: "convert2xkt",
  converterApplicationVersion: "v1.1.10",
  conversionDate": "09-11-2023- 18-29-01",
    xktFiles: [
      "../../assets/models/xkt/v10/split/Karhumaki-Bridge/model.xkt",
      "../../assets/models/xkt/v10/split/Karhumaki-Bridge/model_1.xkt",
      "../../assets/models/xkt/v10/split/Karhumaki-Bridge/model_2.xkt",
      "../../assets/models/xkt/v10/split/Karhumaki-Bridge/model_3.xkt",
      "../../assets/models/xkt/v10/split/Karhumaki-Bridge/model_4.xkt",
      "../../assets/models/xkt/v10/split/Karhumaki-Bridge/model_5.xkt",
      "../../assets/models/xkt/v10/split/Karhumaki-Bridge/model_6.xkt",
      "../../assets/models/xkt/v10/split/Karhumaki-Bridge/model_7.xkt",
      "../../assets/models/xkt/v10/split/Karhumaki-Bridge/model_8.xkt"
    ]
  }
});

We can also provide the paths to the XKT files as HTTP URLs:

const sceneModel = xktLoader.load({
  id: "myModel",
  manifest: {
  inputFile: "assets/models/gltf/Karhumaki/model.glb.manifest.json",
  converterApplication: "convert2xkt",
  converterApplicationVersion: "v1.1.10",
  conversionDate": "09-11-2023- 18-29-01",
    xktFiles: [
      "https://xeokit.github.io/xeokit-sdk/assets/models/xkt/v10/split/Karhumaki-Bridge/model.xkt",
      "https://xeokit.github.io/xeokit-sdk/assets/models/xkt/v10/split/Karhumaki-Bridge/model_1.xkt",
      "https://xeokit.github.io/xeokit-sdk/assets/models/xkt/v10/split/Karhumaki-Bridge/model_2.xkt",
      "https://xeokit.github.io/xeokit-sdk/assets/models/xkt/v10/split/Karhumaki-Bridge/model_3.xkt",
      "https://xeokit.github.io/xeokit-sdk/assets/models/xkt/v10/split/Karhumaki-Bridge/model_4.xkt",
      "https://xeokit.github.io/xeokit-sdk/assets/models/xkt/v10/split/Karhumaki-Bridge/model_5.xkt",
      "https://xeokit.github.io/xeokit-sdk/assets/models/xkt/v10/split/Karhumaki-Bridge/model_6.xkt",
      "https://xeokit.github.io/xeokit-sdk/assets/models/xkt/v10/split/Karhumaki-Bridge/model_7.xkt",
      "https://xeokit.github.io/xeokit-sdk/assets/models/xkt/v10/split/Karhumaki-Bridge/model_8.xkt"
    ]
  }
});