Style layers

A StyleLayer draws the features of one source (and, for vector tiles, one source layer) in one way, chosen by a filter and colored by paint properties. It’s the same model as a layer in a MapLibre style.

Building layers in Rust

use mapterm::StyleLayer;
use serde_json::json;

StyleLayer::background("bg").color("#101418");

StyleLayer::fill("parks", "omt").source_layer("park").color("#1a3220");

StyleLayer::line("roads", "omt")
    .source_layer("transportation")
    .filter(json!(["in", ["get", "class"], ["literal", ["motorway", "trunk", "primary"]]]))
    .color(json!(["match", ["get", "class"], "motorway", "#eb6e3c", "#d2c36e"]))
    .min_zoom(6.0);

StyleLayer::symbol("towns", "omt")
    .source_layer("place")
    .filter(json!(["==", ["get", "class"], "town"]))
    .text(json!(["get", "name"]))
    .sort_key(json!(["get", "rank"]))
    .color("#dddddd");

StyleLayer::circle("stops", "transit").glyph("•").color("#ffcc00");

StyleLayer::raster("imagery", "esri");

Builder	Sets
source_layer(name)	The vector tile layer to draw
min_zoom(z), max_zoom(z)	Zoom range
filter(expr)	Which features to draw (try_filter returns an error instead of hiding the layer)
color(c)	The layer’s main color: fill-color, line-color, circle-color, text-color or background-color
opacity(o)	The matching *-opacity
text(t)	text-field: an expression or a "{name}" template
glyph(g)	mapterm:glyph: the character drawn at points
sort_key(k)	symbol-sort-key: lower values are placed first
paint(name, v), layout(name, v)	Any other property by its style-spec name

Every value can be a constant or an expression.

From style JSON

let (layer, warnings) = StyleLayer::from_json(&json!({
    "id": "water", "type": "fill", "source": "omt", "source-layer": "water",
    "paint": { "fill-color": "#16304a" }
}))?;

map.add_style_layers(&style_doc) adds every layer of a style document.

What each layer type uses

Type	Paint	Layout
background	background-color, background-opacity	visibility
fill	fill-color, fill-opacity, fill-outline-color	visibility
line	line-color, line-opacity, line-width, line-dasharray	visibility
circle	circle-color, circle-opacity	visibility, mapterm:glyph
symbol	text-color, text-opacity, icon-color, icon-opacity	visibility, text-field, text-font (bold, italic), text-transform, text-anchor, text-variable-anchor, text-offset, symbol-placement, symbol-spacing, symbol-sort-key, icon-image (as a glyph), mapterm:glyph
raster	raster-opacity (cell-color mode)	visibility

Fills become cell backgrounds and lines braille dots: one dot wide, two over 6 px and three over 14 px; line-dasharray draws them dotted. Line labels repeat every symbol-spacing (250 px, about 31 columns, by default); text-variable-anchor tries positions in order until one fits, and text-offset is in ems (about two columns wide, a row tall). Opacity is blended with whatever is underneath, since cells have no alpha. Bold and italic come from the font names in text-font ("Noto Sans Bold" is bold).

The mapterm:glyph extension

mapterm:glyph is the one property mapterm adds to the spec: the character drawn for a point. Circles draw ● by default; symbols draw the glyph before their text, like a map marker. Without it, a point’s icon-image becomes a one-cell symbol when mapterm knows the icon (✚ hospital, ✈ airport, ⋔ restaurant, …; see the icons module):

StyleLayer::symbol("pins", "sites").glyph("◆").text("{name}").color("cyan")

Labels never overlap

Markers and labels from every layer, style and custom, are placed together after the lines and fills are drawn, highest priority first, and a label that would overlap one already placed is dropped. Layer order sets priority (higher layers win) and symbol-sort-key orders labels within a layer.