export-bitmap Command

Usage

Supported Bitmap Types
Setting The Zoom Level Or The Map Scale
Setting The Width Or Height
Scaling

Web Maps
Troubleshooting

"Bitmap Too Big"

Exports the current map to a bitmap file.

Usage

export-bitmap 
   [file=<output file>] 
   [width=<bitmap width>] 
   [height=<bitmap height>] 
   [zoom=<zoom>] 
   [map-scale=<map scale>]
   [scale=<scale>] 
   [dpi=<DPI>]
   [aspect=<true/false>] 
   [subpixel=<subpixel precision>]
   [color-depth=<8 or 32>]
   [world-file=<true/false>] 
   [kml=<true/false>] 
   [ozi=<true/false>]

All parameters are optional:

file: specifies the exported bitmap file name. If not set, output/output.png will be used.
width: specifies the width of the bitmap. If not set, the width of the current map view will be used.
height: specifies the height of the bitmap. If not set, the height of the current map view will be used.
zoom: specifies the zoom level to use when exporting. If not set, the current map zoom level will be used.
map-scale: specifies the map scale to use when exporting. If not set, the map-scale will be calculated automatically. See zoom-map-scale Command for more information about map scales.
scale: specifies the graphics scale to use. If not set, the normal scale of 1 is used. Note that this parameter is equivalent to dpi - you can only set one of them, not both.
dpi: specifies the DPI resolution to use when exporting. If not set, 100 DPI is used. Note that this parameter is equivalent to scale - you can only set one of them, not both.
aspect: specifies whether to preserve the map view aspect ratio when determining the bitmap size. The aspect ratio is preserved by default.
subpixel: a positive integer value that is used as a scaling factor when rendering. The bitmap is then downscaled back to the original width and height, but with improved subpixel accuracy. The default value is 1 (no scaling and thus no subpixel accuracy). Recommended values are 2 or 3, anything larger increases the time and resources needed to generate the bitmap. See Maperitive Beta: Subpixel Accuracy article for more info.
color-depth: the color depth of the exported bitmap. Can be either 8 or 32 (which is the default). Only works for PNGs and it doesn't work when running Maperitive on Mono.
world-file: specifies whether to generate the World sidecar file. World file is not generated by default.
kml: specifies whether to generate a KML sidecar file which tells Google Earth how to georeference the bitmap. KML file is not generated by default.
ozi: specifies whether to generate an OziExplorer MAP file which tells OziExplorer how to georeference the bitmap. MAP file is not generated by default.

The command records a list of generated files. This list can be automatically forwarded to subsequent file commands like ftp-upload Command and zip Command.

Supported Bitmap Types

export-bitmap Command can export the map to the following bitmap types:

PNG
JPEG (JPG or JPEG extension)
GIF
TIFF (TIF or TIFF extension)
BMP
Enhanced Metafile (EMF extension)
Windows Metafile (WMF extension)

You can specify the bitmap type by specifying the file extension of the output file name:

export-bitmap file=output.tiff

Setting The Zoom Level Or The Map Scale

If you specify the zoom or map-scale parameters, Maperitive will adjust the bitmap size so that map bounds remain the same. Let's say you are viewing a map through a 1000x800 window on a zoom level 10 and you call

export-bitmap zoom=11

Increasing the zoom level by one will actually increase the map size by 100%, so you'll end up with an exported bitmap that's 2000 pixels wide and 1600 pixels tall.

You cannot specify both the zoom and the map scale at the same time.

Setting The Width Or Height

If you specify the width or the height parameter, Maperitive will adjust zoom level so that map bounds remain the same. Again, let's say you are viewing a map through a 1000x800 window on a zoom level 10 and you call

export-bitmap width=500

The resulting exported bitmap will be 500 pixels wide and 400 pixels tall and it will be rendered using the zoom level of 9.

Scaling

The scale parameter allows you to generate bitmaps with higher resolution, which is more suitable for printing maps (the other option is to use the export-svg Command). The below sample bitmap was generated with the scale value of 8:

Web Maps

export-bitmap Command uses all the map sources currently registered in the map. This includes web maps (like Mapnik or Osmarender), so if you have one of those, be warned that exporting can take a very long time since Maperitive has to download each tile from the web before it can generate an exported bitmap. In order not to overload OSM servers, Maperitive limits how fast web tiles can be downloaded.

Troubleshooting

"Bitmap Too Big"

There is a limit of how large a bitmap can be produced using the export-bitmap. To quote Bob Powel, an authority on GDI+ (the graphics engine Maperitive uses), "the maximum size of a bitmap is governed by the memory available to the application. Even in the best possible case of an application with very little used resources, the address space is limited so as you fill it up (2 gigs max for a 32 bit process I think) the maximum you can allocate is reduced."

If this limit has been reached, GDI+ reports a system exception which is then handled by the export-bitmap and a more user-friendly message is displayed: "Could not generate the bitmap, it is probably too big".

What can you do about it? Frankly, I'm not sure. It probably depends on how large your bitmap is. Here are some possible options:

Try to restart Maperitive and then export the bitmap as soon as you can.
Reduce the memory fragmentation - try to run Maperitive on a cleanly started machine, without other programs.
More RAM? (don't quote me on this)