Skip to content

Tutorial

Jump to bottom
Maxim Rebguns edited this page Jul 23, 2025 · 3 revisions

You will most likely be doing java -jar <filename> to run FreePaperMaps in the terminal. For the sake of brevity, I will refer to this command as freepapermaps.

Getting map data

To start, you need a .osm file, which is an XML file in the OpenStreetMap data format. This file has all the geographic data used to make the map. The easiest way to obtain an .osm file is to go to https://openstreetmap.org, zoom in on an area, and then click export. Beware that you will not be able to get anything larger than a small town using the export feature. If you need something larger, use https://planet.openstreetmap.org/

Using the CLI

To get a current list of all options, use freepapermaps --help.

The simplest thing you can do is make a map using the default style. Let's say your OSM file is called map.osm. You can run the following command:

freepapermaps -o map.svg -W 5in map.osm
  • -o map.svg specifies the name of the output file
  • -W 5in (capital W) tells FreePaperMaps to constrain the width of the map to 5 inches
  • map.osm is the name of the OSM input file

If you open the SVG file in an image viewer or web browser, you will see that something resembling a map was made. It is a very rudimentary wireframe, though. If you want something more elegant or meaningful, you will need to make a style.

Styling

FreePaperMaps supports styling using an XML style file. Create a new file with the .xml file extension using a text editor. Paste the following XML and save:

<?xml version="1.0" encoding="UTF-8"?>
<style>
  <setting k="background-color" v="#b764db"/>

  <selectors>
    <way id="building"><tag k="building" v=""/></way>
    <way id="path"><tag k="highway" v="footway"/></way>
  </selectors>

  <layers>
    <polyline ref="building" fill="#5a2172" stroke="#000000" width="0.5"/>
    <polyline ref="path" stroke="#5b0731" width="1"/>
  </layers>
</style>

Then, let's specify the style file when we run FreePaperMaps (in this case I called mine style.xml):

freepapermaps -o map.svg -W 5in -s style.xml map.osm

Here is an example from running this command on an OSM data file of Gonzales Elementary School in Santa Fe, New Mexico:

A map showing school grounds with a light purple background, dark purple buildings, and reddish-purple paths.

From this example, we learn that:

  • You can set the map's background color with the <setting> element
  • You can have one or more <way>s in <selectors> that match all ways with the given tags
  • Each <way> has an id which you can then reference in the <layers>
  • The <polyline> layer is used to draw a line that can also be filled
  • We can specify attributes for <layers>, such as stroke and width
  • Layers are drawn from first to last in order, so the building layer is below the path layer on the map

However, that is not it. FreePaperMaps supports drawing nodes as well. You can have more than one tag per selector. Also, <polyline> is not the only supported layer. Furthermore, the command-line interface has other options that I didn't discuss.

To learn more about FreePaperMaps, check out these resources:

  • The examples in the README
  • The options help by running freepapermaps --help
  • Other pages on this Wiki

Clone this wiki locally