mbm_grd2geovrml(1)

NAME
mbm_grd2geovrml - Create and execute commands which generate a TerraVision tileset and GeoVRML terrain set that can be combined with other geospatial data for viewing in a web browser.

VERSION
Version 5.0

SYNOPSIS
mbm_grd2geovrml bath_file -tvdir tvparent -vrmldir vrmlparent -olat lat -olon lon -vrmlurl url Additional Options: -elevscale vert_exag -nowrz -noview -pallette pal -newimage type|file -white -zmax maxclip -zmin minclip -basename basename

DESCRIPTION
mbm_grd2geovrml is a macro that takes as input a GMT geographic-coordinate bathymetry grid file (bath_file) and produces a terrain tile set that may be viewed in a web browser with an appropriate plugin. The bathymetry (geometry) is paired with imagery (texture) to produce artificially illuminated terrain or slope shaded terrain. Alternatively, a co-registered image may be provided as a substitute to the latter imagery which is generated from the bathymetry data. This may be used to, for instance, draping a side scan sonar image over the bathymetry. Before the geoVRML files can be created an intermediate TerraVision tile set must be created from the input GMT bathymetry file and a TIFF image that is either generated from the bathymetry or specified from an existing file with the -newimage option. This tileset is then used to generate a GeoVRML quadtree multi-resolution set of files. The resulting set of files will be created in vrmlparent/<basename>, where <basename> is the same as bath_file without the usual '.grd' extension. This behavior may be overridded with the -basename option. This is useful if an existing image file is specified with the -newimage file option, in which case the image file base name should be used with -basename (see second example below). The index.html file produced in this directory can be loaded into Netscape 4.7 on a PC (properly configured with CosmoPlayer and GeoVRML 1.1) for interactive visualization. The resulting terrain can be used as a 3D basemap for use in visualizing other georeferenced data that has also been placed in GeoVRML using the same -olat and -olon settings. GeoVRML (and TerraVision) expects rectangular gridded elevation data and browsers render all terrain data within the rectangle. This presents a problem for ocean bathymetric data which often have irregular (not rectangular) boundaries. Before converting a grid file to TerraVision format mbm_grd2geovrml replaces all no-data elevation values with a coarse resolution spline-filled extrapolation from the data in the irregular area. This results in a rectangular grid with smooth transitions from areas of elevation data to areas of no data. In the resulting GeoVRML the no data areas are colored black (or white if -white is specified). If -newimage file is specified then the outer boundaries will stay the same color as in the image.

AUTHORSHIP
Mike McCann (mccann@mbari.org)
  Monterey Bay Aquarium Research Institute

SIMPLE DESCRIPTION OF BASIC OPTIONS

    bath_file
    A GMT gridded bathymetry file in geographic (lat/lon) coordinates. The file can be expressed with just the base name without the .grd extension, in which case the macro will append '.grd.gz' to bath_file and uncompress the data upon input. If the compressed data file does not exist then '.grd' will be appended to bath_file and it will be used, if it exists.

-tvdir
    tvparent The TerraVision tileset destination directory. A subdirectory named bath_file (without the .grd extension) will be created here.

-vrmldir
    vrmlparent
    The GeoVRML tileset destination directory. A subdirectory named bath_file (without the .grd extension) will be created here.

-olat
    lat

-olon
    lon
    The geoOrigin latitude and longitude in decimal degrees. Because of single precision arithmetic in VRML97 it is necessary to define a geoOrigin from which offsets are computed before coordinates are passed into the visualization pipeline. The geoOrigin should be within 5 degrees of the extent of the grid file in order to have submeter precision in the location of objects within the resulting GeoVRML output. See the GeoVRML spec for more details.
    The GeoOrigin of the terrain must be the same as the GeoOrigin of any other GeoVRML content (e.g. navigation tracks, sample locations) that you wish to combine with the terrain.

