xeokit-bim-viewer is an open source 2D/3D BIM viewer that runs in the browser and loads models from your file system.
The viewer is built on xeokit, and is bundled as part of the xeokit SDK.
The viewer is developed by xeolabs and OpenProject, and is integrated within OpenProject BIM 10.4 and later.
The viewer can be used as a stand-alone JavaScript application. In combination with open source CLI model conversion tools, it represents a low-cost, high-performance way to get your IFC models on the Web, that allows you the freedom to convert and host your models on your own server or GitHub repository.
To view your models with this viewer:
- Fork the xeokit-bim-viewer repository on GitHub.
- Convert your IFC STEP files using open source CLI tools.
- Add your converted models to your fork's data directory.
- Serve your fork using GitHub Pages.
Then users can view your models in their browsers, with URLs like this:
https://xeokit.github.io/xeokit-bim-viewer/app/index.html?projectId=OTCConferenceCenter&tab=storeys
Read the documentation below to get started.
- Features
- Demos
- Need Help?
- License
- The Viewer Application
- Model Database
- Programming API
- Customizing Viewer Style
- xeokit Components Used in the Viewer
- Building the Viewer
Get in touch if you could use a little help getting started.
- Uses xeokit for efficient model loading and rendering.
- Works in all major browsers, including mobile.
- Loads models from the file system.
- Loads multiple models.
- Saves and loads BCF viewpoints
- 3D and 2D viewing modes.
- Interactively X-ray, highlight, show, hide and section objects.
- Tree views of structure, layers and storeys.
- Full-precision geometry.
- Supports IFC2x3 and IFC4.
- Customize viewer appearance with your own CSS.
- JavaScript programming API for all viewer functions.
Click the links below to run some demos.
| Live Demo | Model Source |
|---|---|
| OTC Conference Center | Details |
| Holter Tower | Details |
| West Riverside Hospital | Details |
| Schependomlaan | Details |
| Schependomlaan Ground Floor | Details |
| Duplex | Details |
xeokit-bim-viewer is bundled within the xeokit SDK. See Pricing for licensing options.
The ./app/index.html page provides a ready-to-use instance of xeokit-bim-viewer. We'll just call it viewer from now on.
The viewer loads projects and models from the ./app/data directory.
To view a project, load the viewer with the project's ID on the URL:
https://xeokit.github.io/xeokit-bim-viewer/app/index.html?projectId=WestRiversideHospital
This section aims to show you how how to add your own models to the viewer application.
Let's examine the structure of the ./app/data directory, where the viewer keeps its projects and models.
Shown below is a portion of the ./app/data directory. We'll describe it from the root directory downwards.
Within the root, we have a directory for each project, along with a manifest of the projects in index.json.
Within a project directory, we have a directory for each model in the project, along with a manifest of the models in index.json.
Within a model directory, we have two files that comprise the model itself:
geometry.xkt- the model's geometry, formatted as.XKT, which is xeokit's native binary geometry format, andmetadata.json- the model's structural metadata, a JSON file containing the IFC element hierarchy.
.app/data/
└── projects
├── index.json
├── Duplex
│  ├── index.json
│  └── models
│  └── design
│  ├── geometry.xkt
│  └── metadata.json
└── WestRiversideHospital
├── index.json
└── models
├── architecture
│  ├── geometry.xkt
│  └── metadata.json
├── structure
│  ├── geometry.xkt
│  └── metadata.json
└── electrical
├── geometry.xkt
└── metadata.json
The index.json at the root of ./data is shown below.
Within this file, the id of each project matches the name of that project's subdirectory.
{
"projects": [
{
"id": "Duplex",
"name": "Duplex",
"position": [-20, 0.0, -10.0],
"scale": [1.0, 1.0, 1.0],
"rotation": [0.0, 0.0, 0.0]
},
{
"id": "WestRiversideHospital",
"name": "West Riverside Hospital",
"position": [20, 0.0, 0.0],
"scale": [1.0, 1.0, 1.0],
"rotation": [0.0, 0.0, 0.0]
},
//...
]
}The index.json for the "WestRiversideHospital" project is shown below.
Within this file, the id of each model matches the name of that model's subdirectory. Each model's name is the human-readable name that's displayed in the viewers Models tab.
{
"id": "WestRiversideHospital",
"name": "West Riverside Hospital",
"models": [
{
"id": "architectural",
"name": "Hospital Architecture"
},
{
"id": "structure",
"name": "Hospital Structure"
},
{
"id": "electrical",
"name": "Hospital Electrical",
"saoEnabled": false
}
],
"viewerConfigs": {
"backgroundColor": [0.9, 0.9, 1.0],
"saoEnabled": true
},
"viewerContent": {
"modelsLoaded": [
"structure",
"architectural"
]
},
"viewerState": {
"tabOpen": "models"
}
}The optional viewerConfigs section specifies configurations for the viewer to set on itself as it loads the project. See the complete list of available viewer configurations in Viewer Configurations.
The optional viewerContent array specifies IDs of models that the viewer will load initially, right after it's applied the configurations.
The optional viewerState section specifies how the viewer should set up the initial state of its UI, right after its loaded the initial models. See the complete list of available viewer states in Viewer States.
The geometry.xkt and metadata.json files for each model are created from an IFC file using open source CLI tools. Learn how to create those files in the Creating Files for Offline BIM tutorial.
While not essential, you can learn about the format of an .xkt geometry file in XKT Format specification.
The table below lists the complete set of available configurations. Think of these as user preferences. These may be provided to the viewer within project info files, as described in Model Database, or set programmatically on the viewer with BIMViewer#setConfigs(), as described in Configuring the Viewer.
| Property | Type | Range | Default Value | Description |
|---|---|---|---|---|
| "backgroundColor" | Array | [1.0,1.0,1.0] |
Canvas background color | |
| "cameraNear" | Number | [0.01-0.1] |
0.05 |
Distance to the near clipping plane |
| "cameraFar" | Number | [1-10000] |
3000.0 |
Distance to the far clipping plane |
| "smartPivot" | Boolean | true |
Enables a better pivot-orbiting experience when click-dragging on empty space in camera orbit mode. | |
| "saoEnabled" | Boolean | false |
Whether or not to enable Scalable Ambient Obscurance (SAO) | |
| "saoBias" | Number | [0.0...10.0] |
0.5 |
SAO bias |
| "saoIntensity" | Number | [0.0...200.0] |
100.0 |
SAO intensity factor |
| "saoScale" | Number | [0.0...1000.0] |
500.0 |
SAO scale factor |
| "saoKernelRadius" | Number | [0.0...200.0] |
100.0 |
The maximum area that SAO takes into account when checking for possible occlusion |
| "saoBlur" | Boolean | true |
Whether Guassian blur is enabled for SAO | |
| "saoInteractive" | Boolean | true |
When true, applies SAO when moving the camera, otherwise applies it once the camera stops moving |
|
| "saoInteractiveDelay" | Number | 200 |
when "saoInteractive" is false, this is the time delay in milliseconds after which SAO is applied after the camera has stopped moving |
|
| "viewFitFOV" | Number | [10.0...70.0] |
30 |
When fitting objects to view, this is the amount in degrees of how much they should fit the user's field of view |
| "viewFitDuration" | Number | [0..5] |
0.5 |
When fitting objects to view with an animated transition, this is the duration of the transition in seconds |
| "perspectiveFOV" | Number | [10.0...70.0] |
55 |
When in perspective projection, this is the field of view, in degrees, that the user sees |
| "objectColorSource" | String | "model", "viewer" | "model" | Where the colors for model objects will be loaded from |
In Model Database we saw how a project can specify directives for how the viewer should set up the initial state of its UI, right after the project has loaded. The table below lists the available directives. These can also be set on the viewer using BIMViewer#setViewerState(). So far, we have:
| Property | Type | Range | Default Value | Description |
|---|---|---|---|---|
| "focusObject" | String | ID of object to focus on | ||
| "tabOpen" | String | "objects", "classes" or "storeys" | Which explorer tab to open | |
| "expandObjectsTree" | Number | [0..*] | 0 | How deep to expand the "objects" tree |
| "expandClassesTree" | Number | [0..*] | 0 | How deep to expand the "classes" tree |
| "expandStoreysTree" | Number | [0..*] | 0 | How deep to expand the "storeys" tree |
| "setCamera" | { eye: Number[], look: Number[], up: Number[] } | 0 | Camera position |
This section goes deeper into the viewer, describing how to instantiate a viewer, and how to use its JavaScript programming API.
The viewer is implemented by the JavaScript BIMViewer class, which provides a complete set of methods to programmatically control it.
Using these methods, we can:
- create and configure a viewer,
- query what models are available,
- load projects and models,
- interact with the 3D view,
- save and load BCF viewpoints,
- control the various viewer tools, and
- drive the state of the viewer's UI.
In the example below, we'll create a BIMViewer, with a Server through which it will load projects and models from the file system.
We'll configure the Server to load that data from the ./app/data directory.
We'll also configure our BimViewer with DOM elements to hold the four parts of its UI, which are:
- the 3D canvas,
- the explorer panel containing the tree views,
- the toolbar,
- the NavCube, and
- the "backdrop" element, which covers everything in the UI to prevent interaction whenever the viewer is busy loading a model.
const server = new Server({
dataDir: "./data"
});
const myBIMViewer = new BIMViewer(server, {
canvasElement: document.getElementById("myCanvas"), // The 3D WebGL canvas
explorerElement: document.getElementById("myExplorer"), // Container for the explorer panel
toolbarElement: document.getElementById("myToolbar"), // Container for the toolbar
navCubeCanvasElement: document.getElementById("myNavCubeCanvas"), // Canvas for the NavCube
busyModelBackdropElement: document.querySelector(".xeokit-busy-modal-backdrop") // Busy modal dialog backdrop element
});Configuring the BIMViewer with separate places to locate its parts allows us to integrate them more flexibly into our web page.
In our app/index.html page, the HTML elements look like this:
<div id="myViewer" class="xeokit-busy-modal-backdrop">
<div id="myExplorer" class="active"></div>
<div id="myContent">
<div id="myToolbar"></div>
<canvas id="myCanvas"></canvas>
</div>
</div>
<canvas id="myNavCubeCanvas"></canvas>See app/css/style.css for how we've styled these elements.
Also see css/BIMViewer.css for the CSS styles that BIMViewer applies to the elements it creates internally.
With our viewer created, let's use BIMViewer#setConfigs() to configure it.
We'll enable Scalable Ambient Obscurance and set the canvas background color to white:
myBIMViewer.setConfigs({
"saoEnabled": "white",
"backgroundColor": [1.0, 1.0, 1.0]
});See Viewer Configurations for the list of available configurations.
With our viewer created and configured, let's find out what content is available.
Let's query what projects are available.
myBIMViewer.getProjectsInfo((projectsInfo) => {
console.log(JSON.stringify(projectsInfo, null, "\t"));
});Internally, the viewer will call Server#getProjects() to get the projects info.
As described earlier in Model Database, the projects info is the JSON in ./app/data/projects/index.json. We'll just log that info to the console.
The projects info will look similar to:
{
"projects": [
{
"id": "Duplex",
"name": "Duplex"
},
{
"id": "Schependomlaan",
"name": "Schependomlaan"
},
{
"id": "WestRiversideHospital",
"name": "West Riverside Hospital"
}
]
}Now we know what projects are available, we'll get info on one of those projects.
myBIMViewer.getProjectInfo("WestRiversideHospital", (projectInfo) => {
console.log(JSON.stringify(projectInfo, null, "\t"));
});Internally, the viewer will call Server#getProject() to get that project info. Like before, we'll just log it to the console.
The project info will be the contents of ./app/data/projects/WestRiversideHospital/index.json.
The project info will be similar to:
{
"id": "WestRiversideHospital",
"name": "West Riverside Hospital",
"models": [
{
"id": "architectural",
"name": "Hospital Architecture"
},
{
"id": "structure",
"name": "Hospital Structure"
},
{
"id": "electrical",
"name": "Hospital Electrical",
"saoEnabled": false
}
],
"viewerConfigs": {
"backgroundColor": [0.9, 0.9, 1.0],
"saoEnabled": true
},
"viewerContent": {
"modelsLoaded": [
"structure",
"architectural"
]
},
"viewerState": {
"tabOpen": "models"
}
}In this project info, we have:
id- ID of the project,name- human-readable name of the project,models- info on each model in this project,viewerConfigs- configurations for the viewer to apply when loading the project,viewerContent- which models the viewer should immediately load when loading the project, andviewerState- how the viewer should set up its UI after loading the project.
When we later load the project in section Loading a Project, the viewer is going to pass the viewerConfigs to BIMViewer#setConfigs(), which we described earlier in Configuring the Viewer.
In the viewerConfigs we're enabling the viewer's Scalable Ambient Obscurance effect, which will create ambient shadows in the crevices of our models. This is an expensive effect for the viewer to render, so we've disabled it for the "electrical" model, which contains many long, thin wire objects that don't show the SAO effect well.
Let's attempt to get some info on an object within one of our project's models.
We say "attempt" because it's up to the Server to try to find that info for us, which might not exist.
Internally, the viewer will call Server#getObjectInfo(), which will attempt to load that object info from a file.
If you were to substitute Server with your own implementation, your implementation might get that info from a data store, such as a relational database, populated with metadata for all the objects in your project's models, keyed to their IDs.
We'll go ahead and assume that our Server has info an an object.
myViewer.getObjectInfo("WestRiversideHospital", "architectural", "2HaS6zNOX8xOGjmaNi_r6b",
(objectInfo) => {
console.log(JSON.stringify(objectInfo, null, "\t"));
},
(errMsg) => {
console.log("Oops! There was an error getting info for this object: " + errMsg);
});If the object does not exist in the specified project and model, the method will invoke its error callback.
Our file system database does happen to have info for that object, stored in ./app/data/projects/WestRiversideHospital/models/architectural/objects/2HaS6zNOX8xOGjmaNi_r6b.json.
Since our object info exists, we'll get a result similar to this:
{
"id": "2HaS6zNOX8xOGjmaNi_r6b",
"projectId": "WestRiversideHospital",
"modelId": "architectural",
"name": "Basic Wall:Exterior - Metal Panel on Mtl. Stud:187578",
"type": "IfcWall",
"parent": "2hExBg8jj4NRG6zzD0RZML"
}By now, you've probably noticed that our file system database is structured to support RESTful URIs, which our
Serverconstructs from the project, model and object IDs we supplied to the viewer's query methods.
Let's now load some of the projects and models that we queried in the previous section.
Let's start by loading the project we just queried info on.
myBIMViewer.loadProject("WestRiversideHospital",
() => {
console.log("Nice! The project loaded successfully.");
},
(errMsg) => {
console.log("Oops! There was an error loading this project: " + errMsg);
});If that succeeds, the viewer will now have two models loaded, "architectural" and "structure", since those are specified in the project info's viewerContent.
The viewer will also enable Scalable Ambient Obscurance, since that's specified by the saoEnabled property in the viewerConfigs. The viewer will also set various other configs on itself, as specified in that section.
The viewer will also open its "Models" tab, thanks to the tabOpen property in the project info's viewerState section.
We can confirm that the two models are loaded by querying the IDs of the models that are currently loaded in the viewer:
const modelIds = myBIMViewer.getModelLoadedIds();
console.log(modelIds);The result would be:
["architectural", "structure"]With our project loaded, let's load another of its models.
We could start by getting the IDs of all the models in our project, just to make sure the model is available:
const modelIds = myBIMViewer.getModelIds();
console.log(modelIds);The result would be:
["architectural", "structure", "electrical"]To load the model:
myBIMViewer.loadModel("electrical",
() => {
console.log("Nice! The model loaded successfully.");
},
(errMsg) => {
console.log("Oops! There was an error loading this model: " + errMsg);
});If we no longer need that model, we can unload it again:
myBIMViewer.unloadModel("electrical");When we no longer need the project, unload like so:
myBIMViewer.unloadProject();Note that we can only load one project at a time.
BIMViewer has various methods with which we can programmatically control the state of its UI.
Let's take a quick look at some of these methods to get an idea of what sort of UI state we can control with them. This won't be an exhaustive guide - see the BIMViewer class documentation for the complete list.
Having loaded a couple of models in the previous section, let's open the viewer's Objects tab, which contains a tree view of the containment hierarchy of the objects within those models:
myBIMViewer.openTab("objects");To confirm which tab is currently open:
const tabId = myBIMViewer.getOpenTab();
console.log("Currently open tab: '" + tabId + "'"); // "objects"Now let's arrange the camera to fit an object in view:
myBIMViewer.flyToObject("1fOVjSd7T40PyRtVEklS6X", ()=>{ /* Done */ });TODO: Complete this section once API methods are finalized
Bim Collaborative Format (BCF) is a format for managing issues on a BIM project. A BCF record captures the visual state of a BIM viewer, which includes the camera position, the visibility and selected states of the objects, and any section planes that are currently active.
A BCF record saved from one BIM viewer can be loaded into another viewer, to synchronize the visual states of both viewers.
Note that BCF viewpoints do not record which models are currently loaded. It's assumed that both the source and target viewers have the same models loaded.
Use the BIMViewer#saveBCFViewpoint() to save a JSON BCF record of the current view:
const viewpoint = bimViewer.saveBCFViewpoint({
// Options - see BIMViewer#saveBCFViewpoint() documentation for details
});Our viewpoint JSON will look similar to below. Before saving this viewpoint, we've hidden one object, selected another object, and created section plane to slice our model. The viewpoint also contains a PNG snapshot of the viewer's canvas, which we've truncated here for brevity.
{
perspective_camera: {
camera_view_point: { x: 0.0, y: 0.0, z: 0.0 },
camera_direction: { x: 1.0, y: 1.0, z: 2.0 },
camera_up_vector: { x: 0.0, y: 0.0, z: 1.0 },
field_of_view: 90.0
},
lines: [],
clipping_planes: [{
location: { x: 0.5, y: 0.5, z: 0.5 },
direction: { x: 1.0, y: 0.0, z: 0.0 }
}],
bitmaps: [],
snapshot: {
snapshot_type: png,
snapshot_data: "data:image/png;base64,......"
},
components: {
visibility: {
default_visibility: false,
exceptions: [{
ifc_guid: 4$cshxZO9AJBebsni$z9Yk,
originating_system: xeokit.io,
authoring_tool_id: xeokit/v1.0
}]
},
selection: [{
ifc_guid: "4$cshxZO9AJBebsni$z9Yk",
}]
}
}
Use the BIMViewer#loadBCFViewpoint() to load a JSON BCF record:
bimViewer.loadBCFViewpoint(viewpoint, {
// Options - see BIMViewer#loadBCFViewpoint() documentation for details
});The app/index.html file for the standalone viewer contains CSS rules for the various viewer elements, which you can modify as required.
The viewer displays a modal dialog box whenever we load a model. The dialog box has a backdrop element, which overlays the viewer. Whenever the dialog becomes visible, the backdrop will block interaction events on the viewer's UI.
Within our app/index.html page, the main <div> is the backdrop element:
<div id="myBIMViewer" class="xeokit-busy-modal-backdrop">
<div id="myExplorer" class="active"></div>
<div id="myContent">
<div id="myToolbar"></div>
<canvas id="myCanvas"></canvas>
</div>
</div>
<canvas id="myNavCubeCanvas"></canvas>As defined in css/BIMViewer.css, the backdrop gets the following style, which allows the dialog to position itself correctly within the backdrop:
.xeokit-busy-modal-backdrop {
position:relative;
}If you need to tweak CSS relating to the dialog, search for "xeokit-busy-dialog" within css/BIMViewer.css.
Tooltips are not part of the core JavaScript for the viewer. Instead, viewer HTML elements are marked with data-tippy-content attributes that provide strings to show in their tooltips.
For example, the Toggle 2D/3D button's element looks like this:
<button type="button" class="xeokit-threeD xeokit-btn fa fa-cube fa-2x" data-tippy-content="Toggle 2D/3D"></button>In the app/index.html file for the standalone viewer, we're using tippy.js, which automatically creates tooltips for those elements.
TODO: Correct this section - viewer can load from model and viewer
The viewer loads colors for the various IFC element types straight from the IFC model, except where overrides are defined in the configuration file ./src/IFCObjectDefaults/ViewerIFCObjectColors.js.
You can add or remove configurations in that file if you need to customize the color and pickability of specific IFC types.
For example, to ensure that IfcWindow and IfcSpace types are initially visible, transparent and pickable (ie. able to be selected by clicking on them), you might configure that file as shown below:
const IFCObjectDefaults = {
IfcSpace: {
visible: true,
pickable: true,
opacity: 0.2
},
IfcWindow: {
visible: true,
pickable: true,
opacity: 0.5
}
};
export {IFCObjectDefaults};Sometimes IFC models have opaque IfcWindow and IfcSpace elements, so it's a good idea to have configurations in there so that we can see through them.
The viewer is built on various xeokit SDK components and plugins that are designed to accelerate the development of BIM and CAD visualization apps.
The table below lists the main ones used in this viewer.
| Component | Purpose |
|---|---|
Viewer |
The WebGL-based viewer at the heart of BIMViewer. |
XKTLoaderPlugin |
Loads model geometry and metadata. |
NavCubePlugin |
Navigation cube gizmo that allows us to rotate the scene and move the camera to look at it along a selected axis or diagonal. |
TreeViewPlugin |
Implements the Objects, Classes and Storeys tree views within the explorer panel. |
SectionPlanesPlugin |
Manages interactive section planes, which are used to slice objects to reveal inner structures. |
BCFViewpointsPlugin |
Saves and loads BCF viewpoints. |
ContextMenu |
Implements the context menus for the explorer tree views and 3D canvas. |
To install the npm package:
npm i @xeokit/xeokit-bim-viewer
To build the ES6 module in /dist/main.js:
npm run build
To build the API documentation in /docs/:
npm run docs