Developer Docs

Appearance

Floor Plan SDK API reference ​

FloorPlanEngine ​

The main class for interacting with the floor plan engine.

Constructor ​

ts
constructor({ container, options }: { container?: Element; options?: FpeConfig })

Creates a new FloorPlanEngine instance.

  • container: The DOM element to render the floor plan in.
  • options: Configuration options (see FpeConfig)

Example:

js
const container = document.getElementById('floor-plan-container')
const floorPlan = new FloorPlanEngine({
  container,
  options: {
    // ...
  }
})

Properties ​

  • fpeNode: The HTMLElement containing the floor plan.
  • view: The WebGlView instance handling the rendering.
  • interaction: Manages user interactions with the floor plan.
  • availableHelpers: A record of available helper classes.
  • helper: Instantiated helper objects.

Update settings ​

set ​

ts
set(args: FpeConfig): void

Updates the floor plan engine configuration. See FpeConfig for options.

Load methods ​

loadFloorById ​

ts
loadFloorById(floorId: string, accessTokenOptions?: TokenOptions): Promise<boolean | Error>

Loads a floor by its unique identifier.

loadLayoutById ​

ts
loadLayoutById(layoutId: string, accessTokenOptions?: TokenOptions): Promise<boolean | Error>

Loads a layout by its unique identifier.

loadSpaceGraphJson ​

ts
loadSpaceGraphJson(spaceGraphJson: SpaceGraphJson): void

Loads a SpaceGraphJson into the engine.

Query methods ​

getElements ​

ts
getElements({
    select?: ElementSelect,
    where?: ElementFilter
}): QueryPick<ElementData, ElementSelect>[]

Filter by ElementFilter and select the returned properties with ElementSelect which defaults to DefaultSelect

Return type matches ElementSelect

getElementById ​

ts
getElementById({
    id: string,
    select?: ElementSelect
}): QueryPick<ElementData, ElementSelect>

Return type matches ElementSelect

getSpaces ​

ts
getSpaces({
    select?: SpaceSelect,
    where?: SpaceFilter
}): QueryPick<SpaceData, SpaceSelect>[]

Filter by SpaceFilter and select the returned properties with SpaceSelect which defaults to DefaultSelect

Return type matches SpaceSelect

getSpaceById ​

ts
getSpaceById({
    id: string,
    select?: SpaceSelect
}): QueryPick<SpaceData, SpaceSelect>

Return type matches SpaceSelect

Wayfinding methods ​

Walkable routes on the loaded floor, see the guide. The navigation mesh is built on the first call and reused until another floor is loaded; the wayfinding module is loaded on demand. Points outside the walkable area are mapped to the closest walkable point. Both methods return null while no floor is loaded.

getPath ​

ts
getPath({
    start: Vector2,
    end: Vector2
}): Promise<WayfindingResult | null>

Shortest walkable route between two points, see WayfindingResult. path is empty when the points are not connected.

findClosest ​

ts
findClosest({
    start: Vector2,
    where: SpaceFilter | ElementFilter
}): Promise<FindClosestResult | null>

The closest reachable space or element matching SpaceFilter or ElementFilter, with the route to it, see FindClosestResult. target is null when nothing matching is reachable.

Zoom methods ​

zoomExtents ​

ts
zoomExtents(margin?: number, animate?: Animate, boundingBox?: BoundingBox2d): Promise<boolean>

Zooms to the extent of the scene in the viewport.

zoomToElement ​

ts
zoomToElement(node: string | LayoutElement | LayoutSpace, margin?: number, animate?: Animate): Promise<boolean | Error>

Zooms to the bounding box of an element.

setZoom ​

ts
setZoom(bb: BoundingBox2d, animate?: Animate): Promise<boolean>

Sets zoom to a specific bounding box.

zoomByFactor ​

ts
zoomByFactor(factor: number, animate?: Animate): Promise<boolean>

Zooms the current view by a factor.

Marker / window methods ​

addInfoWindow ​

ts
addInfoWindow(args?: InfoWindowArgs): InfoWindow

Adds an InfoWindow to the floor plan.

addHtmlMarker ​

ts
addHtmlMarker(args?: HtmlMarkerArgs): HtmlMarker

