Skip to content
A vector topographic mapping tool, with layers available for NSW and Tasmania. Pre-built maps also available:
Ruby
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin change 'remove' command to 'delete' Feb 12, 2019
docs fix typo Feb 14, 2019
lib version bump Feb 13, 2019
COPYING added copyright and GPL Dec 10, 2011
README.md version bump Feb 13, 2019
history.md version bump Feb 13, 2019
nswtopo.gemspec move layers to separate nswtopo-layers repository Feb 11, 2019

README.md

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.

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

Windows

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

macOS

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

Linux

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

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 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.app/Contents/MacOS/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 DATA_25994.zip
  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 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
  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.

You can’t perform that action at this time.