Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

nswtopo – Vector Topographic Mapping Tool

Version 2.0.0

This software is a tool for downloading and compiling high-resolution vector topographic maps from internet map servers. Map layers are currently provided for NSW and Tasmanian topographic maps. Maps are produced in scalable vector graphics (SVG) format for use and further editing with vector graphics programs such as Inkscape or Illustrator. A number of other raster formats, including GeoTIFF, KMZ, mbtiles and Avenza Maps, can also be produced.

The software was originally designed for the production of rogaining maps and includes several useful features for this purpose (including control checkpoint layers, arbitrary map rotation and magnetic declination marker lines). However the software is also useful for anyone wanting to create custom NSW topo maps for outdoor recreation, particularly on mobile apps.

The nswtopo software is written in the Ruby language and runs as a command-line tool. Some familiarity with command-line usage and conventions is helpful.


The preferred operating system for nswtopo is a Unix-style OS such as Linux or macOS. These systems have conventional command-line interfaces. Operation in Windows is possible but you're more likely to encounter problems, since I do not frequently test the software in a Windows environment.

The following software is required in order to run nswtopo:

  • The Ruby programming language. You'll need at least Ruby 2.5.
  • The GDAL command-line utilities, version 2.3 or later, for geospatial data processing.
  • ImageMagick, a command-line image manipulation tool.
  • The Google Chrome web browser, for getting font information and rendering your map.

Some optional software helps with additional functionality:

  • A zip command utility (either zip or 7z), if you wish to produce KMZ maps.
  • SQLite, if you need to produce maps in mbtiles format.
  • pngquant, if you wish to produce indexed colour map images.
  • Inkscape, if you wish to make manual edits or additions to your map.

Finally, a geographic viewing or mapping program such as Google Earth Pro is useful for easily defining the area you wish to map, and for viewing your resulting map and other GPS data.

You can check that the required tools are correctly installed by using the following commands:

$ ruby --version
$ identify -version
$ gdalinfo --version

Each program should return version information if it's installed correctly.


  • A complete Ruby installation for Windows can be downloaded here (be sure to select Add Ruby executables to your PATH when installing).

  • Download a pre-built ImageMagick binary for Windows. Be sure to select add application directory to your system path and install legacy utilities when installing.

  • Install the GDAL utilities using the OSGeo4W installer. Use the advanced install option as only the GDAL package is required. When presented with the package list, select All -> Uninstall to deselect everything, then open Commandline Utilites and choose Install for the GDAL package. (Accept the required dependencies on the following page.) Make GDAL available on the command line with the following:

    setx PATH "%PATH%;C:\OSGeo4W64\bin"
    setx GDAL_DATA "C:\OSGeo4W64\share\gdal"
  • (Other ways of obtaining Windows GDAL utilities are listed here, but check the minimum version requirement.)

  • Download and install Google Chrome.

  • If you want to create KMZ maps, install 7-Zip and add its location to your PATH:

    setx PATH "%PATH%;C:\Program Files\7-Zip"

    Note: When using the Windows Command Prompt, I strongly recommend disabling QuickEdit mode in the Properties window to avoid frustration.


  • ImageMagick and GDAL can obtained for macOS by first setting up MacPorts, a macOS package manager; follow these instructions on the MacPorts site. After MacPorts is installed, use it to install the packages with sudo port install gdal and sudo port install imagemagick
  • Alternatively, you can download and install pre-built binaries; try here for GDAL, and the instructions here for ImageMagick. (This may or may not be quicker/easier than installing XCode and MacPorts!)
  • Type ruby -v in a terminal window to see whether a compatible Ruby version already exists. If not, you can install Ruby a number of ways, as explained here. (If you are using MacPorts, sudo port install ruby25 +nosuffix should also work.)
  • Download and install Google Chrome.


Dependencies should be easy to install on a Linux PC. The appropriate Ruby, ImageMagick and GDAL packages should all be available using your distro's package manager (Pacman, RPM, Aptitude, etc).


The easiest way to install the latest nswtopo release is with Ruby's built-in gem package manager:

$ gem install nswtopo

Verify that the nswtopo command is available in your terminal of choice by issuing the following command. You should see the current version number:

$ nswtopo -v

Installing Layers

Layer definitions are kept in a separate nswtopo-layers repository, enabling their maintenance independent of the nswtopo codebase. Install the layers as follows:

$ gem install nswtopo-layers

Refer to the repository for layer documentation.

Manual Installation

Installation via ruby gem is not strictly necessary. It's possible use the git repositories directly:

$ git clone

Add the program to your PATH: in Windows, by editing the environment variable in Control Panel; in Linux or macOS, by adding to your home directory's .profile file:

export PATH=/path/to/nswtopo/bin:$PATH

Finally, reload your terminal and install the layers:

$ git clone
$ nswtopo config --layer-dir nswtopo-layers/layers


Interaction with nswtopo is significantly revamped for version 2.0. Map data is now stored in a single file. A folder or configuration file is no longer required for each map. Separate commands are used to initialise the map file, add various layers and finally render to an output. Most commands take the following format:

$ nswtopo <command> [options] <map.tgz> [...]

Optional command settings can be given as short and/or long options (e.g. -b or --bounds), some of which take a value. The options you choose determine how the command is run. Commands will run with sensible defaults when no options are selected. Positioning of command options is permissive: you can add them before or after non-option arguments (such as layer names, filenames, etc).

