Skip to main content

Extending Massif

The CartoCSS project is meant to be a base. A child project extends it and restates only what it changes, so a new Massif release is picked up by replacing the base files and leaving yours alone. Both CartoCSS flavours (plain and icon font) take a child; the compiled ones do not, since they carry no CartoCSS any more — compile your child instead (massif-style css2xml mine.json mine.xml, style CLI).

A child is a <name>.json beside project.json, loaded like a variant (name: 'mine'):

{
"extends": "./project.json",
"styles": ["mine-colors.mss", "variables.mss", "style.mss", "mine-rules.mss"],
"styleparameters": {
"variant": { "default": "streets", "values": { "streets": "streets", "outdoor": "outdoor", "topo": "topo", "hybrid": "hybrid", "eink": "eink" } },
"poiStyle": { "default": "plain", "values": { "badge": "badge", "plain": "plain" } },
"track_min_zoom": 13
}
}

Four things it can do:

  • Colours and fonts — a stylesheet listed before variables.mss redeclares a variable: @motorway, @water, @wood, @font_medium... The compiler keeps the first declaration of a variable, so yours wins. The names are listed in variables.mss.

  • Rules — a stylesheet listed after style.mss adds rules. A new attachment (#landcover[class = 'wood']::mine_pattern { … }) draws with its layer, over the base, without touching it.

  • Road widths — variables.mss also declares each road class's fill width, ramped over zoom as the road rules have it (the road_osm_low look included): @road_width_motorway, _trunk, _primary, _secondary, _tertiary, _minor, _service. A rule of yours takes one to draw around the road without copying its numbers; this one is a band right outside a primary road's fill, over its casing:

    #transportation[zoom >= 12][class = 'primary']::mine_band {
    line-color: #d33; line-width: 3; line-gap-width: @road_width_primary;
    }

    The casing width is not a variable: it depends on the variant (e-ink outlines the major roads from z8, the others from z14). The base's own rules inline their widths: redeclaring a @road_width_* moves your rules, not Massif's roads.

  • Defaults — styleparameters merge key by key: set a parameter's default, or declare a new one for your own rules. table.key sets one entry of a table (poi-fill.cafe) and keeps the rest. styles does not merge; it is restated whole.

A layer is replaced by moving the base one out of reach through its parameter and drawing your own: track_min_zoom: 24 hides Massif's tracks, a rule after style.mss draws them your way. POIs are one template, %poi, drawn into one attachment, ::poi, so a child widens a class — draws it where the base's rank ladder does not yet — or narrows one, with a rule of its own:

#poi[zoom >= 15][class = 'bakery']::poi {
@extend %poi;
shield-placement-priority: (30000000 + ((((get([param::poi-boost], [subclass])) ?? (0)) != 0) ? ((get([param::poi-boost], [subclass])) ?? (0)) : ((get([param::poi-boost], [class])) ?? (0))));
}
#poi[zoom < 17][class = 'pharmacy']::poi { display: none; }

The term after 30000000 is the one every base POI rule adds, so an app's poi-boost.<class> still reaches a rule that states its own priority. To only re-rank a class, set poi-boost.<class> instead of writing a rule (style README).

The bus and tram stops' zooms are project constants, moved with no rule at all:

"constants": { "poi_bus_minzoom": 15, "poi_bus_label_minzoom": 16, "poi_tram_minzoom": 16,
"poi_tram_label_minzoom": 16, "poi_pt_shelter_minzoom": 15 }

So are the rank ladder's: poi_rank10_minzoom (14), poi_rank30_minzoom (15), poi_rank30_label_minzoom (16), poi_rank70_minzoom (16), poi_rank_all_minzoom (17).

How the template, the attachment and display compile: CartoCSS templates.

POI icons resolve by name: the POI's subclass, else its class, else default (a small bare dot). Each name is an entry of the glyph table, so a child adds an icon in its styleparameters as glyph.<name> (merged into the base table) and the POIs of that class or subclass draw it, on the disc of their category:

"styleparameters": { "glyph.sports_centre": "mine/sports_centre.png" }

In the sprite flavour the value is a file: the glyph as a distance field, which is what the style tints, as the converter cuts icons-glyph/*.png out of a sprite (massif-style mapbox2css over a style whose sprite carries your drawing writes one). In the icon-font flavour it is the glyph's character in MassifIcons. A class with no icon waits for z17 under the rank ladder; one that gets an icon this way is drawn from its rank's zoom, as the base's own classes are.

A rule extending %poi draws a POI with Massif's look whatever selects it: colours, disc and halo are tables read by the POI's subclass, then its shelter_type, then its class, so a viewpoint brought in early is bare and green and a walker's shelter a green badge. They are editable like any palette: poi-icon-background-fill-subclass-viewpoint, poi-icon-background-fill-shelter_type-basic_hut, …

The OpenStreetMap example​

osm.json ships in both CartoCSS flavours: Massif re-skinned with OpenStreetMap Carto's colours, as Alpimaps' OSM style has them. Load it as name: 'osm'. Its three files:

  • osm-colors.mss (before variables.mss) — the palette redeclared: OSM Carto's road colours, some ramped over zoom as OSM Carto ramps them (a variable may hold an expression: @primary: linear([view::zoom], (11, #f3ba5c), (12, #fcd6a4));), its water, woods, landuse and buildings.
  • osm-rules.mss (after style.mss) — what the palette cannot say: tracks as a brown line under white dashes by tracktype, OSM Carto's textures over woods, scrub, wetland and rock, and the POIs above (bakeries early, pharmacies late).
  • osm.json — the defaults: POIs as bare glyphs (poiStyle: plain), Massif's tracks out of reach (track_min_zoom: 24), roads outlined and widened at low zoom as OSM Carto does (road_osm_low: 1), tunnels plain until z13 (tunnel_min_zoom: 13), bus stops from z15, named from z16, and public-transport shelters from z15 (constants).

custom.json is the smaller example: two colours, one rule, a new parameter.

Two limits. A variable names a value: two palette entries with the same colour share one name, and redeclaring it changes both. And a child changes the CartoCSS only.

The MapLibre side​

MapLibre has no child styles. The MapLibre variants are generated by styles/massif/build.py from a Python palette and layer modules: a MapLibre variant of your own is a fork of that folder — edit palette.py, run python3 build.py — or a JSON patch over a published style.