Skip to main content

Massif with the SDK

The SDK takes Massif as a CartoCSS project: one set of rules for all five variants, the variant being a style parameter like the others. Get a flavour from npm (@massif-maps/styles) or from a massif-styles-v* release; what the four CartoCSS flavours are and which to pick: Massif.

Load it​

Ship the flavour's folder (or its zip) in the app's assets, and name the variant as the style:

map.addLayer('basemap', {
    type: 'vector',
    source: { type: 'http', url: 'https://tiles.openfreemap.org/planet/{z}/{x}/{y}.pbf', maxZoom: 14 },
    style: {
        type: 'mbvt',
        // cartocss/ or cartocss-iconfont/: <name>.json; the compiled flavours: <name>.xml
        project: { type: 'project', assets: { type: 'dir', path: 'styles/massif' }, name: 'outdoor' },
    },
});

The same spec from Kotlin, Swift and the web: your first map. A zip works as it is: assets: { type: 'zip', data: … } (asset packages). With the object API it is a CompiledStyleSet(assetPackage, "outdoor") handed to an MBVectorTileDecoder.

name is streets, outdoor, topo, hybrid or eink, or osm / custom for the two extension examples. A variant is project.json plus that one parameter, so switching variants live is a parameter change, not a reload:

decoder.setStyleParameter("variant", "eink");   // object API: the MBVectorTileDecoder
style.set("params.variant", "eink");            // surface API: the layer's `style` object

Style parameters​

The full list, with defaults, is in the style's README. The ones an app usually sets:

ParameterDefaultWhat
variantstreetswhich of the five maps
poiStylebadgeplain: POI glyphs without their disc
poi-boost-<class>0added to that POI class's placement priority: 100000 = one layer, negative demotes
buildings20 none, 1 flat footprints at every zoom, 2 footprints then 3D blocks from z15
building_opacity1the 3D buildings' alpha looking straight down
track_min_zoom, path_min_zoom12where tracks, paths and trails appear
highlight_drinking_water0water points larger and placed first
sac_scale_labels0 (1 on e-ink)the T1..T6 grade along each trail
road_osm_low0major roads drawn as OSM Carto draws them at low zoom
lighting1 (0 on e-ink)0 draws every colour flat, lit by no hour

A colour-only change repaints without decoding a tile again: live style parameters.

Legend​

Every CartoCSS flavour ships legend.json. getLegend("") resolves it against the live parameters, so the swatches follow the variant: legends.

Relief, imagery and the optional archives​

  • Relief and contours (every variant): the project lists a hillshade slot under the contour lines and a contour layer at three depths (lines, index lines, labels among the names). A composite layer fills them from the app's own DEM, so a variant draws relief only where the app attaches it - the examples do for outdoor and topo:

    const base = map.addLayer('basemap', { type: 'composite-vector', source: vectorTiles, style: 'massif' });
    const dem = map.source('dem', { type: 'http', url: 'https://tiles.mapterhorn.com/{z}/{x}/{y}.webp',
                                    maxZoom: 16, metaData: { dem_encoding: 'terrarium' } });
    const contours = map.source('contours', { type: 'contour', source: 'dem', baseInterval: 20 });
    base.call('addExternalDataSource', 'hillshade', dem.handle, 1); // HILLSHADE
    base.call('addExternalDataSource', 'contour', contours.handle, 2);           // VECTOR

    The #hillshade rule carries the values Massif was tuned with (exaggeration 0.35, 0.5 in topo, opacity 0.55, gone by z16).

  • Imagery (hybrid): a raster layer under the vector layer; the style's background is transparent for that variant.

  • Bathymetry and low-zoom landcover (bathymap, all variants): merge the archive into the main tiles with a "merged-mbvt" source. Past its max zoom (z6) the archive is cut into the requested tile, so it reaches the z7.8-8 handover to OpenMapTiles' own landcover.

    source: { type: 'merged-mbvt', source: { type: 'mbtiles', path: 'region.mbtiles' },
              source2: { type: 'mbtiles', path: 'bathymap.mbtiles' } }

  • Routes (outdoor, topo): their own datasource in the route slot, the same way. Contours may also come from a tileset rather than the device (contours). The tile schema each expects: Massif with MapLibre.

Fonts​

The CartoCSS flavours name font roles (regular, medium, bold, italic) and ship no font: the SDK draws them with the device's fonts. The icon-font flavours ship fonts/MassifIcons.ttf, found by the decoder in the project's fonts/ folder.