The map.tgz argument is the filename of your map file. Any name can be used. The .tgz extension is suggested as it reflects the actual file format (a gzipped tar archive).


Help is available from the command line. If a command is issued without arguments, a short usage screen will be displayed as reminder. More detailed help is available using the --help option:

$ nswtopo --help
$ nswtopo <command> --help


General usage for the nswtopo program is described here. Detailed documentation for each of the available commands is also available:

  • init: initialise map bounds and scale
  • info: display map layers and metadata
  • add: add named map layer
  • contours: add contours from elevation data
  • spot-heights: add spot heights from elevation data
  • relief: add shaded relief
  • grid: add UTM grid
  • declination: add magnetic declination lines
  • controls: add rogaine control markers
  • overlay: add KML or GPX overlay
  • delete: delete map layer
  • render: render map in various formats
  • layers: list available map layers
  • config: configure nswtopo

Workflow for Rogaine Setters

The following workflow is suggested to create a rogaine map.

  1. Configure nswtopo, if you haven't already done so. Download and save the 9GB SPOT5 vegetation data for NSW. Set its location, and that of Google Chrome:

    $ nswtopo config --path /path/to/s5hgps_nsw_y20082012_bcvl0.tif nsw.vegetation-spot5
    $ nswtopo config --chrome "/Applications/Google Chrome"
  2. Set out the expected bounds of your course using the polygon tool in Google Earth, saving it as bounds.kml. Use a partially transparent style to make it easier to see. Configure a new map file with these bounds:

    $ nswtopo init --bounds bounds.kml preliminary.tgz
  3. Add the base topographic layers and a grid:

    $ nswtopo add preliminary.tgz nsw/vegetation-spot5
    $ nswtopo add preliminary.tgz nsw/topographic
    $ nswtopo grid preliminary.tgz
  4. Download digital elevation model (DEM) tiles for your area from the ELVIS website. Various DEM resolutions will be available depending on location. Prefer 2m and 5m tiles from NSW, with 1m ACT and NSW tiles if needed. Add contours to your map from this data:

    $ nswtopo contours -i 5 -x 50 --replace nsw.topographic.contours preliminary.tgz
  5. Create and view your preliminary map:

    $ nswtopo render preliminary.tgz svg tif
  6. Use the preliminary map to assist you in setting your rogaine. I recommend using a mobile mapping app such as Avenza Maps, Locus Map or Galileo Maps/Guru Maps. Save in the tif or zip format for Avenza Maps, or mbtiles format for Locus or Guru. During setting, use the app (or a handheld GPS unit) to record waypoints for the locations you flag.

  7. Use Google Earth to finalise your control locations. Name each waypoint with its control number. Add extra waypoints named HH (hash house), W (water drop) and ANC (all-night cafe), as appropriate. Save the waypoints as a controls.kml file.

  8. Again in Google Earth, mark out any boundaries and out-of-bounds areas using the polygon tool. Style them as they should appear on your map: I recommend filled black 30%. Save the boundaries as a boundaries.kml file.

  9. Create a new map with your desired dimensions:

    $ nswtopo init --bounds controls.kml --dimensions 210,297 --rotation magnetic rogaine.tgz

    If you have trouble fitting your controls to the map sheet, you can use the automatic rotation feature (--rotation auto) to minimise the map area.

  10. Add all your layers:

    $ nswtopo add rogaine.tgz nsw/vegetation-spot5
    $ nswtopo add rogaine.tgz nsw/topographic
    $ nswtopo contours -i 5 -x 50 --replace nsw.topographic.contours rogaine.tgz
    $ nswtopo spot-heights --replace rogaine.tgz
    $ nswtopo overlay rogaine.tgz boundaries.kml
    $ nswtopo relief rogaine.tgz
    $ nswtopo declination rogaine.tgz
    $ nswtopo controls rogaine.tgz controls.kml
  11. Optionally, you can add any unmarked tracks you've found on the course. Trace them out with Google Earth, or record them with a GPS or phone while setting. Then add them to your map:

    $ nswtopo overlay --stroke "#FF7518" --stroke-width 0.3 --stroke-dasharray 1.8,0.6 rogaine.tgz unmarked.kml

    (Use the --simplify option for tracks recorded with a GPS.)

  12. At this point you will need to render the map before adding peripheral information such as a map title, credits, safety information and control descriptions. There are two ways to do this:

    1. Render the map to a high-resolution raster and make the edits in a raster graphics editor such as Photoshop or GIMP. First choose a print resolution (say 600 ppi) to render the map in PNG format:

      $ nswtopo render --ppi 600 rogaine.tgz rogaine.png

      Open the PNG in the graphics editor, then add your information layers there. Export directly (usually in TIFF format) for sending to the printers.

    2. Keep the map in vector (SVG) format and make your edits in a vector graphics editor such as Inkscape.

      $ nswtopo render rogaine.tgz rogaine.svg

      After you've added your information layers, save the SVG and use nswtopo to render it to the final raster for printing:

      $ nswtopo render --external rogaine.svg --ppi 600 rogaine.tgz rogaine.tif

    I recommend the first method. Inkscape can be difficult to use. More importantly, it is not SVG standards-compliant, so some errors may be introduced. By using a raster graphics editor, you can be confident in the final appearance of the printed map. If your PC struggles with the image size at 600 ppi, a resolution as low as 300 ppi will still yield satisfactory results.


A vector topographic mapping tool, with layers available for NSW and Tasmania. Pre-built maps also available:







No packages published