Reference Source
public class | source

XKTLoaderPlugin

Extends:

Plugin → XKTLoaderPlugin

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, via .XKT format version 6.
  • 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.
  • Does not (yet) support textures or physically-based materials.

Credits

XKTLoaderPlugin and the xeokit-gltf-to-xkt tool (see below) are based on prototypes by Toni Marti at uniZite.

Creating .XKT Files and Metadata

See Creating Files for Offline BIM.

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

XKTLoaderPlugin can also load an accompanying JSON metadata file with each model, which creates a MetaModel corresponding to the model Entity and a MetaObject corresponding to 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.

Usage

In the example below we'll load the Schependomlaan model from a .XKT file, along with an accompanying JSON IFC metadata 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.

import {Viewer} from "../src/viewer/Viewer.js";
import {XKTLoaderPlugin} from "../src/plugins/XKTLoaderPlugin/XKTLoaderPlugin.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/schependomlaan.xkt",
    metaModelSrc: "./metaModels/schependomlaan/metaModel.json",     // Creates a MetaModel (see below)
    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();

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/duplex.xkt",
     metaModelSrc: "./metaModels/duplex/metaModel.json",
     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/OTCConferenceCenter.xkt",
    metaModelSrc: "./metaModels/OTCConferenceCenter/metaModel.json",
    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/OTCConferenceCenter.xkt",
    metaModelSrc: "./metaModels/OTCConferenceCenter/metaModel.json",
    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.

  • [Run example]

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/duplex.xkt",
     metaModelSrc: "./metaModels/duplex/metaModel.json", // Creates a MetaObject instances in scene.metaScene.metaObjects
     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 "./../src/viewer/scene/utils.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/duplex.xkt",
     metaModelSrc: "./metaModels/duplex/metaModel.json" // Creates a MetaObject instances in scene.metaScene.metaObjects
});

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.

xktLoader.globalizeObjectIds = true;

const model = xktLoader.load({
     id: "model1",
     src: "./models/xkt/schependomlaan/schependomlaan.xkt",
     metaModelSrc: "./metaModels/schependomlaan/metaModel.json"
});

const model2 = xktLoader.load({
   id: "model2",
   src: "./models/xkt/schependomlaan/schependomlaan.xkt",
   metaModelSrc: "./metaModels/schependomlaan/metaModel.json"
});

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);

Constructor Summary

Public Constructor
public

constructor(viewer: Viewer, cfg: Object)

Member Summary

Public Members
public set

Sets a custom data source through which the XKTLoaderPlugin can load models and metadata.

public get

Gets the custom data source through which the XKTLoaderPlugin can load models and metadata.

public set

Sets the blacklist of IFC types that are never loaded by this XKTLoaderPlugin.

public get

Gets the blacklist of IFC types that are never loaded by this XKTLoaderPlugin.

public set

Sets whether we load objects that don't have IFC types.

When loading models with metadata and this is true, XKTLoaderPlugin will not load objects that don't have IFC types.

public get

Gets whether we load objects that don't have IFC types.

When loading models with metadata and this is true, XKTLoaderPlugin will not load objects that don't have IFC types.

public set

Sets whether XKTLoaderPlugin globalizes each Entity#id and MetaObject#id as it loads a model.

public get

Gets whether XKTLoaderPlugin globalizes each Entity#id and MetaObject#id as it loads a model.

public set

Sets the whitelist of the IFC types loaded by this XKTLoaderPlugin.

public get

Gets the whitelist of the IFC types loaded by this XKTLoaderPlugin.

public set

objectDefaults: {String: Object}

Sets map of initial default states for each loaded Entity that represents an object.

public get

objectDefaults: {String: Object}

Gets map of initial default states for each loaded Entity that represents an object.

public get

Gets the .xkt format versions supported by this XKTLoaderPlugin/

Method Summary

Public Methods
public

load(params: *): Entity

Loads an .xkt model into this XKTLoaderPlugin's Viewer.

Inherited Summary

From class Plugin
public

ID for this Plugin, unique within its Viewer.

public

The Viewer that contains this Plugin.

public

Destroys this Plugin and removes it from its Viewer.

public

error(msg: String)

Logs an error message to the JavaScript developer console, prefixed with the ID of this Plugin.

