TreeViewPlugin

A Viewer plugin that provides an HTML tree view to navigate the IFC elements in models.

[Run this example]

Overview

• A fast HTML tree view, with zero external dependencies, that works with huge numbers of objects.
• Each tree node has a checkbox to control the visibility of its object.
• Has three hierarchy modes: "containment", "types" and "storeys".
• Automatically contains all models (that have metadata) that are currently in the Scene.
• Sorts tree nodes by default - spatially, from top-to-bottom for IfcBuildingStorey nodes, and alphanumerically for other nodes.
• Allows custom CSS styling.
• Use ContextMenu to create a context menu for the tree nodes.

Credits

TreeViewPlugin is based on techniques described in Super Fast Tree View in JavaScript by Chris Smith.

Usage

In the example below, we'll add a TreeViewPlugin which, by default, will automatically show the structural hierarchy of the IFC elements in each model we load.

Then we'll use an XKTLoaderPlugin to load the Schependomlaan model from an .xkt file.

[Run this example]

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

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

const treeView = new TreeViewPlugin(viewer, {
    containerElement: document.getElementById("myTreeViewContainer")
});

const xktLoader = new XKTLoaderPlugin(viewer);

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

Manually Adding Models

Instead of adding models automatically, we can control which models appear in our TreeViewPlugin by adding them manually.

In the next example, we'll configure the TreeViewPlugin to not add models automatically. Then, once the model has loaded, we'll add it manually using TreeViewPlugin#addModel.

const treeView = new TreeViewPlugin(viewer, {
     containerElement: document.getElementById("myTreeViewContainer"),
     autoAddModels: false  // <<---------------- Don't auto-add models
});

const xktLoader = new XKTLoaderPlugin(viewer);

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

model.on("loaded", () => {
     treeView.addModel(model.id);
});

Adding models manually also allows us to set some options for the model. For example, the rootName option allows us to provide a custom name for the root node, which is sometimes desirable when the model's "IfcProject" element's name is not suitable:

model.on("loaded", () => {
     treeView.addModel(model.id, {
         rootName: "Schependomlaan Model"
     });
});

Initially Expanding the Hierarchy

We can also configure TreeViewPlugin to initially expand each model's nodes to a given depth.

Let's automatically expand the first three nodes from the root, for every model added:

const treeView = new TreeViewPlugin(viewer, {
     containerElement: document.getElementById("myTreeViewContainer"),
     autoExpandDepth: 3
});

Showing a Node by ID

We can show a given node using its ID. This causes the TreeViewPlugin to collapse, then expand and scroll the node into view, then highlight the node.

See the documentation for the TreeViewPlugin#showNode method for more information, including how to define a custom highlighted appearance for the node using CSS.

Let's make the TreeViewPlugin show the node corresponding to whatever object Entity that we pick:

viewer.cameraControl.on("picked", function (e) {
    var objectId = e.entity.id;
    treeView.showNode(objectId);
});

This will de-highlight any node that was previously shown by this method.

Note that this method only works if the picked Entity is an object that belongs to a model that's represented in the TreeViewPlugin.

Customizing Appearance

We can customize the appearance of our TreeViewPlugin by defining custom CSS for its HTML elements. See our example's source code for an example of custom CSS rules.

Model Hierarchies

TreeViewPlugin has three hierarchies for organizing its nodes:

• "containment" - organizes the tree nodes to indicate the containment hierarchy of the MetaObjects.
• "types" - groups nodes by their IFC types.
• "storeys" - groups nodes within their IfcBuildingStoreys, and sub-groups them by their IFC types.

The table below shows what the hierarchies look like:

1. Containment Hierarchy	2. Types Hierarchy	3. Storeys Hierarchy

Let's create a TreeViewPlugin that groups nodes by their building stories and IFC types:

const treeView = new TreeViewPlugin(viewer, {
     containerElement: document.getElementById("myTreeViewContainer"),
     hierarchy: "stories"
});

Sorting Nodes

TreeViewPlugin sorts its tree nodes by default. For a "storeys" hierarchy, it orders IfcBuildingStorey nodes spatially, with the node for the highest story at the top, down to the lowest at the bottom.

For all the hierarchy types ("containment", "classes" and "storeys"), TreeViewPlugin sorts the other node types alphanumerically on their titles.

If for some reason you need to prevent sorting, create your TreeViewPlugin with the option disabled, like so:

const treeView = new TreeViewPlugin(viewer, {
     containerElement: document.getElementById("myTreeViewContainer"),
     hierarchy: "stories",
     sortNodes: false // <<------ Disable node sorting
});

Note that, for all hierarchy modes, node sorting is only done for each model at the time that it is added to the TreeViewPlugin, and will not update dynamically if we later transform the Entitys corresponding to the nodes.

Pruning empty nodes

