MapTiler GeoSplats SDK

The GeoSplats SDK provides all the functions and data required to create fully functional web applications with interactive maps and photorealistic SplatModel visualizations on the map. Each SplatModel can be accurately positioned and combined with our 3D terrain and any MapTiler base map.

🌐 Website   🔑 Get API Key

📦 Installation

npm install --save @maptiler/geosplats

🚀 Basic Usage

import { Map, SplatModel } from "@maptiler/geosplats";
import "@maptiler/geosplats/dist/maptiler-geosplats.css";

//Render basic map, container expects id or HTMLElement
//If you omit center, there is some default place in Prague
const map = new Map({
  apiKey: "YOUR_MAPTILER_API_KEY_HERE",
  container: "map",
  center: [14.454266884169874, 50.089376703005215],
});

map.on("load", () => {
  //Creates SplatModel instance
  const splatModel = new SplatModel({
    model: "YOUR_MAPTILER_SPLAT_MODEL_ID_HERE",
  });

  //Adds SplatModel to map (map needs to be loaded, otherwise this is ignored)
  map.addSplatModel(splatModel);
});

💡 Related Examples

• How to add a splat model to your map
• Change map basemap
• Capture events

Check out the full list of examples and tutorials

📘 API Reference

For detailed guides, API reference, and advanced examples, visit our comprehensive documentation:

Complete API documentation

Examples of the main functions and methods

//Render basic map, container expects id or HTMLElement
const map = new Map({
  apiKey: "YOUR_MAPTILER_API_KEY_HERE",
  container: "map",
  center: [14.454266884169874, 50.089376703005215],
  basemap: "hybrid-v4",
});

map.on("load", () => {
  //map is ready
  map.setPitch(30);
  map.setBearing(90);

  //Change map center
  map.setCenter({ lng: 16.609643, lat: 49.191569 });

  //This click event takes into consideration terrain
  map.on("click", (event) => {
    //LngLat
    console.log(event.position);
  });

  //Creates SplatModel instance
  //center provided in constructor overrides center declared in json if present
  const splatModel = new SplatModel({
    model: "YOUR_MAPTILER_SPLAT_ID_HERE",
    center: { lng: 16.609643, lat: 49.191569 },
  });

  //Adds SplatModel to map (map needs to be loaded, otherwise this is ignored)
  //You should show loading indicator
  map.addSplatModel(splatModel);
  //You can also set initial position of camera - i.e. zoomed to specific building
  map.addSplatModel(geoSplat, {position: {lat: 54.829993658211436, lng: 18.293415032279434}, zoom: 19});

  //Returns center of map as LngLat
  map.getCenter((center) => {
    console.log(center);
  });
});

