Plan

Plan instances expose plan data that is relevant for the Viewer in a way that is stable and suitable for long-term use by developers. They do not expose every single piece of data that PlanStudio is able to collect.

We intend on exposing more data to the SDK over time. Please get in touch with us if you have specific needs for querying data that the SDK doesn’t currently meet.

You cannot directly create Plan instances or modify them.

Getting a plan
- locatrix.plans.loadPlan(viewerToken[, options])
- locatrix.plans.unload(plan)
Querying plan data
Rotation/Camera framing
Evac Paths
- plan.getEvacPathsFromPoint(point[, useClosestDiagramFilter])
- plan.getEvacPathsFromFloorPlan(floorPlan[, floorPlanEvacPaths])
Features

Getting a plan

When the viewer loads a plan, it makes it available for querying via viewer.getLoadedPlan().

Plans can be loaded directly without the need for a viewer via locatrix.plans.loadPlan().

`locatrix.plans.loadPlan(viewerToken[, options])`

viewerToken: <string>
options: <Object>
- planCode: <string>
- prepareWorldPaths: <boolean> Default: false
- revisionNumber: <number> Default: latest revision number
Returns: <Promise<Plan>>

Returns a promise that will resolve with the loaded plan.

If the given viewerToken is an allAreasAndChildren type issued from the ESAPI, the planCode to load must be provided.

The promise will reject if there are network errors while loading the plan.

Plans loaded in this way must be manually unloaded with locatrix.plans.unload() when they are no longer needed.

`locatrix.plans.unload(plan)`

plan: <Plan>

Unloads the given plan.

Querying plan data

`plan.getPlanCode()`

Returns: <string>

Returns the plan code associated with this plan.

`plan.getCampusCode()`

Returns: <string>

Returns the campus code associated with this plan.

`plan.getBuildingCode()`

Returns: <string> | <null>

Returns the building code associated with this plan. The returned value will be null for site plans.

`plan.getFloorCode()`

Returns: <string> | <null>

Returns the floor code associated with this plan. The returned value will be null for site plans.

`plan.getIconTypes()`

Returns: <string[]>

Returns an array of all icon types contained within this plan.

Rotation/Camera framing

`plan.getNaturalRotation()`

Returns: <number>

Returns the natural rotation of this plan, in degrees. This can be passed directly to viewer.setRotation() to display the plan in its natural rotation.

The natural rotation is the rotation that is seen when the plan is loaded in PlanStudio, and is a good fit for viewing the plan.

`plan.getFocalPointAndZoomToFit(rotation, viewerWidth, viewerHeight[, includeLayerIds])`

rotation: <number>
viewerWidth: <number>
viewerHeight: <number>
includeLayerIds: <string[]>
Returns: <Object>
- focalPoint: <Object>
  - latitude: <number>
  - longitude: <number>
- zoom: <number>

Returns the focal point and zoom that would be required to fit the whole plan into a Viewer that has been set to use the given rotation. This focal point and zoom is used as the default when the plan is first loaded. Optionally uses only the layers specified by includeLayerIds when fitting the plan, and ignores all other layers.

`plan.getFocalPointAndZoomToFill(rotation, viewerWidth, viewerHeight, forPlanCode[, includeLayerIds])`

rotation: <number>
viewerWidth: <number>
viewerHeight: <number>
forPlanCode: <string>
includeLayerIds: <string[]>
Returns: <Object>
- focalPoint: <Object>
  - latitude: <number>
  - longitude: <number>
- zoom: <number>

It is typical for site plans to cover a larger area than is actually relevant, so that their background map/satellite imagery fully covers the visible area in evacuation signs. In order to provide a similar framing in the Viewer, this method allows you to get a more zoomed-in framing than plan.getFocalPointAndZoomToFit() provides.

You are required to provide a plan code so that you are guaranteed to be able to see that plan’s footprints as well as any evac paths/assembly areas for that plan. This requirement means that the method is only suitable for use with site plans.

Evac Paths

`plan.getEvacPathsFromPoint(point[, useClosestDiagramFilter])`

point: <Object>
- latitude: <number>
- longitude: <number>
useClosestDiagramFilter: <boolean> Default: false
Returns: <EvacPath[]>

Returns an array of evac paths that can be taken to evacuate from the given point. These evac paths can be passed to viewer.setEnabledEvacPaths() for display.

You can obtain latitude/longitude values to use with this method from the point property of "click" events in the Viewer.

Additionally, you can pass true as the useClosestDiagramFilter parameter to filter the evacuation paths according to the closest evacuation diagram to the given point.

`plan.getEvacPathsFromFloorPlan(floorPlan[, floorPlanEvacPaths])`

floorPlan: <Plan>
floorPlanEvacPaths: <EvacPath[]>
Returns: <EvacPath[]>

Returns an array of evac paths that can be taken to evacuate from the given floorPlan, based on that plan’s footprints in this plan. This method is only suitable for use with site plans - e.g sitePlan.getEvacPathsFromFloorPlan(floorPlan).

If you pass it the result from plan.getEvacPathsFromPoint as the floorPlanEvacPaths parameter, then the resulting evac paths will match those of a site plan in an Evacuation Diagram.

Features

`plan.getFeatures()`

Returns: <Feature[]>

Returns an array of all features in the plan.

`plan.getFeaturesNearPoint(point, radiusMeters)`

point: <Object>
- latitude: <number>
- longitude: <number>
radiusMeters: <number>
Returns: <Feature[]>

Returns an array of all features contained/intersecting the given radius (meters) of the given latitude/longitude.

`plan.getEvacSigns()`

Returns: <Feature[]>

Returns an array of all evac signs in the plan sorted by sign ref. This is guaranteed to be the same order as in PlanStudio Sign Preview Mode.