Reference Source
public class | source

StoreyViewsPlugin

Extends:

Plugin → StoreyViewsPlugin

A Viewer plugin that provides methods for visualizing IfcBuildingStoreys.

[Run this example]

Overview

StoreyViewsPlugin provides a flexible set of methods for visualizing building storeys in 3D and 2D.

Use the first two methods to set up 3D views of storeys:

Use the second two methods to create 2D plan view mini-map images:

Usage

Let's start by creating a Viewer with a StoreyViewsPlugin and an XKTLoaderPlugin.

Then we'll load a BIM building model from an .xkt file.

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

// Create a Viewer, arrange the camera

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

// Add an XKTLoaderPlugin

const xktLoader = new XKTLoaderPlugin(viewer);

// Add a StoreyViewsPlugin

const storeyViewsPlugin = new StoreyViewsPlugin(viewer);

// Load a BIM model from .xkt format

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

Finding Storeys

Getting information on a storey in our model:

const storey = storeyViewsPlugin.storeys["2SWZMQPyD9pfT9q87pgXa1"]; // ID of the IfcBuildingStorey

const modelId  = storey.modelId;  // "myModel"
const storeyId = storey.storeyId; // "2SWZMQPyD9pfT9q87pgXa1"
const aabb     = storey.aabb;     // Axis-aligned 3D World-space boundary of the IfcBuildingStorey

We can also get a "storeys" event every time the set of storeys changes, ie. every time a storey is created or destroyed:

storeyViewsPlugin.on("storeys", ()=> {
     const storey = storeyViewsPlugin.storeys["2SWZMQPyD9pfT9q87pgXa1"];
     //...
});

Showing Entitys within Storeys

Showing the Entitys within a storey:

storeyViewsPlugin.showStoreyObjects("2SWZMQPyD9pfT9q87pgXa1");

Showing only the Entitys in a storey, hiding all others:

storeyViewsPlugin.showStoreyObjects("2SWZMQPyD9pfT9q87pgXa1", {
    hideOthers: true
});

Showing only the storey Entitys:

storeyViewsPlugin.showStoreyObjects("2SWZMQPyD9pfT9q87pgXa1", {
    hideOthers: true
});

When using this option, at some point later you'll probably want to restore all Entitys to their original visibilities and appearances.

To do that, save their visibility and appearance states in an ObjectsMemento beforehand, from which you can restore them later:

const objectsMemento = new ObjectsMemento();

// Save all Entity visibility and appearance states

objectsMemento.saveObjects(viewer.scene);

// Show storey view Entitys

storeyViewsPlugin.showStoreyObjects("2SWZMQPyD9pfT9q87pgXa1");

//...

// Later, restore all Entitys to their saved visibility and appearance states
objectsMemento.restoreObjects(viewer.scene);

Arranging the Camera for Storey Plan Views

The StoreyViewsPlugin#gotoStoreyCamera method positions the Camera for a plan view of the Entitys within the given storey.

Let's fly the Camera to a downward-looking orthographic view of the Entitys within our storey.

storeyViewsPlugin.gotoStoreyCamera("2SWZMQPyD9pfT9q87pgXa1", {
    projection: "ortho", // Orthographic projection
    duration: 2.5,       // 2.5 second transition
    done: () => {
        viewer.cameraControl.planView = true; // Disable rotation
    }
});

Note that we also set CameraControl#planView true, which prevents the CameraControl from rotating or orbiting. In orthographic mode, this effectively makes the Viewer behave as if it were a 2D viewer, with picking, panning and zooming still enabled.

If you need to be able to restore the Camera to its previous state, you can save it to a CameraMemento beforehand, from which you can restore it later:

const cameraMemento = new CameraMemento();

// Save camera state

cameraMemento.saveCamera(viewer.scene);

// Position camera for a downward-looking orthographic view of our storey

storeyViewsPlugin.gotoStoreyCamera("2SWZMQPyD9pfT9q87pgXa1", {
    projection: "ortho",
    duration: 2.5,
    done: () => {
        viewer.cameraControl.planView = true; // Disable rotation
    }
});

//...

// Later, restore the Camera to its saved state
cameraMemento.restoreCamera(viewer.scene);

Creating StoreyMaps

The StoreyViewsPlugin#createStoreyMap method creates a 2D orthographic plan image of the given storey.

This method creates a StoreyMap, which provides the plan image as a Base64-encoded string.

Let's create a 2D plan image of our building storey:

const storeyMap = storeyViewsPlugin.createStoreyMap("2SWZMQPyD9pfT9q87pgXa1", {
    width: 300,
    format: "png"
});

