Skip to main content

RMTS Recipe basics

Join the Mapbox Developers Discord Communityarrow-right

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
macOSLinuxWindows
arrow-downmacos-arm64 arrow-downmacos-x86-64arrow-downlinux-arm64 arrow-downlinux-x86-64arrow-downwindows-x86-64

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=${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.1,
      "resampling": "bilinear",
      "buffer": 1,
      "units": "Pa",
      "source_rules": {
        "filter": ["==", ["get", "GRIB_COMMENT"], "Pressure [Pa]"],
        "name": ["to-number", ["get", "GRIB_VALID_TIME"]],
        "order": "asc"
      }
    }
  }
}

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=${TOKEN}" \
  -d @"${RECIPE_LOCATION}" \
  --header "Content-Type:application/json"

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=${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}"
Join the Mapbox Developers Discord Communityarrow-right
Was this page helpful?