Skip to main content

Map Perspective

|

This example demonstrates how to toggle the map view angle between 2D (vertical look-down at the map) and 3D (perspective, tilted map, looking toward the horizon).

Live Demo​

Code Implementation​

index.ts
import {
  GemKit,
  GemMap,
  PositionService,
  BuildingsVisibility,
} from '@magiclane/maps-sdk';

let map: GemMap | null = null;
let mapPreferences: any = null;
let isInPerspectiveView = false;

const VIEW_3D_ANGLE = 30;
const VIEW_2D_ANGLE = 90;

// Toggle perspective view
function onChangePerspectiveButtonPressed() {
  isInPerspectiveView = !isInPerspectiveView;

  if (!mapPreferences) return;

  if (isInPerspectiveView) {
    mapPreferences.buildingsVisibility = BuildingsVisibility.threeDimensional;
    mapPreferences.tiltAngle = VIEW_3D_ANGLE;
  } else {
    mapPreferences.buildingsVisibility = BuildingsVisibility.twoDimensional;
    mapPreferences.tiltAngle = VIEW_2D_ANGLE;
  }
}

// Map created callback
function onMapCreated(gemMap: GemMap) {
  map = gemMap;
  mapPreferences = map.preferences;
}

// Main entry
window.addEventListener('DOMContentLoaded', async () => {
  const gemKit = await GemKit.initialize(GEMKIT_TOKEN);
  await PositionService.instance;

  const viewId = 5;
  gemKit.createView(viewId, (gemMap: GemMap) => {
    onMapCreated(gemMap);
  });
});

Key Features​

View Angle Control​

Toggle between different map viewing perspectives:

  • 2D View (90°): Vertical look-down view, map appears flat from directly above
  • 3D View (30°): Tilted perspective view, looking toward the horizon
  • Dynamic Switching: Smooth transition between view modes

Building Visibility​

The example controls building rendering based on the perspective:

  • 2D Mode: Buildings rendered in two-dimensional style
  • 3D Mode: Buildings displayed with three-dimensional depth and detail
  • Synchronized Settings: Building visibility automatically matches the view angle

How It Works​

  1. Initialize Map: Create the map view and get access to map preferences
  2. Create UI Button: Add a toggle button in the top-right corner
  3. Handle Toggle: Switch between 2D and 3D perspectives on button click
  4. Update Settings: Adjust tilt angle and building visibility simultaneously
  5. Visual Feedback: Update button icon to reflect current mode

Implementation Details​

Tilt Angle Configuration​

The map perspective is controlled through the tiltAngle property:

  • 90 degrees: Orthogonal/vertical view (looking straight down)
  • 30 degrees: Perspective view (tilted toward horizon)
  • Range: Valid angles are between 0° and 90°

Buildings Visibility Modes​

The SDK provides two building rendering modes:

  • BuildingsVisibility.twoDimensional: Flat building representation
  • BuildingsVisibility.threeDimensional: 3D building models with depth

Map Preferences​

Map preferences are accessed through map.preferences:

  • Control tilt angle with mapPreferences.tiltAngle
  • Control building rendering with mapPreferences.buildingsVisibility
  • Changes take effect immediately

UI Components​

Perspective Toggle Button​

The button provides visual feedback and interaction:

  • Position: Fixed in top-right corner
  • Icons: 🗻 for 2D mode, 🗺️ for 3D mode
  • Styling: Purple background matching the app theme
  • Interaction: Click to toggle between perspectives

Use Cases​

  • Navigation: 3D perspective helps users orient themselves while navigating
  • Exploration: 2D view provides better overview for route planning
  • Urban Areas: 3D buildings provide better context in cities
  • Comparison: Switch between views to understand terrain and features

Next Steps​

Last updated on