For AI agents: a documentation index is available at /llms.txt. Markdown versions of all pages are available by appending .md to any URL.

Custom loading animation effect

This example demonstrates how to add a custom loading animation while the splat model is loading.

You must always initialize a Map instance before adding a SplatModel. Initialize the map with the VOID style so the system doesn’t render any tiles, leaving the map empty.

Before the model loads, you can display a custom loading animation screen. Then, you can capture the model loading event splatmodel:load and, once loading is complete, hide the loading screen or perform any other action like add a basemap.

NPM module setup


npm install --save @maptiler/geosplats
---
layout: none
---


import { SplatModel, Map, ReferenceMapStyleDefaults, config } from "https://cdn.maptiler.com/maptiler-geosplats//maptiler-geosplats.mjs";;
import '@maptiler/geosplats/dist/maptiler-geosplats.css';

config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';
const map = new Map({
  apiKey: config.apiKey,
  container: "map",
  basemap: ReferenceMapStyleDefaults.VOID
});

//Show a error message 
map.on('error', (e) => {
  const message = e.message.toLowerCase();
  console.log(message);

  // Hide the loader so any error message is visible
  const loader = document.getElementById("loader");
  if (loader) {
    loader.classList.add("hidden");
  }

  if (message.includes('gpu') || message.includes('apple device')) {
    const errorEl = document.getElementById('webGpuError');
    if (errorEl) {
      errorEl.classList.remove('d-none');
      if (message.includes('gpu')) {
        errorEl.textContent =
          'Your browser does not support WebGPU. It is necessary to use a modern browser that supports it. Also make sure to enable hardware acceleration in your browser settings.';
      } else {
        errorEl.textContent = e.message;
      }
    }
  }
});

let splatModel;

map.on("load", () => {
  splatModel = new SplatModel({
    model: "YOUR_MAPTILER_SPLAT_MODEL_ID_HERE"
  });
  map.addSplatModel(splatModel);

  // Capture splat model load event
  map.on("splatmodel:load", () => {
    // Hide the custom loading screen or perform any other desired action after the model has loaded.
    const loader = document.getElementById("loader");
    if (loader) {
      loader.classList.add("hidden");
      setTimeout(() => {
        loader.remove();
      }, 500);
    }

    map.setBasemap('satellite-v4'); //Add a basemap
    
    setTimeout(() => {
      map.zoomIn(); //Zoom in 
    }, 300);
  });

});

Learn more

Check out the MapTiler GeoSplats SDK JS reference

Edit model in custom editor

Edit model in custom editor

Examples

Build a custom 3D editor to adjust the position, rotation, and scale of splat models and save their properties to a database.

How to add a splat model to your map

Add splat model

Examples

Learn 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.

Change map basemap

Change basemap

Examples

Learn how to dynamically switch between different MapTiler basemaps while maintaining photorealistic 3D splat models in your scene.

Change the opacity and visibility of splats

Opacity and visibility

Examples

Learn how to dynamically control the transparency and visibility of photorealistic splats objects using the MapTiler GeoSplats SDK.

Was this helpful?