Adds a custom HtmlMarker to the floor plan.

addMarker ​

ts
addMarker({ position, color, size }?: MarkerArgs): MarkerPin

Adds a MarkerPin to the floor plan.

Position methods ​

getPlanPosition ​

ts
getPlanPosition(point: Vector2): Vector2

Converts screen coordinates to plan coordinates.

getScreenPosition ​

ts
getScreenPosition(point: Vector2): Vector2

Converts plan coordinates to screen coordinates.

Layer / graphics methods ​

addLayer ​

ts
addLayer({ id, baseLayer }?: { id?: string; baseLayer?: BaseLayers }): PlanLayer

Creates a new PlanLayer or returns an existing one by id.

getLayer ​

ts
getLayer(id: any): PlanLayer

Gets a PlanLayer by name.

drawNodeUpdate ​

ts
drawNodeUpdate(id: string, style?: 'selected' | ShapeStyle | false): void

Updates the style of a node in the floor plan by specifying a new ShapeStyle. Provide false to reset.

Misc methods ​

addHelper ​

ts
addHelper(helper: string | typeof Helper, options?: any): Helper

Adds a helper and removes previous instances of it.

removeHelper ​

ts
removeHelper(helperId: string): void

Removes a helper by its id.

exportImage ​

ts
exportImage({ format, fileName, quality, output, maxWidth, download }?: ExportImage): Promise<string | Error>

Exports the current view as an image.

destroy ​

ts
destroy(): void

Destroys the floor plan instance, cleaning up all resources.

Event Handling ​

  • on<EventType extends FpeEvent>(event: EventType, handler: FpeEventHandler<EventType>, ctx?: any): this
  • once<EventType extends FpeEvent>(event: EventType, handler: FpeEventHandler<EventType>, ctx?: any): this
  • off<EventType extends FpeEvent>(event: EventType, handler?: FpeEventHandler<EventType>, ctx?: any): this

PlanLayer ​

Represents a layer in the floor plan for adding graphics. Allows to add a PlanGraphic to the layer.

ts
class PlanLayer {
  addGraphic(args: GraphicArgs): PlanGraphic
  deleteGraphic(graphic: PlanGraphic): void
  // clear all shapes from the layer
  clear(): void
  // destroy layer and all shapes
  destroy(): void
}

PlanGraphic ​

Represents a graphic element on a layer.

ts
class PlanGraphic {
  shapes: Shape[]
  fixedScreenSize: boolean | ZoomRange
  set({ position, style, shapes }?: GraphicUpdate): void
  on(event: string, callback: any, context?: any): this
  off(event: string, callback?: any): this
  destroy(): void
}

InfoWindow ​

Represents an HTML info window in the floor plan.

ts
class InfoWindow {
  position: Vector2
  height: number
  width: number
  closeButton: any
  html: any
  el: Element

  set({
    width,
    height,
    position,
    html,
    closeButton
  }: {
    width: any
    height: any
    position: any
    html: any
    closeButton: any
  }): void
  remove(): void
}

HtmlMarker ​

Represents a custom HTML marker in the floor plan.

ts
class HtmlMarker {
  position: Vector2
  size: Vector2
  offset: Vector2
  isHidden: boolean
  id: string
  el: HTMLElement

  set({ position, offset }: Pick<HtmlMarkerArgs, 'position' | 'offset'>): void
  remove(): void
}

MarkerPin ​

Represents a plan marker in the floor plan.

ts
class MarkerPin {
  position: Vector2
  color: string
  size: number
  id: string

  on(eventType: string, callback: any, context?: any): void
  off(eventType?: string, callback?: any): void
  set(updateArgs: MarkerUpdateArgs): void
  remove(): void
}

Types ​

FpeConfig ​

Configuration options for the FloorPlanEngine.

Mostly used to set the floor plan theme and visibility.

ts
interface FpeConfig {
  theme?: FloorPlanTheme
  visibility?: FloorPlanVisibility
  units?: Units
  shapeLayers?: ShapeLayers
  spaceLabelMapping?: SpaceLabelMapping
  // deprecated, use `visibility`
  hideElements?: HideableElement[]
  ui?: UI
  panZoom?: boolean
  zoomRange?: [number, number]
  showSpaceDividers?: boolean
  showCeilingLamps?: boolean
  showFloorPlan?: boolean
  destroyOnDomRemove?: boolean
  preserveViewbox?: string
}