public

fire(event: String, value: Object)

Fires an event at this Plugin.

public

log(msg: String)

Logs a message to the JavaScript developer console, prefixed with the ID of this Plugin.

public

on(event: String, callback: Function)

Subscribes to an event fired at this Plugin.

public

warn(msg: String)

Logs a warning message to the JavaScript developer console, prefixed with the ID of this Plugin.

Public Constructors

public constructor(viewer: Viewer, cfg: Object) source

Creates this Plugin and installs it into the given Viewer.

Override:

Plugin#constructor

Params:

NameTypeAttributeDescription
viewer Viewer

The Viewer.

cfg Object

Plugin configuration.

cfg.id String
  • optional
  • default: "XKTLoader"

Optional ID for this plugin, so that we can find it within Viewer#plugins.

cfg.objectDefaults Object
  • optional

Map of initial default states for each loaded Entity that represents an object. Default value is IFCObjectDefaults.

cfg.dataSource Object
  • optional

A custom data source through which the XKTLoaderPlugin can load model and metadata files. Defaults to an instance of XKTDefaultDataSource, which loads uover HTTP.

cfg.includeTypes String[]
  • optional

When loading metadata, only loads objects that have MetaObjects with MetaObject#type values in this list.

cfg.excludeTypes String[]
  • optional

When loading metadata, never loads objects that have MetaObjects with MetaObject#type values in this list.

cfg.excludeUnclassifiedObjects Boolean
  • optional
  • default: false

When loading metadata and this is true, will only load Entitys that have MetaObjects (that are not excluded). This is useful when we don't want Entitys in the Scene that are not represented within IFC navigation components, such as TreeViewPlugin.

cfg.maxGeometryBatchSize Number
  • optional
  • default: 50000000

Maximum geometry batch size, as number of vertices. This is optionally supplied to limit the size of the batched geometry arrays that PerformanceModel internally creates for batched geometries. A low value means less heap allocation/de-allocation while loading batched geometries, but more draw calls and slower rendering speed. A high value means larger heap allocation/de-allocation while loading, but less draw calls and faster rendering speed. It's recommended to keep this somewhere roughly between 50000 and `50000000.

Public Members

public set dataSource: Object source

Sets a custom data source through which the XKTLoaderPlugin can load models and metadata.

Default value is XKTDefaultDataSource, which loads via HTTP.

public get dataSource: Object source

Gets the custom data source through which the XKTLoaderPlugin can load models and metadata.

Default value is XKTDefaultDataSource, which loads via HTTP.

public set excludeTypes: String[] source

Sets the blacklist of IFC types that are never loaded by this XKTLoaderPlugin.

When loading models with metadata, causes this XKTLoaderPlugin to not load objects whose types are in this list. An object's type is indicated by its MetaObject's MetaObject#type.

Default value is undefined.

public get excludeTypes: String[] source

Gets the blacklist of IFC types that are never loaded by this XKTLoaderPlugin.

When loading models with metadata, causes this XKTLoaderPlugin to not load objects whose types are in this list. An object's type is indicated by its MetaObject's MetaObject#type.

Default value is undefined.

public set excludeUnclassifiedObjects: Boolean source

Sets whether we load objects that don't have IFC types.

When loading models with metadata and this is true, XKTLoaderPlugin will not load objects that don't have IFC types.

Default value is false.

public get excludeUnclassifiedObjects: Boolean source

Gets whether we load objects that don't have IFC types.

When loading models with metadata and this is true, XKTLoaderPlugin will not load objects that don't have IFC types.

Default value is false.

public set globalizeObjectIds: Boolean source

Sets whether XKTLoaderPlugin globalizes each Entity#id and MetaObject#id as it loads a model.

Set this true when you need to load multiple instances of the same model, to avoid ID clashes between the objects in the different instances.

When we load a model with this set true, then each Entity#id and MetaObject#id will be prefixed by the ID of the model, ie. <modelId>#<objectId>.

Entity#originalSystemId and MetaObject#originalSystemId will always hold the original, un-prefixed, ID values.

Default value is false.

See the main XKTLoaderPlugin class documentation for usage info.

public get globalizeObjectIds: Boolean source

Gets whether XKTLoaderPlugin globalizes each Entity#id and MetaObject#id as it loads a model.

