Provided by: terraintool_1.13-2_all bug

NAME

       terraintool — Generating surface meshes for cave survey software

SYNOPSIS

       terraintool

DESCRIPTION

       TerrainTool is used to create surface topographic data for the cave survey packages Survex
       (link to URL http://survex.com)  and Therion (link to URL http://therion.speleo.sk) . This
       uses   the   results   of   the   Shuttle   Radar   Topography   Mission   (link   to  URL
       http://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.  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.

       More  recently, the Advanced Spaceborne Thermal Emission and Reflection Radiometer (ASTER)
       (link  to  URL  http://www.jpl.nasa.gov/news/news.cfm?release=2009-103)       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  "voids"
       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 "artefacts" - spurious features which are by-products of the
       imaging process.

       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 "order" (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 below.

       TerrainTool does the following:-

          ·  Automatically downloads SRTM data from the NASA ftp site as needed.

          ·  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.

          ·  Re-samples the data using bilinear 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 and Linux operating systems. The latest Java Runtime (JRE 6 or JDK
       6) is required and can be downloaded free of charge from
        (link to URL http://www.oracle.com/technetwork/java/javase/downloads/index.html) Oracle.

       "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> btinternet.com or via the Survex list (link to URL http://survex.com/maillist.html) .

Driving Instructions

       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. Select the required region and coordinate system using the Options menu

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

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

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

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

          6. 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.

          7. Incorporate the terrain data into your survey project.

File Menu

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

       Create dialog items

       Item                                                                   Meaning
       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 ant 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. If "Auto-download" is enabled, data
       files  will be downloaded as needed from the Nasa ftp site. These are stored in the "data"
       subdirectory for later re-use if necessary, avoiding the need to download  the  same  file
       again.

       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.

       Save as...

       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. Occasionally, there
       may be missing values (known as "voids") 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 "repair" 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.

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

Options Menu

       Coordinates...

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

       Coordinate Systems

       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}
       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.

       Auto download enables/disables the automatic downloading of data from the NASA SRTM site.

       Region

       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.

       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.

       SRTM Only

       Creates  terrain using only SRTM data. Any "voids" 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.

       ASTER Only

       Creates  terrain  using  only  ASTER data. This has higher resolution and greater coverage
       than SRTM data but must be manually downloaded and  installed  (see  below).  Its  greater
       resolution  causes  TerrainTool to run more slowly than with SRTM data. The end-result may
       show signs of "artefacts" - spurious features produced by the imaging process.

       SRTM plus ASTER

       Uses ASTER to fill any "voids" in the SRTM data. This option minimises the processing time
       and  "artefact"  penalties of using ASTER data whilst leaving the least number of voids in
       the finished product.

       Legacy ASTER Data

       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.

Installing ASTER data files

       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 "granules" 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 "order". 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.

       Each  "granule"  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 "data" (in the directory containing TerrainTool.jar).   This
       is  used  to  store both SRTM tiles and ASTER granules. Use a standard "zip" 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.

       A similar procedure can be used to install SRTM data  files  manually.  Simply  copy  data
       tiles (e.g. N51W003.hgt.zip) into the "data" sub-directory.

AUTHOR

       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)