Skip to main content

Raster MTS Recipe Specification


Current version: 1

A raster recipe is a JSON document containing configuration options that tell Raster MTS how to turn raster source data into Mapbox Raster Tiles (MRT).

Recipes must be constructed according to the rules in this recipe reference.

Recipe top-level fields

A recipe is a JSON object that must contain the following top-level fields:

Required fieldsDescriptionData type
version The version of the Mapbox Tiling Service recipe reference that the recipe uses.Integer
type Key to show this as a Raster MTS recipe"rasterarray"
sources List of input source filesList<SourceObject>
minzoom The lowest zoom level for the tileset.Integer
maxzoom The highest zoom level for the tileset. Should be greater or equal to minzoom.Integer
layers The names of the layers and their configuration options.Object<String, LayerObject>
{
"version": 1,
"type":"rasterarray",
"sources":[{"uri":"mapbox://tileset-source/{ACCOUNT}/{SOURCE_NAME}"}],
"minzoom":0,
"maxzoom":6,
"layers": { layername: LayerObject, ... }
}

Recipe version

The recipe version indicates the version of the Raster MTS recipe reference that the recipe uses. The current version is 1. Using any version other than the current version or a previous version will result in an error.

Layers

The recipe layers object contains key-value pairs associating the names of tile layers with their configuration. For each key-value pair, the key is the name of the layer, and the value is a LayerObject containing the configuration and options for the layer.

Each layer must have a name (for example "temperature", "precipitation", or "cloud" in the example below). This is the unique identifier for the layer of data in your final tileset. In any tileset, each layer name must be unique. The layer name must be a string with only underscores (_) and alphanumeric characters.

The corresponding LayerObject for each layer name describes how that MRTs should be created.

Layer example

...
"layers": {
"Pressure": {
"tilesize": 512,
"offset": -100,
"buffer": 1,
"scale": 0.1,
"units": "Pa",
"source_rules": {"name": ["to-number", ["get", "GRIB_VALID_TIME"]]},
}
},
...

Layer configuration

Required fieldsDescriptionData type
tilesize Tile size (excluding buffer). Must be a power of twoInteger
offset Offset of the encoding, which defines the minimum permissible value.Integer
buffer Number of pixels surrounding each edge of a tileInteger
scale Scale of the encoding (for example a reasonable scale for temperature can be 0.1)Float

Tile Size

The tilesize must be a power of two and defines the resolution (excluding the buffer) of data in each raster tile. The tile size is an essential control which helps manage data transfer. For example, a tilesize of 512 may produce sharp, retina-resolution output but may be unnecessary to represent a smoothly varying temperature field. In contrast, a tilesize of 128 would reduce the resolution by a factor of four and require one sixteenth the total data transfer.

Buffer

The buffer defines the number of pixels around the border of each tile which are duplicated across tiles. In general, this value should be 1 to decrease tile boundary artifacts when using a raster layer with linear resampling.

Offset and Scale

While any numerical format is acceptable as source input, data in each layer is encoded as a 32-bit unsigned integer. A single value (2³² - 1) is reserved to denote no data. Depending on the range and precision of your data, you must select a suitable floating point offset and scale. Given some encoded pixel value, the value is computed as:

value = offset + scale * pixel

The offset and scale have a significant effect on the resulting tileset. The offset defines the minimum value which may be encoded. Source values lower than this bound will trigger an error. The scale defines the fixed increment between each representable value.

To determine an appropriate offset and scale for your data, it is appropriate to examine the source input, for example using gdalinfo -stats to examine the range of data contained in each band. For example, to encode air temperature in Celsius, -100 might be a reasonably safe offset you never expect to exceed, although -274 is an offset which is impossible to exceed. The offset defines a permissible range of values but does not significantly impact the size of the resulting tileset.

The scale defines the precision of the resulting tileset, and as such has a significant effect on the size of the tileset. To reduce data transfer, choose a value as large as tolerable while balancing posterization due to quantization. For example, 0.1 may be an acceptable increment for temperatures in Celsius, while 1 or 10 degrees Celsius may be too large.

Optional layer configuration

Optional fieldsDescriptionData type
units Units of layer variableString
input_no_data_value A source data value which denotes masked dataNumber
resampling Resampling applied to source data during reprojecting to spherical mercator tiles"nearest" | "bilinear" | "cubic" | "cubic_spline" | "lanczos" | "average" | "gauss" | "mode" | "min" | "max" | "med" | "q1" | "q3" | "sum" | "rms"
source_rules Rules for mapping sources to bandsObject<String, SourceRuleObject>

Units

Units is an optional string used strictly for annotating the data, for example so that units are presented to designers when styling the data in Mapbox Studio. Any string value is permitted, for example "C", "Celsius", or "kg/m²/s".

Input no data value

Input no data value specifies a custom source data value which denotes masked pixels. Source data will often contain metadata which specifies how its mask is encoded. Instead of reencoding your source data when this metadata is not available or is not correct, you may use input_no_data_value to specify a custom no data value. For example, "input_no_data_value": 9999 would result in a tileset which masks all pixels with source data value 9999.

This option only affects interpretation of source data. The internal representation of masked pixels within MRT tiles is unrelated to input_no_data_value.

Resampling

The coordinate Coordinate Reference System (CRS) of your source data will often differ from Spherical Mercator projection with which MTS stores data for transmission and display. By default during the tiling phase, Raster MTS will resample your data using bilinear interpolation. Use the resampling layer configuration option to specify a different resampling strategy.

Note that this configuration option differs from the raster-resampling Mapbox Style Spec property, which affects how tiled data is resampled during rendering to the screen.

Source Rules

Source rules are additional configuration that can be added to recipe for processing. They are build upon expressions. Below are the supported expression rules for Raster MTS.

Optional fieldsDescriptionData type
filter Expression for selecting a single element of a rasterexpression
sort_key Expression for sorting the selected elementsexpression
name Expression for naming the selected elementsexpression
order Sorting order for the selected elementsString

Source rule example

{
"source_rules":{
"filter":["==",["get","GRIB_COMMENT"],"Total precipitation [kg/(m^2)]"],
"sort_key": ["to-number",["get","GRIB_VALID_TIME"]],
"name":["to-number",["get","GRIB_VALID_TIME"]],
"order":"asc"
}
}

The source_rules field allows you to select a single element of a raster. For example, in this recipe, the precipitation data exists in a band labeled with Total precipitation [kg/(m^2)]. You can find this information with gdalinfo.

The following construct indicates that Raster MTS should only process bands that have a GRIB_COMMENT that includes Total precipitation [kg/(m^2)].

"filter":["==",["get","GRIB_COMMENT"],"Total precipitation [kg/(m^2)]"],

We then name the constructed slice of data with:

"name":["to-number",["get","GRIB_VALID_TIME"]],

And then organize those distinct slices of data with:

"order":"asc".
Was this page helpful?