mapprism-2d

Quick Start ​

This walkthrough uses realistic defaults and demonstrates the most common runtime actions you will perform in production:

  • initialize from map2d
  • switch basemaps
  • add/update layers
  • subscribe to map events
  • use measurement tools

If you are using the CDN distribution instead of npm imports, keep the same code and replace only the module/CSS loading as shown in Getting Started Option B.

1) Create a practical map2d config ​

ts
const config = {
  map2d: {
    initialView: { center: [-79.4346, 41.1922], zoom: 15, bearing: 0 },
    basemap: "hybrid",
    layerPanel: true,
    hud: true,
    tools: {
      measurement: {
        controls: true,
      },
    },
    layers: [
      {
        id: "xyz_dem",
        name: "DEM",
        type: "raster",
        url: "https://storage.mapprism.com/demo/2d/xyz_dem/{z}/{x}/{y}.png",
        visible: true,
        opacity: 1,
        order: 0,
        scheme: "tms",
      },
      {
        id: "xyz_hillshade",
        name: "Hillshade",
        type: "raster",
        url: "https://storage.mapprism.com/demo/2d/xyz_hillshade/{z}/{x}/{y}.png",
        visible: true,
        opacity: 0.5,
        order: 1,
        scheme: "tms",
      },
    ],
  },
};

Why this shape works well:

  • layerPanel: true gives non-technical users immediate layer controls.
  • hud: true provides quick zoom/scale feedback during inspection.
  • Mixed layer opacity (DEM + Hillshade) makes terrain interpretation easier.

2) Instantiate the map safely ​

ts
import { MapPrism2D } from "@mapprism/mapprism-2d";

const container = document.getElementById("map2d");
if (!container) throw new Error("Missing #map2d");

const map = new MapPrism2D(container, config);

3) Add event hooks early ​

ts
map.on("ready", () => {
  console.log("Map ready");
});

map.on("viewchange", (view) => {
  console.log("New view:", view);
});

map.on("layerchange", (layers) => {
  console.log("Layer state changed:", layers);
});

This makes debugging and host-UI synchronization much easier as your integration grows.

4) Drive runtime behavior through the API ​

ts
map.setBasemap("hybrid-2.5d");

map.addLayer({
  id: "contours",
  name: "Contours",
  type: "pmtiles",
  url: "https://storage.mapprism.com/demo/2d/piney_contours.pmtiles",
  visible: true,
  opacity: 1,
  order: 10,
});

map.updateLayer("xyz_hillshade", { opacity: 0.35 });

5) Enable field measurements ​

ts
map.tools.measurement.startLine();   // Enter to finalize
map.tools.measurement.startArea();   // Enter to finalize polygon
map.tools.measurement.startDelete(); // Click an existing drawing to remove it

Practical next step ​

Once this is working, implement View Handoff so your 2D and Potree states stay aligned during transitions.