Migrating from leaflet to glmap (For Humans & AI Agents)

Overview

🌱 ELI5 (3 Golden Rules to Switch from Leaflet)
Switching an existing R script or Shiny app from leaflet to glmap takes three simple habits:

1. Replace leaflet() |> addProviderTiles(…) with glmap(basemap = “dark”) (or “positron”).
2. Delete pal <- colorNumeric(…) and addLegend(…)—just pass color = ~column, palette = “viridis” directly into add_points() or add_polygons().
3. In Shiny, replace leafletOutput / renderLeaflet / leafletProxy with glmapOutput / renderGlmap / glmap_proxy.

⚙️ Technical Mode (API & Reactivity Mapping)
glmap was designed so that R users and AI coding agents familiar with leaflet can transition immediately while gaining 100x–500x faster C++17 binary serialization and 60 FPS WebGL2 GPU rendering. All functions use consistent snake_case, evaluate tidy/formula aesthetics (~expr) via C/R 256-entry RGB lookup tables, and emit leaflet-compatible Shiny input events (_click, _bounds, _zoom, _marker_click, _shape_click).

---

Complete Function-by-Function Mapping

leaflet Function	glmap Function	Key Parameter Differences
leaflet(data)	glmap(data, basemap = "dark")	Includes basemap out of the box ("dark", "positron", "voyager", "osm", "satellite")
addTiles() / addProviderTiles()	set_basemap("positron")	Or set basemap = directly in glmap()
addCircleMarkers() / addMarkers()	add_points()	lng $\rightarrow$lon, fillOpacity $\rightarrow$opacity, pass color = ~col, palette = "viridis" directly
addLabelOnlyMarkers()	add_labels()	label $\rightarrow$text
addPolylines()	add_lines()	weight $\rightarrow$width
addPolygons()	add_polygons()	fillColor $\rightarrow$fill_color, fillOpacity $\rightarrow$fill_opacity, color $\rightarrow$line_color, weight $\rightarrow$line_width
addRasterImage()	add_raster()	Streams raw Float32 values to GPU shader; supports hillshade = TRUE and live UI palette switching
addHeatmap() (leaflet.extras)	add_heatmap()	Built-in WebGL2 additive Gaussian kernel shader
(No built-in equivalent)	add_hexbin()	Built-in C++17 64-bit hexagonal spatial aggregation for 1M+ points
setView(lng, lat, zoom)	set_view(lng, lat, zoom, pitch, bearing)	Supports 3D camera pitch and bearing
flyTo(lng, lat, zoom)	fly_to(lng, lat, zoom, pitch, bearing)	Smooth WebGL camera animation
fitBounds(lng1, lat1, lng2, lat2)	fit_bounds(c(xmin, ymin, xmax, ymax))	Also accepts an sf or SpatRaster object directly
leafletOutput() / renderLeaflet()	glmapOutput() / renderGlmap()	Drop-in Shiny UI & Server replacements
leafletProxy()	glmap_proxy()	Supports clear_layer(), clear_layers(), set_layer_visibility(), set_layer_opacity(), set_raster_style(), set_filter()

---

Side-by-Side Migration Examples

Example 1: Polygons Colored by a Continuous Attribute

leaflet

library(leaflet)

pal <- colorNumeric("viridis", domain = nc$BIR74)

leaflet(nc) |>
  addProviderTiles(providers$CartoDB.Positron) |>
  addPolygons(
    fillColor = ~pal(BIR74),
    fillOpacity = 0.75,
    color = "#ffffff",
    weight = 1,
    popup = ~NAME
  ) |>
  addLegend("bottomright", pal = pal, values = ~BIR74, title = "Births 1974")

glmap

library(glmap)

glmap(nc, basemap = "positron") |>
  add_polygons(
    fill_color = ~BIR74,
    palette = "viridis",
    fill_opacity = 0.75,
    line_color = "#ffffff",
    line_width = 1,
    popup = ~NAME
  )

---

Example 2: terra::SpatRaster with Live Interactive Shader Controls

leaflet

# Projects and renders a static PNG in R on the CPU; changing colors requires re-running R
pal <- colorNumeric("terrain", values(dem), na.color = "transparent")
leaflet() |>
  addTiles() |>
  addRasterImage(dem, colors = pal, opacity = 0.8)

glmap

# Uploads raw Float32 values to GPU texture; user can switch palettes & toggle hillshade at 0ms in browser
glmap(basemap = "dark") |>
  add_raster(dem, palette = "terrain", hillshade = TRUE, opacity = 0.8)