/usr/share/doc/terraintool/README.html is in terraintool 1.13-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>TerrainTool - create surface topographic data for Survex and Therion</title>
<meta http-equiv="Content-Language" content="en-gb" />
<meta name="robots" content="robots.txt" />
<meta name="Copyright" content="Copyright (c) 2008 - 2017 Mike McCombe" />
<meta name="Rating" content="General" />
<meta name="revisit-after" content="25 Days" />
</head>
<body>
<div id="content">
<h1>TerrainTool</h1>
<p>
TerrainTool is used to create surface topographic data for the cave survey packages <a href="http://survex.com">Survex</a> and <a href="http://therion.speleo.sk">Therion</a>.
This uses the results of the <a href="http://www2.jpl.nasa.gov/srtm/">Shuttle Radar Topography Mission</a> (SRTM) in which the shuttle <i>Endeavour</i> 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.
</p>
<p>
More recently, the <a href="http://www.jpl.nasa.gov/news/news.cfm?release=2009-103">Advanced Spaceborne Thermal Emission and Reflection Radiometer (ASTER)</a> 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.
</p>
<p>
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 <a href="#Installing_ASTER_data_files">below</a>.
</p>
<p>
TerrainTool does the following:-
</p>
<ul>
<li>
Automatically downloads SRTM data from the NASA https site as needed.
</li>
<li>
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.
</li>
<li>
Re-samples the data using bilinear interpolation to create a rectangular mesh of user-specified spacing.
</li>
<li>
Displays a coloured topographic map of the mesh.
</li>
<li>
Adds a user-specified offset (3-D) to the coordinates to align with coordinates used for the underground survey.
</li>
<li>
Saves the mesh as surface data in Survex (.svx) or Therion (.th) format.
</li>
</ul>
<p>
The programme, written in Java, provides a conventional GUI-style interface and will run under Windows, Solaris, macOS and Linux operating systems. The latest Java
Runtime is required and can be downloaded free of charge from <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Oracle</a> or openJDK.
The JRE needs to be at least version 7. Mac users should note that the the legacy version 6 implementation provided by Apple is no longer sufficient.
</p>
<p>
"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 <a href="http://survex.com/maillist.html">Survex list</a>.
</p>
<h2>Installation</h2>
<p>
Sorry, there's no fancy package installer but as there's only one file it should be pretty straightforward.
</p>
<ol>
<li>
If you don't already have the Java Standard Edition (SE) installed, <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">download</a> it from the Oracle
website now. Unless you plan to develop your own Java software, the Java Runtime Environment (JRE) will suffice.
</li>
<li>
<a href="TerrainTool.jar">Download the TerrainTool</a> "jar". Internet Explorer users 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! I suggest you save it in its own directory. When you first run the programme, it will create
"terraintool.properties" (in the same directory) and a subdirectory called "data".
</li>
<li>
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".
</li>
</ol>
<p>
Thanks to Wookey, Terraintool is available in Debian 7 ('Wheezy') or Ubuntu 12.04 ('Precise Pangolin') onwards. To install it select 'terraintool' in your favourite package manager (Upgrade Center, Synaptic, Aptitude) and install it.
On the command line do
</p>
<p>
sudo apt-get install terraintool
</p>
<p>
If your system has a firewall, you <i>may</i> need to tell it to allow java to have outgoing ftp access. Otherwise, it won't be able to download the data files from the
NASA site. This version of TerrainTool doesn't support Internet access via a proxy. I can easily add this if anyone wants it - but I have no means of testing it.
</p>
<h2>Driving Instructions</h2>
<p>
TerrainTool is a conventional GUI-based application with a menu bar and dialog boxes to gather user-information. To get started, do the following:
</p>
<ol>
<li>
Select the required <a href="#Region">region</a> and <a href="#Coordinates">coordinate system</a> using the Options menu
</li>
<li>
Go to <a href="#Create">Create</a> on the File menu to specify the size, location and resolution of the mesh.
</li>
<li>
<a href="#Save_as">Save</a> the results as in Survex (.svx) or Therion (.th) format
</li>
<li>
Use Survex to process the file and Aven to view the results in 3D. Remember to enable viewing of surface legs in Aven!
</li>
<li>
Use the Offset command in the Options menu to fully align the terrain data with the coordinates used in your survey.
</li>
<li>
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. </li>
<li>
Incorporate the terrain data into your survey project.
</li>
</ol>
<h3>File Menu</h3>
<p>
<strong><a name="Create" id="Create">Create</a></strong>... is used to calculate the terrain mesh. A dialog box is used to gather the following:-
</p>
<table class="ubsstable">
<tr>
<th>
Item
</th>
<th>
Meaning
</th>
</tr>
<tr>
<td>
Grid Reference
</td>
<td>
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.
</td>
</tr>
<tr class="altRow">
<td>
E-W Range
</td>
<td>
The distance (in metres) between the East and West edges of the mesh.
</td>
</tr>
<tr>
<td>
N-S Range
</td>
<td>
The distance (in metres) between the North and South edges of the mesh.
</td>
</tr>
<tr class="altRow">
<td>
Spacing
</td>
<td>
The distance (in metres) between adjacent cells in the mesh.
</td>
</tr>
<tr>
<td>
Grid ref is at
</td>
<td>
Specifies where current point (see "Grid Reference" above) lies in relation to the boundaries of the mesh.
</td>
</tr>
</table>
<p>
Pressing <strong>OK</strong> 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.
</p>
<p>
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.
</p>
<p>
<strong>Lat/Long</strong>... 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.
</p>
<p>
Latitude and longitude values can be expressed as either
</p>
<ul>
<li>
real values in degrees (e.g. 46.25), where negative values are West / South, or
</li>
<li>
values in degrees, minutes and seconds (e.g. 46 N 15' 22.6")
</li>
</ul>
<p>
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.
</p>
<p>
<strong><a name="Save_as" id="Save_as">Save as</a>...</strong>
</p>
<p>
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.
</p>
<p>
Otherwise, height values are defined for each point in the mesh. Easting and Northing values are those of the current coordinate system.
</p>
<h3>
Options Menu
</h3>
<p>
<strong><a name="Coordinates" id="Coordinates">Coordinates</a>...</strong>
</p>
<p>
This is used to select the type of coordinates to use. The following are currently supported:
</p>
<table class="ubbsstable">
<tr>
<th>
Coordinate System
</th>
<th> </th>
</tr>
<tr>
<td>
Austrian
</td>
<td>
The Austrian (BMN) coordinate system, in three zones
</td>
</tr>
<tr class="altRow">
<td>
Irish Grid
</td>
<td>
The Irish grid system, used in both Northern Ireland and the Republic of Ireland.
</td>
</tr>
<tr>
<td>
Lambert 93
</td>
<td>
The Lambert 93 coordinate system. A conformal conical projection occasionally used in France.
</td>
</tr>
<tr class="altRow">
<td>
Lambert (5 zones)
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
NZMG
</td>
<td>
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.
</td>
</tr>
<tr class="altRow">
<td>
NZTM2000
</td>
<td>
New Zealand Transverse Mercator, successor to NZMG.
</td>
</tr>
<tr>
<td>
OSGB
</td>
<td>
Ordnance Survey of Great Britain - the normal British grid system.
</td>
</tr>
<tr class="altRow">
<td>
UTM
</td>
<td>
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.
</td>
</tr>
</table>
<p>
One of the design objectives of this software is to be able to add further coordinate systems with minimal difficulty.
</p>
<p>
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.
</p>
<p>
<strong>Auto download</strong> enables/disables the automatic downloading of data from the NASA SRTM site.
</p>
<p>
<strong><a name="Region" id="Region">Region</a></strong>
</p>
<p>
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.
</p>
<p>
<strong><a name="Offset" id="Offset">Offset</a></strong>
</p>
<p>
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
</p>
<ul>
<li>
Your cave survey coordinates might not use the full easting and northing values
</li>
<li>
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.
</li>
</ul>
<p>
<strong>SRTM Only</strong>
</p>
<p>
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.
</p>
<p>
<strong>ASTER Only</strong>
</p>
<p>
Creates terrain using only ASTER data. This has higher resolution and greater coverage than SRTM data but must be manually downloaded and installed
(<a href="#Installing_ASTER_data_files">see below</a>). 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.
</p>
<p>
<strong>SRTM plus ASTER</strong>
</p>
<p>
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.
</p>
<p>
<strong>Legacy ASTER Data</strong>
</p>
<p>
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.
</p>
<h2>
<a name="Installing_ASTER_data_files" id="Installing_ASTER_data_files">Installing ASTER data files</a>
</h2>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</div>
</body>
</html>
|