Floor Plan Rendering & Viewport Transitions

This document details how the SDK renders vector floor plans from IMDF files, manages floor-level switching states, and coordinates camera zoom transitions between outdoor and indoor views.

---

🎨 Floor Plan Rendering (RenderOptions)

The rendering pipeline translates IMDF layers into MapLibre paint variables. You can customize the visibility, opacity, and structural parameters of layers using the renderOptions property on <FloorLayers> or the Zustand store:

export interface RenderOptions {
  /** Background canvas color overlay. */
  backgroundColor?: string;
  
  /** Outdoor ground geometries. */
  grounds?: {
    render?: boolean;
    includeLayers?: string[];
    omitLayers?: string[];
  };
  
  /** 3D or 2D partitions. */
  walls?: {
    render?: boolean;
    alpha?: number;
    /** Default height in centimeters. Default is 280 (2.8m). */
    maxHeightCm?: number;
    /** If true, draws structural lines. */
    showStructuralWalls?: boolean;
  };
  
  /** PEDESTRIAN and SERVICE openings. */
  doors?: {
    render?: boolean;
  };
  
  /** Windows and translucent dividers. */
  windows?: {
    render?: boolean;
  };
  
  /** Fixtures and furniture models. */
  objects?: {
    render?: boolean;
  };
  
  /** Anchor names and text annotations. */
  annotations?: {
    render?: boolean;
  };
  
  /** Escalators, stairs, and vertical structures. */
  stairs?: {
    render?: boolean;
  };
  
  /** Display a north-pointing orientation compass. */
  compass?: boolean;
  
  /** Warped georeferenced blueprint parameters. */
  floorplan?: {
    render?: boolean;
    /** Opacity overlay slider (0-1). */
    alpha?: number;
    /** Height offset in centimeters to prevent z-fighting in 3D. Default is 2. */
    elevationInCm?: number;
  };
}

Inferred Structural Walls

Since standard IMDF files do not contain a dedicated "wall" layer, the SDK automatically infers structural walls at runtime by calculating the mathematical difference:

$$\text{Walls} = \text{Level Outline Footprint} \setminus \left( \bigcup \text{Unit Polygons} \right)$$

This difference geometry is extruded in 3D mode as a MapLibre fill-extrusion layer with height set to maxHeightCm.

---

🪜 Floor Switcher & Stacking Views

The <FloorSwitcher /> component controls active floor visibility. It reads state from floorSlice and coordinates several viewing styles:

1. Single-Floor Isolation (Default)

Renders the active floor plan and hides all other floors, maximizing rendering efficiency.

2. Cumulative Stacking View

Renders multiple floors concurrently up to a specified level index (mirroring Smplrspace's map.showUpToLevel(levelIndex)). Lower floors are rendered as translucent overlays.

3. Exploded Multi-Floor View (3D Only)

Explodes all floors vertically in 3D space, separating level polygons with a vertical offset of 15 meters per level. This allows users to trace vertical pipes, elevator shafts, and wayfinding pathways across the entire building.

🛹 Keyboard Shortcuts

When the floor switcher is focused, the following hotkeys are available:

• ↑ / ↓: Step one floor level up or down.
• 0 to 9: Instantly jump to a specific floor ordinal.
• E: Toggle the 3D Exploded Multi-Floor View.

---

🔄 Outdoor↔Indoor Viewport Transitions (DynamicFocus)

To prevent visual clutter, the <DynamicFocus /> component orchestrates smooth, animated transitions between outdoor vector basemaps and indoor floor plans:

graph LR
    Outdoor[Outdoor Basemap Zoom < 16] -- Zoom In --> Transition[Campus Footprints Zoom 16-18]
    Transition -- Zoom In >= 18 --> Indoor[Indoor Floor Plan & Assets]
    Indoor -- Zoom Out < 16 --> Outdoor

• Entering Indoor View (Zoom $\ge$ 18): Smoothly transitions MapLibre pitch to 50°, rotates bearing to align with the building's homography grid, fades out outdoor roads, and renders indoor rooms, furniture, and live RTLS assets.
• Exiting to Outdoor View (Zoom $<$ 16): Resets pitch to 0°, rotates bearing back to true North (0°), hides floor plan levels, and restores global vector roads.
• Transition Duration: Animated over a 1,200 ms map.easeTo duration.
• Campus Footprints: Intermediary zoom ranges render 3D building outlines extruded to their real-world height (extracted from IMDF building.height or calculated as 4 meters $\times$ number of levels).