terraintool — Generating surface meshes for cave survey software

       This      manpage      was       generated       from       the       online       documentation       at
       http://www.ubss.org.uk/terraintool/terraintool.php,       which      is      also      reproduced      in
       file:///usr/share/doc/terraintool/README.html.  Permission is granted to copy, distribute  and/or  modify
       this document under the terms of the GNU General Public License, Version 3 published by the Free Software
       Foundation.

       On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-
       licenses/GPL.

                                                                                                  Terraintool(1)

       TerrainTool  was  written to create surface topographic data for the cave survey packages Survex(linktoURLhttp://survex.com)  and Therion(linktoURLhttp://therion.speleo.sk)   using  the  results  of  the
       ShuttleRadarTopographyMission(linktoURLhttp://www2.jpl.nasa.gov/srtm/)  (SRTM) in which the
       shuttle Endeavour mapped the height of the Earth's surface between the latitudes 60 degrees North and  56
       degrees  South - about 80% of the Earth's land mass. Published resolution was 1 arc-second for the US and
       its territories and 3 arc-seconds elsewhere.  The latter corresponds to about 90m  at  the  equator.  The
       resulting  data  is  royalty-free  and,  for  many  countries,  may  be the only data publicly available.
       TerrainTool is able to automatically download the "tiles" of data that it needs,  directly  from  a  USGS
       server.

       Because  the  SRTM  radar imaging worked by using an oblique scan of the earth's surface, it had problems
       with shadowing where, despite multiple passes, areas remained hidden, resulting in  voids  in  the  data.
       This  is  particularly  noticeable in mountainous areas. A subsequent project AdvancedSpaceborneThermalEmissionandReflectionRadiometer(ASTER)(linktoURLhttp://www.jpl.nasa.gov/news/news.cfm?release=2009-103)    used   infra-red  nadir-viewing  camera  (i.e.
       directly downward) which, in post-processing over multiple orbits created stereo images from which height
       could be derived. This overcame the shadowing problem but the view  could  be  obstructed  by  cloud  and
       vegetation  cover  and suffered from "artefacts" - spurious features which are by-products of the imaging
       process. On it's own, the ASTER Digital Elevation Model (DEM) is unsuitable for cave surveying.

       Finally complete in February 2020, NASA released a new DEM by re-processing "global"  1  arc-second  SRTM
       data  and  carefully filling in the voids with re-processed ASTER data.  The result, NASADEM, is thus the
       highest resolution void-free near-global DEM that we have available. The only disadvantages are

          •  The tiles are typically 9 times the size of the 3 arc-second SRTM data,  so  they  take  longer  to
             download and process and occupy more disk space

          •  You  need  to  be logged into an Earthdata account to download the data. Unfortunately, TerrainTool
             cannot to do this for you so auto-download is  disabled.  However,  signing  up  for  an  Earthdata
             account   is   quick   and   easy   at   https://urs.earthdata.nasa.gov/users/new/(linktoURLhttps://urs.earthdata.nasa.gov/users/new/)

       With the completion of NASADEM, this release of TerrainTool uses it as its only source of data.

       Having  logged  in  to  your  Earthdata  account,  you  can  find  the   NASADEM   data   by   going   to
       https://lpdaac.usgs.gov/products/nasadem_hgtv001/(linktoURLhttps://lpdaac.usgs.gov/products/nasadem_hgtv001/)  ) selecting "Access Data" and "Download Data" next to
       "Data Pool" and clicking on the directory link will take you to a huge page  containing  all  the  tiles,
       currently    at    https://e4ftl01.cr.usgs.gov/MEASURES/NASADEM_HGT.001/2000.02.11/(linktoURLhttps://e4ftl01.cr.usgs.gov/MEASURES/NASADEM_HGT.001/2000.02.11/) Please note  that  this  URL  might  be
       subject  to  change  without notice. The page can take several minutes to download so don't panic if your
       browser freezes! Tile files are the ones ending  ".zip"  and  preceded  by  the  relevant  lat/long  e.g.
       NASADEM_HGT_n52w003.zip  You  can  download  tiles  with  a browser. Do NOT try unpacking the zip files -
       TerrainTool reads them in zipped form.

       TerrainTool does the following:-

          •  Converts between the spherical (Lat/Lon) coordinates used  in  the  tiles  and  a  variety  of  map
             coordinates  used  by  cave surveyors so that the surface mesh and cave survey can be combined in a
             single model based on the local map  coordinate  system.  Coordinate  systems  currently  supported
             include British (OSGB) grid, Irish grid, UTM, French (Lambert conical projections), Austrian grids,
             Slovenian  Grid  and  New  Zealand's  NZMG  and  NZTM2000. The internal design is intended to allow
             additional coordinate systems to be added easily.

          •  Re-samples the data using biaxial interpolation to create  a  rectangular  mesh  of  user-specified
             spacing.

          •  Displays a coloured topographic map of the mesh.

          •  Adds  a  user-specified  offset  (3-D)  to  the  coordinates to align with coordinates used for the
             underground survey.

          •  Saves the mesh as surface data in Survex (.svx) or Therion (.th) format.

       The programme, written in Java, provides a conventional GUI-style interface and will run  under  Windows,
       Solaris, macOS and Linux operating systems.

       "TerrainTool"  was written by Mike McCombe who is very grateful to UBSS for giving it a home. Please feel
       free to contact Mike with feedback or requests for help at mikemccombe <at> mikemccombe.co.uk or via  the
       Survexlist(linktoURLhttp://survex.com/maillist.html) .

       TerrainTool  is  a  conventional  GUI-based  application with a menu bar and dialog boxes to gather user-
       information. To get started, do the following:

          1. If you already know which tiles you will need from the NASADEM dataset, download them now and  save
             them    in   the   data   directory.   This   is   ~/.local/share/terraintool/   by   default,   or
             $XDG_DATA_HOME/terraintool/ if $XDG_DATA_HOME is set. Otherwise, when you try to create  the  mesh,
             TerrainTool will provide an error message to say which tile it needs and where to store it.

          2. Select the required coordinatesystem using the Options menu.

          3. Go to Create on the File menu to specify the size, location and resolution of the mesh.

          4. Save the results as in Survex (.svx) or Therion (.th) format

          5. Use  Survex  to process the file and Aven to view the results in 3D.  Remember to enable viewing of
             surface legs in Aven!

          6. Use the Offset command in the Options menu to fully align the terrain  data  with  the  coordinates
             used in your survey.

          7. When generating surface data in Therion format, Therion needs to be told the coordinate system used
             for  the  surface  data  in a form that it recognises (e.g. EPSG:27700). See the description of the
             surface command in the Therion Book for more details.

          8. Incorporate the terrain data into your survey project.

Create... is used to calculate the terrain mesh. A dialog box is used to gather the following:-

       CreatedialogitemsItemMeaning
       Grid Reference                                                         The grid reference for the mesh, expressed in the current
       coordinate type. This point can be at the centre of the mesh, any
       of the corners or the mid-point of any of the sides (see below). An
       example in the correct format is shown below the text field.
       E-W Range                                                              The distance (in metres) between the East and West edges of the
       mesh.
       N-S Range                                                              The distance (in metres) between the North and South edges of the
       mesh.
       Spacing                                                                The distance (in metres) between adjacent cells in the mesh.
       Grid ref is at                                                         Specifies where current point (see "Grid Reference"
       above) lies in relation to the boundaries of the mesh.

       Pressing OK starts the calculation of the mesh points. The NASADEM tiles need to be availale in the  data
       directory  $XDG_DATA_HOME/terraintool  ("$HOME/.local/share/terraintool"  by default if $XDG_DATA_HOME is
       not defined.

       At the end of the calculation, results are displayed as a simple coloured relief map. The mouse  position
       is displayed (in current coordinates) in the message bar on the bottom edge of the frame.

       Lat/Long...  provides  a  means  of defining the current point in terms of latitude and longitude, rather
       than as a grid reference. If the point can be represented as  a  valid  grid  reference  in  the  current
       coordinate  system,  it  is  used to initialise the "Grid Reference" field of the "Create..." dialog box.
       Likewise, the current grid reference is used to initialise the Lat and Long fields with the latitude  and
       longitude of the current point.

       Latitude and longitude values can be expressed as either

          •  real values in degrees (e.g. 46.25), where negative values are West / South, or

          •  values in degrees, minutes and seconds (e.g. 46 N 15' 22.6")

       Latitude  and  Longitude  are usually based on the WGS-84/GRS-80 datum and ellipsoid. The user may select
       alternatives, which will cause the lat and long values to be re-calculated.

       Saveas...

       Once a mesh has been calculated, the "Save as..." command can be used to save the terrain data. Normally,
       this will be in Survex (.svx) or Therion (.th) format.

       Otherwise, height values are defined for each point in the mesh.  Easting and Northing values  are  those
       of the current coordinate system.

       terraintool — Generating surface meshes for cave survey software

Coordinates...

       This is used to select the type of coordinates to use. The following are currently supported:

       CoordinateSystems
       Coordinate System                                                                      Description
       Austrian                                                                               T{
       The Austrian (BMN) coordinate system, in three zones
       T}
       Irish Grid                                                                             T{
       The Irish grid system, used in both Northern Ireland and the
       Republic of Ireland.
       T}
       Lambert 93                                                                             T{
       The Lambert 93 coordinate system. A conformal conical projection
       occasionally used in France.
       T}
       Lambert (5 zones)                                                                      T{
       The coordinate system most commonly used in France. Three zones (I,
       II and III) cover North, Central and Southern France. Zone IV is
       used in Corsica. A fifth zone (II-extended) covers the whole of
       France, at the expense of greater distortion.
       T}
       NZMG                                                                                   T{
       New Zealand Map Grid - New Zealand's coordinate system superseded in 2010. Maps
       based on this are no longer available, but still widely used. Based on a conformal
       orthomorphic projection.
       T}
       NZTM2000                                                                               T{
       New Zealand Transverse Mercator, successor to NZMG.
       T}
       OSGB                                                                                   T{
       Ordnance Survey of Great Britain - the normal British grid system.
       T}
       Slovenian Grid                                                                         T{
       A Transverse-Mercator grid used in Slovenia
       T}
       UTM                                                                                    T{
       Universal Transverse Mercator, devised by the US Department of
       Defense to cover the globe (except polar regions) in 60 zones. Also
       used by many national mapping agencies, often with a national or
       regional datum instead of WGS84.
       T}

       One  of  the  design  objectives  of  this  software is to be able to add further coordinate systems with
       minimal difficulty.

       Selecting a coordinate system from the drop-down list results in automatic selection of sensible defaults
       for the datum and ellipsoid. The user is free to override this selection using the  other  two  drop-down
       lists.  Whilst,  for example, OSGB invariably uses its own datum and the "Airy Sphere", other systems are
       frequently used with a variety of datums. UTM, for example, is used in Spain  with  the  European  (1950)
       Datum and Australia with their own (MGI) datum.

       Offset

       This  provides  a  simple  way of adding a fixed 3-D offset to mesh point in the mesh as it is saved. You
       might want to do this because

          •  Your cave survey coordinates might not use the full easting and northing values

          •  The height values differ from "known" surface heights in your survey. SRTM heights  are  referenced
             to  EGM96  (Earth  Geopotential  Model 1996) and may be significantly offset from a national height
             datum.

terraintool