.TH "Terraintool" "1" 
.SH "NAME" 
terraintool \(em Generating surface meshes for cave survey software 
.SH "SYNOPSIS" 
.PP 
\fBterraintool\fR 
.SH "DESCRIPTION" 
.PP 
TerrainTool was written to create surface topographic data for 
the cave survey 
packages \fISurvex (link to URL http://survex.com) \fR and 
\fITherion (link to URL http://therion.speleo.sk) \fR using the 
results of 
the \fIShuttle Radar 
Topography Mission (link to URL http://www2.jpl.nasa.gov/srtm/) \fR (SRTM) in which the shuttle 
\fIEndeavour\fP 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. 
 
.PP 
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 
\fIAdvanced 
Spaceborne Thermal Emission and Reflection Radiometer 
(ASTER) (link to URL http://www.jpl.nasa.gov/news/news.cfm?release=2009-103) \fR 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. 
 
.PP 
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 
 
.IP "   \(bu" 6 
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 
 
.IP "   \(bu" 6 
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 
\fIhttps://urs.earthdata.nasa.gov/users/new/ (link to URL https://urs.earthdata.nasa.gov/users/new/) \fR 	 
.PP 
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) 
 
.PP 
Having logged in to your Earthdata account, you can find the 
NASADEM data by going to 
\fIhttps://lpdaac.usgs.gov/products/nasadem_hgtv001/ (link to URL https://lpdaac.usgs.gov/products/nasadem_hgtv001/) \fR ) 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 
\fIhttps://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/) \fRPlease 
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. 
 
.PP 
TerrainTool does the following:\- 
 
.IP "   \(bu" 6 
If required, automatically downloads SRTM data from the USGS 
server. 
 
.IP "   \(bu" 6 
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. 
 
.IP "   \(bu" 6 
Re-samples the data using biaxial interpolation to create a 
rectangular mesh of user-specified spacing. 
 
.IP "   \(bu" 6 
Displays a coloured topographic map of the mesh. 
 
.IP "   \(bu" 6 
Adds a user-specified offset (3-D) to the coordinates to align with 
coordinates used for the underground survey. 
 
.IP "   \(bu" 6 
Saves the mesh as surface data in Survex (.svx) or Therion (.th) format. 
 
.PP 
The programme, written in Java, provides a conventional GUI-style 
interface and will run under Windows, Solaris, macOS and Linux operating 
systems.  
 
.PP 
"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 
\fISurvex list (link to URL http://survex.com/maillist.html) \fR. 
 
.SH "Driving Instructions" 
.PP 
TerrainTool is a conventional GUI-based application with a menu bar 
and dialog boxes to gather user-information. To get started, do the 
following: 
 
.IP "   1." 6 
Select the required \fIcoordinate 
system\fR using the Options menu. If you're not using the NASA 
DEM you'll also need to specify the 
\fIregion\fR          
.IP "   2." 6 
Go to \fICreate\fR on the File menu to 
specify the size, location and resolution of the mesh. 
 
.IP "   3." 6 
\fISave\fR the results as in Survex (.svx) 
or Therion (.th) format 
 
.IP "   4." 6 
Use Survex to process the file and Aven to view the results in 3D. 
Remember to enable viewing of surface legs in Aven! 
 
.IP "   5." 6 
Use the Offset command in the Options menu to fully align the 
terrain data with the coordinates used in your survey. 
 
.IP "   6." 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. 
 
.IP "   7." 6 
Incorporate the terrain data into your survey project. 
 
.SH "File Menu" 
.PP 
\fICreate\fP... is used to calculate 
the terrain mesh. A dialog box is used to gather the following:\- 
 
.sp 1 
\fBCreate dialog items\fR 
.TS 
tab(); 
l l l l l l l l l l l l l l l l l l. 
\fBItem\fR\fBMeaning\fR 
Grid ReferenceThe 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 RangeThe distance (in metres) between the East and West edges of the 
mesh. 
N-S RangeThe distance (in metres) between the North and South edges of the 
mesh. 
SpacingThe distance (in metres) between adjacent cells in the mesh. 
Grid ref is atSpecifies where current point (see "Grid Reference" 
above) lies in relation to the boundaries of the mesh. 
.TE 
.PP 
Pressing \fIOK\fP 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. 
 
.PP 
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. 
 
.PP 
\fILat/Long\fP... 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. 
 
.PP 
Latitude and longitude values can be expressed as either 
 
.IP "   \(bu" 6 
real values in degrees (e.g. 46.25), where negative values are West 
/ South, or 
 
.IP "   \(bu" 6 
values in degrees, minutes and seconds (e.g. 46 N 15' 22.6") 
 
.PP 
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. 
 
.PP 
\fISave as...\fP        
.PP 
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. 
 
.PP 
Otherwise, height values are defined for each point in the mesh. 
Easting and Northing values are those of the current coordinate 
system. 
 
.SH "Options Menu" 
.PP 
\fICoordinates...\fP        
.PP 
This is used to select the type of coordinates to use. The 
following are currently supported: 
 
.PP 
\fBCoordinate Systems\fR  
.TS 
tab(); 
l l. 
Coordinate SystemDescription 
AustrianT{ 
The Austrian (BMN) coordinate system, in three zones 
T} 
Irish GridT{ 
The Irish grid system, used in both Northern Ireland and the 
Republic of Ireland. 
T} 
Lambert 93T{ 
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} 
NZMGT{ 
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} 
NZTM2000T{ 
New Zealand Transverse Mercator, successor to NZMG. 
T} 
OSGBT{ 
Ordnance Survey of Great Britain \- the normal British grid system. 
T} 
Slovenian GridT{ 
A Transverse-Mercator grid used in Slovenia 
T} 
UTMT{ 
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} 
.TE 
.PP 
One of the design objectives of this software is to be able to add 
further coordinate systems with minimal difficulty. 
 
.PP 
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. 
 
.PP 
\fIAuto download\fP         enables/disables the automatic downloading of SRTM data from 
the USGS site. This option is disabled when the NASA DEM is 
selected. 
 
.PP 
\fIRegion\fP        
.PP 
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. 
 
.PP 
\fIOffset\fP        
.PP 
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 
 
.IP "   \(bu" 6 
Your cave survey coordinates might not use the full easting and 
northing values 
 
.IP "   \(bu" 6 
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. 
 
.PP 
\fINASA\fP        
.PP 
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. 
 
.PP 
\fISRTM\fP        
.PP 
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. 
 
.SH "AUTHOR" 
.PP 
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. 
 
.PP 
On Debian systems, the complete text of the GNU General Public 
License can be found in /usr/share/common-licenses/GPL. 
 
.\" created by instant / docbook-to-man