Layers

Loading terrain…

Terrain, elevation contours and country borders share one map. Layers form an ordered list; geometry also uses depth testing.

Add, move, remove

const id = map.addLayer({ type: "line", source: borders, color: "#ff9e64" });
map.moveLayer(id);              // move to the end
map.removeLayer(id);

Every layer accepts an optional id. addLayer(layer, beforeId) inserts before another layer; moveLayer(id, beforeId) reorders it.

Type	Data / key options
background	color, density; no source
raster	Elevation tile or provider; classifier, colors
contour	Field or elevation provider; levels, labels
line	Vector lines; color, colorProperty, colors, padCells, filterAtResolution, simplify, sharedArcs
fill	Vector polygons; color, colorProperty, colors, drape
fill-extrusion	Vector buildings; heightProperty, height, heightScale
symbol	DOM text labels; textProperty, priorityProperty
circle	Stamped glyph discs sized in CSS pixels; radius, radiusProperty, radiusScale, color
glyph	Points and labels in copied text; size, ramp, textProperty
heatmap	Density relief; radius, weightProperty, colors, bounds, height, threshold
model	Your polygons and attribution; no source

Sources

const cities = {
  features: [{
    geometryType: "point" as const,
    rings: [[[-58.38, -34.6]]],
    properties: { name: "Buenos Aires" },
  }],
};
map.addLayer({ type: "glyph", source: cities, textProperty: "name", color: "#ff9e64" });

Vector layers accept a GlyphMapVectorFeatureCollection or GlyphMapVectorProvider. Static features use geometryType ("point", "line", "polygon") and rings; polygon hole groups use polygons. Add attribution to the collection to include its credits.

Provider layers can select sourceLayer; all vector layers accept filter: (feature) => boolean, applied after source-layer selection. Without terrain or a custom groundElevation, features sit on the datum.

Raster

map.addLayer({
  type: "raster", source: reliefProvider,
  classifier: GlyphMapClassifiers.etopo1V1, colors: terrainColors,
  minElevation: 0, density: 2,
});

colors supplies one colour per classifier band. Optional minElevation / maxElevation flatten terrain outside a metre window; colours retain the original elevations. padCells keeps nearby provider tiles mounted. See terrain.

Contour

map.addLayer({
  type: "contour", source: reliefProvider,
  levels: { interval: 500 }, minElevation: 0,
  color: "#ffe8b8", labels: true, labelEvery: 5,
});

levels accepts a count, an explicit elevation array, or { interval } in metres. Intervals stay fixed while panning. Elevation windows clip contours independently of terrain; match their floors. generalize is a smoothing radius in output cells: the field is smoothed at about that radius before the levels are cut and closed rings smaller than it are dropped, so a line keeps the bends a reader can see and loses per-sample jitter. It follows the zoom in half-octave steps, so zooming in brings detail back; omitted or 0 cuts the native grid. Labels default off; labelEvery defaults to 5. getContourFieldRange(id) reports the data range.

Fill

map.addLayer({ type: "fill", source: regions, color: "#4a5a3a", drape: "flat" });

drape: "surface" (default) follows terrain; "flat" keeps a datum overlay. A predicate can choose per feature. For OSM water, use glyphMapOpenMapTilesWaterDrape: ocean flat, lakes draped. colorProperty plus colors maps property values to colours.

Fill-extrusion

map.addLayer({
  type: "fill-extrusion", source: osm, sourceLayer: "building",
  heightProperty: "render_height", baseOffsetProperty: "render_min_height",
  height: 8, heightScale: 1, color: "#8a8f9c",
  colorVariation: 0.5, facade: true,
});

Heights and base offsets are true metres above terrain, exempt from terrain exaggeration. height is the fallback; heightScale multiplies height. facade and colorVariation default off. See a live street view.

outline: "braille" opts into braille roof rings and, when tilted, vertical corner edges at the mesh’s planted base and roof heights. The body uses . so edges carry the shape. Only footprints spanning at least two projected cells get outlines; the cutoff follows zoom and output density. Scene depth and exact building planes hide occluded edges, while incident faces accept their own edge without a depth bias. All glyphs fit the universal atlas. Omitted preserves the original output. Building outlines currently support braille only.

Add fill: false alongside outline: "braille" for outlines only: no building mesh is mounted or rasterized. Terrain and nearer building faces still hide roof rings and vertical corners. fill defaults to true and is ignored without braille outlines.

