About the MBTiles format

MBTiles is a container format for tiled data. The format is based on the SQLite database engine: each MBTiles file is a SQLite database with at least two tables:

  • A metadata table with information about the file format version, the extents of the data, and so on

  • A table with BLOBs of data for each individual tile

The tiles are always structured in an industry-standard Web Mercator quadtree-like tile pyramid. The tiles themselves can contain either images in the JPEG or PNG format, or vector data. In the latter case, Google’s Protocol Buffers library is used to encode the vector shapes into a binary representation.

LuciadLightspeed provides support for the MBTiles format through TLcdMBTilesModelDecoder. This decoder supports both image and vector tiles, but the data type determines how you must visualize the tiles. See Visualizing image tiles and Visualizing vector tiles for more information.

Determining the type of your data

The models returned by TLcdMBTilesModelDecoder always contain a TLcdMBTilesModelDescriptor. This descriptor in turn contains a TLcdMBTilesDataSource. The data source object offers metadata for the MBTiles file, and has a getDataType method which tells you whether the file contains image or vector tiles: 

//First create the model
ILcdModelDecoder decoder =
    new TLcdCompositeModelDecoder(TLcdServiceLoader.getInstance(ILcdModelDecoder.class));
ILcdModel model = decoder.decode(sourceName);
ILcdModelDescriptor descriptor = model.getModelDescriptor();
if (descriptor instanceof TLcdMBTilesModelDescriptor) {
  TLcdMBTilesModelDescriptor mbtiles = (TLcdMBTilesModelDescriptor) descriptor;
  TLcdMBTilesDataSource.MBTilesType dataType = mbtiles.getDataSource().getDataType();
  switch (dataType) {
  case IMAGE_TILES:
    // Treat model as image data.
    break;
  case VECTOR_TILES:
    // Treat model as vector data.
    break;
  default:
    throw new IllegalArgumentException(dataType + " is not a recognized MBTiles tile format");
  }
}

Visualizing image tiles

If you have determined that your model contains image tiles, you can visualize the data using standard raster layers in both GXY views and Lightspeed views.

Visualizing image tiles in a GXY view

This snippet shows how to create an ILcdGXYLayer for the ILcdModel returned by the MBTiles decoder, and how to add it to the ILcdGXYView: 

//First create the model
ILcdModelDecoder decoder = new TLcdMBTilesModelDecoder();
ILcdModel model = decoder.decode(sourceName);

//Create a layer for the model with default styling
ILcdGXYLayer layer = TLcdGXYLayer.create(model);
//Wrap the layer with an async layer wrapper to ensure
//that the view remains responsive while data is being painted
layer = ILcdGXYAsynchronousLayerWrapper.create(layer);

//Add the async layer to the GXY view (an ILcdGXYView)
view.addGXYLayer(layer);

This results in an MBTiles image layer with default styling. See Visualizing Raster Data for more information about visualizing and styling raster data in GXY views.

Visualizing image tiles in a Lightspeed view

This snippet shows how to create an ILspLayer for the ILcdModel returned by the MBTiles decoder, and add it to the ILspView. 

//First create the model
ILcdModelDecoder decoder = new TLcdMBTilesModelDecoder();
ILcdModel model = decoder.decode(sourceName);

//Create a layer for the model with default styling
ILspLayer layer = TLspRasterLayerBuilder.newBuilder()
                                        .model(model)
                                        .build();

//Add the layer to the Lightspeed view (an ILspView)
view.addLayer(layer);

This results in an MBTiles image layer with default styling. See Visualizing Raster Data for more information about visualizing and styling raster data in Lightspeed views.

Visualizing vector tiles

If you have determined that your model contains vector tiles, you can visualize it in a Lightspeed view only.

GXY views currently don’t support vector tiles.

LuciadFusion currently doesn’t support vector tiles either. For an overview of the data types you can serve through the various LuciadFusion services, see Supported data types.