LuciadRIA can load and visualize Mapbox Vector Tiles (MVT), both when they’re served using TileJSON and when they’re packaged as a single PMTiles archive.

Working with Mapbox Vector Tiles, MBTiles, TileJSON and PMTiles

Mapbox Vector Tiles is a compact binary format for a single map tile’s vector geometry and attributes, following the Mapbox Vector Tile Specification v2.1. It consists of the data that LuciadRIA decodes and renders as tileset features. For its visualization, you point to a Mapbox GL style, which decides how the features in those tiles are painted, following the Mapbox style specification.

MVT clients can get Mapbox Vector Tiles in different ways:

  • From an MBTiles service through TileJSON: LuciadRIA reads TileJSON 3.0 descriptors: a small JSON file that points the client to a set of tiles through a {z}/{x}/{y} URL template, and carries metadata such as the zoom range, the data bounds, and the list of vector layers.

    This is the typical way in which an MBTiles dataset is served: MBTiles itself is a SQLite container that bundles the tiles. A tile server, such as LuciadFusion, exposes its contents through a TileJSON descriptor and per-tile URLs.

  • As a PMTiles file: LuciadRIA reads PMTiles v3 archives containing MVT tiles; a single-file, cloud-optimized archive packs all tiles and an index into one .pmtiles file. The client reads it directly over HTTP range requests, so no tile server is needed. Raster PMTiles archives aren’t supported.

LuciadRIA reads the data from both sources through the same MapboxVectorTileSetModel: MapboxVectorTileSetModel.createFromURL treats a .pmtiles URL as a PMTiles archive, and any other URL as a TileJSON descriptor. The steps in Visualizing the tiles apply to both.

Visualizing the tiles

Visualizing Mapbox Vector Tiles on a map requires three steps:

  1. Create a MapboxVectorTileSetModel from a TileJSON descriptor or a PMTiles archive.

  2. Create a MapboxStyle from a Mapbox GL style. The style decides how the vector tiles are painted.

  3. Use a MapboxVectorTileSetLayer to visualize the model with the style. 

// Create a model for the Mapbox Vector Tiles. The URL is either a TileJSON
// descriptor (e.g. served from an MBTiles dataset) or a remote .pmtiles archive.
const model = await MapboxVectorTileSetModel.createFromURL(
    "https://sampleservices.luciad.com/mbtiles/samplesmbtiles/tile.json");
// Create a Mapbox GL style that decides how the vector tiles are painted.
const style = await MapboxStyle.createFromURL(
    "https://sampledata.luciad.com/data/mbtiles/osm_styles/osm-bright/osm-bright-style.json");
// Create a layer that renders the model with the style.
const layer = new MapboxVectorTileSetLayer(model, {style, label: "Mapbox Vector Tiles"});

You can also create a style from an inline object or JSON string with MapboxStyle.createFromObject. To restyle a layer at runtime, assign a new MapboxStyle to MapboxVectorTileSetLayer.style. The visible tiles are then re-fetched and re-painted with the new style.

Using the style provided by LuciadFusion

When LuciadFusion serves a Mapbox Vector Tiles dataset with a Mapbox Vector Tiles GL style alongside it, the model descriptor carries the style URL automatically. Read it from MapboxVectorTileSetModelDescriptor.styleUrl so that you don’t need to hard-code a style URL: 

const model = await MapboxVectorTileSetModel.createFromURL(fusionDataset);
// When served by LuciadFusion with a style alongside the data, modelDescriptor.styleUrl
// is populated automatically. Fall back to a known style URL when it is absent.
const styleUrl = model.modelDescriptor.styleUrl ?? fallbackStyleUrl;
const style = await MapboxStyle.createFromURL(styleUrl);
const layer = new MapboxVectorTileSetLayer(model, {style, label: "Mapbox Vector Tiles"});

If the data source doesn’t advertise a style, styleUrl is null. This may be the case in a PMTiles file for example, or if a TileJSON is served without LuciadFusion. Always provide a fallback style URL for that case.

Mapbox Vector Tiles are typically derived from OpenStreetMap. If you want raster imagery instead of vector tiles, see How to visualize imagery from OpenStreetMap tile servers.

Limitations

You can’t pick features of a MapboxVectorTileSetLayer using RIAMap.pickAt(). This also means that hovering and selection of features in a MapboxVectorTileSetLayer isn’t supported.