Add blank: true with unfilled braille outlines to erase rear raster content inside the visible building faces. Face depth preserves nearer terrain, elevated roads and other nearer meshes; courtyards stay open. This skips lighting and solid glyph shading and reuses the outline pass’s projected faces. The default is false, preserving the see-through outline output. Tiny faces still blank covered cells even when their footprint is too small for an outline. DOM symbol labels remain overlays and are not erased by this cell mask.

For OpenMapTiles, pass buildingOutline: "braille" to glyphMapOpenMapTilesLayers. The /maps workbench and its code export draw braille lines and blanked outlines without fill for buildings by default; ?lines=box switches to box lines with the normal building fill.

Labels and point marks

map.addLayer({
  type: "symbol", source: cities, textProperty: "name",
  textAnchor: "left", textOffset: [1, 0], color: "#ffe8b8",
});

• symbol labels points and lines, not polygons; text(feature) composes labels.
• priorityProperty / minPriority control decluttering; labels wrap at 20 characters, up to three lines.
• textAnchor defaults to "center"; textOffset defaults to [0, 0], in cells with y down.
• glyph uses size / sizeProperty / sizeScale in cell rows; default size: 0 is one cell, with ramp ["·", "•", "●"].
• Glyph altitude / altitudeProperty / altitudeScale use true metres above ground; onSelect(feature) handles selection.
• Use symbol for DOM interaction; glyph and circle marks are stamped into the copied text.
• circle is the same stamp as glyph, sized in CSS pixels instead of cell rows: radius / radiusProperty * radiusScale are divided by the grid’s cell height to get the disc radius in cell rows, and a radius under half a row becomes the single smallest mark (·). Features sharing a cell merge into one mark. color tints the mark; omitted keeps the terrain’s colour. There is no element per circle, and no density, ramp, altitude, label or onSelect; use glyph for those.

Line detail at low zoom

Line layers can opt into simplify: "vw". It reuses the bake pipeline’s latitude-corrected Visvalingam–Whyatt simplifier, with a tolerance of half the current output cell’s degrees (view.span / cols, adjusted for layer density). Quarter-octave zoom buckets cache each source line, so orbiting does not repeat simplification. Zooming in retains finer source detail. Endpoints stay fixed; closed rings that would collapse below a triangle retain their source geometry. Walking retains full source detail.

sharedArcs: true also reconstructs polygon boundary topology per source feature set or tile: exact shared edges (in either direction) become one arc, split at junctions before VW. Junction endpoints stay fixed, and the arc geometry and zoom buckets are cached. Explicit line features keep their own paths. Differently sampled edges are not snapped together; bake shared arcs before tile clipping when source tiles need consistent simplification.

The experimental experimentalGlyphStrategy: "box" joins accepted paths in one graph per layer and frame, including coincident feature/tile endpoints. Diagonal steps add one staircase corner using the same depth and ownership tests; when both corners are blocked, both cells point into the hidden corner instead. Immediate backtracks collapse before joining. A closed ring whose projected extent is under two cells becomes one depth-tested · at its geometry centroid. Open lines retain their joined cells, including short stubs; unjoined cells restore the surface instead of leaving dots. Box depth tests read the surface before the layer wrote any ink; staircase corners cannot borrow cells from a separate path.

Omitting these options leaves the default output unchanged. The /maps borders enable live VW and shared arcs, and its OpenStreetMap line rows enable VW; only boundaries request shared polygon arcs. The page draws its lines in braille by default; ?lines=box opts into box for comparison.

Lines accept colorProperty and colors with the same per-feature fallback as fills. filterAtResolution(feature, degreesPerCell) can make a live resolution cut after filter; it receives the actual overlay cell size and 0 while walking. A shared polygon arc carries the properties every polygon contributing to it agrees on, so a border between two polygons of one class keeps its colour and a border between two classes falls back to the layer color; explicit line features retain their own.

Per-layer appearance

Option	Applies to	Effect
density	All layers	Mesh detail; strokes at 1 or omitted follow the surface grid, other values use an independent grid
renderMode	Mesh layers	Override scene mode; a different mode costs an extra pass
glyphPalette	Mesh layers	Override the character ramp independently of colours; a different ramp costs an extra pass

Mesh layers are raster, fill, fill-extrusion, heatmap, and model.

Markers

const marker = map.addMarker({ at: [-58.38, -34.6], label: "Buenos Aires", elevation: 30 });
marker.remove();

Markers are individual DOM elements, separate from layers. marker.el exposes the element. elevation defaults to 0, passes through the projection’s elevation axis, and does not automatically follow terrain.