make_geovrml tsmApi utility - manual page version 1.12

NAME

make_geovrml - create a GeoVRML 1.0 terrain hierarchy
SYNOPSIS
make_geovrml -dem <dem-pyramidt> -oi <oi-pyramid> -vrmldir <dir> [...]
DESCRIPTION
This utility can be used to create a hierarchy of tree files for a VRML terrain dataset. Tree files are used to spatially organise the mutli-resolution terrain tiles and implement the level of detail management. Tree files also specify bounding box information for the geometry contained within each tile.

Currently you generate a tree hierarchy by supplying a DEM (elevation) and OI (ortho-rectified imagery) pyramid in TerraVision format. The term pyramid means a multi-resolution hierarchy of data which has been segmented into equally-sized tiles over each resolution. This utility will then generate a tree hierarchy for the specified dataset using the GeoVRML 1.0 syntax.

The DEM and OI pyramids that are required for input to this program can be generated from raw source data using the make_dem and make_oi utilities (see below).

An index.html file is created in the dataset directory. You can point your web browser at this file in order to display the dataset in a GeoVRML-enable VRML browser.

A number of command line options are supported. These are described below. The position of any optional argument on the command line is not significant. Running the program with no parameters will display a short help text.

With options added by Mike McCann (-olat, -olon, -noview, -hud, -maxrange, -wrl, -touch) make_geovrml will work only with Geodetic data (Latitude, Longitude coordinates) DEM input. To create a GeoVRML terrain heirarchy whose highest level of detail is the same resolution as the input data you may do the following: quadruple the image size before running make_oi and use the -numpolys 16 option in make_geovrml. See the last example below.

Required Parameters:

-dem <dem-pyramid>
This specifies the elevation data that you wish to use in order to create the tree hierarchy. It should be the filename or URL of a TerraVision DEM dataset. If you specify this argument, then you must also specify the -oi command line option. Alternatively, you can use the -geo command line option to define an OI and DEM at once. Examples of valid dem-pyramid names include:
-oi <oi-pyramid>
This specifies the imagery data that you wish to use as the texture map for the tree hierarchy. It should be the filename or URL of a TerraVision OI dataset. If you specify this argument, then you must also specify the -dem command line option. Alternatively, you can use the -geo command line option to define an OI and DEM at once. Examples of valid oi-pyramid names include:
-vrmldir <dir>
This option is used to specify the directory to which the VRML tree pyramid will be written. It should be a localdisk filename or a a URL in the format file://localhost/filename. Subdirectories called trees and images will be created inside the directory that you specify.
-olat <latitude>
This option is used to specify the GeoOrigin Latitude.
-olon <longitude>
This option is used to specify the GeoOrigin Longitude.
Optional Output Parameters:
-pixpertex <pixels>
This value can be used to scale the range that is used by the level of detail mechanism to switch to higher resolution tiles. The switch will happen when the a single pixel in the tile's texture map (a texel) projects to the specified number of pixels on the screen. By default, this pixel value is 1.0, i.e. the switch to higher resolution occurs when there is the potential for one pixel of texture (not necessarily geometry) error.

 

 

Note that this value is dependent upon the pixel resolution of the viewport that the user is using. We cannot know this a priori and so we make the assumption that the viewport will be 500 x 500 pixels. All LOD range calculations are based upon this assumption.

