mbtileswrite

Write georeferenced image or data grid to MBTiles file

Since R2024b

Syntax

mbtileswrite(filename,A,R)

mbtileswrite(filename,A,R,Name=Value)

Description

mbtileswrite(filename,A,R) writes the specified georeferenced image or data grid to an MBTiles file. Specify the image or data grid using an array and a raster reference object. The input image or data grid must be referenced to Earth.

When combined with the addCustomBasemap function, the mbtileswrite function enables you to add custom basemaps that can be used in offline environments.

mbtileswrite(filename,A,R,Name=Value) specifies additional options using one or more name-value arguments. For example, you can write an attribution or description to the file.

Examples

Create MBTiles File from Image

Create an MBTiles file using imagery stored in a GeoTIFF file. Then, use the MBTiles file to add a custom basemap.

Read a GeoTIFF file containing imagery of Boston into the workspace as an array and a map cells reference object. The array is a grid of cells referenced to projected coordinates.

[A,R] = readgeoraster("boston.tif");

Write the imagery to an MBTiles file. Then, use the MBTiles file to add a custom basemap. The addCustomBasemap function issues a warning because the MBTiles file does not contain global data for zoom level 0.

filename = "boston.mbtiles";
mbtileswrite(filename,A,R)
addCustomBasemap("bostonBasemap",filename)

Warning: File does not contain global data for zoom level 0.

Create a map using the limits of the imagery. Calculate the latitude and longitude limits by unprojecting the xy-limits that are stored in the reference object.

xlimits = R.XWorldLimits;
ylimits = R.YWorldLimits;
projcrs = R.ProjectedCRS;
[latlim,lonlim] = projinv(projcrs,xlimits,ylimits);

figure
geolimits(latlim,lonlim)

Change the basemap to the custom basemap. The black background indicates areas where the basemap tile contains no data.

geobasemap bostonBasemap

Create MBTiles File from Quantitative Data

To create an MBTiles file that contains full-color tiles from quantitative data, you must first convert the data to an indexed image and a colormap, and then convert the indexed image and colormap to an RGB image.

Search the Web Map Service (WMS) Database for a layer containing terrain elevation data from the WMS server hosted by MathWorks®. The elevation data is derived from GMTED2010.

layers = wmsfind("mathworks",SearchField="serverurl");
elevation = refine(layers,"elevation");

Read global elevation data from the server. Specify the raster size as 2048-by-4096, and specify the format as BIL. The wmsread function represents the data using an array and a geographic cells reference object.

[Z,R] = wmsread(elevation,Latlim=[-90 90],Lonlim=[-180 180], ...
    ImageHeight=2048,ImageWidth=4096,ImageFormat="image/bil");

Convert the elevation data to an indexed image and a colormap. An indexed image is an array of integers, where each integer maps to a row of the colormap. Each row of the colormap is an RGB triplet that specifies the red, green, and blue components of a color.

• Prepare to visualize the water areas in blue by setting elevations at or below sea level (Z <= 0) to a value below sea level.

• Specify the number of colors to include in the colormap as 256.

• Create a colormap that is appropriate for elevation data.

• Rescale the elevation data to the interval [0, 255].

• Create the indexed image by converting the rescaled elevation data to an array of 16-bit unsigned integers. Note that the largest value of the unsigned integer type must be greater than the number of colors in the colormap.

% create colormap
Z(Z <= 0) = -1;
numColors = 256;
cmap = demcmap(Z,numColors);

% create indexed image
X = rescale(Z,0,numColors-1);
X = uint16(X);

Convert the indexed image to an RGB image of 8-bit unsigned integers.

rgb = ind2rgb8(X,cmap);

Write the RGB image and reference object to an MBTiles file. Add an attribution to the file by using the Attribution name-value argument.

mbtileswrite("gmted2010.mbtiles",rgb,R,Attribution="US Geological Survey")

Use the MBTiles file to add a custom basemap.

addCustomBasemap("gmted2010","gmted2010.mbtiles")

Create a geographic globe that uses the custom basemap. Position the camera above South America.

uif = uifigure;
g = geoglobe(uif,Basemap="gmted2010");

campos(g,-18,-62)

Input Arguments

filename — Filename

string scalar | character vector

Filename, specified as a string scalar or a character vector. You must include the extension .mbtiles.

The way you specify filename depends on the location you are writing to.

• To write to the current folder, specify the name of the file, such as "myImage.mbtiles".

• To write to a folder different from the current folder, specify the full or relative path name, such as "C:\myfolder\myImage.mbtiles" or "dataDir\myImage.mbtiles".

If filename is the name of an existing file, then mbtileswrite overwrites the file.

Data Types: char | string

A — Georeferenced image or data grid

M-by-N numeric or logical matrix | M-by-N-by-3 numeric array

Georeferenced image or data grid, specified as an M-by-N numeric or logical matrix, or an M-by-N-by-3 numeric array.

Some data types and values of M and N cause the mbtileswrite function to issue a warning:

• When A has a data type other than uint8, the function issues a warning and writes the MBTiles file using the uint8 data type.

• When M and N are less than 256, the function issues a warning and writes the MBTiles file by resizing the array so that either M or N is greater than or equal to 256.

R — Spatial reference for A

GeographicCellsReference object | GeographicPostingsReference object | MapCellsReference object | MapPostingsReference object

Spatial reference for A, specified as a GeographicCellsReference, GeographicPostingsReference, MapCellsReference, or MapPostingsReference object.

The mbtileswrite function writes the MBTiles file using the coordinate reference system (CRS) that is stored in R.

• When R is a GeographicCellsReference or GeographicPostingsReference object and the GeographicCRS property of the object is empty, the function writes the MBTiles file using the WGS 84 geographic CRS, which has the EPSG code 4326.

• When R is a MapCellsReference or MapPostingsReference object, the ProjectedCRS property of the object must not be empty. The projected CRS must be suitable for reprojection to the WGS 84 / Pseudo-Mercator projected CRS, which has the EPSG code 3857.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: mbtileswrite(A,R,Attribution="Natural Earth") writes an attribution to the MBTiles file.

Attribution — Attribution

string scalar | character vector

Attribution, specified as a string scalar or a character vector.

Data Types: string | char

Description — Description

string scalar | character vector

Description, specified as a string scalar or a character vector.

Data Types: string | char

More About

MBTiles

MBTiles is a file format used to efficiently store map tiles. MBTiles files are useful for creating maps in offline environments.

Algorithms

The mbtileswrite function writes MBTiles files using version 1.1 of the MBTiles specification.

Alternative Functionality

The mbtileswrite function enables you to store and share map tiles. If you do not need to store or share the map tiles, then you can add a custom basemap directly from an array and a raster reference object by using the addCustomBasemap function.

Version History

Introduced in R2024b