const imageData = storeyMap.imageData; // Base64-encoded image data string
const width     = storeyMap.width; // 300
const height    = storeyMap.height; // Automatically derived from width
const format    = storeyMap.format; // "png"

We can also specify a height for the plan image, as an alternative to width:

 const storeyMap = storeyViewsPlugin.createStoreyMap("2SWZMQPyD9pfT9q87pgXa1", {
     height: 200,
     format: "png"
});

Picking Entities in StoreyMaps

We can use StoreyViewsPlugin#pickStoreyMap to pick Entities in our building storey, using 2D coordinates from mouse or touch events on our StoreyMap's 2D plan image.

Let's programmatically pick the Entity at the given 2D pixel coordinates within our image:

const mouseCoords = [65, 120]; // Mouse coords within the image extents

const pickResult = storeyViewsPlugin.pickStoreyMap(storeyMap, mouseCoords);

if (pickResult && pickResult.entity) {
    pickResult.entity.highlighted = true;
}

Constructor Summary

Public Constructor
public

constructor(viewer: Viewer, cfg: Object)

Member Summary

Public Members
public get

When true, the elements of each floor map image will be proportionally resized to encompass the entire image.

public

modelStoreys: {String: {String: Storey}}

A set of Storeys for each MetaModel.

public

storeys: {String: Storey}

A Storey for each `IfcBuildingStorey.

Method Summary

Public Methods
public

createStoreyMap(storeyId: String, options: *): StoreyMap

Creates a 2D map of the given storey.

public

Destroys this StoreyViewsPlugin.

public

Gets the ID of the storey that contains the given 3D World-space position.

public

Gets the ID of the storey which's bounding box contains the y point of the world position

public

gotoStoreyCamera(storeyId: String, options: *)

Arranges the Camera for a 3D orthographic view of the Entitys within the given storey.

public

Returns whether a position is above or below a building

public

pickStoreyMap(storeyMap: StoreyMap, imagePos: Number[], options: *): PickResult

Attempts to pick an Entity at the given pixel coordinates within a StoreyMap image.

public

showStoreyObjects(storeyId: String, options: *)

Shows the Entitys within the given storey.

public

storeyMapToWorldPos(storeyMap: *, imagePos: *, options: {}): *

public

withStoreyObjects(storeyId: String, callback: Function)

Executes a callback on each of the objects within the given storey.

public

worldDirToStoreyMap(storeyMap: StoreyMap, worldDir: Number[], imageDir: Number[])

Converts a 3D World-space direction vector to a 2D vector within a StoreyMap image.

public

worldPosToStoreyMap(storeyMap: StoreyMap, worldPos: Number[], imagePos: Number[]): Boolean

Converts a 3D World-space position to a 2D position within a StoreyMap image.

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, forget: Boolean)

Fires an event on this Plugin.

public

Returns true if there are any subscribers to the given event on this Plugin.

public

log(msg: String)

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

public

off(subId: String)

Cancels an event subscription that was previously made with Plugin#on or Plugin#once.

public

on(event: String, callback: Function, scope: Object): String

Subscribes to an event on this Plugin.

public

once(event: String, callback: Function, scope: Object)

Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is subIdd.

public

scheduleTask(task: *)

Schedule a task to perform on the next browser interval

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: "StoreyViews"

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

cfg.fitStoreyMaps Boolean
  • optional
  • default: false

If enabled, the elements of each floor map image will be proportionally resized to encompass the entire image. This leads to varying scales among different floor map images. If disabled, each floor map image will display the model's extents, ensuring a consistent scale across all images.

Public Members

public get fitStoreyMaps: * | boolean: * source

When true, the elements of each floor map image will be proportionally resized to encompass the entire image. This leads to varying scales among different floor map images. If false, each floor map image will display the model's extents, ensuring a consistent scale across all images.

Return:

* | boolean

public modelStoreys: {String: {String: Storey}} source

A set of Storeys for each MetaModel.

These are created and destroyed automatically as models are loaded and destroyed.

public storeys: {String: Storey} source

A Storey for each `IfcBuildingStorey.

There will be a Storey for every existing MetaObject whose MetaObject#type equals "IfcBuildingStorey".

These are created and destroyed automatically as models are loaded and destroyed.

Public Methods

public createStoreyMap(storeyId: String, options: *): StoreyMap source

Creates a 2D map of the given storey.

Params:

NameTypeAttributeDescription
storeyId String

ID of the IfcBuildingStorey object.

options *
  • optional

Options for creating the image.

options.width Number
  • optional
  • default: 300

Image width in pixels. Height will be automatically determined from this, if not given.

options.height Number
  • optional
  • default: 300

Image height in pixels, as an alternative to width. Width will be automatically determined from this, if not given.

