Skip to main content

RMTS Recipe basics


In this example, we'll process GFS pressure data from NOAA using Raster MTS.

Prerequisites

To follow along, you'll need:

  • GFS data (which we'll provide an example of).
  • Either the curl or the rmts-cli command-line utilities.
  • You will need the api_rasterarrays feature flag enabled on your Mapbox account.
arrow-downGFS pressure data

To make use of the rmts-cli, download the binary which matches your architecture, and then provide it with executable permissions:

mv rmts-{your_arch} rmts
chmod +x ./rmts

Then, configure rmts-cli for use with your account and token:

rmts configure

Environment variables

  • ACCOUNT - Set this to your account username.
  • ENDPOINT - The path to the Mapbox tilesets API.
  • RECIPE_LOCATION - The local file location of your Raster MTS recipe.
  • SOURCE_NAME - The name used to create your tileset-source. Once your tileset-source has been created, you must reference that returned tileset-source URI in your recipe.
  • SOURCE_LOCATION - The local file location of your raster source.
  • TILESET_ID - The name of your tileset prefixed with the above account name. The account name and tileset name must be separated by a period.
  • TOKEN - A secret token for your Mapbox account.

We'll reference these values in later steps.

ACCOUNT=your-account-name
ENDPOINT="https://api.mapbox.com/tilesets/v1"
RECIPE_LOCATION="./gfs-pressure.json"
SOURCE_NAME=gfs-pressure-example
SOURCE_LOCATION="./gfs-pressure.grib2"
TILESET_ID=your-account-name.gfs-example
TOKEN="sk.foobar"

Designing a Raster MTS recipe

The task of a Raster MTS Recipe is to describe how source data is mapped to the MRT-formatted tiles which Raster MTS delivers.

A good data source for Raster MTS is one with one or more bands, each containing scalar numerical data. For example, this may be a GRIB2 file obtained from a meteorological agency. The GDAL tool gdalinfo is an excellent tool for understanding the structure of your data.

Running gdalinfo on this sample source, we see the (truncated) output:

$ gdalinfo gfs-pressure.grib2
...
Band 1 Block=1440x1 Type=Float64, ColorInterp=Undefined
Description = 80[m] HTGL="Specified height level above ground"
Metadata:
GRIB_COMMENT=Pressure [Pa]
GRIB_DISCIPLINE=0(Meteorological)
GRIB_ELEMENT=PRES
GRIB_FORECAST_SECONDS=0
GRIB_IDS=CENTER=7(US-NCEP) SUBCENTER=0 MASTER_TABLE=2 LOCAL_TABLE=1 SIGNF_REF_TIME=1(Start_of_Forecast) REF_TIME=2023-10-30T18:00:00Z PROD_STATUS=0(Operational) TYPE=1(Forecast)
GRIB_PDS_PDTN=0
GRIB_PDS_TEMPLATE_ASSEMBLED_VALUES=3 0 2 0 81 0 0 1 0 103 0 80 255 0 0
GRIB_PDS_TEMPLATE_NUMBERS=3 0 2 0 81 0 0 0 1 0 0 0 0 103 0 0 0 0 80 255 0 0 0 0 0
GRIB_REF_TIME=1698688800
GRIB_SHORT_NAME=80-HTGL
GRIB_UNIT=[Pa]
GRIB_VALID_TIME=1698688800

Create a tileset source

Next, we'll create a Tileset Source by uploading our GFS data to MTS. If you're using API directly, you'll need to make a request for each individual source file that you'll be referencing in your recipe. In the example GFS data that we're processing, we only have a single source file so we'll make the following POST once.

curl \
-X POST "${ENDPOINT}/sources/${ACCOUNT}/${SOURCE_NAME}?access_token=${YOUR_MAPBOX_ACCESS_TOKEN}" \
-F file=@${SOURCE_LOCATION} \
--header "Content-Type: multipart/form-data"

Create a recipe

A recipe is a step of instructions used for processing the raster data.

{
"version": 1,
"type": "rasterarray",
"sources": [
{
"uri": "mapbox://tileset-source/{ACCOUNT}/{SOURCE_NAME}"
}
],
"minzoom": 0,
"maxzoom": 3,
"layers": {
"pressure": {
"tilesize": 256,
"offset": -100,
"scale": 0.10,
"resampling": "bilinear",
"buffer": 1,
"units": "Pa",
"source_rules": {
"filter": [
"==",
[
"get",
"GRIB_COMMENT"
],
"Pressure [Pa]"
],
"name": [
"to-number",
[
"get",
"GRIB_VALID_TIME"
]
],
"order": "asc"
}
}
}
}

alert
Note

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 "Pressure [Pa]. 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 "Pressure [Pa]".

"filter":["==",["get","GRIB_COMMENT"],"Pressure [Pa]"],

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"

Create an empty tileset

Create an empty tileset and provide the recipe to be used for processing.

curl \
-X POST "${ENDPOINT}/${TILESET_ID}?access_token=${YOUR_MAPBOX_ACCESS_TOKEN}" \
-d @"${RECIPE_LOCATION}" \
--header "Content-Type:application/json"

alert
Note

If you're using the API directly, you'll need to wrap your recipe in an additional JSON structure to include a recipe and name property.

{
"recipe": {...},
"name": "example_tileset_name"
}

Publish a Tileset

At this point you have uploaded a source, created an empty tileset, and provided a recipe to be used for processing the source to this tileset. Now you can start processing your tileset by publishing it.

curl -X POST "${ENDPOINT}/${TILESET_ID}/publish?access_token=${YOUR_MAPBOX_ACCESS_TOKEN}"

Get your tileset's job information

At this point, Raster MTS will begin to process your job with a job_id. You can retrieve your job's information by calling the API endpoint below with your job_id.

curl "\${ENDPOINT}/\${TILESET_ID}/jobs/{job_id}?access_token=\${TOKEN}"
Was this page helpful?