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


  <!ENTITY dhsurname   "<surname>Wookey</surname>">
  <!ENTITY dhdate      "<date>March 19, 2012</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-2012</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 is used 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>. This uses
    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.
    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.
  </para>
  <para>
    More recently, the
    <ulink url="http://www.jpl.nasa.gov/news/news.cfm?release=2009-103">Advanced Spaceborne Thermal Emission and Reflection Radiometer (ASTER)</ulink>
    project has published data at 1 arc-second resolution for the land
    masses between 83 degrees North and 83 degrees South and is also
    royalty-free. Whilst the SRTM data contains numerous
    &quot;voids&quot; caused by shadowing in steep or mountainous
    areas, the ASTER data was built from stereo images taken over a
    much longer period of time and as a result is much more complete.
    It does, however, suffer from &quot;artefacts&quot; - spurious
    features which are by-products of the imaging process.
  </para>
  <para>
    SRTM data is available to all on the Internet from a NASA server
    and TerrainTool automatically fetches anything it needs. The
    mechanism for accessing ASTER data is slightly more complicated in
    that users need to register first on the US or Japanese website and
    then &quot;order&quot; (at no cost) the files that they need. A few
    minutes later, the system sends the user an e-mail containing a
    link to a zip file containing the relevant files. This can be
    downloaded via FTP or using a standard web browser. A zip file
    containing the tiles for the UK and Ireland, for example, was a
    little over 500MB. Unfortunately, it's not possible for a tool like
    TerrainTool to take care of the downloading of ASTER data
    automatically. More instructions on how to do this manually can be
    found <link linkend="Installing_ASTER_data_files">below</link>.
  </para>
  <para>
    TerrainTool does the following:-
  </para>
  <itemizedlist>
    <listitem>
      <para>
        Automatically downloads SRTM data from the NASA ftp site as needed.
      </para>
    </listitem>
    <listitem>
      <para>
        Converts between spherical (Lat/Lon) coordinates and a variety of
        map coordinates. Coordinate systems currently supported include
        British (OSGB) grid, Irish grid, UTM, French (Lambert conical
        projections) and Austrian. Additional mapping systems can be added
        quite easily.
      </para>
    </listitem>
    <listitem>
      <para>
        Re-samples the data using bilinear 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 and Linux operating
    systems. The latest Java Runtime (JRE 6 or JDK 6) is required and
    can be downloaded free of charge from
    <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html"></ulink>Oracle.
  </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;
    btinternet.com 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>
      <listitem>
        <para>
          Select the required <link linkend="Region">region</link> and
          <link linkend="Coordinates">coordinate system</link> using the
          Options menu
        </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 ant 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 Nasa ftp
        site. These are stored in the &quot;data&quot; subdirectory 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>
        <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. Occasionally, there may be
        missing values (known as &quot;voids&quot;) in the SRTM data -
        particularly in mountainous areas where steep faces may have been
        hidden from the Shuttle's line of sight. Generally, TerrainTool
        will &quot;repair&quot; individual voids by interpolating from the
        surrounding cells. However, if this isn't possible, gaps are left
        in the mesh where no data is available.
      </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>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 data from the NASA SRTM site.
      </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.
      </para>
      <para>
        <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>
        <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">SRTM Only</emphasis>
      </para>
      <para>
        Creates terrain using only 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
        connction, missing tiles will be automatically downloaded from the
        NASA server.
      </para>
      <para>
        <emphasis role="strong">ASTER Only</emphasis>
      </para>
      <para>
        Creates terrain using only ASTER data. This has higher resolution
        and greater coverage than SRTM data but must be manually downloaded
        and installed
        (<link linkend="Installing_ASTER_data_files">see below</link>). Its
        greater resolution causes TerrainTool to run more slowly than with
        SRTM data. The end-result may show signs of &quot;artefacts&quot; -
        spurious features produced by the imaging process.
      </para>
      <para>
        <emphasis role="strong">SRTM plus ASTER</emphasis>
      </para>
      <para>
        Uses ASTER to fill any &quot;voids&quot; in the SRTM data. This
        option minimises the processing time and &quot;artefact&quot;
        penalties of using ASTER data whilst leaving the least number of
        voids in the finished product.
      </para>
      <para>
        <emphasis role="strong">Legacy ASTER Data</emphasis>
      </para>
      <para>
        By default, version 1.11 onwards of TerrainTool assumes ASTER data 
        to be from the ASTER 2 dataset. This contains fewer artefacts than 
        the original ASTER dataset. However, if you need to use the original 
        data files, select this option.
      </para>
    </refsect1>
    <refsect1 id="Installing_ASTER_data_files">
    <title>Installing ASTER data files</title>
    <para>
      Obtaining ASTER data is free and quite straightforward. The first
      step is that you will need to register and, when you've logged in
      you can use the tool on the WIST web site to select the
      &quot;granules&quot; you need - most easily by just dragging an
      area on a map of the world. Having ticked various boxes to confirm
      agreement to their terms and conditions, the selection is bundled
      up into an &quot;order&quot;. A few minutes later, the system sends
      an e-mail to the address you gave at registration and this contains
      a link to a zip file containing the tiles you selected and
      instructions on how to download it using either a browser or a
      command-line ftp client.
    </para>
    <para>
      Each &quot;granule&quot; contains the data for a 1-degree by
      1-degree tile of the earth's surface and is in two files - an xml
      descriptor (e.g. ASTGTM_N50E002.zip.xml) and a zip file (e.g.
      ASTGTM_N50E002.zip) containing the data itself. The first time you
      run TerrainTool it will create a sub-directory called
      &quot;data&quot; (in the directory containing TerrainTool.jar).
      This is used to store both SRTM tiles and ASTER granules. Use a
      standard &quot;zip&quot; utility (e.g. WinZip) to extract the data
      files (e.g. ASTGTM_N50E002.zip) and place them in this directory.
      Do NOT unpack the zip files themselves - TerrainTool decompresses
      the contents as it reads them.
    </para>
    <para>
      A similar procedure can be used to install SRTM data files
      manually. Simply copy data tiles (e.g. N51W003.hgt.zip) into the
      &quot;data&quot; sub-directory.
    </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:
-->