TokenOptions ​

Options for access tokens required by certain API methods.

ts
interface TokenOptions {
  accessToken: string
  refreshToken?: string
  tokenExpiry?: number
}

InfoWindowArgs ​

Arguments for creating an InfoWindow.

ts
interface InfoWindowArgs {
  // pixel width of the window - default 100
  width?: number
  // pixel height of the window - default 80
  height?: number
  // coordinates of the window in meters
  position?: Vector2
  // html string as content of the info window
  html?: string
  // If true , a close button will appear in the top right corner of the info window.
  closeButton?: boolean
}

HtmlMarkerArgs ​

Arguments for creating an HtmlMarker.

ts
interface HtmlMarkerArgs {
  // coordinates of the window in meters
  position?: Vector2
  offset?: Vector2
  // html string as content of the info window
  el?: HTMLElement
  // If true , a close button will appear in the top right corner of the info window.
  closeButton?: boolean
}

MarkerArgs ​

Arguments for creating a MarkerPin.

ts
interface MarkerArgs {
  position: Vector2
  color?: string
  size?: number
}

Animate ​

Options for animation durations.

ts
type Animate = boolean | number

BoundingBox2d ​

Represents a 2D bounding box.

ts
interface BoundingBox2d {
  min: Vector2
  max: Vector2
}

FloorPlanTheme ​

Theming options for the floor plan as part of floor plan configuration.
Check ElementFilter and SpaceFilter for advanced theming.

ts
type FloorPlanTheme = {
  /** define the background */
  background?: BackgroundOptions
  /** set style by node id */
  byId?: Record<string, ShapeStyle>
  /** set style by filter, e.g. area: { gte: 50 } */
  byFilter?: {
    where: ElementFilter | SpaceFilter
    style: ShapeStyle
  }[]
  /** set style by node type, e.g. 'layout:space', 'element:asset' */
  byType?: Record<string, ShapeStyle> & {
    /** assets additionally accept an asset stamp */
    'element:asset'?: ShapeStyle & { label?: NodeLabel }
  }
  fontFamily?: string
  roomStamps?: {
    /** show the area information in room stamps */
    roomStampDisplay?: (
      | 'usage'
      | 'area'
      | 'customId'
      | 'name'
      | 'id'
      | ['customAttribute', string]
    )[]
    /** text color for room stamps */
    text?: Rgb
    /** whether the room stamp text should have an outline to assist with contrast issues */
    textOutline?: boolean
    /** if set room stamps have a fixed size - otherwise they adapt to the zoom level */
    fontSize?: number
  }
  /** render assets with textures rather than solid colors */
  showAssetTextures?: boolean
  /** wall contours are merged to one continuous outline, needed if you want white walls */
  wallContours?: boolean
}

NodeLabel ​

An asset stamp — a text label drawn on top of each asset, configured via theme.byType['element:asset'].label. Nothing is rendered unless display is set and the asset has a value for it.

ts
type NodeLabel = {
  /** which asset fields to render, one per line */
  display: 'customId'[]
  fontSize?: number
  /** text color */
  text?: Rgb
  /** outline the text to assist with contrast issues */
  textOutline?: boolean
  /** only render the label while zoom is within [min, max] */
  visible?: ZoomRange
  /**
   * fixed screen size (1/zoom) scaling:
   * `true` (default) always scales, `false` renders at world scale,
   * a `[min, max]` range scales within the range and clamps to the
   * boundary scale outside it
   */
  fixedScreenSize?: boolean | ZoomRange
}

FloorPlanVisibility ​

Show/hide elements and spaces as part of the floor plan configuration. Hidden nodes are omitted from rendering and from exportImage.
Uses the same filter composition as FloorPlanTheme — see ElementFilter and SpaceFilter.

A node's own rules are checked before its parent's, so hiding a space also hides the elements inside it unless they carry their own rule. Resolution precedence, most specific first: byId › byFilter › parent byId › parent byFilter › byType.

