MB-System Unix Manual Page: mbm_grd2geovrml

### MB-System Unix Manual Page

#

##

##

##

##

##

##

##

##

##

##

##

##

    mbm_grd2geovrml
    Section:  MB-System 5.0  (1)
    Updated:  3 June 2013
    Index

    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.

     Index

    NAME
    VERSION
    SYNOPSIS
    DESCRIPTION
    AUTHORSHIP
    SIMPLE DESCRIPTION OF BASIC OPTIONS
    DESCRIPTION OF OPTIONAL OPTIONS
    ENVIRONMENT VARIABLE AND LOG FILE
    EXAMPLES
    SEE ALSO
    BUGS

Last Updated: 3 June 2013

Return to list of MB-System manual pages...

Back to MB-System Home Page...