Getting Started

This guide is the fastest path from install to a working map instance.

mapprism-2d is the 2D plugin/module of the larger MapPRISM system.
If you already have a MapPRISM config object in your app, you can usually integrate this module in a few minutes.

---

1) Choose npm package or CDN

Option A: npm (recommended for app builds)

npm install @mapprism/mapprism-2d maplibre-gl

maplibre-gl is a peer dependency, so your host app installs and controls its version.

Option B: CDN (browser-only integration)

Public CDN base:

https://pub-78d8b203e7a5426d953b50368fb4be3f.r2.dev/cdn/mapprism-2d/latest/dist

Include CSS from CDN and load MapLibre UMD + a tiny shim so the ESM build can resolve maplibre-gl:

<link
  rel="stylesheet"
  href="https://unpkg.com/maplibre-gl@4.3.2/dist/maplibre-gl.css"
/>
<link
  rel="stylesheet"
  href="https://pub-78d8b203e7a5426d953b50368fb4be3f.r2.dev/cdn/mapprism-2d/latest/dist/mapprism-2d.css"
/>

<script src="https://unpkg.com/maplibre-gl@4.3.2/dist/maplibre-gl.js"></script>
<script type="importmap">
{
  "imports": {
    "maplibre-gl": "/maplibre-gl-shim.js"
  }
}
</script>

/maplibre-gl-shim.js:

export default window.maplibregl;

Then import MapPrism2D from CDN:

<script type="module">
  import { MapPrism2D } from "https://pub-78d8b203e7a5426d953b50368fb4be3f.r2.dev/cdn/mapprism-2d/latest/dist/index.esm.js";

  // ... instantiate as usual
</script>

---

2) Include the required CSS

import "maplibre-gl/dist/maplibre-gl.css";
import "@mapprism/mapprism-2d/mapprism-2d.css";

The first stylesheet is MapLibre base styling.
The second stylesheet provides optional UI components shipped by mapprism-2d (layer panel, HUD, measurement controls), all scoped under the .mp2d- prefix.

If you use the CDN option above, this step is already handled by <link> tags.

---

3) Prepare a container element

Create a map container with an explicit size (height is required).

<div id="map2d" style="height: 480px; width: 100%;"></div>

Without a defined height, MapLibre has no viewport to render into.

---

4) Instantiate MapPrism2D

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

const container = document.getElementById("map2d");

if (!container) {
  throw new Error("Missing #map2d container");
}

const map = new MapPrism2D(container, {
  map2d: {
    initialView: {
      center: [-79.4346, 41.1922],
      zoom: 15,
      bearing: 0,
    },
    basemap: "hybrid",
    layers: [],
  },
});

The constructor is synchronous, but map internals initialize asynchronously.

---

5) Wait for readiness before advanced interaction

map.on("ready", () => {
  console.log("mapprism-2d is ready");
});

A safe rule: attach events immediately, but defer operations that depend on rendered layers until ready fires.

---

Common first integrations

• Load survey layers from your config through map2d.layers.
• Enable built-in panel/HUD with map2d.layerPanel and map2d.hud.
• Wire 3D/2D transitions with getView() and setView().

---

Where to go next

• Quick Start for a practical end-to-end setup
• map2d Schema for full configuration fields and defaults
• MapPrism2D API for method signatures and runtime behavior
• View Handoff for Potree integration patterns