Sometimes a model contains subtrees of objects that don't have any geometry. These are models whose MetaModel contains trees of MetaObjects that don't have any Entitys in the Scene.

For these models, the tree view would contain nodes that don't do anything in the Scene when we interact with them, which is undesirable.

By default, TreeViewPlugin will not create nodes for those objects. However, we can override that behaviour if we want to have nodes for those objects (perhaps for debugging the model):

const treeView = new TreeViewPlugin(viewer, {
     containerElement: document.getElementById("myTreeViewContainer"),
     hierarchy: "stories",
     pruneEmptyNodes: false // <<------ Create nodes for object subtrees without geometry
});

Context Menu

TreeViewPlugin fires a "contextmenu" event whenever we right-click on a tree node.

The event contains:

• event - the original contextmenu MouseEvent
• viewer - the Viewer
• treeViewPlugin - the TreeViewPlugin
• treeViewNode - the TreeViewNode representing the tree node
  
  

Let's use ContextMenu to show a simple context menu for the node we clicked.

[Run an example]

import {ContextMenu} from "../src/extras/ContextMenu/ContextMenu.js";

const treeViewContextMenu = new ContextMenu({
    items: [
        [
            [
                {
                    title: "Hide",
                    doAction: function (context) {
                        context.treeViewPlugin.withNodeTree(context.treeViewNode, (treeViewNode) => {
                            if (treeViewNode.objectId) {
                                const entity = context.viewer.scene.objects[treeViewNode.objectId];
                                if (entity) {
                                    entity.visible = false;
                                }
                            }
                        });
                    }
                },
                {
                    title: "Hide all",
                    doAction: function (context) {
                        context.viewer.scene.setObjectsVisible(context.viewer.scene.visibleObjectIds, false);
                    }
                }
            ],
            [
                {
                    title: "Show",
                    doAction: function (context) {
                        context.treeViewPlugin.withNodeTree(context.treeViewNode, (treeViewNode) => {
                            if (treeViewNode.objectId) {
                                const entity = context.viewer.scene.objects[treeViewNode.objectId];
                                if (entity) {
                                    entity.visible = true;
                                    entity.xrayed = false;
                                    entity.selected = false;
                                }
                            }
                        });
                    }
                },
                {
                    title: "Show all",
                    doAction: function (context) {
                        const scene = context.viewer.scene;
                        scene.setObjectsVisible(scene.objectIds, true);
                        scene.setObjectsXRayed(scene.xrayedObjectIds, false);
                        scene.setObjectsSelected(scene.selectedObjectIds, false);
                    }
                }
            ]
        ]
    ]
});

treeView.on("contextmenu", (e) => {

    const event = e.event;                           // MouseEvent
    const viewer = e.viewer;                         // Viewer
    const treeViewPlugin = e.treeViewPlugin;         // TreeViewPlugin
    const treeViewNode = e.treeViewNode;             // TreeViewNode

    treeViewContextMenu.show(e.event.pageX, e.event.pageY);

    treeViewContextMenu.context = {
        viewer: e.viewer,
        treeViewPlugin: e.treeViewPlugin,
        treeViewNode: e.treeViewNode
    };
});

Clicking Node Titles

TreeViewPlugin fires a "nodeTitleClicked" event whenever we left-click on a tree node.

Like the "contextmenu" event, this event contains:

• event - the original click MouseEvent
• viewer - the Viewer
• treeViewPlugin - the TreeViewPlugin
• treeViewNode - the TreeViewNode representing the tree node
  
  

Let's register a callback to isolate and fit-to-view the Entity(s) represented by the node. This callback is going to X-ray all the other Entitys, fly the camera to fit the Entity(s) for the clicked node, then hide the other Entitys.

[Run an example]

treeView.on("nodeTitleClicked", (e) => {
    const scene = viewer.scene;
    const objectIds = [];
    e.treeViewPlugin.withNodeTree(e.treeViewNode, (treeViewNode) => {
        if (treeViewNode.objectId) {
            objectIds.push(treeViewNode.objectId);
        }
    });
    scene.setObjectsXRayed(scene.objectIds, true);
    scene.setObjectsVisible(scene.objectIds, true);
    scene.setObjectsXRayed(objectIds, false);
    viewer.cameraFlight.flyTo({
        aabb: scene.getAABB(objectIds),
        duration: 0.5
    }, () => {
        setTimeout(function () {
            scene.setObjectsVisible(scene.xrayedObjectIds, false);
            scene.setObjectsXRayed(scene.xrayedObjectIds, false);
        }, 500);
    });
});

To make the cursor change to a pointer when we hover over the node titles, and also to make the titles change to blue, we'll also define this CSS for the <span> elements that represent the titles of our TreeViewPlugin nodes:

#treeViewContainer ul li span:hover {
     color: blue;
     cursor: pointer;
}