Georeference imagery

You can place a scanned aerial image or a historical map onto a Mapbox map with spatial referencing. Follow steps here for taking a non-georeferenced JPEG image and turning it into a tileset ready for import to Mapbox Studio.

Use the free and open-source application Quantum GIS and some plugins to georeference an image onto a map. You can save the image and upload it to Mapbox when complete.

Load QGIS plugins

To start, you’ll need the latest version of QGIS installed and ready to go. Once you’ve installed and opened QGIS, you’ll need to add a couple of plugins – the tileLayer plugin and the georeferencer GDAL plugin.

To install a plugin, from the menu select: Plugins->Manage and Install Plugins. Search for the plugin by name to install it.

manage plugins

Set up the tileLayer plugin

Once your plugins are loaded, you’ll need a little prep work before adding a satellite reference layer. In your favorite text editor, make a Tabbed Separated Values (*.tsv) file and save it in a local directory. Then add the following line to it:

Mapbox	Mapbox{z}/{x}/{y}.png?access_token=<your access token>

Note: you will need to ensure the values are tab-separated. Copying and pasting the above will fail.

You will also need to change ____ which you can get from your [tokens]( page. Note: do not include the angle brackets in your edited file.

Close and save the TSV file.

This file gives you access to Mapbox Satellite with Streets.

When you load a tileLayer, you’re loading a Mapbox web service. In this case, we’ll point the tileLayer plugin’s definition directory to the folder where our TSV is stored:

  1. Go to the menu Web->TileLayerPlugin->Add Tile Layer…
  2. Click Settings.
  3. Add your External layer definition directory, or location where you stored your TSV file. tilelayer-tsv
  4. Select your Mapbox tileLayer and click Add to add it to your map. add-tilelayer

For this example, we’re georeferencing a portion of a historical Map of Multnomah County, Oregon from 1889. Download the image by choosing JP2 from the dropdown and pressing GO. The image will download automatically. Images like this pose their own challenges for finding suitable points to match, but let’s rough it in for now.

Start georeferencing

This historical map is of Portland, OR, located in the northwest part of the United States.

Now that you have an image to reference, you can start georeferencing. Zoom to your location in QGIS and open the georeferencer plugin. To open plugin: Go to the menu Raster->Georeferencer->Georeferencer.

To open the file in Georeferencer, click on the Open Raster icon and open the JP2 file.

georef open

Familiarize yourself with the interface, particularly zooming to your reference points and adding points.

You’ll need to find features on your image that match the map. Try to find unique identifiers like street markings, old railroad lines, interesting curves in a river, or building and park corners. These are great ground control points (GCPs). The more points that you can identify the better.

georef matching features

Next, start adding points on your image by clicking a point on the image and then the corresponding point on the Mapbox tileLayer.

georef click

Repeat this step for at least 3 or more points that are spread out over your image. Once your points are set, start georeferencing by choosing File->Start Georeferencing and setting the transformation settings, including the name and destination path of your image:

  • Transformation type: Linear
  • Resampling method: Nearest neighbor
  • Compression: NONE
  • Target SRS: EPSG: 3857


Click Ok and your image should be transformed onto the map if the Load in QGIS when done setting is checked. If QGIS does not automatically reload, press the Start Georeferencing icon and wait for the process to load.

If the image is skewed or not in the correct location, then you’ll want to double check your points or confirm your original projection is the same. You can always go back to add or delete your GCPs and transform your image again.


Upload raster layer

Once you’re happy with your new image, you can upload your image directly in a style or add it as a raster tileset to your tilesets page.

View full map

Next article:

Upload to Mapbox using cURL

Additional questions? Ask our support team or learn more about How Mapbox Works.