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/v1.5.5/fpe.js?key=YOUR_API_KEY"></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 publishable API key in the script tag ?key=YOUR_API_KEY
  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)

The default options are the following:

startupOptions = {
  hideElements: [],
  panZoom: true,
  planRotation: null,
  roomStampSize: null,
  ui: {
    menu: true,
    scale: true,
    coordinates: true
  },
  theme: {
    background: {
      color: '#f3f5f8',
      showGrid: true
    },
    wallContours: false,
    elements: {
      roomstamp: { showArea: true }
    }
  },
  units: {
    system: 'metric',
    digits: 0,
    roomDimensions: 'area'
  }
}

Theme

The Theme object is used to customize the look-and-feel of the floor plan.

theme = {
  background: {
    color: '#fff',
    showGrid: false
  },
  // merges the wall contours to be able to draw white walls with outline
  wallContours: true,
  // specify fill colors by element type
  elements: {
    // furniture elements
    interior: { fill: [255, 255, 255] },
    // space can be colored by category or type
    space: {
      category: {
        circulate: { fill: [255, 255, 255] },
        wash: { fill: [255, 255, 255] }
      }
    },
    // only show the name of the space
    roomstamp: { showArea: false }
  }
}

Open in codesandbox Screenshot below:

Theme floor plan

In the above code snippet

  • we set the background to gray color and turn off the display of grids
  • show only contours of walls
  • hide the area information

Units

The Units object is used to set the parameters of the units of dimensions.

units = {
  system: 'metric',
  roomDimensions: 'boundingBox'
}

In the above code snippet

  • we set the units to use the metric system
  • display the room dimensions as 4m x 3m instead of 12㎡
units = {
  system: 'imperial',
  digits: 1,
  roomDimensions: 'area'
}

Open in codesandbox Screenshot below:

Theme floor plan

In the above code snippet

  • we set the units to use the imperial system
  • display 1 digit after decimal point (only for area)
  • display the room dimensions as square feet

UI

With the UI we can specify the appearance of the user interface.

ui = {
  menu: false,
  scale: false,
  coordinates: true
}

menu, scale and coordinates set to true: user interface

only scale is set to true: user interface

Spaces and furniture

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

TIP

By adding your own external ids to spaces and furniture items through either the conversion service or via our upcoming editor it gets really simple to match each space to your existing system.

Sample space ( visit the API reference for more details ):

await floorPlan.loadScene('a9aaafdf-d5b6-4b4a-82a0-9efb6d5b155a')
floorPlan.computed.spaces[0] = {
  ...
  // potentially defined external ids like your own room id
  externalIds: [],
  // this references the furniture pieces in the space
  furniture: [
    "3fe8855a-8215-4e1e-a9fb-144eef373828" // the furniture element 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: "Work"
}

Sample furniture item ( visit the API reference for more details ):

// get a furniture item that is referenced by the space above
floorPlan.computed.furniture
.find(item => item.id === '3fe8855a-8215-4e1e-a9fb-144eef373828') = {
  ...
  // potentially defined external ids like your own desk id
  externalIds: [],
  // unique id for the furniture element
  id: "3fe8855a-8215-4e1e-a9fb-144eef373828",
  // product meta data ( generic or real )
  productData: {
    ...
    name: "Table 160x80x75",
    // multiple furniture items can have the same product id
    productId: "429399fd-b8c0-49a9-9eb9-3c271aab08bb",
    // tags describing the item
    tags: ["table", "rectangular"]
  }
}

Zoom

The SDK provides methods to zoom into an element (space, furniture) with or without animation using the zoomToElement method and also to zoom to the extent of the scene, with a specified margin using zoomExtents. Below is an example demonstrating the usage of these methods.

Open in codesandbox Screenshot below:

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:

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:

Save floor plan as image

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

Sample applications

IoT sensor demo, showcasing how to visualize data from external sources

In this case meeting spaces and desks are highlighted based on occupancy data from IoT sensors.
The data updates every 5 seconds.

Open in codesandbox Screenshot below:

Highlight furniture based on the space that they are in

Spaces and furniture reference each other. This can be used to set the highlight (change the color) accordingly.

Open in codesandbox Screenshot below:

Highlight based on external id from Google Sheet

A Google Sheet data source is used to set the highlight color of some of the spaces.

Open in codesandbox Screenshot below:

Zoom to spaces based on external id, save image

The following example demonstrates the usage of external ids and the exportImage method.

Open in codesandbox Screenshot below:

Add marker on click

The following example demonstrates the adding a marker on click.

Open in codesandbox Screenshot below: