Post processing MBTiles with MBPipe
Clone this wiki locally
MBPipe is a command-line tool for running batch operations on all of the tile images stored within an MBTiles file. It takes two parameters: a command and a path to an mbtiles file. The command should be something that takes input from the standard input (stdin) and outputs it to the standard output (stdout). (More on what this means at Wikipedia.)
Compression: 24/32-bit full-color PNGs to 8-bit paletted PNGs with PNGQuant
PNGQuant is a PNG quantization utility - it can take a full-color 24-bit PNG file and turn it into a limited-palette 8-bit PNG. When reading from stdin and writing to stdout the command takes a single argument - the number of colors to limit the palette to.
mbpipe 'pngquant 64' file.mbtiles
Valid palette sizes range from 1 to 255. Take into consideration the number of colors and details in your design when choosing an optimal palette size. Flat designs with a few colors can get away with smaller palettes than more detailed, colorful designs.
You can download a pngquant binary for Mac OS X.
Recompressing 8-bit PNGs with AdvPNG
mbpipe 'advpng -z -4' file.mbtiles
Or use a different compression setting of your choice. If AdvPNG produces a larger file, it will output the original file.
Compression: JPEGs with ImageMagick
ImageMagick is a powerful command-line utility for processing images. It can do many things including format conversion, compression, color adjustment, and image enhancement. See the extensive documentation for more details.
The standard ImageMagick command is
convert. To read and write to stdin and stout with ImageMagick, use
<format>:- in place of file name in the command. For example, if you are reading from PNG and writing to JPEG, your command would look like this:
mbpipe 'convert -format jpg -quality 90% png:- jpg:-' file.mbtiles
The Natural Earth tilesets on MapBox.com were created this way, but with an additional parameter to sharpen the images slightly:
mbpipe 'convert -format jpg -quality 90% -sharpen 0.1 png:- jpg:-' file.mbtiles
JPEG is a good compression option for tilesets with lots of texture, such as hillshades, photo imagery, or artistic effects such as simulated paper textures. For such tilesets, even with a high JPEG quality setting like 90% dramatic reductions in filesize can be made.
Effect: Adding transparency for 'Glass' tilesets with ImageMagick
The MapBox World Glass tileset was rendered in TileMill as a fully-opaque greyscale design. The transparency was added after the fact with MBPipe and ImageMagick. This is the command that was used:
mbpipe 'convert -size 256x256 xc:white png:- -alpha Off -compose Copy_Opacity -composite -monochrome -alpha On png:-' world-glass.mbtiles
Note: this command must be entered as a single line.
This command creates a new solid white image the same size as a tile (
-size 256x256 xc:white) and applies the input image as the alpha channel to that flat image (
png:- -alpha Off compose Copy_Opacity -composite). Normally the
Copy_Opacity operator copies only the actual alpha channel of the input image (which in this case is solid opaque), but when the input image has no alpha channel (which we ensure with
-alpha Off) it is treated instead as a greyscale mask where white is fully opaque and black is fully transparent. The final part (
-monochrome -alpha On png:-) specifies that the output should be a greyscale PNG with an alpha channel.
Effect: Alternative color versions with ImageMagick
The Black & White NASA Blue Marble tilesets on MapBox.com were also created with MBPipe, starting with the full-color versions of the files. ImageMagick was used to desaturate the colors as well as adjust the levels for a higher contrast between land and ocean:
mbpipe 'convert -colorspace Gray -level 10%,70%,2.0 jpg:- jpg:-' file.mbtiles
In this case, the input was already JPG, and we kept the same format and quality for the output.
Not all utilities you may want to use support reading from or writing to stdin and stdout. Notable examples include
pngcrush. You will have to find alternatives to these.