-vrmlurl
    url
    All default URLs that are placed in the VRML files will be relative. However, you should use the -vrmlurl option to specify an absolute URL for the set of tiles. Then all of the URLs that are used in the VRML files (image texture links and childUrls in the GeoLOD node) will use this as their base URL. This is generally not desirable because hardcoding absolute URLs into your datasets means that the dataset is nonportable to another server, or different location on the same server. However, it may be necessary to write absolute URLs in your tile files, especially if you have many levels because some VRML browsers have problems with relative links, resulting in tiles and images that will not load.

DESCRIPTION OF OPTIONAL OPTIONS

-elevscale
    vert_exag
    Factor with which to multiply elevations resulting in a vertical exaggeration of the terrain. The default value is 1.0. Factors greater than 1.0 increase vertical exaggeration.

-nowrz
    By default vrml output files are gzipped and saved with the .wrz extension. Specify -nowrz to override this and save the files uncompressed with the .wrl extension.

-noview
    By default a GeoViewpoint node with description 'home' is included with each GeoVRML tile file. These viewpoints are helpful for creating terrain-only visualizations, but they also quickly fill up the viewpoint list when many tiles are loaded. If you are creating GeoVRML tilesets to combine with other GeoVRML content that contain viewpoints then you may want to not have these 'home' viewpoints. Specify -noview to not include a GeoViewpoint with each tile.

-newimage
    type|file
    By default an orthorectified image for the bathymetry is created by running mbm_grdtiff(1) and then quadrupling the image size using ImageMagick mogrify(1). (The quadrupling together with the '-numpixels 16' argument in the make_geovrml(1) command results in identical resolution of the highest level GeoVRML tiles and the original bathymetric data.) Making this image can be a time consuming process. By default, if a file with '.tif' appended to bath_file (without the .grd extension) or appended to basename (if -basename option is specified) exists in $TMPDIR then a new image is not created. To override this either remove the .tif file or specify the -newimage option.
    type|file is the type used in the -G option of mbm_grdtiff(1) or the name of a TIFF file that you wish draped over the bathymetry. The default type value is 2 for synthetic illumination with Haxby color map (this may be modified with the -pallette option). Use 5 to shade the image by slope value. If <type|file> is an image file name then that file is assumed to be orthorectified TIFF image (ending in .tif) that is co-registered with the bathymetry file. This can be used to for example drape a side-scan sonar image over the elevation data. It is up to the user to confirm the co-registration between the terrain data and the image data.

-white
    By default a black background is generated for the orthorectified image. If a white background is desired (for example, for printing purposes) then use this option. Typically, for computer visual display a black background works best.

-zmax
    maxclip

-zmin
    minclip Maxclip and minclip may be used clip the elevation data at set values. For instance, to clip the elevation data at sealevel and tile only bathymetry use -zmax 0. To force a color map of the standard Haxby colors between 4000 and 3000 meters depth use -zmin -4000 -zmax -3000.

-pallette
    pal The number of Color Lookup Table that is passed on to the -W1/ option of mbm_grdtiff(1). The default value is 1 - the Haxby color map. For reference, the color tables values are:
            pallette = 1: Haxby colors [default]
            pallette = 2: high Intensity colors
            pallette = 3: low Intensity colors
            pallette = 4: grayscale
            pallette = 5: uniform grayscale

ENVIRONMENT VARIABLE AND LOG FILE
The environment variable TMPDIR must be defined. It specifies the directory in which mbm_grd2geovrml does its work. $TMPDIR should have sufficient space to hold the temporary grid and image files that get created. The resulting 4 times magnified tiff images are left in $TMPDIR. These large image files are reused unless the -newimage option is specified. A log file is saved at the end of processing in the vrmlparent directory. It includes all the commands and their output. This file may be edited and executed again in order to produce customized output.

EXAMPLES
This example creates a GeoVRML set of terrain tiles from the bathymetry data in file PapauA_bath.grd. The geometry files will not be compressed and viewpoints will be included with each tile.
  mbm_grd2geovrml PapauA_bath \
    -olat 21 -olon -157 \
    -tvdir ~/TileSets/Pyramids/hawaii \
    -vrmldir ~/TileSets/geoVRML/hawaii \
    -nowrz -vrmlurl \
    http://menard/vrml/terrain/hawaii/PapauA_bath
