TerrainTool

TerrainTool was written to create surface topographic data for the cave survey packages Survex and Therion using the results of the Shuttle Radar Topography Mission (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 in 2000. 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. In due course, NASA released all of the data at the full 1 arc-second resolution. The resulting data is royalty-free and, for many countries, may be the only data publicly available.

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) 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 quite 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 disadvantages are

With the completion of NASADEM, this release of TerrainTool uses it as its only source of data.

Having logged in to your Earthdata account, you can find the NASADEM dataset by going to 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 of the tiles, currently at 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:-

The programme, written in Java, provides a conventional GUI-style interface and will run under Windows, Solaris, macOS and Linux operating systems. This version is built to run with JDK 21 which can be downloaded free of charge from Oracle or The Open JDK Project. Sorry this will require existing users to upgrade their Java installation but this Java version is flagged for Long-Term Support and is the most up to date for production use.

"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 mike<at>mikemccombe.co.uk or via the Survex list.

Installation

Sorry, there's no fancy package installer but as there's only one file it should be pretty straightforward.

  1. If you don't already have JDK 21 installed, do it now! Windows users will need to set the system PATH variable to point to the jdk-21\bin directory and remove references to any earlier Java releases
  2. Download the TerrainTool "jar". Depending on your browser you may find that the file that arrives is called TerrainTool.zip. If this happens, just rename it to be TerrainTool.jar. Do not try unpacking the ZIP file!
  3. Double-clicking the jar file should start the programme. If you need to start it from a command line interface, try "java -jar TerrainTool.jar".

Thanks to Wookey, TerrainTool has been available in Debian and Ubuntu since 2012 (7/'Wheezy' and 12.04/'Precise Pangolin' respectively). To install it select 'terraintool' in your favourite package manager (Upgrade Center, Synaptic, Aptitude) and install it. On the command line do

sudo apt-get install terraintool

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. If you already know which tiles you will need from the NASADEM dataset, download them now and save them in the data directory for later re-use if necessary. On Windows this will be in a directory called ".terraintool" in the user's top-level directory on the system drive e.g. c:\users\mike\.terraintool and on unix or linux at ~/.local/share/terraintool/ Otherwise,when you try to create the mesh, TerrainTool will provide an error message to say which tile it needs and where to store it.
  2. Select the required coordinate system using the Options menu.
  3. Go to Create on the File menu to specify the size, location and resolution of the mesh.
  4. Save the results as in Survex (.svx) or Therion (.th) format
  5. Use Survex to process the file and Aven to view the results in 3D. Remember to enable viewing of surface legs in Aven!
  6. Use the Offset command in the Options menu to fully align the terrain data with the coordinates used in your survey.
  7. 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.
  8. Incorporate the terrain data into your survey project.

File Menu

Create

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

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. The NASADEM tiles are stored in the data directory for later re-use if necessary. On Windows this will be in a directory called ".terraintool" in the user's top-level directory on the system drive e.g. C:\Users\mike\.terraintool and on Unix/linux at ~/.local/share/terraintool/

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

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

Latitude and longitude values can be expressed as either

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 in Survex (.svx) or Therion (.th) format or as a Comma Separated Variable (.csv) file that can be loaded into a spreadsheet.

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 System
Austrian The Austrian (BMN) coordinate system, in three zones
Irish Grid The Irish grid system, used in both Northern Ireland and the Republic of Ireland.
Lambert 93 The Lambert 93 coordinate system. A conformal conical projection occasionally used in France.
Lambert (5 zones) 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.
NZMG 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.
NZTM2000 New Zealand Transverse Mercator, successor to NZMG.
OSGB Ordnance Survey of Great Britain - the British grid system.
Slovenian Grid A Transverse-Mercator grid used in Slovenia
UTM 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.

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.

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

Source Code

Terraintool was developed using the Apache Netbeans IDE with the GUI elements created using the javax.Swing API. For those interested in building TerrainTool themselves, or perhaps are just curious, the source code can be found here;