ts
type FloorPlanVisibility = {
  /** show/hide by node id */
  byId?: Record<string, VisibilityRule>
  /** show/hide by filter, e.g. type: { nin: ['element:wall'] }; the last matching filter wins */
  byFilter?: VisibilityFilter[]
  /** show/hide by node type, e.g. 'element:asset', 'roomStamp' */
  byType?: Partial<Record<HideableElement, VisibilityRule>>
}

HideableElement ​

A node type that can be hidden — every element and space type, plus roomStamp for the labels drawn on top of spaces. Used by visibility.byType and by the deprecated hideElements.

ts
type HideableElement =
  | 'element:asset'
  | 'element:door'
  | 'element:wall'
  | 'element:window'
  // …all other element types
  | 'layout:space'
  | 'spatialGraph:edge'
  | 'annotation:floorPlanImage'
  | 'roomStamp'

VisibilityRule ​

Whether a matched node is shown. Modeled as an object (like ShapeStyle) so it can gain predicate fields in future without a breaking change.

ts
type VisibilityRule = {
  show: boolean
}

VisibilityFilter ​

A visibility rule applied to every node matching a filter.

ts
type VisibilityFilter = {
  where: ElementFilter | SpaceFilter
  show: boolean
}

Rgb ​

An RGB color represented as a tuple of three integers in the range 0–255.

ts
type Rgb = [number, number, number] // [red, green, blue]

ShapeStyle ​

Style options for shapes.

ts
interface ShapeStyle {
  // Color formats can be hex string, hex number or rgb array
  // '#ff0000', 0xff0000, [255, 0, 0]
  stroke?: string | number | number[]
  strokeWidth?: number | 'native'
  strokeOpacity?: number
  fill?: string | number | number[] | false
  fillOpacity?: number
  dash?: boolean
}

GraphicArgs ​

Arguments for adding a graphic to a layer.

ts
interface GraphicArgs {
  // list of shapes to be drawn
  shapes: Shape[]
  // optional base position of the graphic
  position?: Vector2
  // clear all existing graphics in the layer
  clearLayer?: boolean
  // make the graphic clickable and/or draggable.
  // `drag: true` follows the pointer; `drag: 'event-only'` emits drag events without moving it.
  interaction?: { click?: boolean; drag?: boolean | 'event-only' }
  // keep a constant screen size regardless of zoom (pair with a centered position).
  // `true` always applies 1/zoom scaling; a `[min, max]` ZoomRange applies it within
  // the range and clamps to the boundary scale outside it
  fixedScreenSize?: boolean | ZoomRange
}

Shape ​

Available shapes for graphics. The curves are part of the Space Graph geometry definitions.

ts
type Shape =
  | PolygonCurve
  | PolygonWithHolesCurve
  | PolylineCurve
  | RectangleCurve
  | CircleCurve
  | LineCurve
  | GroupShape
  | TextShape
  | ArcCurve
  | BezierCurve
  | CompositeCurve

TokenOptions ​

Options for access tokens required by certain API methods.

ts
interface TokenOptions {
  publishableAccessToken?: string
  secretAccessToken?: string
  temporaryAccessToken?: TemporaryAccessToken
  temporaryAccessTokenScopes?: ScopeDefinitionArray
}

TokenOptions ​

ts
interface TemporaryAccessToken {
  authorization: string
  expiresAt: number
}

Animate ​

Options for animation durations.

ts
type Animate = boolean | number

BoundingBox2d ​

Represents a 2D bounding box.

ts
interface BoundingBox2d {
  min: Vector2
  max: Vector2
}

Vector2 ​

Represents a 2D vector.

ts
type Vector2 = [number, number]

WayfindingResult ​

A walkable route: the path polyline in plan coordinates and its distance in meters. path is empty when no route exists.

ts
type WayfindingResult = {
  path: Vector2[]
  distance: number
}

FindClosestResult ​

The route to the closest reachable node matching a query, or target: null when none is reachable.

ts
type FindClosestResult = WayfindingResult & {
  target: { id: string; position: Vector2 } | null
}

ZoomRange ​

A [min, max] zoom range (inclusive bounds) used for zoom-dependent rendering, e.g. GraphicArgs.fixedScreenSize.

ts
type ZoomRange = [min: number, max: number]

Copyright © 2018-present Archilogic