Expose core to plugins via engine-agnostic `map:*` APIs by BhattaraiSijan · Pull Request #75 · NASA-IMPACT/MMGIS

BhattaraiSijan · 2026-04-23T15:32:51Z

Main change

Prepare the core to listen to plugins through the mmgisAPI Event Bus. New providers and emits are registered in Map_.js and routed through Map_.engine.* so Leaflet and deck.gl behave identically.

API	Purpose
`addOverlay` / `removeOverlay` / `clearOverlays`	Ephemeral GeoJSON overlays (not persisted, not in Layers tool)
`setBasemap` / `getBasemap` / `getBasemapStyles`	Runtime basemap switching
`zoomIn` / `zoomOut`	Camera stepping
`on('map:click' \| 'map:mousemove', h)`	Pointer events. Payload: `{lat, lng, latlng, containerPoint?}`

src/essence/Ancillary/BasemapSwitcher.js (jQuery UI) is removed.

Adapter changes

DeckGLAdapter.setBasemapStyle() — didn't exist; added for parity.
DeckGLAdapter._emitClick / _emitMouseMove — deck.gl's onClick / onHover only invoked internal feature handlers, so on('click' | 'mousemove', …) subscribers never fired. Added bridges normalizing PickingInfo to the same shape LeafletAdapter._normalizeEvent emits (including latlng so legacy consumers like Ancillary/Coordinates.js work unchanged on deck.gl).
DeckGLHelpers case 'vector' — deck.gl accepted only its native style keys (strokeColor/strokeWidth as RGBA). Leaflet's adapter accepts Leaflet's native vocab (color/weight/fillColor as CSS) directly. Made both adapters accept the same style dictionary via a _toRgba parser and Leaflet→deck.gl key aliases (deck.gl-native wins when both given). Also fixed a latent bug — deck.gl's default point radius is in meters, sub-pixel at typical zooms — via getPointRadius + pointRadiusUnits: 'pixels'.

Leaflet basemap via native `L.tileLayer`

The Leaflet engine now supports msv.basemap.provider = 'mapbox' | 'maplibre' (previously deck.gl-only). An earlier iteration mounted a MapLibre/Mapbox GL Map behind a transparent Leaflet with event-based camera sync — two render loops and a 256-vs-512 tile-size mismatch caused overlay drift and mis-projected clicks (tools recording coordinates saved wrong data).

Replaced with native L.tileLayer. _resolveBasemapTileSpec translates mapbox://styles/... → Mapbox Static Tiles API, raw {z}/{x}/{y} templates → passthrough, anything else → OSM fallback. One render loop, one projection.

Other

minZoom: 1 on Mapbox tile layers. Mapbox's 512-sized Static Tiles + zoomOffset: -1 means Leaflet zoom 0 resolves to URL zoom -1, which doesn't exist. Map minZoom bumped to match.
_resolveBasemapStyles(config, engineType) returns engine-appropriate defaults — Leaflet gets raster templates, deck.gl gets MapLibre vector style.json URLs. Same user-facing names on both (Streets / Light / Dark; Leaflet adds Terrain).
'none' added to BasemapProvider union, removing a pre-existing as any.
NewMissionModal + tab-ui-config updated to surface the basemap option for Leaflet missions.

Test plan

Until the companion plugin PR lands, exercise the APIs from the browser console on a running mission via window.mmgisAPI.*. For example:

await window.mmgisAPI.addOverlay({
    id: 'sanity',
    geojson: { type: 'Feature', geometry: { type: 'LineString', coordinates: [[-74, 40], [-73, 41]] } },
    style: { color: '#1a73e8', weight: 3 },
})

Verify on each matrix cell (Leaflet + Mapbox, Leaflet + MapLibre, deck.gl + Mapbox, deck.gl + MapLibre):

Overlay renders as a visible 3px blue line.
setBasemap(name) swaps styles; zoomIn / zoomOut step and clamp.
on('map:click' | 'map:mousemove', …) fires with {lat, lng, latlng, containerPoint}.
removeOverlay / clearOverlays remove cleanly.

dzole0311 · 2026-04-27T13:36:28Z

