keplergl / keplergl/kepler.gl

[Bug] 3D map with terrain jitters when moving around

Open
#3,394 6 comments 0 reactions 1 assignee Claimed by @igorDykhta View on GitHub
bug
Dominant language
TypeScript
Stars
12k
Forks
2k
Avg merge
1d 5h
Merged PRs (30d)
66

Description

**Describe the bug**
After adding terrain to a maplibre map in 3d mode, the map camera elevation changes during movement, seemingly following terrain elevation.
This bug was observed and resolved over at `react-map-gl` at v8 (see https://github.com/visgl/react-map-gl/issues/2211) while Kepler is currently using v7.
The weird thing is when I tested the bug with `react-map-gl` directly, I was only able to reproduce it with `react-map-gl` v7 + `maplibre-gl-js` v2.
Kepler is currently dependent on MaplibreGL 3.6.2, which according to my tests should only jitter on "moveend".
I'll summarize the versions and bug behavior:
| `react-map-gl` | `maplibre-gl-js` | Bug behavior |
| --- | --- | --- |
| 8.1.1 | 4.7.1 | no issue |
| 8.1.1 | 2.4.0 / 3.6.2 | no issue |
| 7.1.6 | 3.6.2 | jitter on moveend |
| 7.1.6 | 2.4.0 | jitter during move |

**To Reproduce**
Move the map to somewhere with a lot of mountains then move around.

I've created a minimal repo to reproduce this issue with Kepler: https://github.com/leverglowh/keplergl-terrain-jitter
Steps are the usual: `git clone`, `npm install`, add `.env` file, `npm run dev` (starts at port `5668`)
Only relevant code is in `/src/App.tsx`.

---

To test `react-map-gl` with `maplibre-gl-js` all I did was:
1. clone https://github.com/visgl/react-map-gl/tree/master/examples/get-started/maplibre
2. pin versions in `package.json`. Note: import path changes between v8 and v7, see [import changes](https://github.com/visgl/react-map-gl/blob/master/docs/upgrade-guide.md)
3. update `app.jsx` to include terrain: update line 17 to be:
```jsx
mapStyle = {{
version: 8,
sources: {
osm: {
type: "raster",
tiles: ["https://a.tile.openstreetmap.org/{z}/{x}/{y}.png"],
tileSize: 256,
attribution: "© OpenStreetMap Contributors",
maxzoom: 19,
},
terrain: {
type: "raster-dem",
url: "https://tiles.mapterhorn.com/tilejson.json",
},
hillshadeSource: {
type: "raster-dem",
url: "https://tiles.mapterhorn.com/tilejson.json",
},
},
layers: [
{
id: "osm",
type: "raster",
source: "osm",
},
{
id: "hillshade",
type: "hillshade",
source: "hillshadeSource",
layout: { visibility: "visible" },
paint: { "hillshade-shadow-color": "#473B24" },
},
],
terrain: {
source: "terrain",
exaggeration: 1.5,
},
sky: {},
}}
```
4. `npm install`
5. `npm run start`

**Expected behavior**
Given the current dependencies, I would expect Kepler's map to jitter on moveend, and not during move.
Would be nice if it didn't jitter at all.

Would also be nice if we could upgrade to `react-map-gl` v8, but that requires some work since export paths and types changed.

**Screenshots**

https://github.com/user-attachments/assets/9737eb0c-8289-4c9e-aa64-8f116a1abd78

**Desktop (please complete the following information):**
- OS: both macOS and Windows
- Browser: chrome, safari, firefox
- Version: tested from 3.2.0 to latest 3.2.6, didn't try earlier versions

**Additional context**
I'll link some resources I bumped into while investigating this:
- Maplibre GL exposes a callback called `transformCameraUpdate` that could potentially let you override the elevation (I think, it didn't work for me) https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#transformcameraupdate
- Maplibre GL (only since v5) introduced a method `setCenterClampedToGround` https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#setcenterclampedtoground
- Maplibre jitter on low map pitch (https://github.com/maplibre/maplibre-gl-js/issues/7025): not the case of this issue, but with the introduction of `maxPitch` option it could be

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.