nswtopo – Vector Topographic Mapping Tool
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 PATHwhen installing).
Download a pre-built ImageMagick binary for Windows. Be sure to select
add application directory to your system pathand
install legacy utilitieswhen installing.
Install the GDAL utilities using the OSGeo4W installer. Use the
advanced installoption as only the GDAL package is required. When presented with the package list, select
All -> Uninstallto deselect everything, then open
Commandline Utilitesand choose
Installfor 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 gdaland
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!)
ruby -vin 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 +nosuffixshould 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
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.
Installation via ruby gem is not strictly necessary. It's possible use the git repositories directly:
$ git clone https://github.com/mholling/nswtopo.git
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
Finally, reload your terminal and install the layers:
$ git clone https://github.com/mholling/nswtopo-layers.git $ 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.
--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).
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
$ 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.
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.app/Contents/MacOS/Google Chrome"
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
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
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 DATA_25994.zip
Create and view your preliminary map:
$ nswtopo render preliminary.tgz svg tif
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.
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
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
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.
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 DATA_25994.zip $ nswtopo spot-heights --replace nsw.topographic.spot-heights rogaine.tgz DATA_25994.zip $ nswtopo overlay rogaine.tgz boundaries.kml $ nswtopo relief rogaine.tgz DATA_25994.zip $ nswtopo declination rogaine.tgz $ nswtopo controls rogaine.tgz controls.kml
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
--simplifyoption for tracks recorded with a GPS.)
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:
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.
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.