Trevor Strieber edited this page Jun 2, 2018 · 11 revisions
Clone this wiki locally

This page is outdated (see #3438). Please don't trust it.

Mapnik Renderers

Mapnik supports a variety of rendering backends. See OutputFormats for comparisons of different output formats.

agg_renderer | Anti-Grain Geometry

The AGG renderer (Antigrain Geometry) is the primary renderer in Mapnik.

  • AGG 's fast scanline rendering with subpixel anti-aliasing is the standout reason for the beauty of Mapnik output.
  • Anti-Aliasing and Subpixel Rendering on Wikipedia
  • The AGG renderer's buffer can easily be encoded in a variety of formats. Currently Mapnik supports writing to png and jpeg.
  • Version 2.3 of the AGG C++ library is included/embedded within the source tree of Mapnik and compiled automatically during the Scons process.
  • The primary developer of AGG, Maxim Shemanarev, passed away in November 2013. Because AGG is open source, we happily maintain our own version with bugfixes.
  • Mapnik can also build against a system version of AGG, but this is NOT RECOMMENDED since packaged versions have likely not been updated with critical bug fixes

While Mapnik was the first to use AGG rendering for mapping, the AGG renderer is also now an optional rendering engine in the MapServer and MapGuide projects.

cairo_renderer | Cairographics

The Cairo renderer is an auxiliary renderer in Mapnik.

  • Cairo was added in r656 due to its similar reputation for high quality graphics output to various formats
  • Cairo has the '''added advantage''' of supporting both Vector and Raster output.
  • Mapnik can render to any surface supported by cairo, either directly or by rendering to a cairo context.
  • You can demo the PNG, JPEG, SVG, PDF, and PS formats using the OSM export tool
  • Cairo is optional during Mapnik Scons build process but is enabled automatically if found (using pkg-config).
  • Pkg-config must find libcairo as well as Cairomm(C++ bindings) and Pycairo (python bindings)
  • If Pkg-config is successful you will see the added compiler flags: -DHAVE_CAIRO -DHAVE_PYCAIRO

Python Example Code

Writing to SVG with Mapnik's Cairo renderer:

    import mapnik
    import cairo
    mapfile = 'mapfile.xml'
    projection = '+proj=latlong +datum=WGS84'
    mapnik_map = mapnik.Map(1000, 500)
    mapnik.load_map(mapnik_map, mapfile)
    bbox = mapnik.Envelope(-180.0,-90.0,180.0,90.0)
    # Write to SVG
    surface = cairo.SVGSurface('mapfile.svg', mapnik_map.width, mapnik_map.height)
    mapnik.render(mapnik_map, surface)
    # Or write to PDF
    surface = cairo.PDFSurface('mapfile.pdf', mapnik_map.width, mapnik_map.height)
    mapnik.render(mapnik_map, surface)
  • Note: Cairo can also write to PostScript and other image formats
  • Note: 'mapnik.render()' can also render to Cairo Contexts


The SVG renderer is written by Carlos López Garcés, started as part of GSOC 2010 and the "better printing project". The idea is that while the Cairo backend offers both PDF and SVG support, we can do better by having a custom implementation to handle things such as layer grouping, re-used of svg/bitmap symbols, and texts on paths. Only the basics are implemented at this point and those needed custom features are still a ways off, but the renderer has much promise. Currently is is not built by default but can be enabled with the build flag SVG_RENDERER=True.

The svg_renderer uses some very cool features of boost karma to generate SVG really fast and should be a good example of ways to leverage boost karma more in the future, potentially for other types of innovative vector output.


The Grid renderer is designed to output highly optimized feature "hit grids", known as UTFGrids (based on the final encoding format). It does this by leveraging and extending modular parts of the antigrain geometry library to rasterize feature id's into a buffer, then outputs metadata about the relevant feature attributes for the given ids, all enclosed within a compact, highly compressible json file using utf8 encoded feature ids for space efficiency. The grid_renderer was first available in the Mapnik 2.0.0 release.

The UTFGrid spec provides details of the format:

See the implementations list for examples:

Further References