mapprism-2d

View Handoff (3D <-> 2D) ​

Use this guide when your application has both:

  • a 3D viewer (for example Potree), and
  • a MapPrism2D map view

The goal is simple: users should not lose spatial context while switching modes.

Core idea ​

mapprism-2d exposes two methods for synchronization boundaries:

  • setView(...) for applying external camera state to 2D
  • getView() for exporting current 2D state back to your 3D system

This lets the host app own transition timing and UX while mapprism-2d stays focused on map behavior.

This pattern syncs only when a user switches panels.
It is easier to reason about and usually enough for production UX.

3D -> 2D handoff ​

ts
map.setView(
  {
    center: [-79.4346, 41.1922],
    bearing: 45,
    zoom: 17,
  },
  { animate: true }
);

2D -> 3D handoff ​

ts
const view = map.getView();
// view.center is WGS84 [lng, lat]
// Convert and apply to your 3D camera model as needed.

Pattern B: Continuous runtime sync (optional) ​

If your UX needs both panels continuously linked, enable runtime sync in map2d.sync:

ts
const config = {
  map2d: {
    // ...
    sync: {
      enabled: true,
      master: "auto",      // "auto" | "map2d" | "potree"
      mapPriorityMs: 1200,
      potree: {
        viewer: window.viewer,
        throttleMs: 50,
      },
    },
  },
};

When to use it ​

  • live split-screen workflows
  • synchronized operator and analyst views
  • interactions where both viewers remain visible/active

When to avoid it ​

  • simple toggle-based interfaces
  • apps where explicit transition animation is enough
  • environments where camera ownership must stay deterministic

Coordinate reminder ​

getView() and setView() always use WGS84 coordinates ([lng, lat]).

If your 3D system stores EPSG:3857 or engine-native coordinates, convert at the handoff boundary in your host app.

Integration checklist ​

  1. Attach map ready handler.
  2. Implement panel transition events in host UI.
  3. On 3D -> 2D, call setView(...).
  4. On 2D -> 3D, read getView() and update 3D camera.
  5. Add viewchange subscriptions if you maintain global app state.