Default value is false.

public set includeTypes: String[] source

Sets the whitelist of the IFC types loaded by this XKTLoaderPlugin.

When loading models with metadata, causes this XKTLoaderPlugin to only load objects whose types are in this list. An object's type is indicated by its MetaObject's MetaObject#type.

Default value is undefined.

public get includeTypes: String[] source

Gets the whitelist of the IFC types loaded by this XKTLoaderPlugin.

When loading models with metadata, causes this XKTLoaderPlugin to only load objects whose types are in this list. An object's type is indicated by its MetaObject's MetaObject#type.

Default value is undefined.

public set objectDefaults: {String: Object} source

Sets map of initial default states for each loaded Entity that represents an object.

Default value is IFCObjectDefaults.

public get objectDefaults: {String: Object} source

Gets map of initial default states for each loaded Entity that represents an object.

Default value is IFCObjectDefaults.

public get supportedVersions: string[]: * source

Gets the .xkt format versions supported by this XKTLoaderPlugin/

Return:

string[]

Public Methods

public load(params: *): Entity source

Loads an .xkt model into this XKTLoaderPlugin's Viewer.

Params:

NameTypeAttributeDescription
params *

Loading parameters.

params.id String
  • optional

ID to assign to the root Entity#id, unique among all components in the Viewer's Scene, generated automatically by default.

params.src String
  • optional

Path to a .xkt file, as an alternative to the xkt parameter.

params.xkt ArrayBuffer
  • optional

The .xkt file data, as an alternative to the src parameter.

params.metaModelSrc String
  • optional

Path to an optional metadata file, as an alternative to the metaModelData parameter (see user guide: Model Metadata).

params.metaModelData *
  • optional

JSON model metadata, as an alternative to the metaModelSrc parameter (see user guide: Model Metadata).

params.objectDefaults {String: Object}
  • optional

Map of initial default states for each loaded Entity that represents an object. Default value is IFCObjectDefaults.

params.includeTypes String[]
  • optional

When loading metadata, only loads objects that have MetaObjects with MetaObject#type values in this list.

params.excludeTypes String[]
  • optional

When loading metadata, never loads objects that have MetaObjects with MetaObject#type values in this list.

params.edges Boolean
  • optional
  • default: false

Whether or not xeokit renders the model with edges emphasized.

params.position Number[]
  • optional
  • default: [0,0,0]

The model World-space 3D position.

params.scale Number[]
  • optional
  • default: [1,1,1]

The model's World-space scale.

params.rotation Number[]
  • optional
  • default: [0,0,0]

The model's World-space rotation, as Euler angles given in degrees, for each of the X, Y and Z axis.

params.matrix Number[]
  • optional
  • default: [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]

The model's world transform matrix. Overrides the position, scale and rotation parameters.

params.edges Boolean
  • optional
  • default: false

Indicates if the model's edges are initially emphasized.

params.saoEnabled Boolean
  • optional
  • default: true

Indicates if Scalable Ambient Obscurance (SAO) will apply to the model. SAO is configured by the Scene's SAO component. Only works when SAO#enabled is also true

params.pbrEnabled Boolean
  • optional
  • default: false

Indicates if physically-based rendering (PBR) will apply to the model. Only works when Scene#pbrEnabled is also true.

params.backfaces Number
  • optional
  • default: false

When we set this true, then we force rendering of backfaces for the model. When we leave this false, then we allow the Viewer to decide when to render backfaces. In that case, the Viewer will hide backfaces on watertight meshes, show backfaces on open meshes, and always show backfaces on meshes when we slice them open with SectionPlanes.

params.excludeUnclassifiedObjects Boolean
  • optional
  • default: false

When loading metadata and this is true, will only load Entitys that have MetaObjects (that are not excluded). This is useful when we don't want Entitys in the Scene that are not represented within IFC navigation components, such as TreeViewPlugin.

params.globalizeObjectIds Boolean
  • optional
  • default: false

Indicates whether to globalize each Entity#id and MetaObject#id, in case you need to prevent ID clashes with other models. See XKTLoaderPlugin#globalizeObjectIds for more info.

Return:

Entity

Entity representing the model, which will have Entity#isModel set true and will be registered by Entity#id in Scene#models.