📦 Model Floorplan

ModelFloorplanPlugin

Overview

The Model Floorplan plugin provides a set of floorplan interactions for the VR 3D model state.

With this plugin, you can display a more detailed 2D floorplan while in the VR 3D model state. The integrated features are as follows:

• Supports displaying 2D floorplans (png / svg formats).
• Room label display: supports custom label styles.
• Displays the camera position and orientation from before entering the 2D floorplan: supports a custom camera icon.
• Supports multi-floor VR listings, i.e. switching between multiple floors.
• Adaptive alignment between the 2D floorplan and the VR 3D model in the top-down view.
• Clicking a room on the 2D floorplan automatically navigates into the corresponding room in VR at an appropriate point.
• Compass display: configuration is not yet supported, but you can override the default styles using CSS selector specificity.
• Supports gesture shortcuts: swiping on the 2D floorplan view quickly switches back to the model state; when you release in the model state, if the angle is close enough to the floorplan's display angle, the model automatically rotates and the floorplan is shown. This feature supports configuration to disable it.

External Demo

Open the Model Floorplan demo to try the plugin outside this documentation page.

Installation

Choose yarn or npm as needed:

npm install @realsee/dnalogel

Import via ES:

import { ModelFloorplanPlugin } from "@realsee/dnalogel"

Development Guide

Initialization

When initializing the Five instance, configure ModelFloorplanPlugin in the initialization plugins parameter.

import { Five } from '@realsee/five'
import { ModelFloorplanPlugin } from '@realsee/dnalogel'

// Initialize the five instance
const five = new Five({
  plugins: [
    [ModelFloorplanPlugin, "modelFloorplanPlugin", {
      // Initialization parameters
    }]
  ]
})

Loading Data

// Get the plugin instance
const pluginInstance = five.plugins.modelFloorplanPlugin
// Load data
pluginInstance.load(floorplanServerData)

Core Plugin Methods

The core methods provided by ModelFloorplanPlugin are:

• async load(data: FloorplanServerData) loads floorplan data;

You need to load floorplan data manually. For the source of [FloorplanServerData], see the OpenAPI reference.

• appendTo(wrapper: Element) mounts the DOM node;

You can load the floorplan DOM module into your own HTML structure.

• async show(opts?: ShowOpts): true shows the floorplan;

When you call the plugin's show() method, the plugin automatically drives the five instance into the model top-down state and displays the floorplan for the floor corresponding to the current point.

const floorplanPlugin = five.plugins.modelFloorplanPlugin
floorplanPlugin.show()
floorplanPlugin.show(options)

If you need to customize the display logic, you can also pass options for configuration. The configuration options are declared as follows:

interface ShowOpts {
  floorIndex?: number   // The floor to display; defaults to the floor corresponding to the current point
  userAction?: boolean  // When the floorplan is displayed, calls to the relevant Five APIs will pass through userAction
  modelOpacity?: number // The opacity of the model when the floorplan is displayed; defaults to 0.01
  immediately?: boolean // Whether the image should appear immediately; by default there is a 500ms animation. Note that this immediately option cannot cancel the model animation
}

• async hide(options?: { isAutoHide?: boolean; userAction?: boolean ) hides the floorplan

You can call hide() directly to hide the floorplan. When the autoShowEnable option is set to true (the default), swiping on the floorplan beyond a certain threshold will automatically close it.

• updateSize() updates the floorplan size;
• changeConfigs(config: Partial<Config>, userAction = true) modifies the floorplan configuration;
• setState(state: PartialDeep<State>, options: BaseOptions = {}) changes the plugin State;
• enable(options: BaseOptions = {}) enables the plugin;
• disable(options: BaseOptions = {}) disables the plugin;
• dispose() destroys the plugin;

Custom Configuration

ModelFloorplanPlugin supports a rich set of custom configuration options (see [ModelFloorplanParameterType] for details). Common options include:

• selector?: string | Element the DOM node the plugin mounts to

A DOM selector or DOM node instance.

Note: the DOM container must have the same width and height as the five canvas, and a higher z-index than the five canvas.

• scale?: number the floorplan scale ratio

Changing this parameter also changes the scale of the VR model beneath the floorplan. Defaults to 1.

• hoverEnable?: boolean whether to enable mouse hover highlighting of rooms

Defaults to true. When the mouse hovers over a room, that room is highlighted.

• getLabelElement?: (room: FloorplanRoomItem) => Element | null configures room labels

If this function is configured, it is called for every room label, and the label's Element is replaced with the Element returned by the callback.

If the return value is null or another empty value, the current label is not displayed.

If this function is not configured, all labels are displayed by default.

• cameraImageUrl?: string custom [radar] icon

The CSS styles passed via style override the default styles, including backgroundImage, width, height, etc.

• autoShowEnable: boolean gesture shortcuts

Swiping on the 2D floorplan view quickly switches to the model state; when you release in the model state, if the angle is close enough to the floorplan's display angle, the model automatically rotates and the floorplan is shown. Enabled by default.

Event Hooks

Floorplan-related events are bound to the hooks object. You can use the hooks.on method to listen for events. For example:

• showAnimationEnded

Triggered when the floorplan finishes appearing. It only fires on the transition from invisible to visible; calling show multiple times only triggers showAnimationEnded once.

five.plugins.modelFloorplanPlugin.hooks.on('showAnimationEnded', ({ auto, userAction }) => {
  console.log('Whether the floorplan was auto-shown because the user swiped the model: ', auto)
  console.log('Whether the floorplan was shown due to a user action: ', userAction)
  console.log('Floorplan finished showing')
})

• hide

Triggered when the floorplan finishes disappearing.

five.plugins.modelFloorplanPlugin.hooks.on('hide', ({ auto, userAction }) => {
  console.log('Whether the floorplan was auto-hidden because the user swiped the model: ', auto)
  console.log('Whether the floorplan was hidden due to a user action: ', userAction)
  console.log('Floorplan has disappeared')
})

Source Reference

ModelFloorplanPlugin example source