-
Notifications
You must be signed in to change notification settings - Fork 83
Post processing MBTiles with MBPipe
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.)
MBPipe is a utility in the mbtiles node.js module. You can install it via npm with the command npm install -g mbtiles.
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.
Our fork of AdvPNG adds stdin/stdout support to the original AdvPNG, making it suitable for use with mbpipe. Download, compile and install (./configure && make install) AdvPNG, then run
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.
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.
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.
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 optipng and pngcrush. You will have to find alternatives to these.