Provided by: terraintool_1.16-3_all 
NAME
terraintool — Generating surface meshes for cave survey software
SYNOPSIS
terraintool
DESCRIPTION
TerrainTool was written 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)
using 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. 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 Advanced Spaceborne Thermal Emission and Reflection Radiometer (ASTER)
(link to URL http://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/ (link to URL
https://urs.earthdata.nasa.gov/users/new/)
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)
Having logged in to your Earthdata account, you can find the NASADEM data by going to
https://lpdaac.usgs.gov/products/nasadem_hgtv001/ (link to URL
https://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/ (link to URL
https://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:-
• If required, automatically downloads SRTM data from the USGS server.
• 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 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 coordinate system using the Options menu. If you're not using
the NASA DEM you'll also need to specify the region
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 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. If "Auto-download" is enabled, data
files will be downloaded as needed from the USGS server. These are stored in
XDG_DATA_HOME/terraintool (normally "$HOME/.local/share/terraintool" 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.
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}
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.
Auto download enables/disables the automatic downloading of SRTM data from the
USGS site. This option is disabled when the NASA DEM is selected.
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. This option is only relevant to the SRTM DEM. It
is disabled when the NASA DEM is selected.
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.
NASA
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.
SRTM
Creates terrain using 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
connection, missing tiles will be automatically downloaded from the USGS server.
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)