Floor plan engine SDK guide

INFO

Please makes sure to upgrade to Floor Plan Engine V3
V2 and lower will be deprecated soon. New tokens can only be generated for V3

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/v3.0.x/fpe.js"></script>
  <style>
    #hello-plan {
      height: 100%;
    }
    html,
    body {
      height: 100%;
      margin: 0;
      padding: 0;
    }
  </style>
  <body>
    <div id="hello-plan"></div>
    <script type="module">
      // Create publishable access token at https://developers.archilogic.com/access-tokens.html
      const publishableToken = 'd3860d6c-e26e-4934-bd5e-d2f7f707e077'
      const demoSceneId = 'a9aaafdf-d5b6-4b4a-82a0-9efb6d5b155a'
      const container = document.getElementById('hello-plan')
      const floorPlan = new FloorPlanEngine(container)
      floorPlan.loadScene(demoSceneId, { publishableToken })
    </script>
  </body>
</html>

Open in codesandbox (opens new window) Screenshot below:

hello world (opens new window)

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)

Options can be changed on runtime using the set method

floorPlan.set(startupOptions)

TIP

Make sure to take a look at the code examples

Theme

The SDK offers a wide range of theming options.
The startup options playground showcases a lot of variations.

Space can be colored programmatically following the space taxonomy. The following snippet colors all work spaces blue.

const startupOptions = {
  theme: {
    elements: {
      space: {
        program: {
          work: { fill: [214, 234, 248] }
        }
      }
    }
  }
}
const floorPlan = new FloorPlanEngine(container, startupOptions)
floorPlan.loadScene(demoSceneId, { publishableToken })

Space label mapping

2.2.0 +

Map space labels by space usage or space id.
Take a look at the space taxonomy for reference.

const startupOptions = {
  spaceLabelMapping: {
    kitchen: '부엌'
  }
}
const floorPlan = new FloorPlanEngine(container, startupOptions)
floorPlan.loadScene(demoSceneId, { publishableToken })

Open in codesandbox (opens new window) Screenshot below:

(opens new window)

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', {publishableToken})
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: '35fa5b72-b2c2-47bc-ae65-5ea4abf6b17b',
  categories: ['seating'], // product category
  subCategories: ['taskChair'], // product subCategory
}

Take a look at the product taxonomy for reference
And visit the API reference for more details

Events

2.0.0 +

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, nodeId } = evt
  // to get the top resource that was clicked on use the nodeId
  const asset = floorPlan.resources.assets.find(asset => asset.id === nodeId)
  // to get all resources for that position use the position
  const { assets, spaces } = floorPlan.getResourcesFromPosition(pos)
}

mousemove

Fired when moving the mouse

floorPlan.on('mousemove', handleMouseMove)

function handleMouseMove(evt) {
  const { pos, sourceEvent, nodeId } = evt
}

drop

Fired when dropping a draggable Element on the canvas

floorPlan.on('drop', handleDrop)

function handleDrop(evt) {
  const { pos, sourceEvent, nodeId } = evt
}

viewbox

2.2.0 +

Fired when the current view changes on zoom or pan actions or zoom methods.
The viewbox property will give you the current view's bounding box

floorPlan.on('viewbox', handleViewBox)

function handleViewBox(evt) {
  const { pos, viewbox } = evt
}

Zoom

The SDK provides various zoom methods

Zoom extents

It allows you to zoom to the extent of the scene, with a specified margin using zoomExtents

Zoom to element

You can also zoom into an element (space, asset) with or without animation using the zoomToElement method.

// 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 (opens new window) Screenshot below:

(opens new window)

Zoom by factor

2.2.0 +

Zoom the current view by a factor with zoomByFactor
A zoom factor, larger than 1 zooms in, smaller than 1 zooms out

floorPlan.zoomByFactor(1.2, true)

Set zoom

2.2.0 +

Set the view box by providing a bounding box using the setZoom method

Methods

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 (opens new window) Screenshot below:

(opens new window)

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 (opens new window) Screenshot below:

(opens new window)

Add Html marker

2.2.0 +

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

const el = document.createElement('div')
el.classList.add('my-marker')
floorPlan.addHtmlMarker({
  pos: [7, 2],
  el
})

Where

  • pos is the position on the floor plan specified in meters where the info window points
  • el is the HTML Element that you want to mount at that position

Returns Html Marker instance

Open in codesandbox (opens new window) Screenshot below:

(opens new window)

Get resources from position

2.0.0 +

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

floorPlan.on('click', handleClick, floorPlan)

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'
})