-vrmlurl <base-url>
All default URLs that are placed in the VRML files will be relative. However, you may use the -vrmlurl option to specify an absolute URL for the dataset. Then all of the URLs that are used in the VRML files (e.g. links, EXTERNPROTO declarations, Script locations, etc.) 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. (N.B. -absurl can be used as a synonym for -vrmlurl.)
-start <n>
-end <n>
By default, this utility will generate the entire hierarchy of tree files from the input OI and DEM. The number of levels in this tree hierarchy will be the same as in the OI dataset. However, you can uses the -start and -end options to specify a restricted range of levels to be generated (i.e. if you have already generated part of the hierarchy at an earlier juncture). The level numbers that you specify are TerraVision pyramid level numbers. The start level must be the lowest resolution level (highest number) and the end level must be the highest resolution level (lowest number).
-wrz
Compress tile files and save as .wrz
-noview
By default, a "Home" viewpoint is included with each tile. For generating terrain for worlds where you don't want the viewpoint list polluted with many Home viewpoints specify this option.
-touch <level1, level2, level3>
Insert GeoTouchSensors at the specified levels.  When the GeoTouchSensor is activated the next levels will be loaded with higher resolution tiles replacing the tile that is selected. A maximum of 3 levels may be selected. The -hud and -maxrange options may and should be included with this option.
-hud
Include a heads up display in the lower right corder that shows the Geo Coordinates of the the GeoTouchSensor's hitGeoCoord_changed. The -touch <levels> option must be used for this to work.
-maxrange
By default, approtiate ranges are selected for the LODs that control tile loading. If the -touch option is used these ranges can all be set to the same value of the largest range so that automatic loading and unloading does not happen.
Geometry Information Parameters:
-numpolys <n>
This option is used to specify the geometrical complexity of the GeoElevationGrids that are generated for this tree hierarchy.
-elevscale <scale>
This option lets you exaggerate the height values of a terrain by applying a constant scaling factor. By default, this scaling factor is 1.0 (i.e. no scaling). Increasing this value will produce terrain with exaggerated heights. This can sometimes be useful to make a terrain look "more interesting", although of course the model will no longer be an exact representation of the real terrain. The tree program needs to know this information in order to correctly calculate the bounding box information for each tile.
-normals
-nonormals
These two options define whether you wish normals to be calculated for the GeoElevationGrid nodes. By default no normals are created, and hence smaller tree files are produced. However, normals can be used to produce more smoothly-lit terrain models.
-notextures
This options will produce a tree hierarchy where the geometry tiles do not have links to the imagery tiles, i.e. the terrain will appear flat shaded and without imagery.
Optional Input Parameters:
-readlrbt
-readjpeg
-readtiffs
-readrawtiles
-readsetid <id>
-readserver
-readexact
-readmetadata
-readnewtspec
-readoldtspec
-dontvalidatetspec
These options are used to specify which version of a dataset you wish to read. Datasets can exist in different image formats, storage formats, with different metadata locations, etc. If you specify none of these options, then sensible defaults will be used. Generally you will not care about these options. For further information about these options, please refer to the manual page for the copy_dataset utility.
-version
This will display the version of the tsmApi that was used to create the tree utility binary that you are using. Also, if DPSS support is compiled into your binary, then the DPSS version information will be displayed too. This will be followed by tree's help text (which includes the program's version number).
-debug <level>
This option can be used to set the tsmApi debug level. By default, this is set to 0 (no debug information). If you set this to a higher number (1-5), then the tsmApi library will display debugging messages as it performs various operations. This is provided for debugging purposes.
-help
Finally, you can use the -help option to try and display this page over the web. You will need the program "netscape" in your path. If you already have netscape running, then the manual page will be displayed using that netscape session, rather than trying to reload netscape again. Note that occasional network problems may make this page inaccessible from your terminal.
EXAMPLES
  1. The following example will create a VRML tree hierarchy from a specified OI and DEM pyramid. The trees will be written to the directory ./vrml/laguna_beach/trees. (N.B. to make the example readable, we split the one command line over multiple lines using '\' characters at the end of lines to be continued.)
    2.   make_geovrml -oi ~magic/TileSets/Pyramids/laguna_beach.oi \
               -dem magic/TileSets/Pyramids/laguna_beach.dem \
               -vrmldir vrml/laguna_beach
  2. The next example creates a VRML tree hierarchy by specifying a combination of OI and DEM. In addition, we state that geometry that we have generated for this tree hierarchy has had the heights exaggerate by a factor of 5, the 3-D coordiantes scaled down to a smaller range.
    3.   make_geovrml -oi ~magic/TileSets/Pyramids/menlo_park.oi \
               -dem ~magic/TileSets/Pyramids/menlo_park.dem \
               -vrmldir ~magic/VRMLSets/MenloPark \
               -elevscale 5 -worldscale 100000
  3. The next example creates a VRML tree hierarchy by specifying a combination of OI and DEM. In addition, we state that geometry that we have generated for this tree hierarchy in written as gzipped files with the .wrz extension, at GeoOrigin 36.0, -122, with no viewpoints, an absolute url for all child nodes and image textures, GeoTouchsensors at levels 2, 4, and 6, a heads up display, a disabled automatic LOD (-maxrange), a transparent bottom (-onsided), and 16x16 polygons per tile.
    4.   make_geovrml -dem /u/mccann/TileSets/Pyramids/cencal/MontereyA_bath.dem \
               -oi /u/mccann/TileSets/Pyramids/cencal/MontereyA_bath.oi \
               -vrmldir ~mccann/TileSets/geoVRMLmenard/cencal/MontereyA_bath \
               -olat 36 -olon -122 -noview \
               -vrmlurl http://menard.shore.mbari.org/vrml/terrain/cencal/MontereyA_bath \
               -touch 2,4,6 -hud -maxrange -onesided -numpolys 16 -elevscale 1 -wrz
AUTHORS
Yong Tze Chi, SRI International.
Nat Bletter, SRI International. <bletter@ai.sri.com>
Martin Reddy, SRI International. <reddy@ai.sri.com>
Mike McCann, Monterey Bay Aquarium Research Institute. <mccann@mbari.org>
SEE ALSO
Martin Reddy, <reddy@ai.sri.com>
Last modified: Thu Jan 11 13:48:24 PST 2001