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.
  • 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.
  • Does not 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

Use the node.js-based xeokit-gltf-to-xkt tool to convert your glTF IFC files to .xkt format.

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.

[Run this example]

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

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.

[Run example]

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.

[Run example]

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 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.


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

Configuring a custom data source

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

As shown below, we can 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.

[Run example]

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

Static Member Summary

Static Public Members
public static get

The .xkt format version supported by this XKTLoaderPlugin.

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 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.

Method Summary

Public Methods
public

load(params: *): Entity

Loads a .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.

Static Public Members

public static get XKTVersion: Number source

The .xkt format version supported by this XKTLoaderPlugin.

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.

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 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 Methods

public load(params: *): Entity source

Loads a .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.

Return:

Entity

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