Obtaining and Building Terreno

Obtaining Terreno

http://amcg.ese.ic.ac.uk/index.php?title=Terreno

Obtaining and Installing Terreno Prerequisites

The package can use BLAS, LAPACK, CGNS and NetCDF. The INSTALL file says that it requires VTK 4.x, ScientificPython and Numeric.

We handle them as follows:

VTK

The Visualization ToolKit (VTK) package is a library for 3-D computer graphics, image processing and visualization. It is quite useful and is used by many, many other packages for such tasks. The home page is at:

http://www.vtk.org/

and the software can be obtained from:

http://www.vtk.org/get-software.php

with the installation instructions available within the downloaded source code package. This is a very large and complex package, and will take a bit of time to compile and install, even on very fast machines.

BLAS and LAPACK

A very good thing to do is compile and install the ATLAS versions of BLAS and LAPACK rather than generic versions. The ATLAS (Automatically Tuned Linear Algebra Software) package can be found at:

http://math-atlas.sourceforge.net/

and the instructions on how to compile and install the ATLAS versions of BLAS and LAPACK are at:

http://math-atlas.sourceforge.net/atlas_install/

CGNS (CFD General Notation System)

This can be obtained at:

http://sourceforge.net/project/showfiles.php?group_id=74444

Obtain both CGNSlib and CGNStools.

To build a shared version of CGNSlib. 

cd /d1/SOFT
tar xzvf cgnslib_2.5-3.tar.gz
cd cgnslib_2.5
./configure --prefix=/usr/local --enable-shared --enable-lfs --enable-64bit
make
su
make install
This will install: 
/usr/local/include/cgnslib.h
/usr/local/include/cgnslib_f.h
/usr/local/include/cgnswin_f.h
/usr/local/lib/libcgns.so
If you also want the static (nonshared) version of the library: 
cd /d1/SOFT
./configure --prefix=/usr/local --enable-lfs --enable-64bit
make
su
make install
which will additionally install: 
/usr/local/lib/libcgns.a

To build CGNStools: 

cd /d1/SOFT
tar xzvf cgnstools-2-5-2.tar.gz
cd cgnstools
./configure --prefix=/usr/local --with-cgns=/d1/SOFT/cgnslib_2.5 --enable-64bit
make
su
make install
This will install the following tools in /usr/local/bin: 
cgnsplot
cgnswish
convert_dataclass
convert_variables
extract_subset
interpolate_cgns
cgns_to_plot3d
cgns_to_tecplot
cgns_to_vtk
convert_location
patran_to_cgns
tecplot_to_cgns
cgnscheck
cgnsversion
plot3d_to_cgns
unitconv
cgnscalc
cgconfig
adfviewer
cgnsnodes
cgsystem

Building and Installing Terreno

Building the Main Package 

cd /d1/SOFT
svn co https://terreno.svn.sourceforge.net/svnroot/terreno/trunk terreno
cd terreno
#  Since the ATLAS BLAS and LAPACK libs were build using gfortran:
export FC=/usr/bin/gfortran
export F77=/usr/bin/gfortran
./configure --prefix=/usr/local --with-cgns=/usr/local --with-netcdf=/opt/NETCDF/netcdf-3.6.2-sh
make
su
make install
This will install in /usr/local/bin the following: 
coast2vtp
diagnostics
dxf2xyz
grd2vtu
resample
shore
terreno
triangulate2vtu

Building the Python Module

The command needed to build the accompanying Python module is: 

python setup.py build
This unfortunately yields the following sort of error: 
running build
running build_py
creating build
creating build/lib
creating build/lib/terreno
copying python/__init__.py -> build/lib/terreno
copying python/TransferFunctionEditor.py -> build/lib/terreno
copying python/paleontologic.py -> build/lib/terreno
copying python/ImportanceMap.py -> build/lib/terreno
copying python/MeshingParameters.py -> build/lib/terreno
copying python/Terreno.py -> build/lib/terreno
copying python/viewer.py -> build/lib/terreno
copying python/netcdf.py -> build/lib/terreno
copying python/MapParameters.py -> build/lib/terreno
running build_scripts
creating build/scripts-2.4
error: file 'terreno' does not exist

We are presently not sure how to remediate this.

Using Terreno

Overview of Programs

First, we look at the capabilities of each program. Running terreno without arguments obtains: 

