nswtopo 2.0.0.pre.beta1

data/bin/nswtopo

@@ -0,0 +1,430 @@
+#!/usr/bin/env ruby
+
+# Copyright 2011-2019 Matthew Hollingworth
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+begin
+  require 'open3'
+  require 'optparse'
+  require 'pathname'
+  require 'etc'
+  require 'yaml'
+  require 'rdoc'
+  require_relative '../lib/nswtopo.rb'
+  require_relative '../lib/nswtopo/help_formatter.rb'
+
+  extend NSWTopo::Log
+  Thread::report_on_exception = false
+
+  GDAL_VERSION = begin
+    stdout, * = Open3.capture3 "gdalinfo", "--version"
+    stdout[/\d+(?:\.\d+){1,2}/]
+  rescue Errno::ENOENT
+    log_abort "GDAL not installed"
+  end
+
+  case
+  when (RUBY_VERSION.split(/\D+/).take(3).map(&:to_i) <=> [2,5]) < 0
+    log_abort "ruby 2.5 or greater required"
+  when !Zlib.const_defined?(:GzipFile)
+    log_abort "ruby with GZIP_SUPPORT required"
+  when (GDAL_VERSION.split(/\D+/).take(3).map(&:to_i) <=> [2,3]) < 0
+    log_abort "GDAL 2.3 or greater required"
+  end
+
+  digits = '\d+(?:_\d+)*'
+  float  = "[-+]?(?:#{digits}(?=(.)?)(?:\\.(?:#{digits})?)?|\\.#{digits})(?:[eE][-+]?#{digits})?"
+  coords = "#{float},#{float}"
+
+  PositiveInt   = /\A#{digits}\z/
+  PositiveFloat = /\A#{float}\z/
+  NonNegFloat   = 0..Float::INFINITY
+  Dimensions    = /\A#{float},#{float}\z/
+  Margins       = /\A#{float}(?:,#{float})?\z/
+  CoordList     = /\A#{coords}(?:,#{coords})*\z/
+  Rotation      = /\A(?:#{float}|magnetic|auto)\z/
+  AltitudeAngle = 0..90
+  Opacity       = /\A#{float}%?\z/
+  DashArray     = /\A#{float}(?:(?:,#{float})*|(?: #{float})*)\z/
+
+  OptionParser.accept PositiveInt, PositiveInt do |string|
+    raise OptionParser::InvalidArgument, string unless string.to_i.positive?
+    string.to_i
+  end
+
+  OptionParser.accept PositiveFloat, PositiveFloat do |string|
+    raise OptionParser::InvalidArgument, string unless string.to_f.positive?
+    string.to_f
+  end
+
+  OptionParser.accept NonNegFloat, PositiveFloat do |string|
+    raise OptionParser::InvalidArgument, string if string.to_f.negative?
+    string.to_f
+  end
+
+  OptionParser.accept Dimensions, Dimensions do |string|
+    dimensions = string.split(?,).map(&:to_f)
+    raise OptionParser::InvalidArgument, string unless dimensions.all?(&:positive?)
+    dimensions
+  end
+
+  OptionParser.accept Margins, Margins do |string|
+    margins = string.split(?,).map(&:to_f)
+    raise OptionParser::InvalidArgument, string if margins.any?(&:negative?)
+    margins.one? ? margins * 2 : margins
+  end
+
+  OptionParser.accept CoordList, CoordList do |string|
+    string.split(?,).map(&:to_f).each_slice(2).to_a
+  end
+
+  OptionParser.accept Rotation, Rotation do |string|
+    "magnetic" == string ? string : "auto" == string ? string : string.to_f
+  end
+
+  OptionParser.accept AltitudeAngle, PositiveFloat do |string|
+    raise OptionParser::InvalidArgument, string unless AltitudeAngle === string.to_f
+    string.to_f
+  end
+
+  OptionParser.accept Pathname do |string|
+    path = Pathname(string).expand_path
+    raise OptionParser::InvalidArgument, string unless path.exist?
+    path
+  end
+
+  OptionParser.accept Colour do |string|
+    string == "none" ? string : Colour.new(string.downcase).to_s
+  rescue Colour::Error
+    raise OptionParser::InvalidArgument, string
+  end
+
+  OptionParser.accept Opacity, Opacity do |string|
+    opacity = string.end_with?(?%) ? Float(string.chomp ?%) * 0.01 : Float(string)
+    raise OptionParser::InvalidArgument, string unless (0..1) === opacity
+    opacity
+  end
+
+  OptionParser.accept DashArray, DashArray do |string|
+    values = string.split(/[, ]/).map(&:to_f)
+    raise OptionParser::InvalidArgument, string if values.any?(&:negative?)
+    values.join ?\s
+  end
+
+  ansi = lambda do |string|
+    string.to_s.gsub(/\*([-a-zA-Z0-9]+)\*/) do
+      "\e[1m%s\e[0m" % $1
+    end.gsub(/_([-a-zA-Z0-9]+)_/) do
+      "\e[4m%s\e[0m" % $1
+    end.gsub(/~([-a-zA-Z0-9]+)~/) do
+      "\e[3m%s\e[0m" % $1
+    end
+  end
+
+  plain = lambda do |string|
+    string.to_s.gsub(/\*([-a-zA-Z0-9]+)\*/) { $1 }.gsub(/_([-a-zA-Z0-9]+)_/) { $1 }.gsub(/~([-a-zA-Z0-9]+)~/) { $1 }
+  end
+
+  base_parser = OptionParser.new do |parser|
+    parser.separator "  options:"
+    parser.banner = <<~EOF
+      *nswtopo* - download and create vector topographic maps
+        usage: _nswtopo_ [~options~] [<command> ...]
+        commands:
+          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
+        command help: _nswtopo_ <command> --help
+    EOF
+    parser.on "-v", "--version",                   "show version information" do
+      puts NSWTopo::VERSION
+      exit
+    end
+    parser.on "-q", "--quiet",                     "suppress non-error output" do
+      $stdout = File.open(File::NULL, "w")
+    end
+    parser.on "-c", "--config   <path>", Pathname, "load extra configuration" do |path|
+      NSWTopo::Config.extra_path = path
+    end
+    parser.on "-h", "--help",                      "show general help" do
+      puts $stdout.tty? ? ansi[parser] : plain[parser]
+      doc = Pathname(__dir__).parent / "docs" / "README.md"
+      puts nil, RDoc::Markdown.parse(doc.read encoding: Encoding::UTF_8).accept(HelpFormatter.new $stdout.tty?)
+      exit
+    end
+  end
+  base_parser.order!
+
+  command, options = ARGV.shift, Hash.new
+  command_parser = OptionParser.new do |parser|
+    parser.separator "  options:"
+
+    case command
+    when "init"
+      parser.banner = <<~EOF
+        *nswtopo* *init* - initialise map bounds and scale
+          usage: _nswtopo_ _init_ [~options~] <map.tgz>
+      EOF
+      parser.on "-s", "--scale       <scale>",        PositiveInt,  "scale of map (default 25000)"
+      parser.on "-b", "--bounds      <bounds.kml>",   Pathname,     "bounds for map as KML or GPX file"
+      parser.on "-c", "--coords      <x1,y1,...>",    CoordList,    "bounds for map as one or more WGS84",
+                                                                    "longitude/latitude pairs" 
+      parser.on "-d", "--dimensions  <width,height>", Dimensions,   "dimensions of map in mm"
+      parser.on "-m", "--margins     <x[,y]>",        Margins,      "map margins in mm"
+      parser.on "-r", "--rotation    <rotation>",     Rotation,     "map rotation angle in clockwise",
+                                                                    "degrees, 'auto' or 'magnetic'"
+      parser.on "-o", "--overwrite",                                "overwrite existing map file"
+
+    when "info"
+      parser.banner = <<~EOF
+        *nswtopo* *info* - display map layers and metadata
+        usage: _nswtopo_ _info_ [~options~] <map.tgz>
+      EOF
+      parser.on "-e", "--empty", "show empty layers"
+
+    when "add"
+      parser.banner = <<~EOF
+        *nswtopo* *add* - add named map layer
+          usage: _nswtopo_ _add_ [~options~] <map.tgz> <layer> [<layer> ...]
+      EOF
+      parser.on "-r", "--resolution  <resolution>", PositiveFloat, "raster layer resolution in metres"
+      parser.on "-p", "--path        <path>",       Pathname,      "source data path for layer"
+      parser.on "-a", "--after       <layer>",                     "insert after specified layer"
+      parser.on "-b", "--before      <layer>",                     "insert before specified layer"
+      parser.on "-c", "--replace     <layer>",                     "replace specified layer"
+      parser.on "-o", "--overwrite",                               "overwrite layer if it already exists"
+
+    when "contours"
+      parser.banner = <<~EOF
+        *nswtopo* *contours* - add contours from elevation data
+          usage: _nswtopo_ _contours_ [~options~] <map.tgz> <dem.zip>
+      EOF
+      parser.on "-i", "--interval       <interval>", PositiveInt,   "contour interval in metres (default %s)" % NSWTopo::Contour::DEFAULTS["interval"]
+      parser.on "-x", "--index          <index>",    PositiveInt,   "index interval in metres"
+      parser.on "-s", "--smooth         <radius>",   NonNegFloat,   "DEM smoothing radius in mm (default %s)" % NSWTopo::Contour::DEFAULTS["smooth"]
+      parser.on "-t", "--thin",                                     "thin intermediate contours in steep areas"
+      # parser.on "-d", "--density        <density>",  PositiveFloat, "maximum lines/mm before thinning occurs"
+      # parser.on "-m", "--min-length     <length>",   PositiveFloat, "minimum length before contour thinning in mm"
+      parser.on       "--no-depression",                            "don't show or clean depression contours"
+      parser.on "-k", "--knolls         <size>",     NonNegFloat,   "minimum knoll size in mm (default %s)" % NSWTopo::Contour::DEFAULTS["knolls"]
+      parser.on "-a", "--after          <layer>",                   "insert after specified layer"
+      parser.on "-b", "--before         <layer>",                   "insert before specified layer"
+      parser.on "-c", "--replace        <layer>",                   "replace specified layer"
+      parser.on       "--stroke         <colour>",   Colour,        "stroke colour (name or RGB triplet)"
+      parser.on       "--stroke-width   <width>",    PositiveFloat, "stroke width in mm"
+      parser.on       "--fill           <colour>",   Colour,        "label colour (defaults to stroke colour)"
+
+    when "spot-heights"
+      parser.banner = <<~EOF
+        *nswtopo* *spot-heights* - add spot heights from elevation data
+          usage: _nswtopo_ _spot-heights_ [~options~] <map.tgz> <dem.zip>
+      EOF
+      parser.on "-s", "--smooth   <radius>",         NonNegFloat,        "DEM smoothing radius in mm (default %s)" % NSWTopo::Spot::DEFAULTS["smooth"]
+      parser.on       "--spacing  <spacing>",        PositiveFloat,      "minimum spot spacing in mm (default %i)" % NSWTopo::Spot::DEFAULTS["spacing"]
+      parser.on "-p", "--prefer   <knolls|saddles>", %w[knolls saddles], "preferred spot locations"
+      parser.on "-a", "--after    <layer>",                              "insert after specified layer"
+      parser.on "-b", "--before   <layer>",                              "insert before specified layer"
+      parser.on "-c", "--replace  <layer>",                              "replace specified layer"
+
+    when "relief"
+      parser.banner = <<~EOF
+        *nswtopo* *relief* - add shaded relief
+          usage: _nswtopo_ _relief_ [~options~] <map.tgz> <dem.zip>
+      EOF
+      parser.on "-r", "--resolution  <resolution>", PositiveFloat, "resolution in metres (default %i)" % NSWTopo::Relief::DEFAULTS["resolution"]
+      parser.on "-o", "--opacity     <opacity>",    Opacity,       "opacity (default %s)" % NSWTopo::Relief::DEFAULTS["opacity"]
+      parser.on "-a", "--altitude    <altitude>",   AltitudeAngle, "altitude angle in degrees (default %i)" % NSWTopo::Relief::DEFAULTS["altitude"]
+      parser.on "-z", "--azimuth     <azimuth>",    Float,         "azimuth in degrees (default %i)" % NSWTopo::Relief::DEFAULTS["azimuth"]
+      parser.on "-s", "--sources     <sources>",    PositiveInt,   "number of light sources (default %i)" % NSWTopo::Relief::DEFAULTS["sources"]
+      parser.on "-y", "--yellow      <fraction>",   Opacity,       "yellow illumination as a fraction",
+                                                                   "of shading (default %s)" % NSWTopo::Relief::DEFAULTS["yellow"]
+      parser.on "-f", "--factor      <factor>",     PositiveFloat, "exaggeration factor (default %s)" % NSWTopo::Relief::DEFAULTS["factor"]
+
+    when "grid"
+      parser.banner = <<~EOF
+        *nswtopo* *grid* - add UTM grid
+          usage: _nswtopo_ _grid_ [~options~] <map.tgz>
+      EOF
+      parser.on "-i", "--interval  <interval>", PositiveFloat, "interval between grid lines in",
+                                                               "metres (default %i)" % NSWTopo::Grid::DEFAULTS["interval"]
+
+    when "declination"
+      parser.banner = <<~EOF
+        *nswtopo* *declination* - add magnetic declination lines
+          usage: _nswtopo_ _declination_ [~options~] <map.tgz>
+      EOF
+      parser.on "-a", "--angle    <angle>",   Float,         "magnetic declination in clockwise degrees",
+                                                             "(calculated automatically by default)"
+      parser.on "-s", "--spacing  <spacing>", PositiveFloat, "spacing of lines in mm (default %i)" % NSWTopo::Declination::DEFAULTS["spacing"]
+      parser.on "-o", "--offset   <offset>",  Float,         "rightwards offset of lines in mm"
+      parser.on "-r", "--arrows   <arrows>",  PositiveFloat, "spacing of arrows in mm (default %i)" % NSWTopo::Declination::DEFAULTS["arrows"]
+      parser.on       "--stroke   <colour>",  Colour,        "stroke colour (name or RGB triplet)"
+
+    when "controls"
+      parser.banner = <<~EOF
+        *nswtopo* *controls* - add rogaine control markers
+          usage: _nswtopo_ _controls_ [~options~] <map.tgz> <controls.gpx>
+      EOF
+      parser.on "-d", "--diameter   <diameter>",  PositiveFloat, "diameter of markers in mm (default %s)" % NSWTopo::Control::DEFAULTS["diameter"]
+      parser.on "-s", "--spot",                                  "add spots at centres"
+      parser.on "-c", "--colour     <colour>",    Colour,        "colour of markers and labels",
+                                                                 "(name or RGB triplet)"
+      parser.on "-f", "--font-size  <font-size>", PositiveFloat, "font size for labels in mm"
+
+    when "overlay"
+      parser.banner = <<~EOF
+        *nswtopo* *overlay* - add KML or GPX overlay
+          usage: _nswtopo_ _overlay_ [~options~] <map.tgz> <overlay.kml>
+      EOF
+      parser.on       "--opacity          <opacity>", Opacity,       "layer opacity (between 0 and 1)"
+      parser.on       "--stroke           <colour>",  Colour,        "stroke colour (name or RGB triplet)"
+      parser.on       "--stroke-width     <width>",   PositiveFloat, "stroke width in mm"
+      parser.on       "--stroke-opacity   <opacity>", Opacity,       "stroke opacity"
+      parser.on       "--stroke-dasharray <mm,...>",  DashArray,     "stroke dash sequence in mm"
+      parser.on       "--stroke-linecap   <butt|round|square>", %w[butt round square],
+                                                                     "stroke linecap value"
+      parser.on       "--fill             <colour>",  Colour,        "polygon fill colour"
+      parser.on       "--fill-opacity     <opacity>", Opacity,       "polygon fill opacity"
+      parser.on "-s", "--simplify",                                  "apply track simplification"
+      parser.on "-t", "--tolerance        <metres>",  PositiveFloat, "track simplifiction tolerance in metres",
+                                                                     "(scale-appropriate value used by default)"
+      parser.on "-a", "--after            <layer>",                  "insert after specified layer"
+      parser.on "-b", "--before           <layer>",                  "insert before specified layer"
+      parser.on "-c", "--replace          <layer>",                  "replace specified layer"
+
+    when "delete"
+      parser.banner = <<~EOF
+        *nswtopo* *delete* - delete map layers
+          usage: _nswtopo_ _delete_ [~options~] <map.tgz> <layer> [<layer> ...]
+      EOF
+
+    when "render"
+      parser.banner = <<~EOF
+        *nswtopo* *render* - render map in various formats
+          usage: _nswtopo_ _render_ [~options~] <map.tgz> [<format-or-path> ...]
+          formats: #{NSWTopo::Formats.extensions.sort.join ?\s}
+          default: svg
+      EOF
+      parser.on "-p", "--ppi        <ppi>",     PositiveInt, "resolution for raster formats in pixels",
+                                                             "per inch (default %i)" % NSWTopo::Formats::PPI
+      parser.on "-z", "--zoom       <zoom>",    Integer,     "maximum mbtiles zoom level (default %i)" % NSWTopo::Formats::Mbtiles::ZOOM
+      parser.on "-d", "--dither",                            "use indexed colour for raster formats"
+      parser.on "-w", "--worldfile",                         "save additional projection (.prj) and",
+                                                             "world file (.wld) for raster formats"
+      parser.on "-o", "--overwrite",                         "overwrite existing output files"
+      parser.on "-e", "--external   <map.svg>", Pathname,    "render from externally edited SVG"
+      parser.on "-f", "--force",                             "force regeneration of cached SVG"
+
+    when "layers"
+      parser.banner = <<~EOF
+        *nswtopo* *layers* - list available map layers
+          usage: _nswtopo_ _layers_ [~options~]
+      EOF
+
+    when "config"
+      parser.banner = <<~EOF
+        *nswtopo* *config* - configure nswtopo
+          usage: _nswtopo_ _config_ [~options~] [<layer>]
+      EOF
+      parser.on "-d", "--delete        <name>",                      "delete configuration setting"
+      parser.on "-c", "--chrome        <path>",       Pathname,      "set path for Google Chrome"
+      parser.on "-f", "--firefox       <path>",       Pathname,      "set path for Firefox"
+      parser.on "-p", "--path          <path>",       Pathname,      "set path for given layer"
+      parser.on "-r", "--resolution    <resolution>", PositiveFloat, "set resolution for given layer"
+      parser.on       "--layer-dir     <path>",       Pathname,      "set an extra layer directory"
+      parser.on       "--[no-]labelling",                            "enable or disable map labelling"
+
+    when nil
+      raise OptionParser::MissingArgument, "no command specified"
+
+    else
+      raise OptionParser::InvalidArgument, command
+    end
+
+    parser.on "-h", "--help",  "show help for this command" do
+      puts $stdout.tty? ? ansi[parser] : plain[parser]
+      doc = Pathname(__dir__).parent / "docs" / "#{command}.md"
+      puts nil, RDoc::Markdown.parse(doc.read encoding: Encoding::UTF_8).accept(HelpFormatter.new $stdout.tty?)
+    rescue Errno::ENOENT
+    ensure
+      exit
+    end
+  rescue OptionParser::ParseError => error
+    warn ansi[base_parser] if $stderr.tty?
+    raise error.message
+  end
+  command_parser.parse! into: options
+
+  case command
+  when "layers"
+    raise OptionParser::NeedlessArgument, ARGV if ARGV.any?
+    NSWTopo.layers options
+    exit
+  when "config"
+    layer = ARGV.shift
+    raise OptionParser::NeedlessArgument, ARGV if ARGV.any?
+    NSWTopo.config *layer, **options
+    exit
+  end
+
+  raise OptionParser::MissingArgument, "no map path specified" if ARGV.empty?
+  tgz_path = Pathname(ARGV.shift)
+
+  begin
+    in_path = case command
+    when "init"
+      raise "#{tgz_path} already exists" if !options.delete(:overwrite) && tgz_path.exist?
+    else
+      raise "no such file #{tgz_path}" unless tgz_path.exist?
+      raise "#{tgz_path} is not a file" unless tgz_path.file?
+      tgz_path
+    end
+
+    command = command.tr ?-, ?_
+    arity, error = NSWTopo.method(command).arity, nil
+
+    NSWTopo::Archive.open(tgz_path, *in_path) do |archive|
+      args = [archive, *ARGV, options]
+      case
+      when arity >= 0 && args.length > arity
+        raise OptionParser::NeedlessArgument, ARGV.last(args.length - arity).join(?\s)
+      when arity >= 0 ? args.length < arity : args.length + arity + 1 < 0
+        raise OptionParser::MissingArgument
+      end
+
+      NSWTopo.send command, *args
+    rescue NSWTopo::PartialFailureError => error
+    end
+    raise error.message if error
+  end
+rescue OptionParser::ParseError => error
+  warn ansi[command_parser] if $stderr.tty?
+  log_abort error.message
+rescue Interrupt
+  abort $stderr.tty? ? "\r\e[K\e[31mnswtopo:\e[0m interrupted" : "nswtopo: interrupted"
+rescue RuntimeError => error
+  log_abort error.message
+end

data/docs/README.md

@@ -0,0 +1,78 @@
+# Description
+
+Use *nswtopo* to create vector topographic maps of NSW and other states. Various *commands* allow you to initialise your map, add layers and render outputs in a number of formats. Pre-designed map layers download topographic data from internet maps servers and local sources.
+
+# Commands
+
+Help screens are available describing usage for each commands. Use the `--help` option with the command:
+
+```
+$ nswtopo init --help
+```
+
+# Configuration
+
+An important initial step is to configure the location of *Google Chrome* on your PC. Chrome is required for rendering the map in most formats. Use the *configure* command to set the path:
+
+```
+$ nswtopo config --chrome "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+nswtopo: configuration updated
+```
+
+Use forward slashes for paths, even on Windows.
+
+# Map Files
+
+Most commands need a map file to work on. Name this file anything you want. A `.tgz` extension is suggested, as the file is in *gzipped tar* archive format. All map contents are contained within the file, so a separate directory per map is not necessary.
+
+# Example
+
+A typical map creation sequence might look as follows. We initialise the map from a bounds file, add several layers and finally produce an output SVG:
+
+```
+$ nswtopo init -b bounds.kml map.tgz
+scale:      1:25000
+dimensions: 433mm × 509mm
+extent:     10.8km × 12.7km
+area:       138.0km²
+rotation:   0.0°
+```
+
+```
+$ nswtopo add map.tgz nsw/vegetation-spot5
+nswtopo: added layer: nsw.vegetation-spot5
+```
+
+```
+$ nswtopo add map.tgz nsw/topographic
+nswtopo: added layer: nsw.topographic.plantation-horticulture
+nswtopo: added layer: nsw.topographic.urban-areas
+...
+nswtopo: added layer: nsw.topographic.spot-heights
+```
+
+```
+$ nswtopo declination map.tgz
+nswtopo: added layer: declination
+```
+
+```
+$ nswtopo add map.tgz controls.gpx
+nswtopo: added layer: controls
+```
+
+```
+$ nswtopo relief map.tgz DATA_25994.zip
+nswtopo: added layer: relief
+```
+
+```
+$ nswtopo contours -i 5 -x 50 --replace nsw.topographic.contours map.tgz DATA_25994.zip
+nswtopo: added layer: contours
+```
+
+```
+$ nswtopo render map.tgz svg
+nswtopo: created map.svg
+```
+

data/docs/add.md

@@ -0,0 +1,49 @@
+# Description
+
+Use this command to add named layers to the map from among those distributed with *nswtopo*. Refer to the website for a description of the various layers. Use the `nswtopo layers` command to display a list of available layers.
+
+Layers are arranged hierarchically, with some layers being shorthand for a collection of other layers. For example, the `nsw/topographic` layer contains a large number of component layers, such as `nsw/topographic/roads`, `nsw/topographic/watercourses` etc.
+
+The forward-slash character is used indicate the nested folder structure of these layers. However, once added to the map, these layers are renamed with periods (`nsw.topographic.watercourses`), and the use of period and slash characters is interchangeable.
+
+# Options
+
+Some layers, such as vegetation layers, require a dataset to be present on your computer. Specify the location of the dataset with the `--path` option. The path can be absolute, or relative to the working directory.
+
+Raster layers (vegetation, shaded relief) typically have an appropriate image resolution set for that data. If desired, you can choose a different value using the `--resolution` option. Resolution is in metres per pixel, indicating the dataset quality rather than an output resolution such as pixels per inch.
+
+For repeated use, it's easier to set the path or resolution for a layer in a permanent configuration file. Use the *config* command for this task.
+
+# Positioning Layers
+
+By default, layers are added to the map in an appropriate position for the type: vegetation and aerial layers first, followed by topographic feature layers, overlays, shaded relief, grid, declination and controls.
+
+To instead select a specific position for the new layer, use the `--after` or `--before` option with an existing layer name. For example, to insert a KML overlay between existing topographic layers:
+
+```
+$ nswtopo add --after nsw.topographic.urban-areas map.tgz new-suburb.kml
+```
+
+# Other Layers
+
+While *grid*, *declination*, overlay and *controls* layers each have a dedicated command, it's possible to add them directly if you don't need to change default settings:
+
+```
+$ nswtopo add map.tgz out-of-bounds.kml grid controls.gpx
+```
+
+Georeferenced rasters (e.g. GeoTIFFs) can also be added directly:
+
+```
+$ nswtopo add map.tgz underlay.tif
+```
+
+For advanced users, custom layer definitions can added by referencing the `.yml` definition file:
+
+```
+$ nswtopo add --after nsw.topographic.water-areas map.tgz bathymetry.yml
+```
+
+# Failed Layers
+
+Map servers can sometimes be uncooperative, resulting in layers which fail to download. In this event, simply run the `add` command again to retry the failed layers. Existing layers will not be re-downloaded.

data/docs/config.md

@@ -0,0 +1,24 @@
+# Description
+
+Configure and view permanent *nswtopo* settings using the *config* command. For example, to set the *Google Chrome* path for rendering maps:
+
+```
+$ nswtopo config --chrome "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+nswtopo: configuration updated
+```
+
+To set the path for a vegetation dataset:
+
+```
+$ nswtopo config --path ~/SPOT5/s5hgps_nsw_y20082012_bcvl0.tif nsw.vegetation-spot5
+nswtopo: configuration updated
+```
+
+To review your current configuration:
+
+```
+$ nswtopo config
+chrome: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+nsw.vegetation-spot5:
+  path: "/Users/matthew/SPOT5/s5hgps_nsw_y20082012_bcvl0.tif"
+```

data/docs/contours.md

@@ -0,0 +1,37 @@
+# Description
+
+Generate contour lines directly from a Digital Elevation Model (DEM) with the *contours* command. Any DEM in a planar projection can be used, but high-resolution data is needed for good results.
+
+# Obtaining the DEM
+Use the *ELVIS* website [http://elevation.fsdf.org.au] to download DEM tiles for any NSW location. The NSW 2-metre and 5-metre tiles are ideal. 1-metre NSW and ACT tiles also work but are more detailed than necessary. (Do not download Geoscience Australia tiles or point-cloud data.)
+
+DEM tiles from the ELVIS website are delivered as doubly-zipped files. It's not necessary to unzip the download, although unzipping the first level to a folder will improve processing time.
+
+# Contour Configuration
+Choose a contour interval in metres using the `--interval` option. A five metre interval is recommended as it conveys excellent detail and is not too dense for 1:25000 maps in most areas. Specify an index contour interval with the `--index` option.
+
+Noise in raw elevation data usually produces unsuitably rough contour lines. Some smoothing of the DEM removes most such artefacts. A default smoothing radius of 0.2mm is applied, configurable with the `--smooth` option. Increase the radius to produce smoother contours at the expense of detail.
+
+# Layer Position
+
+Use an `--after`, `--before` or `--replace` option to insert the contours in an appropriate layer position. You will most likely want to replace an existing contour layer:
+
+```
+$ nswtopo contours --replace nsw.topographic.contours map.tgz DATA_25994.zip
+```
+# Style
+
+Contours are rendered in brown at a thickness of 0.08mm. Change line colour with `--stroke`, thickness with `--stroke-width` and label colour with `--fill`. Colour can be an *RGB triplet* (e.g. *800080*) or *web colour* name (e.g. *purple*).
+
+# Contour Thinning
+A small contour interval can produce very dense contours in steep terrain. An advanced `--thin` option is available to selectively remove contours in steep areas such as cliffsides. It emulates a manual contour thinning technique. An index multiple of eight (e.g. 5m contours with 40m index contours) produces the most aesthetic results.
+
+(*GDAL* with *SpatiaLite* and *GEOS* support is required to perform contour thinning.)
+
+# Knolls & Depressions
+
+Contours generated from a DEM can include depression artefacts, most noticeabley at pinch-points in flat or closed-in watercourses. These do not usually represent true depression contours, which are rare. Any isolated depression contours are automatically detected and removed. All nested depression contours are retained and rendered as true depression contours. This behaviour can be disabled with the `--no-depression` option.
+
+Contours for tiny knolls are also removed. Use the `--knolls` option to specify the minimum size for knolls to be retained.
+
+When creating contours from a DEM, it's recommended to also generate a new spot heights layer. Use the *spot-heights* command to generate them using the same DEM.

data/docs/controls.md

@@ -0,0 +1,9 @@
+# Description
+
+Add rogaine controls to a map with the *controls* command. Collect your control waypoints in a GPX or KML file. *Google Earth* is useful for managing and naming your waypoints during course-setting.
+
+# Naming
+Any waypoint with a two- or three-digit name will be identified and marked as a control. Name a waypoint as *HH* or *ANC* to identify it as the hash house or all-night cafe. Suffix any control name with *W*, or have a separate waypoint so named, to identify it as a water drop.
+
+# Styling
+Controls are marked and labelled in the conventional style. You can change aspects of this style with the `--diameter`, `--colour` and `--font-size` options. The `--spot` option adds a centre spot for each control.

data/docs/declination.md

@@ -0,0 +1,15 @@
+# Description
+
+Use the *declination* command to add lines of magnetic declination to the map. These are useful primarily in rogaining maps, where they facilitate compass bearings.
+
+# Declination Angle
+
+The magnetic declination angle is obtained from the NOAA online calculator using the World Magnetic Model. An accuracy of ±0.5° is typical. In the event that the calculator is offline, you can provide a declination angle manually using the `--angle` option.
+
+# Appearance
+
+Declination lines are spaced at one-kilometre intervals, or according to the `--spacing` option if passed. Small directional arrows are provided periodically along each line at 160mm intervals.
+
+The `--offset` option shifts the lines along the horizontal, if fine-tuning is required.
+
+Change colour using the `--stroke` option, with an *RGB triplet* (e.g. *800080*) or *web colour* name (e.g. *purple*).

data/docs/delete.md

@@ -0,0 +1,15 @@
+# Description
+
+Use the *delete* command to delete layers from the map. Specify the name of the layer or layers you wish to delete:
+
+```
+$ nswtopo delete map.tgz nsw.relief grid
+```
+
+When deleting multiple layers, a form of wildcard is also available:
+
+```
+$ nswtopo delete map.tgz "nsw.topographic.*"
+```
+
+Use the *info* command to see the names of layers currently in the map file.