Image IO

Mapnik supports reading and writing a variety of image formats.

These formats can be used as:

• Output formats for rendered map tiles
• Input formats for symbols or icons for symbolizers like the MarkersSymbolizer
• Input formats for the Raster datasource plugin. Note: if you are looking for what raster geodata formats are supported see also what the GDAL datasource plugin supports.

Format strings

Mapnik functions like mapnik.Image.save in python or mapnik::save_to_string in C++ accept a string for various image formats. The string assumes a format like:

  format:key=value

So, for example to create a full color, 32 bit PNG with a custom compression level you could do:

im = mapnik.Image(256,256)
im.save('file.png','png32:z=1')

Where z indicates the zlib encoding option and 1 indicates the value, in this case Z_BEST_SPEED or fast compression at the expense of larger size. See below for all PNG options. Also note that the above code creates a blank image - in a real world situation you would likely use mapnik.render to render map data to the image before saving it.

Supported Formats

As of Mapnik 2.3.x the following formats are supported:

Format	Read	Write
PNG	✓	✓
JPEG	✓	✓
TIFF	✓	experimental
WEBP	experimental	experimental

Default output details

In Mapnik >= 2.3.x by default:

• PNG output is paletted png with no greater than 256 colors (aka. png8)
• JPEG output uses a quality of 85.
• TIFF output uses PHOTOMETRIC_RGB and COMPRESSION_DEFLATE
• WEBP output uses WEBP_HINT_GRAPH as an image_hint to indicate to the encoder that the image is likely a discrete tone image (this may change in the future) and otherwise uses WEBP encoder defaults.

See the C++ image_util.cpp file for definitive defaults that are set for various encoders (as this wiki page may become out of date).

TIFF output options

TIFF output support in Mapnik is experimental and does not yet support any user-configurable options. It also does not output geotiff tags. These are features we may support in the future if there is interest

JPEG output options

JPEG output support in Mapnik is robust but simple. You can control just one option: the quality of the jpeg authored.

quality can be an integer value between 1 and 100 and can be passed to Mapnik by appending the number to the format string like:

• jpeg100 - will use a quality of 100
• jpeg50 - will use a quality of 50

PNG output options

There generally two types of PNG Mapnik can author: 1) reduced color paletted png, and 2) full color png. Mapnik also accepts a variety of key:value options that can customize the encoding and may apply to only one kind of PNG type.

So, the two main types can be requested using the formats names:

Name	Type
png, png8 , or png256	Creates reduced color/quantized paletted png NOTE: in Mapnik versions older than 2.3.x the png keyword used to map to full color png
png24 or png32	Creates full color png with millions of possible colors (and much larger file size)

And the key:value options can be controlled as follows:

Key	Value	Default	Description
c	integer, 0-256	256	Max number of colors to allow in the image, the fewer colors the smaller the final size, but potential lower visual quality. It is not recommended to reduce this value below 64 unless your rendered map style is very simple because otherwise adjacent tiles might end up with different final colors for the same original color.
z	integer, -1 to 9	-1 (Z_DEFAULT_COMPRESSION)	Level of compression - directly maps to zlib options: 0 is no compression, 1 is BEST_SPEED, and 9 is BEST_COMPRESSION (available in >= Mapnik 2.x)
t	integer, 0 to 2	2	Transparency mode: 0-no alpha, 1-binary alpha(0 or 255), 2-full alpha range, default is 2, works differently depending on whether you have requested full color png or paletted png. In >= Mapnik 2.2.x png32:t=0 will create full color png that is rgb and not rgba (more details. If using paletted png then this option is most meaningful for the octree encoder (see m=o below).
m	string, o or h	h	Applies to paletted png only. This is the quantization method: o stands for octree and h stands for hextree. The octree quantizer only supports limited alpha ranges and so for images with detailed alpha this may produce a poorer quality image. However the octree encoder is faster than the hextree encoder. The hextree encoder is default (as of >= Mapnik 2.3.x) because it produces the highest quality output - nearly visually identical to full color png. If your maps do no contain any alpha (e.g. they have a completely opaque background) then full color png or png8:m=o may produce smaller pngs at a faster rate, however we plan to optimize this pathway automatically in the future.
g	float, 1.0 - 2.0	2.0	Not likely that you need to change this option. It is the gamma correction for pixel arithmetic in hextree method. 1.0 means no gamma correction
s	string, default, filtered, huff, or rle	default	Not likely that you need to change this option. It is the ZLIB compression strategy. See zlib docs for more details (available in Mapnik >= 2.x)
e	string, miniz or libpng	'libpng`	Experimental: not recommended to set this option. e=miniz triggers using the experimental miniz encoder support instead of libpng. In some cases this encoder provides better encoding speeds with minor size differences but it also does not work fully yet (bugs we need to track down)

WEBP output options