Automating Tile Generation with TileMill

MapBox hasn’t documented this anywhere that I can find, which either means (a) they haven’t gotten around to it or (b) this isn’t a stable API and it could change in a future TileMill release. If you automate your tile generation this way, make sure your job still works when you install a new version of TileMill. With all of that said, I’ve been asked this question often enough that I figured it deserved a post.

The first step is locating TileMill’s index.js. On Ubuntu it is sitting at /usr/share/tilemill. On Windows it’ll depend on whether you’re 32bit or 64bit, but assuming you put it in the default place it’ll be something like C:\Program Files (x86)\TileMill-v0.10.1\tilemill. Because TileMill’s node isn’t in the system path on Windows, before you do anything you’ll need to be in that folder.

Windows
1
cd "C:\Program Files (x86)\TileMill-v0.10.1\tilemill"

Having node execute index.js by itself just launches TileMill, but there are other command options, including export. To see the full list of commands:

Windows
1
.\node.exe .\index.js --help
Ubuntu
1
/usr/share/tilemill/index.js --help

That will give you:

1
2
3
4
5
6
7
Usage: /usr/share/tilemill/index.js [command] --help for a list of options.
Available commands are:
  start:   start application
  core:    start ui server
  export:  export project
  test:    test server process
  tile:    start tile server

export is what we’re interested in. Firing that command without any arguments will give you your options.

Windows
1
.\node.exe .\index.js export
Ubuntu
1
/usr/share/tilemill/index.js export

You’ve got a lot of options.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
Usage: /usr/share/tilemill/index.js <command> [options...]
Commands: export project
  export <project> <export>

Options:
    --format=[format]                 Export format (png|pdf|svg|mbtiles|upload|sync). (Default: undefined)
    --bbox=[xmin,ymin,xmax,ymax]      Comma separated coordinates of bounding box to export. (Default: undefined)
    --minzoom=[zoom]                  MBTiles: minimum zoom level to export. (Default: undefined)
    --maxzoom=[zoom]                  MBTiles: maximum zoom level to export. (Default: undefined)
    --width=[width]                   Image: image width in pixels. (Default: 400)
    --height=[height]                 Image: image height in pixels. (Default: 400)
    --url=[url]                       URL to PUT updates to. (Default: undefined)
    --log                             Write crash logs to destination directory. (Default: undefined)
    --quiet                           Suppresses progress output. (Default: undefined)
    --scheme=[scanline|pyramid|file]  Enumeration scheme that defines the order in which tiles will be rendered. (Default: "scanline")
    --job=[file]                      Store state in this file. If it exists, that job will be resumed. (Default: false)
    --list=[file]                     Provide a list file for filescheme render. (Default: false)
    --metatile=[num]                  Metatile size. (Default: undefined)
    --scale=[num]                     Scale factor (Default: undefined)
    --concurrency=[num]               Number of exports that can be run concurrently. (Default: 4)
    --files=[path]                    Path to files directory. (Default: "/home/gandalf/Documents/MapBox")
    --syncAPI=[URL]                   MapBox API URL. (Default: "http://api.tiles.mapbox.com")
    --syncURL=[URL]                   MapBox sync URL. (Default: "https://tiles.mapbox.com")
    --syncAccount=[account]           MapBox account name. (Default: "")
    --syncAccessToken=[token]         MapBox access token. (Default: "")
    --verbose=on|off                  verbose logging (Default: "on")
    --config=[path]                   Path to JSON configuration file.

Now you can automate tile generation. A batch file for Windows would look something like this.

Windows
1
2
cd "C:\Program Files (x86)\TileMill-v0.10.1\tilemill"
.\node.exe .\index.js export meckbase C:\tile-depot\meckbase.mbtiles --format=mbtiles --bbox="-81.8949,34.7032,-79.8075,35.8768" --minzoom=9 --maxzoom=11 --metatile=8
  • For the project argument, you’re giving the name of the project folder in MapBox\project, which in this case is meckbase. Do not put project.mml here.
  • metatile is optional, but if you have a healthy amount of RAM bumping it up from the default 2 will make things go faster. It will also reduce rendering problems around tile edges.
  • It assumes MapBox\project is in the default install location. If you put it somewhere else, use the --files=c:\path_to_project option. If you get this wrong the command will give you a can’t find project message.