//SplatModel downloaded, you can hide loading etc
map.on("splatmodel:load", () => {
  //Will fire on model position or elevation change
  map.on("splatmodel:update", (event) => {
    //LngLat
    console.log(event.position);
    //altitude
    console.log(event.altitude);
  });

  map.on("splatmodel:mouseover", (event) => {
    console.log(event);
  });

  map.on("splatmodel:mouseout", (event) => {
    console.log(event);
  });

  //Internally value is clamped: [0, 1]
  splatModel.setOpacity(0.5);

  //Sets visibility and color (see type definition for allowed values)
  splatModel.setBoundingBox(true, "yellow");
  splatModel.setBoundingBox(true, "#ffcc00");
  splatModel.setBoundingBox(true, [20, 60, 102, 0.4]);

  //Disable bounding box
  splatModel.setBoundingBox(false);

  //Returns current altitude in meters
  console.log(splatModel.getAltitude());

  //Set altitude in meters
  splatModel.setAltitude(300);

  //Returns model's scale (after training / before georeferencing, this is going to be 1 in most cases)
  console.log(splatModel.getScale());

  //Set model's scale
  splatModel.setScale(5);

  //Returns model's center as LngLat
  console.log(splatModel.getCenter());

  //Set model's center as LngLatLike
  splatModel.setCenter([14.418269, 50.095494]);

  //Moves camera such that model is centered into viewport - sets pitch to 60 degrees, keeps yaw
  splatModel.fit();

  //Hides splatModel, disables listeners, hides bounding box, opacity set to 0
  splatModel.hide();

  //Shows splatModel, re-enables previous listeners, opacity set to 1
  splatModel.show();

  map.on("splatmodel:click", (event) => {
    //mutually exclusive with map:click event
    //Good place to enable i.e. model dragging
    splatModel.setDraggable(true);
  });

  //Returns model's rotations as an array
  //SplatModelRotationDegree = { xRot: number; yRot: number; zRot: number; }
  let rotation = splatModel.getRotationDegrees();

  //Rotates model by 30 degrees around y-axis
  rotation.yRot += 30;
  splatModel.setRotationDegree(rotation);

  //Sets new zoom for the map
  map.setZoom(12.3);

  //Returns current zoom
  console.log(map.getZoom());

  map.jumpTo({
    center: [13.497569, 47.344369],
    zoom: 12,
    pitch: 80,
    bearing: 60,
  });

  //Possibility to lock current pitch
  map.setPitchLocked(false);

  //Change basemap's style
  //Currently we accept custom string, fallbacks to satellite-v4 if invalid
  map.setBasemap("hybrid-v4");

  //void basemap results in plain model rendering without any map
  map.setBasemap("VOID"); //Or ReferenceMapStyleDefaults.VOID

  //Fires once
  map.once("splatmodel:click", (event) => {});

  //Moves the camera so that the provided bounds are visible.
  map.fitBounds([
    [14.408177, 50.080911],
    [14.44025, 50.085178],
  ]);

  map.on("splatmodel:dragstart", () => {
    console.log("SplatModelDrag start");
  });

  map.on("splatmodel:dragend", () => {
    console.log("SplatModelDrag end");
  });

  map.on("click", (event) => {
    //get altitude on arbitrary location (does not have to be provided by click event)
    map.getAltitudeAt(event.position, (altitude) => {
      console.log(`altitude is ${altitude}`);
    });
  });

  //removes canvas and cleans up all resources related to renderer
  map.remove();

  //Snaps model to terrain and provides altitude via the callback
  //(or you can ignore returned value and handle only splatmodel:update event)
  splatModel.snapToTerrain((altitude) => {
    console.log(`altitude is ${altitude}`);
  });

  //Adds an annotation relative to the model (see AnnotationPosition for details): x and z are
  //normalized to the model's bounding box (0 = center, -1/1 = its faces, x east and z north),
  //so the annotation follows the model when it is moved, dragged, rotated or scaled.
  //Annotations sit on top of the model's surface below them, or on the terrain where there is none.
  splatModel.addAnnotation({
    pos: { x: 0.5, z: -0.25 },
    icon: "🏖️",
    label: "Pool",
    popup: "<h3>Pool</h3><p>Any HTML, shown when the annotation is clicked.</p>",
    data: { id: "pool" }, //anything, for your own use
  });

  //...or at a geographic location instead (lng or lon, and lat), where it stays when the model moves.
  //The optional y lifts an annotation above the surface, in internal world units (1 unit = the size of a zoom 14 map tile).
  splatModel.addAnnotation({ pos: { lng: 14.418269, lat: 50.095494, y: 0.001 }, label: "Entrance" });

  //Annotations fire events on their model, and can be changed later on
  splatModel.on("annotation:click", ({ annotation }) => {
    annotation.setColor("#e69439");
    console.log(annotation.getData());
  });

  //Re-writes void style, renders map together with model
  map.setBasemap("satellite-v4");

  //You can later remove map again
  map.setBasemap("VOID");
});

💬 Support

• ✉️ Contact us - Get in touch or submit a request
• 🐦 Twitter/X - Follow us for updates