Skip to main content

Process RGB imagery

In this example, you'll process a 3-band sample imagery file using Raster MTS. This is a 3 band image representing red, blue, and green (RGB) color channels. The goal is to create a raster source that can be added to a map as a visual layer.

Prerequisites​

To follow along, you'll need:

  • 8-bit GeoTIFF data (sample download below)
  • rasterio CLI to investigate metadata for sample data.
arrow-downSample GeoTIFF file

Environment variables​

Throughout this example, you'll use the following required 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 - A unique identifier given to your tileset. A tileset ID always starts with your Mapbox username, followed by the tileset's unique alphanumeric identifier: username.identifier.
  • YOUR_SECRET_MAPBOX_ACCESS_TOKEN - A secret token for your Mapbox account with tilesets:write (for uploading source, creating tileset and publish job) and tilesets:read scope (for getting job status).

And when replacing these variables in code snippets or commands, refer to this list:

ACCOUNT=your-account-name
ENDPOINT="https://api.mapbox.com/tilesets/v1"
RECIPE_LOCATION="/path/to/file/rastermts-rgb.json"
SOURCE_NAME=rastermts-rgb-example
SOURCE_LOCATION="/path/to/file/rastermts_rgb.tif"
TILESET_ID=your-account-name.rgb-example
YOUR_SECRET_MAPBOX_ACCESS_TOKEN="<Insert your own sk.* token here>"

(Optional) Designing a Raster MTS recipe​

A Raster MTS recipe describes how source data is mapped to the webp tiles that Raster MTS creates.

Using rasterio command rio info on this sample source, you'll see the (truncated) output:

$rio info rastermts_rgb.tif
{
  "blockxsize": 256,
  "blockysize": 256,
  "bounds": [2767020.42392338, 8441093.853814866, 2767631.97392338, 8441705.403814867],
  "colorinterp": [
    "red",
    "green",
    "blue"
  ],
  "compress": "jpeg",
  "count": 3,
  "crs": "EPSG:3857",
  "descriptions": [null, null, null],
  "driver": "GTiff",
  "dtype": "uint8",
  "height": 4077,
  "indexes": [1, 2, 3],
  "interleave": "pixel",
  "lnglat": [24.859314206372513, 60.18659827701693],
  "mask_flags": [["nodata"], ["nodata"], ["nodata"]],
  "nodata": 0.0,
  "res": [0.15, 0.15],
  "shape": [4077, 4077],
  "tiled": true,
  "transform": [0.15, 0.0, 2767020.42392338, 0.0, -0.15, 8441705.403814867, 0.0, 0.0, 1.0],
  "units": [null, null, null],
  "width": 4077
}

Create a tileset source​

First, you'll create a tileset source by uploading your GeoTIFF data to MTS. If you're using the API directly, you'll need to make a request for each individual source file that you reference in your recipe.

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

Create a recipe​

A recipe is a set of instructions used for processing raster data. To use your recipe you will need to create a file and add your own information:

  1. Create a .json file named rastermts-rgb.json.
  2. Paste in the recipe below.
  3. Replace {ACCOUNT} and {SOURCE_NAME} with your own values.
{
    "version": 1,
    "type": "raster",
    "sources": [
        {
            "uri": "mapbox://tileset-source/{ACCOUNT}/{SOURCE_NAME}"
        }
    ],
    "minzoom": 16,
    "maxzoom": 18,
    "layers": {
      "RGB": {
        "source_rules": {
          "filter": [
            ["==", ["get", "colorinterp"], "red"],
            ["==", ["get", "colorinterp"], "green"],
            ["==", ["get", "colorinterp"], "blue"]
          ]
            }
        }
    }
}

Note

The order of band selection in "filter" will be used for RGB encoding.

The following construct indicates that Raster MTS should pick up the "red" band as the first in RGB encoding.

"filter": ['==', ['get', 'colorinterp'], 'red'],

Create an empty tileset​

Now you will create an empty tileset and provide the recipe to be used for processing.

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

Note

If you're using the API directly with curl, 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 tileset source, created an empty tileset, and provided a tileset recipe. Now you can process and publish your tileset.

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

Review tileset 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=\${YOUR_SECRET_MAPBOX_ACCESS_TOKEN}"

Add tileset to map​

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Process RGB imagery</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
  const map = new mapboxgl.Map({
    // TO MAKE THE MAP APPEAR YOU MUST
    // ADD YOUR ACCESS TOKEN FROM
    // https://account.mapbox.com
    accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
    container: 'map',
    maxZoom: 20,
    minZoom: 16,
    zoom: 16,
    center: [24.859, 60.187],
    // Choose from Mapbox's core styles, or make your own style with Mapbox Studio
    style: 'mapbox://styles/mapbox/light-v11'
  });

  map.on('load', () => {
    map.addSource('raster-rgb-source', {
      'type': 'raster',
      'url': 'mapbox://rasterarrayexamples.rgb_sample'
    });
    map.addLayer({
      'id': 'rgb-raster-layer',
      'type': 'raster',
      'source': 'raster-rgb-source'
    });
  });
</script>

</body>
</html>

Troubleshooting​

Here are solutions to some common integration problems:

Empty Tileset

  • If you receive an empty tileset error when trying to publish, check that you updated the recipe with your credentials in the Create A Recipe step.
Was this example helpful?