Reference Source
public class | source

GLTFLoaderPlugin

Extends:

Plugin → GLTFLoaderPlugin

Viewer plugin that loads models from glTF.

  • Creates an Entity representing each model it loads, which will have Entity#isModel set true and will be registered by Entity#id in Scene#models.
  • Creates an Entity for each object within the model, which is indicated by each glTF node that has a name attribute. Those Entities will have Entity#isObject set true and will be registered by Entity#id in Scene#objects.
  • When loading, can set the World-space position, scale and rotation of each model within World space, along with initial properties for all the model's Entitys.

Metadata

GLTFLoaderPlugin 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 provide GLTFLoaderPlugin with a custom lookup table of initial values to set on the properties of each type of Entity. By default, GLTFLoaderPlugin uses its own map of default colors and visibilities for IFC element types.

Quality Setting

By default, GLTFLoaderPlugin will load a high-performance scene representation that's optimized for low memory usage and optimal rendering. The high-performance representation renders large numbers of objects efficiently, using geometry batching and instancing, with simple Lambertian shading that ignores any textures and realistic materials in the glTF.

Specifying performance:false to GLTFLoaderPlugin#load will internally load a heavier scene representation comprised of Node, Mesh, Geometry, Material and Texture components, that will exactly preserve the materials specified in the glTF. Use this when you want to load a model for a realistic preview, maybe using PBR etc.

We tend to use the default performance:true setting for CAD and BIM models, where structure is more important that surface appearance.

Publically, GLTFLoaderPlugin creates the same Entitys for both levels of performance. Privately, however, it implements Entitys using two different sets of concrete subtypes, for its two different internally-managed scene representations.

Usage

In the example below we'll load the Schependomlaan model from a glTF 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 GLTFLoaderPlugin will set the initial colors of object Entitys according to the standard IFC element colors in the GLTFModel's current map. Override that with your own map via property GLTFLoaderPlugin#objectDefaults.

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

We're leaving performance: true since our model has many objects and we're not interested in realistic rendering.

[Run this example]

import {Viewer} from "../src/viewer/Viewer.js";
import {GLTFLoaderPlugin} from "../src/plugins/GLTFLoaderPlugin/GLTFLoaderPlugin.js";

//------------------------------------------------------------------------------------------------------------------
// 1. Create a Viewer,
// 2. Arrange the camera,
// 3. Tweak the selection material (tone it down a bit)
//------------------------------------------------------------------------------------------------------------------

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

// 2
viewer.camera.orbitPitch(20);
viewer.camera.orbitYaw(-45);

// 3
viewer.scene.selectedMaterial.fillAlpha = 0.1;

//------------------------------------------------------------------------------------------------------------------
// 1. Create a glTF loader plugin,
// 2. Load a glTF building model and JSON IFC metadata
// 3. Emphasis the edges to make it look nice
//------------------------------------------------------------------------------------------------------------------

// 1
const gltfLoader = new GLTFLoaderPlugin(viewer);

// 2
var model = gltfLoader.load({                                    // Returns an Entity that represents the model
     id: "myModel",
     src: "./models/gltf/OTCConferenceCenter/scene.gltf",
     metaModelSrc: "./metaModels/OTCConferenceCenter/metaModel.json",     // Creates a MetaModel (see below)
     edges: true,
     performance: true  // Load high-performance scene representation (default is false)
});

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

[Run example]

const model = gltfLoader.load({
     src: "./models/gltf/duplex/scene.gltf",
     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.

[Run this example]

const model = gltfLoader.load({
    id: "myModel",
     src: "./models/gltf/OTCConferenceCenter/scene.gltf",
     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 model = gltfLoader.load({
    id: "myModel",
     src: "./models/gltf/OTCConferenceCenter/scene.gltf",
     metaModelSrc: "./metaModels/OTCConferenceCenter/metaModel.json",
     excludeTypes: ["IfcSpace"]
});

Constructor Summary

Public Constructor
public

constructor(viewer: Viewer, cfg: Object)

Member Summary

Public Members
public set

Sets a custom data source through which the GLTFLoaderPlugin can load metadata, glTF and binary attachments.

public get

Gets the custom data source through which the GLTFLoaderPlugin can load metadata, glTF and binary attachments.

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

Destroys this GLTFLoaderPlugin.

public

load(params: *): Entity

Loads a glTF model from a file into this GLTFLoaderPlugin'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: "GLTFLoader"

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 GLTFLoaderPlugin can load metadata, glTF and binary attachments. Defaults to an instance of GLTFDefaultDataSource, which loads uover HTTP.

Public Members

public set dataSource: Object source

Sets a custom data source through which the GLTFLoaderPlugin can load metadata, glTF and binary attachments.

Default value is GLTFDefaultDataSource, which loads via an XMLHttpRequest.

public get dataSource: Object source

Gets the custom data source through which the GLTFLoaderPlugin can load metadata, glTF and binary attachments.

Default value is GLTFDefaultDataSource, which loads via an XMLHttpRequest.

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 destroy() source

Destroys this GLTFLoaderPlugin.

Override:

Plugin#destroy

public load(params: *): Entity source

Loads a glTF model from a file into this GLTFLoaderPlugin'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 glTF file, as an alternative to the gltf parameter.

params.gltf *
  • optional

glTF JSON, 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.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.backfaces Boolean
  • optional
  • default: false

When true, allows visible backfaces, wherever specified in the glTF. When false, ignores backfaces.

params.edgeThreshold Number
  • optional
  • default: 20

When xraying, highlighting, selecting or edging, this is the threshold angle between normals of adjacent triangles, below which their shared wireframe edge is not drawn.

Return:

Entity

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