For AI agents: a documentation index is available at /llms.txt. Markdown versions of all pages are available by appending .md to any URL.
How to add annotations to a splat model
This example demonstrates how to create interactive annotations on a 3D Gaussian splat model using the MapTiler GeoSplats SDK. Annotations are labelled pins attached to a model that can display HTML popups when clicked.
NPM module setup
npm install --save @maptiler/geosplats
import { SplatModel, Map, config } from "@maptiler/geosplats";
import "@maptiler/geosplats/dist/maptiler-geosplats.css";
config.apiKey = "YOUR_MAPTILER_API_KEY_HERE";
const map = new Map({
apiKey: config.apiKey,
container: "map",
center: [-80.27822, 25.74077],
zoom: 17.5,
pitch: 50,
bearing: -15,
});
let splatModel;
map.on("load", () => {
splatModel = new SplatModel({
model: "YOUR_MAPTILER_SPLAT_MODEL_ID_HERE",
revealParams: { enabled: true },
});
map.addSplatModel(splatModel);
});
map.on("splatmodel:load", () => {
splatModel.addAnnotation({
pos: { x: -0.4, z: -0.2 },
icon: "๐๏ธ",
label: "Sun Pool",
popup: "<h3>๐๏ธ Sun Pool</h3><p>Outdoor pool with a 24h bar.</p>",
});
splatModel.addAnnotation({
pos: { x: -0.06, z: -0.26, y: 0.001 },
icon: "๐ข",
label: "Main Entrance",
color: "#2bb673",
popup: "<h3>๐ข Main Entrance</h3><p>Main hotel lobby, reception, and guest check-in.</p>",
});
splatModel.addAnnotation({
pos: { x: 0.6, z: 0.46 },
icon: "๐พ",
label: "Tennis Courts",
popup: "<h3>๐พ Tennis Courts</h3><p>10 championship courts with floodlighting.</p>",
});
});
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="robots" content="noindex" />
<title>How to add annotations to a splat model</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<div id="map"></div>
<script type="module" src="./main.js"></script>
</body>
</html>
body {
font-family: Inter, sans-serif;
margin: 0;
overflow: hidden;
}
#map {
width: 100%;
height: 100vh;
}
When to add annotations
The addAnnotation() method on SplatModel is only active once the model is attached and loaded onto the map. Calling splatModel.addAnnotation() before the model loads returns undefined and adds nothing.
Wait for the splatmodel:load event on the map before adding annotations:
map.on("splatmodel:load", () => {
splatModel.addAnnotation({
pos: { x: -0.4, z: -0.2 },
icon: "๐๏ธ",
label: "Sun Pool",
popup: "<h3>๐๏ธ Sun Pool</h3><p>Outdoor pool with a 24h bar.</p>",
});
});
Pin labels and icons
Pins consist of an optional emoji icon (icon) and an optional text label (label). The pin automatically resizes to accommodate its content:
- Emoji icon: A single emoji shown on the pin.
- Label: Short text rendered next to the icon in white text with a crisp background.
- Color: An optional pin fill color (such as hex
#2bb673). The default fill is MapTiler blue (#4d7fff).
Keep labels concise. Detailed information, long descriptions, or external links belong in the popup.
Interactive HTML popups
Defining the popup property turns the pin into an interactive card that opens when clicked:
- HTML content: Accepts any standard HTML string, including headings, paragraphs, and formatted text.
- Single active popup: Only one popup opens at a time per map. Opening another pin closes any open card.
- Automatic tracking: The popup tracks the pin across camera pans, rotations, and zoom changes, and hides automatically if the pin moves off-screen.
- Active state collapsing: When a pinโs popup opens, the pin badge collapses to a circular icon so it does not block the card content.
Learn more
Check out the MapTiler GeoSplats SDK reference to explore the full list of annotation options and event listeners.
Related examples
Add splat model
ExamplesLearn how to load a map using the GeoSplats SDK and add a photorealistic splat model. A splat model offer a modern alternative to 3D meshes, perfect for complex scenes.
Model vs geographic positioning
ExamplesPlace annotations using model-relative bounding box coordinates or geographic coordinates.
Pin styles and categories
ExamplesStyle annotations with colors, icons, numbers, and custom popup placement.
Rich HTML popups
ExamplesDisplay custom HTML cards in annotation popups with images, tables, and custom widths.