Blend splat models with 3D terrain

This example shows how to blend a splat model with the surrounding 3D terrain. Terrain blending smoothly integrates photorealistic Gaussian splats into digital elevation models (DEM), eliminating sharp boundaries and clipping artifacts between the captured model and the map’s elevation surface.

Use the dropdown menu in the top-left corner to:

  • Activate or deactivate terrain blending dynamically with the toggle button.
  • Adjust the blending intensity (vertical displacement) with the intensity slider.
  • Fine-tune the smoothness (transition band width) with the smoothness slider.

npm install --save @maptiler/geosplats

main.js

 
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: [-60.04487, -18.1391],
  zoom: 17.5,
  pitch: 60,
});

let splatModel;
let isBlendingEnabled = true;

const dropdownToggle = document.getElementById("dropdown-toggle");
const dropdownPanel = document.getElementById("dropdown-panel");
const btnToggleBlend = document.getElementById("btn-toggle-blend");
const blendControls = document.getElementById("blend-controls");
const intensitySlider = document.getElementById("intensity-slider");
const smoothnessSlider = document.getElementById("smoothness-slider");
const intensityVal = document.getElementById("intensity-val");
const smoothnessVal = document.getElementById("smoothness-val");

dropdownToggle.addEventListener("click", () => {
  const isCollapsed = dropdownPanel.classList.toggle("collapsed");
  dropdownToggle.classList.toggle("collapsed", isCollapsed);
  dropdownToggle.setAttribute("aria-expanded", !isCollapsed);
});

function applyTerrainBlending() {
  if (!splatModel) return;
  const intensity = Math.max(0.001, parseFloat(intensitySlider.value));
  const smoothness = Math.max(0.001, parseFloat(smoothnessSlider.value));
  splatModel.setTerrainBlending(isBlendingEnabled, {
    terrainDisplacement: intensity,
    terrainSmoothness: smoothness,
  });
}

btnToggleBlend.addEventListener("click", () => {
  isBlendingEnabled = !isBlendingEnabled;
  if (isBlendingEnabled) {
    btnToggleBlend.textContent = "Deactivate terrain blending";
    btnToggleBlend.classList.remove("inactive");
    btnToggleBlend.classList.add("active");
    blendControls.classList.remove("disabled");
    intensitySlider.disabled = false;
    smoothnessSlider.disabled = false;
  } else {
    btnToggleBlend.textContent = "Activate terrain blending";
    btnToggleBlend.classList.remove("active");
    btnToggleBlend.classList.add("inactive");
    blendControls.classList.add("disabled");
    intensitySlider.disabled = true;
    smoothnessSlider.disabled = true;
  }
  applyTerrainBlending();
});

intensitySlider.addEventListener("input", (e) => {
  intensityVal.textContent = parseFloat(e.target.value).toFixed(2);
  if (isBlendingEnabled) {
    applyTerrainBlending();
  }
});

smoothnessSlider.addEventListener("input", (e) => {
  smoothnessVal.textContent = parseFloat(e.target.value).toFixed(2);
  if (isBlendingEnabled) {
    applyTerrainBlending();
  }
});

map.on("load", () => {
  splatModel = new SplatModel({
    model: "019e646c-153e-7b9e-9004-c1a3297f202a",
  });
  map.addSplatModel(splatModel);
});

map.once("splatmodel:load", () => {
  splatModel.fit();
});

Configure terrain blending

You can enable or disable terrain blending dynamically at any time using the setTerrainBlending method on a SplatModel instance:


// Disable terrain blending
splatModel.setTerrainBlending(false);

// Enable terrain blending with custom intensity and smoothness
splatModel.setTerrainBlending(true, {
  terrainDisplacement: 0.97,
  terrainSmoothness: 1.0,
});

The method accepts two arguments:

  • enabled: A boolean indicating whether terrain blending is active.
  • params: An optional TerrainBlendingParams object with the following properties:
    • terrainDisplacement: Controls the displacement factor and elevation alignment between the splat model and the terrain mesh.
    • terrainSmoothness: Controls the width and softness of the transition boundary between the splats and the underlying terrain surface.

Learn more

Check out the setTerrainBlending method in the MapTiler GeoSplats SDK reference to explore all available configuration options.

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.

How to enable the model camera collision

Model camera collision

Examples

Learn how to enable the model camera collision. Sets whether the camera movement is restricted by model.

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.

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.

Was this helpful?