Working with GeoTIFFs

This guide explains the basics of preparing a GeoTIFF for TileMill and adding it to a project.

Reproject with GDAL

While TileMill’s renderer does support reprojecting raster data sources on-the-fly, this can slow down your map preview and exports significantly. For this reason it is recommended that you ensure the file is warped to the proper projection before importing it into your TileMill project. This can be done with the gdalwarp command that comes with the GDAL library.

The projection we need to warp is Google Web Mercator, which can be referenced by the code ‘EPSG:3857’. You will also need to know the original projection of the geotiff you are converting. As an example, we’ll work with the medium-sized ‘Natural Earth II with Shaded Relief and Water’ geotiff available from Natural Earth, which is projected to WGS 84 (aka ‘EPSG:4326’).

In your terminal, navigate to the directory where the geotiff is stored and run the following command. (This is one command split across several lines; you should be able to copy and paste the whole thing at once.)

gdalwarp -s_srs EPSG:4326 -t_srs EPSG:3857 -r bilinear \
    -te -20037508.34 -20037508.34 20037508.34 20037508.34 \
    NE2_LR_LC_SR_W.tif natural-earth-2-mercator.tif

You will see this output:

Let’s go through what each piece of that command means. A full description of the gdalwarp command options can be found in the GDAL documentation.

-s_srs means “source spatial reference system” - this is the projection that the flle you are starting with is stored in, which in the case of Natural Earth is EPSG:4326.

-t_srs means “target spatial reference system” - this is the projection that you want to convert the datasource to. For any raster file you want to use with TileMill this should be EPSG:3857.

-r bilinear is telling the program what resampling interpolation method to use. If you want the command to run faster and don’t mind a rougher-looking output, choose near instead of bilinear. If you don’t mind waiting longer for very high-quality output, choose lanczos.

-te -20037508.34 -20037508.34 20037508.34 20037508.34 is telling the program the desired “target extent” of our output file. This is necessary because the Natural Earth geotiff contains data outside the bounds that the web mercator projection is intended to display. The WGS 84 projection can safely contain data all the way to 90° North & South, while web mercator is really only intended to display data up to about 85.05° North & South. The four big numbers after -te represent the western, southern, eastern and northern limits (respectively) of a web mercator map.

If you are working with raster data of a smaller area you will need to make sure that these numbers are adjusted to reflect the area it represents. If that area that does not go too far north or south, you can safely omit this entire option.

LR_LC_SR_W.tif is our original file, and natural-earth-2-mercator.tif is the name of the new file the program will create.

Depending on the size of your file and the resampling method you choose, gdalwarp can take a few seconds to a few hours to do its job. With the cubic resampling method on the medium Natural Earth will should a few minutes or less.

Adding the GeoTIFF to a TileMill project

With the GeoTIFF reprojected, you can load it into your TileMill project. Click Add Layer and browse to find the location where you stored natural-earth-2-mercator.tif. Select 900913 as the SRS projection. Select the file and click Save and Style.

To further adjust the resampling interpolation of the image, add the following CartoCSS to your geotiff layer: raster-scaling: bilinear;. See the CartoCSS reference manual for additional raster-scaling values. Select Save to view any changes made to your CartoCSS.

Adding a non-Mercator GeoTIFF to TileMill

If you’re working with a small GeoTIFF or just want to quickly preview something that is not already projected to Web Mercator, you can skip the initial reprojection step and add the file directly to TileMill. To do this you will need to know the spatial reference system (SRS) of your file so you can tell TileMill.

Click the Add Layer button, browse to the location of your GeoTIFF, and select it. If your GeoTIFF is projected to WGS84 (aka ‘EPSG:4326’), select ‘WGS84’ from the SRS dropdown. If your file is in a different projection, select ‘Custom’.

You’ll now need to enter the custom SRS. If the prokjection has an EPSG code that you know, you can enter it as +init=EPSG:1234 (replacing 1234 with the actual code). Otherwise, you can search for your projection on spatialreference.org. Select the ‘Proj4’ version of the projection and paste that into the custom SRS field.