terraintool(1)
NAME
tunnelx --- Generating surface meshes for cave survey software
SYNOPSIS
tunnelx
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
interfaceand 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)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
