Floor plan engine SDK guide

Overview

The Floor Plan Engine SDK enables you to create interactive, customizable floor plan models embedded in your website.

Interactive example ( you can zoom or pan the plan ):

Audience

This documentation is designed for people familiar with JavaScript programming. This conceptual documentation is designed to let you quickly start exploring and developing applications with the Floor Plan Engine SDK. There is also an API reference provided.

Hello, World

The simplest way to display a floor plan embedded in your website is the following:

TIP

Check the change log for new versions.

<!DOCTYPE html>
<html>
  <meta charset="utf-8">
  <title>fpe hello world demo</title>
  <script src="https://code.archilogic.com/fpe-sdk/v2.0.x/fpe.js?token=<your-access-token>"></script>
  <style>
    #hello-plan {
      height: 100%;
    }
    html, body {
      height: 100%;
      margin: 0;
      padding: 0;
    }
  </style>
  <body>
    <div id="hello-plan"></div>
    <script type="module">
      const demoSceneId = 'a9aaafdf-d5b6-4b4a-82a0-9efb6d5b155a'
      const container = document.getElementById('hello-plan')
      const floorPlan = new FloorPlanEngine(container)
      floorPlan.loadScene(demoSceneId)
    </script>
  </body>
</html>

Open in codesandbox Screenshot below:

hello world

You can observe the following important steps:

  1. We declare the application as HTML5 using the <!DOCTYPE html> declaration.
  2. We load the Floor Plan Engine SDK using a script tag
  3. Add you Access Token in the script tag ?token=YOUR_TOKEN ( ?key= is still supported but will be deprecated in future versions)
  4. We create a div element named "hello-plan" to hold the floor plan.
  5. We create a new FloorPlanEngine instance passing the "hello-plan" element.
  6. We load the scene specified by its unique id by calling: floorPlan.loadScene(demoSceneId)

Startup Options

The FloorPlanEngine has an optional parameter StartupOptions. See below the various options that can be set through this parameter. The options are passed like the following: new FloorPlanEngine(container, startupOptions)

TIP

Make sure to take a look at the interactive startup options playground and the code examples

Resources

When the promise returned by loadScene is resolved, we can expect that the resources.spaces and resources.assets arrays are defined and contain the Space and Asset objects placed in the floor plan.
Each space references the assets that it contains by their unique id.
This allows you to know what's in each space.

Space

https://docs.google.com/drawings/d/1WE5pfuEb010pE-Q8R1t4ewo_CuJxtAj71VcEr91iRvk/edit

Sample space:

await floorPlan.loadScene('a9aaafdf-d5b6-4b4a-82a0-9efb6d5b155a')
floorPlan.resources.spaces[0] = {
  ...
  // this references the assets in the space
  assets: [
    "3fe8855a-8215-4e1e-a9fb-144eef373828" // the asset below
    "47060475-838e-42e8-860e-ba2e6ec071ee"
    "9cd7addb-1f1d-4a7d-af40-6755aae9c789"
  ],
  // unique id for the space
  id: "3c45a15b-4016-44e4-bb61-ce0f828b6848",
  // contour of the space
  polygon: [...],
  // assigned usage function
  usage: "openWorkSpace",
  // space category
  program: "work"
}

visit the API reference for more details

Asset

https://docs.google.com/drawings/d/1PrKiTuVvYiKMKYKppcistMoshzNRHvj6DlXlSIgm-Eo/edit

Sample asset:

// get a asset that is referenced by the space above
floorPlan.resources.assets
.find(item => item.id === '3fe8855a-8215-4e1e-a9fb-144eef373828') = {
  // unique id for the asset
  id: "3fe8855a-8215-4e1e-a9fb-144eef373828",
  // product meta data ( generic or real )
  name: "Table 160x80x75",
  // multiple assets can have the same product id
  productId: "429399fd-b8c0-49a9-9eb9-3c271aab08bb",
  // tags describing the item
  tags: ["table", "rectangular"]
}

visit the API reference for more details

Events

The FloorPlanEngine instance exposes a few useful events subscribe

floorPlan.on(event, callback, context)

subscribe for one event

floorPlan.once(event, callback, context)

unsubscribe

floorPlan.off(event, callback, context)

click

Mouse click or touch event.

Instead of click you can also listen for dblclick

floorPlan.on('click', handleClick)
function handleClick(evt) {
  // returns the plan position, the sourceEvent and if present the id of the node that you clicked on
  const { pos, sourceEvent } = evt
}

mousemove

Fired when moving the mouse

floorPlan.on('mousemove', handleMouseMove)
function handleMouseMove(evt) {
  const { pos, sourceEvent } = evt
} 

drop

Fired when dropping a draggable Element on the canvas

floorPlan.on('drop', handleDrop)
function handleMouseMove(evt) {
  const { pos, sourceEvent } = evt
} 

Methods

Zoom

The SDK provides methods to zoom into an element (space, asset) with or without animation using the zoomToElement method and also to zoom to the extent of the scene, with a specified margin using zoomExtents.

// get an asset
const assetId = floorPlan.resources.assets[0].id
// zoom to the asset with 2m margin and 500ms animation time
floorPlan.zoomToElement(assetId, 2, 500)

Below is an example demonstrating the usage of these methods.

Open in codesandbox Screenshot below:

Add marker

The addMarker method can be used to add extra information to a given location within the floor plan. It requires the following parameters:

floorPlan.addMarker({
  pos: [7, 2],
  color: '#0c9',
})

Where

  • pos is the position on the floor plan specified in meters where the info window points
  • width, height specifies the size of the info window

Returns Marker instance

Open in codesandbox Screenshot below:

Add info window

The addInfoWindow method can be used to add extra information to a given location within the floor plan. It requires the following parameters:

floorPlan.addInfoWindow({
  pos: [7, 2],
  width: 200,
  height: 80,
  html: '<h1>Note</h1><p>This room has 3 desks</p>',
  closeButton: true
})

Where

  • pos is the position on the floor plan specified in meters where the info window points
  • width, height specifies the size of the info window
  • html is the user-specified content to be displayed
  • closeButton if true displays a close button

Returns InfoWindow instance

Open in codesandbox Screenshot below:

Get resources from position

From a given plan position the getResourcesFromPosition methods returns the assets and spaces for that position.

floorPlan.on('click', handleClick)
function handleClick(evt) {
  // returns the plan position, the sourceEvent and if present the id of the node that you clicked on
  const { pos, sourceEvent, nodeId } = evt
  // get a list of assets and spaces for that plan position
  const { assets, spaces } = this.getResourcesFromPosition(pos)
  // proceed by highlighting the resources in focus for instance
}

Highlight a resource

All exposed resources can be colored programmatically node.setHighlight

// get the node of a resource ( asset or a space )
const node = floorPlan.resources.assets[0].node
// use the setHighlight method to temporarily change its color
node.setHighlight({fill: [236, 112, 99]})
// use the same method empty without arguments to reset the color
setTimeout(() => {
  node.setHighlight()
}, 1000)

For a more complex implementation take a look at this example

Save floor plan as image

A method is provided to save the displayed floor plan as either jpg of png image: exportImage

floorPlan.exportImage({
  download: true,
  format: 'jpg'
})