ERROR: no input file provided
Usage:
terreno <-a|r value> <-f infile> []

 -A 
  Maximum element aspect ratio allowed. The default is 1 - increase this if you want anisotropic elements.
 -a 
  Absolute interpolation error for bathymetry approximation.
 -c 
  Value of coastal contour. If a vectorises coastline  is provided via the -w option then this is the depth
  of the supplied coastline. Otherwise a contour is estimated from the bathymetry data. (default: 0.0)
 -D
 Enable debugging. This is pretty paranoid and so will really slow down the processing. So only use if you
 think the mesh is really screwy. This also implied -d (mesh diagnostics).
 -d
  Print out mesh diagnostics.
 -E 
  This specifies the reference ellipsoid to be used for distance measurements. Valid options are:
  Option     Description
  1          GRS80 / WGS84  (NAD83) - default
  2          Clarke 1866    (NAD27)
  A          Airy 1858'
  B          Airy Modified'
  C          Australian National'
  D          Bessel 1841'
  E          Clarke 1880'
  F          Everest 1830'
  G          Everest Modified'
  H          Fisher 1960'
  I          Fisher 1968'
  J          Hough 1956'
  K          International (Hayford)'
  L          Krassovsky 1938'
  M          NWL-9D (WGS 66)'
  N          South American 1969'
  O          Soviet Geod. System 1985'
  P          WGS 72'
  U          user-defined
 -e <1-10>
  How much effort you want from terreno. The default (2) is usually sufficient but you can crank up the
  value for that little expre bit of perfection. Currently this option increases the proportion of the 
  priority queue scanned when looking for sub-optimal elements and increases the number of sweeps over 
  the simplification algorithm.
 -f 
  Bathymetry input file.
 -g 
  Rate of change of element size in metric space. (default: 1.3)
 -h
  Prints this help message.
 -I 
  The reference ellipsoid used for the input data. See the proj4 documentation for a list of valid choices (default is WGS84)
 -i 
  Importance map input file.
 -l 
  Sea level. (default: 0.0)
 -M 
  Type of mesh in the vertical. Valid options are: sigma, zsigma, z. (default: z)
 -m
  Cartesian output
 -n 
  Set number of vertical layers in mesh. (default: 4)
 -o 
  Supported export formats are cgns (3D only), vtk_2d, vtk_3d, stl (2D only) and triangle (3D only) (default: cgns).
 -P <"proj4 parameters">
  Output projection. For complete documentation on projection parameters see the proj4 documentation. Note that
  if a reference ellipsoid is specified here, it overwrites that specified by the -I option if used (default: output 
  projection is same as input.)
 -p
  Output VTK plots of various components of the mesh as meshing progresses.
 -q 
  Smoothen bathymetry. Specify the maximum number of iterations and the tolerence for the smoothening iterations.
 -r 
  Relative interpolation error for bathymetry approximation. (default: 0.01)
 -S 
  Use stereographic projection when calculating approximation. longitude0/latitude0 specified the location of the
  stereographic projection point (i.e. the point at the centre of the projection). (default: off)
 -s 
  Coordinate in sea of interest. This seed is used to identify the region of interest.
 -T
  Remove elements stretched over multiple z-layers if you're seeing sigma-coordinate errors near steep bathymetry
 -t 
  Elevation data from tsunami. The file should be a NetCDF file.
 -u
  Use ncurses to print updates on meshing progress. This is disabled if verbosity is also enabled.
 -V
  Print out version information.
 -v
  Verbose progress information. (default: off)
 -w 
  Ascii file containing shoreline data.
 -z 
  Specifies z-coordinate for the first n levels. This option is only valid for z and zsigma meshes.

Examples

A paper chock full o' examples can be found at:

http://doi:10.1016/j.cageo.2007.06.014

A useful thing to have for these examples is the freely available GEBCO One Minute Grid, which can be obtained (after registration) at:

http://www.bodc.ac.uk/data/online_delivery/gebco/select/

and which contains a one minute resolution file in NetCDF format called:

GridOne.grd

Processing Gridded Data

The example in the paper starts by defining a polygon around the British Isles as: 

-2,49
-2,57
-8,57
-8,53
-10,53
-10,49
-2,49
in a file called polygon. The GMT command grdmask is then used to generate a mask, i.e. 

grdmask polygon -NNaN/NaN/1-R-10/-2/49/57 -I1m -Gmask.grd
where:

The GMT command grdsample is then used to extract the same region at the same resolution from the GEBCO One Minute Grid file GridOne.grd. 

grdsample -R-10/-2/49/57 -I1mGridOne.grd -Gsection.grd
where:

Now the GMT command grdmath is used to apply the land mask to the subsambled GEBCO data: 

grdmath section.grd mask.grd MUL=irish_sea.grd
where:

This provides the basic gridded dataset from which a bathymetric approximation can proceed.

Creating a Shoreline Model with Terreno

An importance map will now be calculated where the point of interest is Liverpool Bay at 3.02 deg. W and 53.44 deg. N. This will be accomplished via the GMT command grdmath, a RPN calculator for NetCDF files. The two-step calculations starts with: 

grdmath -R-12/-0/48/60 -I12m -3.020897 53.446558 GDISTPI MUL 180 DIV 6378 MUL=distance.grd
where:

The importance map is generated in the second step via: 

grdmath distance.grd 2 POW 1.109e-05 MUL NEG EXP 0.2 MAX=importance.grd
where:

Finally, the Terreno command shore is used to generate a shoreline approximation using the importance map, i.e. 

shore -d 500/500/5000 -f section.grd -i importance.grd > shoreline.dat
where:

Creating a Bathymetric Model with Terreno

The shoreline approximation shoreline.dat is incorporated into the initially generated bathymetric mesh using an edge recovery on triangular meshes algorithm. The mesh is then optimized via various specified parameters, with the result a mesh representing the domain's bathymetry to a specified linear interpolation error. A final step creates a prismatic tetrahedral mesh from the optimized 2-D mesh. The Terreno command to generate the final mesh is: 

terreno -g 1.2 -e 7 -s -5/53 -f irish_sea.grd -i importance.grd -r 0.1 -n 4 -w shoreline.dat
where: