nswtopo 2.0.0.pre.beta1 → 3.0

data/bin/nswtopo

@@ -1,19 +1,19 @@
 #!/usr/bin/env ruby
 
-# Copyright 2011-2019 Matthew Hollingworth
+# Copyright 2011-2022 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
+# it under the terms of the GNU Affero 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.
+# GNU Affero 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/>.
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 begin
   require 'open3'
@@ -30,75 +30,80 @@ begin
 
   GDAL_VERSION = begin
     stdout, * = Open3.capture3 "gdalinfo", "--version"
-    stdout[/\d+(?:\.\d+){1,2}/]
-  rescue Errno::ENOENT
+    /^GDAL (?<version>\d+(?:\.\d+){1,2})/ =~ stdout
+    version || raise
+  rescue Errno::ENOENT, RuntimeError
     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 (RUBY_VERSION.split(/\D+/).take(3).map(&:to_i) <=> [3,0,4]) < 0
+    log_abort "ruby 3.0.4 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"
+  when (GDAL_VERSION.split(/\D+/).take(3).map(&:to_i) <=> [3,4]) < 0
+    log_abort "GDAL 3.4 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|
+  pair   = "#{float},#{float}"
+  quad   = "#{float},#{float},#{float},#{float}"
+  field  = '[^\s",]+'
+
+  PositiveInt   = Class.new
+  PositiveFloat = Class.new
+  NonNegFloat   = Class.new
+  Dimensions    = Class.new
+  Inset         = Class.new
+  Margins       = Class.new
+  CoordList     = Class.new
+  Rotation      = Class.new
+  Opacity       = Class.new
+  DashArray     = Class.new
+  Zoom          = Class.new
+  ZlibLevel     = Class.new
+  FieldList     = Class.new
+
+  OptionParser.accept PositiveInt, /\A#{digits}\z/ do |string|
     raise OptionParser::InvalidArgument, string unless string.to_i.positive?
     string.to_i
   end
 
-  OptionParser.accept PositiveFloat, PositiveFloat do |string|
+  OptionParser.accept PositiveFloat, /\A#{float}\z/ do |string|
     raise OptionParser::InvalidArgument, string unless string.to_f.positive?
     string.to_f
   end
 
-  OptionParser.accept NonNegFloat, PositiveFloat do |string|
+  OptionParser.accept NonNegFloat, /\A#{float}\z/ do |string|
     raise OptionParser::InvalidArgument, string if string.to_f.negative?
     string.to_f
   end
 
-  OptionParser.accept Dimensions, Dimensions do |string|
+  OptionParser.accept Dimensions, /\A#{pair}\z/ do |string|
     dimensions = string.split(?,).map(&:to_f)
     raise OptionParser::InvalidArgument, string unless dimensions.all?(&:positive?)
     dimensions
   end
 
-  OptionParser.accept Margins, Margins do |string|
+  OptionParser.accept Inset, /\A#{quad}(?:,#{quad})*\z/ do |string|
+    string.split(?,).map(&:to_f).each_slice(4).entries
+  end
+
+  OptionParser.accept Margins, /\A#{float}(?:,#{float})?\z/ 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|
+  OptionParser.accept CoordList, /\A#{pair}(?:,#{pair})*\z/ do |string|
     string.split(?,).map(&:to_f).each_slice(2).to_a
   end
 