options.format String
  • optional
  • default: "png"

Image format. Accepted values are "png" and "jpeg".

Return:

StoreyMap

The StoreyMap.

public destroy() source

Destroys this StoreyViewsPlugin.

Override:

Plugin#destroy

public getStoreyContainingWorldPos(worldPos: Number[]): String source

Gets the ID of the storey that contains the given 3D World-space position. .

Params:

NameTypeAttributeDescription
worldPos Number[]

3D World-space position.

Return:

String

ID of the storey containing the position, or null if the position falls outside all the storeys.

public getStoreyInVerticalRange(worldPos: Number[]): String source

Gets the ID of the storey which's bounding box contains the y point of the world position

Params:

NameTypeAttributeDescription
worldPos Number[]

3D World-space position.

Return:

String

ID of the storey containing the position, or null if the position falls outside all the storeys.

public gotoStoreyCamera(storeyId: String, options: *) source

Arranges the Camera for a 3D orthographic view of the Entitys within the given storey.

See also: CameraMemento, which saves and restores the state of the Scene's Camera

Params:

NameTypeAttributeDescription
storeyId String

ID of the IfcBuildingStorey object.

options *
  • optional

Options for arranging the Camera.

options.projection String
  • optional

Projection type to transition the Camera to. Accepted values are "perspective" and "ortho".

options.done Function
  • optional

Callback to fire when the Camera has arrived. When provided, causes an animated flight to the saved state. Otherwise jumps to the saved state.

public isPositionAboveOrBelowBuilding(worldPos: Number[]): String source

Returns whether a position is above or below a building

Params:

NameTypeAttributeDescription
worldPos Number[]

3D World-space position.

Return:

String

ID of the lowest/highest story or null.

public pickStoreyMap(storeyMap: StoreyMap, imagePos: Number[], options: *): PickResult source

Attempts to pick an Entity at the given pixel coordinates within a StoreyMap image.

Params:

NameTypeAttributeDescription
storeyMap StoreyMap

The StoreyMap.

imagePos Number[]

2D pixel coordinates within the bounds of StoreyMap#imageData.

options *
  • optional

Picking options.

options.pickSurface Boolean
  • optional
  • default: false

Whether to return the picked position on the surface of the Entity.

Return:

PickResult

The pick result, if an Entity was successfully picked, else null.

public showStoreyObjects(storeyId: String, options: *) source

Shows the Entitys within the given storey.

Optionally hides all other Entitys.

See also: ObjectsMemento, which saves and restores a memento of the visual state of the Entity's that represent objects within a Scene.

Params:

NameTypeAttributeDescription
storeyId String

ID of the IfcBuildingStorey object.

options *
  • optional

Options for showing the Entitys within the storey.

options.hideOthers Boolean
  • optional
  • default: false

When true, hide all other Entitys.

public storeyMapToWorldPos(storeyMap: *, imagePos: *, options: {}): * source

Params:

NameTypeAttributeDescription
storeyMap *
imagePos *
options {}
  • optional
  • default: {}

Return:

*

public withStoreyObjects(storeyId: String, callback: Function) source

Executes a callback on each of the objects within the given storey.

Usage

In the example below, we'll show all the Entitys, within the given IfcBuildingStorey, that have MetaObjects with type IfcSpace. Note that the callback will only be given an Entity when one exists for the given MetaObject.

myStoreyViewsPlugin.withStoreyObjects(storeyId, (entity, metaObject) => {
     if (entity && metaObject && metaObject.type === "IfcSpace") {
         entity.visible = true;
     }
});

Params:

NameTypeAttributeDescription
storeyId String

ID of the IfcBuildingStorey object.

callback Function

The callback.

public worldDirToStoreyMap(storeyMap: StoreyMap, worldDir: Number[], imageDir: Number[]) source

Converts a 3D World-space direction vector to a 2D vector within a StoreyMap image.

Params:

NameTypeAttributeDescription
storeyMap StoreyMap

The StoreyMap.

worldDir Number[]

3D World-space direction vector.

imageDir Number[]

Normalized 2D direction vector.

public worldPosToStoreyMap(storeyMap: StoreyMap, worldPos: Number[], imagePos: Number[]): Boolean source

Converts a 3D World-space position to a 2D position within a StoreyMap image.

Use StoreyViewsPlugin#pickStoreyMap to convert 2D image positions to 3D world-space.

Params:

NameTypeAttributeDescription
storeyMap StoreyMap

The StoreyMap.

worldPos Number[]

3D World-space position within the storey.

imagePos Number[]

2D pixel position within the StoreyMap#imageData.

Return:

Boolean

True if imagePos is within the bounds of the StoreyMap#imageData, else false if it falls outside.