nswtopo – Vector Topographic Mapping Tool

Version 3.1.3

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 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.

Prerequisites

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 3.1.4.
The GDAL command-line utilities, version 3.8 or later, for geospatial data processing.
The Google Chrome or Chromium web browser.

Some optional software helps with additional functionality:

A zip command utility (either zip or 7z), to produce KMZ maps.
SQLite, to produce maps in mbtiles format.
pngquant, to produce indexed colour map images.
ImageMagick, as an alternative to pngquant.
Inkscape, to make manual edits or additions to your map.
The HexaPDF gem, to georeference maps in PDF format.

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
$ gdalinfo --version

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

Windows

A complete Ruby installation for Windows can be downloaded here (be sure to select Add Ruby executables to your PATH 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 or Chromium.
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.

macOS

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 GDAL with sudo port install gdal
Another popular package manager for MacOS is Homebrew. Install GDAL with Homebrew using brew install gdal
Alternatively, you can download and install pre-built binaries for GDAL; try here. (This may or may not be quicker/easier than installing XCode and MacPorts!)
You can install Ruby a number of ways, as explained here. If you are using MacPorts, sudo port install ruby31 +nosuffix should also work. (Note that the ruby installation included in macOS is outdated and won't suffice.)
Download and install Google Chrome or Chromium.

Linux

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

Installation

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 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 .profile file:

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

Finally, reload your terminal and install the layers:

$ git clone https://github.com/mholling/nswtopo-layers.git
$ nswtopo config --layer-dir nswtopo-layers/layers

Usage

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

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

Commands

General usage for the nswtopo program is described here. Detailed documentation for each of the available commands is 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
move: move map layer
render: render map in various formats
layers: list available map layers
config: configure nswtopo

There are also some advanced tools for map developers:

inspect: inspect online and local data sources
scrape: download data from an ArcGIS REST layer

Workflow for Rogaine Setters

The following workflow is suggested to create a rogaine map.

Download and save the 9GB SPOT5 vegetation data for NSW, and set its location:

$ nswtopo config --path /path/to/s5hgps_nsw_y20082012_bcvl0.tif nsw.vegetation-spot5

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.

Nswtopo

Install / Use

README