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:

• showStoreyObjects - shows the Entitys within a storey, and
• gotoStoreyCamera - positions the Camera for a plan view of the Entitys within a storey.
  
  

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

• createStoreyMap - creates a 2D plan view image of a storey, and
• pickStoreyMap - picks the Entity at the given 2D pixel coordinates within a plan view image.

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, applying custom appearances configured on StoreyViewsPlugin#objectStates:

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

[Run this example]

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, with custom appearances as configured for IFC types

storeyViewsPlugin.showStoreyObjects("2SWZMQPyD9pfT9q87pgXa1", {
    useObjectStates: true // <<--------- Apply custom appearances
});

//...

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

[Run this example]

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.

[Run this example]

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"

As with showStoreyEntitys, We also have the option to customize the appearance of the Entitys in our plan images according to their IFC types, using the lookup table configured on StoreyViewsPlugin#objectStates.

For example, we usually want to show only element types like IfcWall, IfcDoor and IfcFloor in our plan images.

Let's create another StoreyMap, this time applying the custom appearances:

const storeyMap = storeyViewsPlugin.createStoreyMap("2SWZMQPyD9pfT9q87pgXa1", {
    width: 300,
    format: "png",
    useObjectStates: true // <<--------- Apply custom appearances
});

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

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

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.

[Run this example]

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