-  OptionParser.accept Rotation, Rotation do |string|
+  OptionParser.accept Rotation, /\A(?:#{float}|magnetic|auto)\z/ 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?
@@ -106,23 +111,37 @@ begin
   end
 
   OptionParser.accept Colour do |string|
-    string == "none" ? string : Colour.new(string.downcase).to_s
+    string == "none" ? string : Colour.new(string.downcase)
   rescue Colour::Error
     raise OptionParser::InvalidArgument, string
   end
 
-  OptionParser.accept Opacity, Opacity do |string|
+  OptionParser.accept Opacity, /\A#{float}%?\z/ 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|
+  OptionParser.accept DashArray, /\A#{float}(?:(?:,#{float})*|(?: #{float})*)\z/ do |string|
     values = string.split(/[, ]/).map(&:to_f)
     raise OptionParser::InvalidArgument, string if values.any?(&:negative?)
     values.join ?\s
   end
 
+  OptionParser.accept Zoom, /\A(?:#{digits},)?#{digits}\z/ do |string|
+    values = string.split(?,).map(&:to_i)
+    raise OptionParser::InvalidArgument, string unless values.all?(10..20)
+    values
+  end
+
+  OptionParser.accept ZlibLevel, /\A\d\z/ do |string|
+    Integer(string)
+  end
+
+  OptionParser.accept FieldList, /\A#{field}(?:,#{field})*\z/ do |string|
+    string.split ?,
+  end
+
   ansi = lambda do |string|
     string.to_s.gsub(/\*([-a-zA-Z0-9]+)\*/) do
       "\e[1m%s\e[0m" % $1
@@ -130,7 +149,7 @@ begin
       "\e[4m%s\e[0m" % $1
     end.gsub(/~([-a-zA-Z0-9]+)~/) do
       "\e[3m%s\e[0m" % $1
-    end
+    end.prepend("\r\e[K")
   end
 
   plain = lambda do |string|
@@ -154,6 +173,7 @@ begin
           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
@@ -188,15 +208,16 @@ begin
         *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"
+      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,  "map dimensions in mm"
+      parser.on "-r", "--rotation    <rotation>",     Rotation,    "map rotation angle in clockwise",
+                                                                   "degrees, 'auto' or 'magnetic'"
+      parser.on "-m", "--margins     <x[,y]>",        Margins,     "map margins in mm"
+      parser.on "-i", "--inset       <x1,y1,x2,y2>",  Inset,       "map inset coordinates in mm"
+      parser.on "-o", "--overwrite",                               "overwrite existing map file"
 
     when "info"
       parser.banner = <<~EOF
@@ -204,72 +225,84 @@ begin
         usage: _nswtopo_ _info_ [~options~] <map.tgz>
       EOF
       parser.on "-e", "--empty", "show empty layers"
+      parser.on "-j", "--json",  "show map bounds as GeoJSON string"
+      parser.on "-p", "--proj",  "show map projection as a proj string"
+      parser.on "-w", "--wkt",   "show map projection as a WKT2 string"
 
     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 "-r", "--resolution  <resolution>", PositiveFloat, "raster resolution in metres per pixel"
+      parser.on       "--ppi         <ppi>",        PositiveFloat, "raster resolution in pixels per inch"
+      parser.on "-o", "--opacity     <opacity>",    Opacity,       "layer opacity (between 0 and 1)"
       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"
+      parser.on "-s", "--strict",                                  "don't continue if a layer fails"
 
     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)"
+      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 "-a", "--auxiliary",                                 "show auxiliary contours"
+      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, "thinning threshold (default %s lines/mm)" % NSWTopo::Contour::DEFAULTS["density"]
+      # 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 (default %s)" % NSWTopo::Contour::DEFAULTS["stroke-width"]
+      parser.on       "--fill          <colour>",     Colour,        "label colour (defaults to stroke colour)"
+      parser.on "-r", "--resolution    <resolution>", PositiveFloat, "DEM processing resolution in metres"
 
     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"
+      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 "-e", "--extent      <extent>",         PositiveFloat,      "minimum feature extent in mm (default %i)" % NSWTopo::Spot::DEFAULTS["extent"]
+      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 "-r", "--resolution  <resolution>",     PositiveFloat,      "DEM processing resolution in metres"
 
     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"]
+      parser.on "-r", "--resolution <resolution>",    PositiveFloat,     "resolution in metres per pixel"
+      parser.on "-p", "--ppi        <ppi>",           PositiveFloat,     "resolution in pixels per inch"
+      parser.on "-o", "--opacity    <opacity>",       Opacity,           "opacity (default %s)" % NSWTopo::Relief::DEFAULTS["opacity"]
+      parser.on       "--shade      <colour>",        Colour,            "shade colour (default %s)" % NSWTopo::Relief::DEFAULTS["shade"]
+      parser.on "-m", "--method     <igor|combined>", %w[igor combined], "relief shading method (default %s)" % NSWTopo::Relief::DEFAULTS["method"]
+      parser.on "-z", "--azimuth    <azimuth>",       Float,             "azimuth in degrees (default %i)" % NSWTopo::Relief::DEFAULTS["azimuth"]
+      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"]
+      parser.on "-i", "--interval      <interval>", PositiveFloat, "interval between grid lines in",
+                                                                   "metres (default %i)" % NSWTopo::Grid::DEFAULTS["interval"]
+      parser.on "-u", "--unlabeled",                               "don't add grid labels"
+      parser.on "-b", "--border",                                  "add map border"
+      parser.on       "--stroke-width  <width>",    PositiveFloat, "stroke width in mm (default %s)" % NSWTopo::Grid::DEFAULTS["stroke-width"]
 
     when "declination"
       parser.banner = <<~EOF
@@ -292,6 +325,7 @@ begin
       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 "-k", "--knockout   <width>",     NonNegFloat,   "symbol knockout width in mm (default %s)" % NSWTopo::Control::DEFAULTS["knockout"]
       parser.on "-f", "--font-size  <font-size>", PositiveFloat, "font size for labels in mm"
 
     when "overlay"
@@ -321,22 +355,30 @@ begin
           usage: _nswtopo_ _delete_ [~options~] <map.tgz> <layer> [<layer> ...]
       EOF
 
+    when "move"
+      parser.banner = <<~EOF
+        *nswtopo* *move* - move map layer
+          usage: _nswtopo_ _move_ [~options~] <map.tgz> <layer>
+      EOF
+      parser.on "-a", "--after   <layer>", "insert after specified layer"
+      parser.on "-b", "--before  <layer>", "insert before specified layer"
+
     when "render"
       parser.banner = <<~EOF
         *nswtopo* *render* - render map in various formats
-          usage: _nswtopo_ _render_ [~options~] <map.tgz> [<format-or-path> ...]
+          usage: _nswtopo_ _render_ [~options~] <map.tgz|map.svg> [<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"
+      parser.on "-p", "--ppi         <ppi>",     PositiveInt, "resolution for raster formats in pixels",
+                                                              "per inch (default %i)" % NSWTopo::Formats::PPI
+      parser.on "-z", "--zoom        <zoom>",    Zoom,        "maximum tile zoom (10-20, default %i)" % NSWTopo::TiledWebMap::DEFAULT_ZOOM
+      parser.on "-b", "--background  <colour>",  Colour,      "background colour (name or RGB triplet)"
+      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 "-f", "--force",                              "force regeneration of cached SVG"
 
     when "layers"
       parser.banner = <<~EOF
@@ -351,11 +393,46 @@ begin
       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"
+      parser.on       "--[no-]debug",                                "enable or disable label debuging"
+      parser.on       "--[no-]gpu",                                  "enable or disable Chrome GPU usage"
+      parser.on       "--[no-]versioning",                           "enable or disable map version checking"
+      parser.on "-z", "--zlib-level    <0-9>",        ZlibLevel,     "set zlib compression level"
+      parser.on "-k", "--knockout      <width>",      NonNegFloat,   "set label knockout width in mm"
+
+    when "scrape"
+      parser.banner = <<~EOF
+        *nswtopo* *scrape* - scrape data from an ArcGIS REST endpoint
+          usage: _nswtopo_ _scrape_ [~options~] <url> <path>
+      EOF
+      parser.on "-l", "--layer     <layer>",       String,      "name of ArcGIS service layer"
+      parser.on "-i", "--id        <id>",          Integer,     "id number of layer"
+      parser.on "-w", "--where     <where>",       String,      "filtering clause"
+      parser.on "-c", "--coords    <x0,y0,x1,y1>", CoordList,   "WGS84 coordinates of bounding box corners"
+      parser.on "-n", "--name      <name>",        /^\w+$/,     "name of saved layer"
+      parser.on "-f", "--fields    <field,...>",   FieldList,   "comma-separated list of fields"
+      parser.on "-d", "--decode",                               "convert coded values where possible"
+      parser.on "-e", "--epsg      <number>",      PositiveInt, "EPSG number for reprojection"
+      parser.on "-p", "--paginate  <number>",      PositiveInt, "number of records per request"
+      parser.on       "--concat",                               "collect all features before saving"
+      parser.on "-u", "--unique    <field>",       String,      "field for counting map-only features"
+
+    when "inspect"
+      parser.banner = <<~EOF
+        *nswtopo* *inspect* - inspect data from an ArcGIS REST endpoint or local data source
+          usage: _nswtopo_ inspect [~options~] <url-or-path>
+      EOF
+      parser.on "-l", "--layer      <layer>",       String,    "name of layer"
+      parser.on "-i", "--id         <id>",          Integer,   "id number of layer"
+      parser.on "-w", "--where      <where>",       String,    "filtering clause"
+      parser.on "-c", "--coords     <x0,y0,x1,y1>", CoordList, "WGS84 coordinates of bounding box corners"
+      parser.on "-f", "--fields     <field,...>",   FieldList, "comma-separated list of fields"
+      parser.on "-d", "--decode",                              "convert coded values where possible"
+      parser.on       "--codes",                               "show coded values for an ArcGIS Layer"
+      parser.on       "--countwise",                           "sort fields by count instead of value"
 
     when nil
       raise OptionParser::MissingArgument, "no command specified"
@@ -381,50 +458,84 @@ begin
   case command
   when "layers"
     raise OptionParser::NeedlessArgument, ARGV if ARGV.any?
-    NSWTopo.layers options
+    NSWTopo.layers **options
     exit
   when "config"
     layer = ARGV.shift
     raise OptionParser::NeedlessArgument, ARGV if ARGV.any?
     NSWTopo.config *layer, **options
     exit
+  when "scrape"
+    url, path = ARGV.shift, ARGV.shift
+    raise OptionParser::MissingArgument, "no URL specified" unless url
+    raise OptionParser::MissingArgument, "no path specified" unless path
+    raise OptionParser::NeedlessArgument, ARGV if ARGV.any?
+    path = Pathname(path).expand_path
+    raise OptionParser::InvalidArgument, "invalid path: #{path}" unless path.parent.directory?
+    raise OptionParser::InvalidOption, "can't specify both --id and --layer" if options[:id] && options[:layer]
+    NSWTopo.scrape url, path, **options
+    exit
+  when "inspect"
+    url_or_path = ARGV.shift
+    raise OptionParser::MissingArgument, "no URL or path specified" unless url_or_path
+    raise OptionParser::NeedlessArgument, ARGV if ARGV.any?
+    [%i[where codes], %i[fields codes], %i[decode codes], %i[id layer]].each do |flags|
+      raise OptionParser::InvalidOption, "can't have --%s with --%s" % flags if options.values_at(*flags).all?
+    end
+    raise OptionParser::InvalidOption, "--countwise requires --fields" if options[:countwise] && !options[:fields]
+    raise OptionParser::InvalidOption, "--decode requires --fields" if options[:decode] && !options[:fields]
+    NSWTopo.inspect url_or_path, **options
+    exit
+  when "add", "relief"
+    raise OptionParser::InvalidOption, "can't specify both --resolution and --ppi" if options[:resolution] && options[:ppi]
   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
+  in_path = case command
+  when "init"
+    raise "already a directory: #{tgz_path}" if tgz_path.directory?
+    raise "file already exists: #{tgz_path}" if !options.delete(:overwrite) && tgz_path.exist?
+    raise "no such directory: #{tgz_path.parent}" unless tgz_path.parent.directory?
+  else
+    raise "no such file: #{tgz_path}" unless tgz_path.exist?
+    raise "not a file: #{tgz_path}" unless tgz_path.file?
+    tgz_path
+  end
 
-    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
+  command = command.tr ?-, ?_
+  ARGV.prepend in_path.basename(".tgz").basename(".tar.gz").basename(".svg") if "render" == command
+
+  nil.tap do |partial_failure|
+    NSWTopo::Archive.open(in_path: in_path, out_path: tgz_path) do |archive|
+      NSWTopo.method(command).parameters.group_by(&:first).inject [archive] do |args, (type, params)|
+        case type
+        when :req
+          raise OptionParser::MissingArgument if ARGV.length < params.length - args.length
+          args.concat ARGV.shift(params.length - args.length)
+        when :rest
+          args.concat ARGV.shift(ARGV.length)
+        else args
+        end
+      end.tap do |args|
+        raise OptionParser::NeedlessArgument, ARGV.join(?\s) if ARGV.any?
+        NSWTopo.send command, *args, **options
+      rescue NSWTopo::PartialFailureError => partial_failure
       end
-
-      NSWTopo.send command, *args
-    rescue NSWTopo::PartialFailureError => error
     end
-    raise error.message if error
+    raise partial_failure if partial_failure
+  rescue NSWTopo::Archive::Invalid
+    raise "unrecognised map file: #{in_path}" unless "render" == command
+    raise OptionParser::InvalidOption, "can't specify --force without a map file" if options[:force]
+    in_path, tgz_path, options = nil, nil, options.merge(svg_path: in_path)
+    retry
   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"
+  log_abort "interrupted"
 rescue RuntimeError => error
   log_abort error.message
 end

data/docs/README.md

@@ -10,20 +10,9 @@ Help screens are available describing usage for each commands. Use the `--help`
 $ 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.
+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.
 
 # Example
 

data/docs/add.md

@@ -10,7 +10,7 @@ The forward-slash character is used indicate the nested folder structure of thes
 
 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.
+Raster layers (vegetation, shaded relief) are typically imported at the data's native resolution. If desired, you can choose a different value using the `--resolution` option, for a data resolution in metres per pixel, or the `--ppi` option for output resolution in 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.
 

data/docs/config.md

@@ -1,6 +1,6 @@
 # Description
 
-Configure and view permanent *nswtopo* settings using the *config* command. For example, to set the *Google Chrome* path for rendering maps:
+Configure and view permanent *nswtopo* settings using the *config* command. For example, to manually set the *Google Chrome* path:
 
 ```
 $ nswtopo config --chrome "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

data/docs/contours.md

@@ -12,6 +12,8 @@ Choose a contour interval in metres using the `--interval` option. A five metre
 
 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.
 
+DEM tiles are normally processed at their maximumum native resolution. Change this using the `--resolution` option. A reduced resolution (say 5 metres) can markedly improve processing speed for 1- and 2-metre tiles.
+
 # 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:
@@ -21,7 +23,7 @@ $ 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*).
+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.

data/docs/init.md

@@ -36,3 +36,11 @@ $ nswtopo init --dimensions 210,297 --coords 148.387,-36.148 map.tgz
 # Map Scale
 
 A 1:25000 scale is conventional and should work well for most purposes. Change to a smaller or larger scale using the `--scale` option.
+
+# Map Inset
+
+Use the `--inset` option to remove a rectangular inset from the map. Specify the inset location as two opposing corner coordinates in millimetres. For example, to remove a 50mm × 100mm inset from the map's top-left corner:
+
+```
+$ nswtopo init --bounds bounds.kml --inset 0,0,50,100 map.tgz
+```