+                    tileSize: 512,
+                    zoomOffset: -1,
+                    minZoom: 1,
+                    attribution: '© Mapbox © OpenStreetMap',


Would it make sense to extract these into shared constants/defaults? Mainly to avoid scattering hardcoded values (tileSize, zoomOffset, attribution strings) and magic numbers/strings

That makes sense @dzole0311 . Thanks.
For now, I just added those constants in the helper and imported them in the adapter.
We should discuss about maybe storing all such engine specific constants to some engine specific configuration files.

dzole0311 · 2026-04-27T13:39:15Z

+    setBasemapStyle(styleUrl: string): void {
+        if (!this._map) return
+        const spec = this._resolveBasemapTileSpec({
+            provider: this._inferProvider(styleUrl),


Is provider actually used here? From this flow it looks like the resolution is done by styleUrl alone so wondering if provider is redundant

Yes, it is redundant here. Thanks @dzole0311 .

As leaflet adapter does not actually spin up mapbox-gl or maplibre-gl based on provider, instead leafletadapter just uses L.tileLayer for both, I just ommitted the provider from the type setBasemapStyle

…-IMPACT/MMGIS into feat/add-basemap-to-leaflet

sandesh-sp · 2026-05-06T19:32:39Z


    const config = {
      msv: {
+        view: [39, -98, 4],


Should this view be hard coded? This is not limited to earth so doesn't make sense to have it center on USA.
Also, I created new mission and it is still initializing to 0, 0, 0 so this might not be working as intended.

sandesh-sp · 2026-05-06T20:06:16Z

          "field": "msv.basemap.provider",
          "name": "Provider",
-          "description": "Renders a vector-tile basemap beneath deck.gl layers using MapboxOverlay. Has no effect on Leaflet-engine missions. 'maplibre' is open-source and requires no token. 'mapbox' requires an access token.",
+          "description": "Renders a vector-tile basemap beneath map layers using MapLibre or Mapbox GL. Works with both Leaflet and deck.gl engine missions. 'maplibre' is open-source and requires no token. 'mapbox' requires an access token.",


Do we need to mention that it works with both Leaflet and deck.gl? Might make more sense to only specify if something is engine specific or UI specific

sandesh-sp · 2026-05-06T20:17:57Z

+    ]
+
+    const mapboxDefaults = MAPBOX_DEFAULTS
+    const maplibreDefaults = isLeaflet ? MAPLIBRE_DEFAULTS_LEAFLET : MAPLIBRE_DEFAULTS_DECKGL


Is it safe to assume we'll only have leaflet or deckgl? or should we add explicit checks?

sandesh-sp · 2026-05-06T20:24:20Z

+        { name: 'Light', style: 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png' },
+        { name: 'Dark', style: 'https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png' },
+        { name: 'Terrain', style: 'https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png' },
+    ]


Should these styles be hardcoded? Might be difficult to change/update things in future.

There might be the case where different style might need different access tokens

sandesh-sp · 2026-05-06T20:30:19Z

+            ? [...basemapConfig.styles]
+            : basemapConfig.provider === 'mapbox'
+                ? [...mapboxDefaults]
+                : [...maplibreDefaults]


If I understand the logic correctly, it'll use the styles from mission config and fall back to default values if basemap isn't provided.
If that's the case, we need a way to provide multiple styles in the mission config page and a field to mark default style.
One potential issue might be when we have something other than earth. Right now, leaflet doesn't render any basemap so user can just add other planet/satellite as tile layer. This need not be addressed right away but should be a simple fix.

I might have found out the root of confusion, there's basemapConfig.styles to store all the styles and basemapConfig.style to store current style. I believe there might be better way to handle this.
One potential drawback will be the need to update both .style and .styles if there's change in name resulting in inconsistency.

sandesh-sp · 2026-05-07T15:05:08Z

+                    Map_.engine.setZoom(next)
+                    return true
+                }),
+                window.mmgisAPI.provide('map:addOverlay', ({ id, geojson, style } = {}) => {


Is the geojson already validated before being passed here?

sandesh-sp · 2026-05-07T15:09:18Z

+                    return true
+                }),
+                window.mmgisAPI.provide('map:removeOverlay', (id) => {
+                    if (!Map_.engine || !_overlayIds.has(id)) return false


will it be helpful if we log error (here and all other functions) when the action fails?

sandesh-sp · 2026-05-07T15:15:42Z

+ * on top of a MapLibre/Mapbox GL basemap.
+ *
+ * **Leaflet**: Creates a MapLibre/Mapbox GL map behind a transparent Leaflet canvas
+ * and synchronises pan/zoom events so the basemap and Leaflet layers stay aligned.


Have we not scrapped this idea and instead decided on having basemap as one of the layer in leaflet?

sandesh-sp · 2026-05-07T15:18:35Z

+     * Optional vector-tile basemap to render beneath map layers.
+     *
+     * - **deck.gl**: renders via `MapboxOverlay` (overlay mode).
+     * - **Leaflet**: renders a MapLibre/Mapbox GL map behind a transparent Leaflet canvas.


same as above, will we have mapbox beneath leaflet or will we use a raster layer as basemap?

sandesh-sp · 2026-05-07T15:34:13Z

 *
 * @throws {Error} If `options.type` is not a supported layer type.
 */
+function _toRgba(


I don't see this being used anywhere

This is not specific to deck.gl so even if this is needed, it can be moved from DeckGLHelpers to some place generic

The comment above this function is for buildDeckLayer and should be moved

sandesh-sp · 2026-05-07T16:00:51Z

+        }
+    }
+
+    setBasemapStyle(styleUrl: string): void {


Do we need to respect basemap's minZoom setting when making the switch?

sandesh-sp · 2026-05-07T16:02:08Z

+    // BASEMAP TILE LAYER METHODS
+    // ========================================
+
+    private _initBasemapTileLayer(basemap: BasemapOptions): void {


Can this call setBasemapStyle for setting the style? I can see quite a bit of overlap between the two

BhattaraiSijan added 16 commits April 14, 2026 12:14

leaflet basemap rendering

2718d32

basemap style switcher fixed

524ff46

basemap switcher APIs setup

4616a20

zoom apis added

b6b2837

APIs for measure tool

0694875

route overlay + click APIs through engine adapter

54bb007

basemap as tilelayer

b7f2934

fix:style urls in maplibre

319533b

changing style urls

7ffc66f

maplibre dark style change

cd67ceb

fix:min zoom set in mapbox leaflet

036be3d

mouseover event emit, for draw

dda2fe9

fix(deck.gl): normalize Leaflet-style keys in vector layers

a3b1a3d

fix(deck.gl): include latlng in normalized pointer events

cbc4536

clean up

ae72021

revert: drop default pointToLayer from vector layer builder

2eb8c4e

BhattaraiSijan requested review from dzole0311, sandesh-sp and slesaad April 23, 2026 15:32

dzole0311 reviewed Apr 27, 2026

View reviewed changes

BhattaraiSijan added 5 commits April 28, 2026 10:07

extract Mapbox/OSM tile defaults into LeafletHelpers constants

748c51b

Merge branch 'development' into feat/add-basemap-to-leaflet

0f23b30

refactor(LeafletAdapter): remove redundant basemap provider inference

51485e0

Merge branch 'feat/add-basemap-to-leaflet' of https://github.com/NASA…

1a21746

…-IMPACT/MMGIS into feat/add-basemap-to-leaflet

fix(Configure): remove empty props destructuring in NewMissionModal

5fd1d93

sandesh-sp reviewed May 6, 2026

View reviewed changes

sandesh-sp reviewed May 7, 2026

View reviewed changes

sandesh-sp requested changes May 7, 2026

View reviewed changes

sandesh-sp reviewed May 7, 2026

View reviewed changes

Conversation

BhattaraiSijan commented Apr 23, 2026

Main change

Adapter changes

Leaflet basemap via native L.tileLayer

Other

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sandesh-sp May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sandesh-sp May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Leaflet basemap via native `L.tileLayer`

sandesh-sp May 6, 2026 •

edited

Loading

sandesh-sp May 6, 2026 •

edited

Loading