<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [


  <!ENTITY dhsurname   "<surname>Wookey</surname>">
  <!ENTITY dhdate      "<date>November 26, 2020</date>">
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>Wookey &lt;wookey@debian.org&gt;</email>">
  <!ENTITY dhusername  "Wookey">
  <!ENTITY dhucpackage "<refentrytitle>Terraintool</refentrytitle>">
  <!ENTITY dhpackage   "terraintool">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhsurname;
    </author>
    <copyright>
      <year>2009-2020</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>Generating surface meshes for cave survey software</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>

    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      TerrainTool was written to create surface topographic data for
      the cave survey
      packages <ulink url="http://survex.com">Survex</ulink> and
      <ulink url="http://therion.speleo.sk">Therion</ulink> using the
      results of
      the <ulink url="http://www2.jpl.nasa.gov/srtm/">Shuttle Radar
      Topography Mission</ulink> (SRTM) in which the shuttle
      <emphasis>Endeavour</emphasis> 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 &quot;tiles&quot; of data
      that it needs, directly from a USGS server.
    </para>
    <para>
      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
      <ulink url="http://www.jpl.nasa.gov/news/news.cfm?release=2009-103">Advanced
      Spaceborne Thermal Emission and Reflection Radiometer
      (ASTER)</ulink> 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
      &quot;artefacts&quot; - 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.
    </para>
    <para>
       Finally complete in February 2020, NASA released a new DEM by
       re-processing &quot;global&quot; 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
    </para>
    <itemizedlist spacing="compact">
      <listitem>
	<para>
	  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
	</para>
      </listitem>
      <listitem>
	<para>
          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
      <ulink url="https://urs.earthdata.nasa.gov/users/new/">https://urs.earthdata.nasa.gov/users/new/</ulink>
	</para>
      </listitem>
    </itemizedlist>
    <para>
      With the completion of NASA DEM, this release (1.16) of
      TerrainTool no longer directly supports the use of ASTER data
      since its use as a fill-in for voids in the SRTM data has
      already been done. TerrainTool now only offers a choice of SRTM
      (because it is small and automatically downloadable) and NASA
      (because of its higher quality and resolution)
    </para>
    <para>
      Having logged in to your Earthdata account, you can find the
      NASADEM data by going to
      <ulink url="https://lpdaac.usgs.gov/products/nasadem_hgtv001/">https://lpdaac.usgs.gov/products/nasadem_hgtv001/</ulink> ) 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
       <ulink url="https://e4ftl01.cr.usgs.gov/MEASURES/NASADEM_HGT.001/2000.02.11/">https://e4ftl01.cr.usgs.gov/MEASURES/NASADEM_HGT.001/2000.02.11/</ulink>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
      &quot;.zip&quot; 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.
    </para>
    <para>
      TerrainTool does the following:-
    </para>
    <itemizedlist spacing="compact">
      <listitem>
	<para>
	  If required, automatically downloads SRTM data from the USGS
	  server.
	</para>
      </listitem>
      <listitem>
	<para>
	  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.
	</para>
    </listitem>
    <listitem>
      <para>
        Re-samples the data using biaxial interpolation to create a
        rectangular mesh of user-specified spacing.
      </para>
    </listitem>
    <listitem>
      <para>
        Displays a coloured topographic map of the mesh.
      </para>
    </listitem>
    <listitem>
      <para>
        Adds a user-specified offset (3-D) to the coordinates to align with
        coordinates used for the underground survey.
      </para>
    </listitem>
    <listitem>
      <para>
        Saves the mesh as surface data in Survex (.svx) or Therion (.th) format.
      </para>
    </listitem>
  </itemizedlist>
  <para>
    The programme, written in Java, provides a conventional GUI-style
    interface and will run under Windows, Solaris, macOS and Linux operating
    systems. 
  </para>
  <para>
    &quot;TerrainTool&quot; 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 &lt;at&gt;
    mikemccombe.co.uk or via the
    <ulink url="http://survex.com/maillist.html">Survex list</ulink>.
  </para>
  </refsect1>
  <refsect1>
    <title>Driving Instructions</title>
    <para>
      TerrainTool is a conventional GUI-based application with a menu bar
      and dialog boxes to gather user-information. To get started, do the
      following:
    </para>
    <orderedlist spacing="compact">
      <listitem>
        <para>
      Select the required <link linkend="Coordinates">coordinate
      system</link> using the Options menu. If you're not using the NASA
      DEM you'll also need to specify the
      <link linkend="Region">region</link>
        </para>
      </listitem>
      <listitem>
        <para>
          Go to <link linkend="Create">Create</link> on the File menu to
          specify the size, location and resolution of the mesh.
        </para>
      </listitem>
      <listitem>
        <para>
          <link linkend="Save_as">Save</link> the results as in Survex (.svx)
          or Therion (.th) format
        </para>
      </listitem>
      <listitem>
        <para>
          Use Survex to process the file and Aven to view the results in 3D.
          Remember to enable viewing of surface legs in Aven!
        </para>
      </listitem>
      <listitem>
        <para>
          Use the Offset command in the Options menu to fully align the
          terrain data with the coordinates used in your survey.
        </para>
      </listitem>
      <listitem>
        <para>
          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.
        </para>
      </listitem>
      <listitem>
        <para>
          Incorporate the terrain data into your survey project.
        </para>
      </listitem>
    </orderedlist>
    </refsect1>
    <refsect1 id="file-menu">
      <title>File Menu</title>
      <para id="Create">
        <emphasis role="strong">Create</emphasis>... is used to calculate
        the terrain mesh. A dialog box is used to gather the following:-
      </para>
      <segmentedlist><title>Create dialog items</title>
 	<segtitle>Item</segtitle>
        <segtitle>Meaning</segtitle>
     
        <seglistitem>
	  <seg>Grid Reference</seg>
          <seg>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.</seg>
        </seglistitem>
	<seglistitem>
          <seg>E-W Range</seg>
          <seg>The distance (in metres) between the East and West edges of the
      mesh.</seg>
        </seglistitem>
	<seglistitem>
          <seg>N-S Range</seg>
          <seg>The distance (in metres) between the North and South edges of the
      mesh.</seg>
        </seglistitem>
	<seglistitem>
          <seg>Spacing</seg>
          <seg>The distance (in metres) between adjacent cells in the mesh.</seg>
        </seglistitem>
	<seglistitem>
          <seg>Grid ref is at</seg>
          <seg>Specifies where current point (see &quot;Grid Reference&quot;
      above) lies in relation to the boundaries of the mesh.</seg>
        </seglistitem>
      </segmentedlist>
      <para>
        Pressing <emphasis role="strong">OK</emphasis> starts the
        calculation of the mesh points. If &quot;Auto-download&quot;
        is enabled, data files will be downloaded as needed from the
        USGS server. These are stored in XDG_DATA_HOME/terraintool
        (normally &quot;$HOME/.local/share/terraintool&quot; for later
        re-use if necessary, avoiding the need to download the same
        file again.
      </para>
      <para>
        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.
      </para>
      <para>
        <emphasis role="strong">Lat/Long</emphasis>... 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 &quot;Grid Reference&quot; field of the
        &quot;Create...&quot; 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.
      </para>
      <para>
        Latitude and longitude values can be expressed as either
      </para>
      <itemizedlist spacing="compact">
        <listitem>
          <para>
            real values in degrees (e.g. 46.25), where negative values are West
            / South, or
          </para>
        </listitem>
        <listitem>
          <para>
            values in degrees, minutes and seconds (e.g. 46 N 15' 22.6&quot;)
          </para>
        </listitem>
      </itemizedlist>
      <para>
        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.
      </para>
      <para id="Save_as">
        <emphasis role="strong">Save as...</emphasis>
      </para>
      <para>
        Once a mesh has been calculated, the &quot;Save as...&quot; command
        can be used to save the terrain data. Normally, this will be in
        Survex (.svx) or Therion (.th) format.
      </para>
      <para>
        Otherwise, height values are defined for each point in the mesh.
        Easting and Northing values are those of the current coordinate
        system.
      </para>
    </refsect1>
    <refsect1 id="options-menu">
      <title>Options Menu</title>
      <para id="Coordinates">
        <emphasis role="strong">Coordinates...</emphasis>
      </para>
      <para>
        This is used to select the type of coordinates to use. The
        following are currently supported:
      </para>
      <table><title>Coordinate Systems</title>
       <tgroup cols=2 align=left colsep=1 rowsep=1>
        <thead>
         <row>
	  <entry>Coordinate System</entry>
          <entry>Description</entry>
         </row>
        </thead>
        <tbody>
         <row>
	  <entry>Austrian</entry>
          <entry>The Austrian (BMN) coordinate system, in three zones</entry>
         </row>
         <row>
	  <entry>Irish Grid</entry>
          <entry>The Irish grid system, used in both Northern Ireland and the
          Republic of Ireland.</entry>
         </row>
         <row>
	  <entry>Lambert 93</entry>
          <entry>The Lambert 93 coordinate system. A conformal conical projection
          occasionally used in France.</entry>
         </row>
         <row>
	  <entry>Lambert (5 zones)</entry>
          <entry>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.</entry>
         </row>
         <row>
	  <entry>NZMG</entry>
          <entry>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.</entry>
         </row>
         <row>
	  <entry>NZTM2000</entry>
          <entry>New Zealand Transverse Mercator, successor to NZMG.</entry>
         </row>
         <row>
	  <entry>OSGB</entry>
          <entry>Ordnance Survey of Great Britain - the normal British grid system.</entry>
         </row>
         <row>
          <entry>Slovenian Grid</entry>
          <entry>A Transverse-Mercator grid used in Slovenia</entry>
         </row>
         <row>
	  <entry>UTM</entry>
          <entry>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.</entry>
         </row>
        </tbody>
       </tgroup>
      </table>
      <para>
        One of the design objectives of this software is to be able to add
        further coordinate systems with minimal difficulty.
      </para>
      <para>
        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 &quot;Airy Sphere&quot;, 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.
      </para>
      <para>
        <emphasis role="strong">Auto download</emphasis>
        enables/disables the automatic downloading of SRTM data from
        the USGS site. This option is disabled when the NASA DEM is
        selected.
      </para>
      <para id="Region">
        <emphasis role="strong">Region</emphasis>
      </para>
      <para>
        The SRTM data site is organised into six regions - Africa,
        Australia, Eurasia, North_America, South_America and Islands
        (New Zealand and islands of the Pacific). As I don't have a
        simple method of determining the region automatically from
        lat/lon, you will need to manually select the right
        region. This option is only relevant to the SRTM DEM. It is
        disabled when the NASA DEM is selected.
      </para>
      <para id="Offset" >
        <emphasis role="strong">Offset</emphasis>
      </para>
      <para>
        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
      </para>
      <itemizedlist spacing="compact">
        <listitem>
          <para>
            Your cave survey coordinates might not use the full easting and
            northing values
          </para>
        </listitem>
        <listitem>
          <para>
            The height values differ from &quot;known&quot; 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.
          </para>
        </listitem>
      </itemizedlist>
      <para>
        <emphasis role="strong">NASA</emphasis>
      </para>
      <para>
        Creates terrain using NASADEM data. Tiles for this DEM need to be
        manually installed. If a required tile is missing the error message
        will include the name of the file that you need to find on the USGS
        server.
      </para>
      <para>
        <emphasis role="strong">SRTM</emphasis>
      </para>
      <para>
        Creates terrain using SRTM data. Any &quot;voids&quot; which cannot be
        filled by interpolation will result in gaps in the output data. If
        auto-download is selected and there is an Internet connection, missing
        tiles will be automatically downloaded from the USGS server.
      </para>
 
    </refsect1>

  <refsect1>
    <title>AUTHOR</title>

    <para>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.
    </para>
	<para>
	  On Debian systems, the complete text of the GNU General Public
	  License can be found in /usr/share/common-licenses/GPL.
	</para>

  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->


