Process RGB imagery
In this example, we'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 which 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.
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
.MAPBOX_ACCESS_TOKEN
- A secret token for your Mapbox account withtilesets:write
(for uploading source, creating tileset and publish job) andtilesets:read
scope (for getting job status).
We'll reference these values in later steps.
ACCOUNT=your-account-name
ENDPOINT="https://api.mapbox.com/tilesets/v1"
RECIPE_LOCATION="./rastermts-rgb.json"
SOURCE_NAME=rastermts-rgb-example
SOURCE_LOCATION="./rastermts_rgb.tif"
TILESET_ID=your-account-name.rgb-example
MAPBOX_ACCESS_TOKEN="<Insert your own sk.* token here>"
Designing a Raster MTS recipe
A Raster MTS Recipe describes how source data is mapped to the webp tiles which Raster MTS creates.
Using rasterio command rio info
on this sample source, we 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
Next, we'll create a Tileset Source by uploading our 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=${MAPBOX_ACCESS_TOKEN}" \
-F file=@${SOURCE_LOCATION} \
--header "Content-Type: multipart/form-data"
tilesets upload-raster-source $ACCOUNT $SOURCE_NAME $SOURCE_LOCATION
Create a recipe
A recipe is a set of instructions used for processing the raster data.
{
"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"]
]
}
}
}
}
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
Create an empty tileset and provide the recipe to be used for processing.
curl \
-X POST "${ENDPOINT}/${TILESET_ID}?access_token=${MAPBOX_ACCESS_TOKEN}" \
-d @"${RECIPE_LOCATION}" \
--header "Content-Type:application/json"
tilesets create $TILESET_ID \
--recipe $RECIPE_LOCATION \
--name "tilesets example tileset"
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=${MAPBOX_ACCESS_TOKEN}"
tilesets publish $TILESET_ID
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=\${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>
// TO MAKE THE MAP APPEAR YOU MUST
// ADD YOUR ACCESS TOKEN FROM
// https://account.mapbox.com
mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
const map = new mapboxgl.Map({
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>