📦 Large-Space Model Floorplan

MapviewFloorplanPlugin

Overview

The Large-Space Model Floorplan plugin is an upgraded version of the Model Floorplan plugin, adding pinch-zoom and drag gesture operations.

With this plugin you can display a more detailed 2D floorplan while in the VR 3D model state. In addition to the following features shared with the Model Floorplan plugin:

• Display of 2D floorplans (png / svg format).
• Room label display: supports custom label styles.
• Display of the camera position and orientation before entering the 2D floorplan: supports a custom camera icon.
• Support for multi-floor VR listings, i.e. switching between floors.
• Adaptive alignment of the 2D floorplan with the VR 3D model in the top-down view.
• Clicking a room in the 2D floorplan automatically navigates to a suitable point in the corresponding VR room.
• Compass display: not configurable for now, but you can override the default style via CSS selector priority.
• Support for gesture shortcuts: swiping on the 2D floorplan interface quickly switches to the model state; when releasing in the model state, if the angle is close to the floorplan's display angle, the model automatically rotates and the floorplan is shown. This feature supports configuration to disable it.

The Large-Space Model Floorplan additionally provides the following features:

• Proportionally zoom the 2D floorplan and the VR 3D model in and out, keeping the two aligned.
• Drag to inspect the zoomed-in floorplan, allowing you to precisely view the contents of a specific region of the floorplan.

External Demo

Open the Large-Space 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 modules:

import { MapviewFloorplanPlugin } from "@realsee/dnalogel"

Development Guide

Initialization

When initializing the Five instance, just configure MapviewFloorplanPlugin in the initialization plugin parameters.

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

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

Loading Data

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

Core Plugin Methods

The core methods provided by MapviewFloorplanPlugin are:

• load(data: FloorplanServerData) Load floorplan data

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

• appendTo(wrapper: Element) Mount the DOM node

You can mount the floorplan DOM module into your HTML structure.

• async show(opts?: ShowOpts): true Show

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

const floorplanPlugin = five.plugins.mapviewFloorplanPlugin
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  // While the floorplan is shown, calls to the relevant Five APIs will pass through userAction
  modelOpacity?: number // The model's opacity when the floorplan is shown; defaults to 0.01
  immediately?: boolean // Whether the image appears immediately; by default there is a 500ms animation. Note that this immediately option cannot cancel the model animation
}

• hide(options?: { isAutoHide?: boolean; userAction?: boolean )

You can call the hide() method directly to hide the floorplan. If the autoShowEnable option is set to true (the default), then when the user swipes on the floorplan beyond a certain distance, the floorplan is automatically closed.

• changeFloor(floorIndex: number) Change the floorplan floor

Some listings have multiple floors (duplexes, villas, etc.), and each floor has a different layout. You can use changeFloor() to directly switch to the layout of the corresponding floor.

Note that for multi-floor listings, only the module of the 3D model for the current floor is highlighted.

Of course, when the user moves between points in the VR panorama and the corresponding floor changes, the floor of the current point is also automatically displayed while the floorplan is shown.

Custom Configuration

MapviewFloorplanPlugin supports a rich set of custom configuration options (see [MapviewFloorplanParameterType] for details). Common options are:

• selector?: string | Element The DOM node to which the plugin is mounted

A DOM selector or DOM node instance.

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

• scale?: number Floorplan zoom ratio

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

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

Defaults to false. Functionality: when the mouse hovers over a room, that room is highlighted.

• getLabelElement?: (room: FloorplanRoomItem) => Element | null Configure 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 returned result is null or a similar empty value, the current label is not displayed.

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

• cameraImage?: { style: React.CSSProperties } Configure the camera icon

The CSS styles passed in style override the default styles, including backgroundImage, width, height, and so on.

• autoShowEnable: boolean Gesture shortcuts

Swiping on the 2D floorplan interface quickly switches to the model state; when releasing in the model state, if the angle is close 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, and you can listen to events using the hooks.on method. For example:

• showAnimationEnded

Floorplan display finished. This only fires on the transition from invisible to visible; calling show multiple times only triggers showAnimationEnded once.

five.plugins.mapviewFloorplanPlugin.hooks.on('showAnimationEnded', ({ auto, userAction }) => {
  console.log('Whether the floorplan was auto-shown due to the user swiping the model: ', auto)
  console.log('Whether the floorplan was shown due to a user action: ', userAction)
  console.log('Floorplan display complete')
})

• hide

Floorplan dismissal finished

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

Source Reference

MapviewFloorplanPlugin example source