This example creates a grid file of the Northeast Pacific at one minute resolution and creates the GeoVRML tiles of it with the elevations clipped at sea level. A new synthetic illuminated Haxby-colored image is generated from the elevation data.
  # Extract 1 minute data for Northeastern Pacific Ocean
  # and convert it to GeoVRML terrain
  #
  grdraster 4 -R-165/-105/15/50\
        -GNEPacific.grd \
        -I1m -V
  mbm_grd2geovrml NEPacific.grd \
    -tvdir ~/TileSets/Pyramids/pacific \
    -vrmldir ~/TileSets/geoVRML/pacific \
    -vrmlurl \
    http://menard/vrml/terrain/hawaii/NEPacific \
    -zmax 0 -olat 35 -olon -135 -newimage
This example generates a slope-shaded image from the bathymetry data in PapauA_bath.grd and saves the geoVRML file in the directory ~/TileSets/geoVRML/hawaii/PapauA_slope. No viewpoints are specified.
  mbm_grd2geovrml PapauA_bath \
      -olat 21 -olon -157 \
      -tvdir ~/TileSets/Pyramids/hawaii \
      -vrmldir ~/TileSets/geoVRML/hawaii \
      -vrmlurl \
      http://menard/vrml/terrain/hawaii/PapauA_slope \
      -noview \
      -newimage 5 \
      -basename PapauA_slope
This example uses a pre-generated side-scan sonar TIFF image and drapes it over the bathymetry data in PapauA_bath.grd. Viewpoints are excluded. Ouptut is written to ~/TileSets/geoVRML/hawaii/PapauA_ssdtl.
  mbm_grd2geovrml PapauA_bath \
      -olat 21 -olon -157 \
      -tvdir ~/TileSets/Pyramids/hawaii \
      -vrmldir ~/TileSets/geoVRML/hawaii \
      -vrmlurl \
      http://menard/vrml/terrain/hawaii/PapauA_ssdtl \
      -noview \
      -newimage PapauA_ssdtl.tif \
      -basename PapauA_ssdtl

SEE ALSO
This macro is built upon some pretty strong shoulders. It uses all of these programs which must be installed on your system. GMT programs: grdclip(1), grdsample(1), grd2xyz(1), blockmean(1), surface(1), grdedit(1), grdmath(1), grdclip(1), mb-system macro: mbm_grdtiff(1) mb-system utility: mbstripNaN(1) tsmApi-2.3 (http://www.tsmapi.com) programs: make_dem(1), make_oi(1) make_geovrml(1) Note that after you've created the TerraVision tile sets with this macro you may rerun make_geovrml(1) with different options, for instance to make files for a different server or with a different vertical exaggeration or background color. This can save a lot of processing time if you don't need to generate a new image from the bathymetric data. ImageMagick (http://www.imagemagick.org) program: mogrify(1)
Please see http://www.mbari.org/~mccann/vrml/ROVDataVis for example content and more information on the project that developed this macro.

BUGS
You need to manually clean up the leftover files that get created in $TMPDIR.
The -vrmlurl option must be specified. As of 19 March 2003 there is a bug in make_geovrml(1) where if the -vrmlurl option is not specified invalid VRML is generated. This is generally not a problem. Because of bugs in VRML browsers all URLs must be absolute anyway.
The GeoVRML content produced by this macro may be viewed using Internet Explorer with the Cortona 4.0 VRML plugin or in Netscape 4.7 with the CosmoPlayer plugin. Both browsers have problems with loading a second world after you have viewed one. Netscape 4.7 often must be closed by killing it with Windows Task Manager. Sometimes the CosmoPlayer plugin will refuse to load at all. If this happens try removing all cp* files in %TEMP% or logging in with another Windows account so that a different profile is used.