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 gdalwarpcommand 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.
