Version 38 (modified by robert, 5 years ago)

--

osgdem

osgdem is utility program for reading geospatial imagery and digital elevation maps (DEM's) and generating large scale 3D terrain databases that OpenSceneGraph applications can load and browse in real-time. What follows is a step-by-step guide to using osgdem, followed by a list of full options available.

Quick step by step guide

What follows are the steps required to get VirtualPlanetBuilder/osgdem compiling and an example of how to use it to process imagery and DEM's to generate a paged databases.

1. Download, compile & install GDAL, and OpenSceneGraph. Then download VirtualPlanetBuilder.

2. For UNIX 'make' users:

cd VirtualPlanetBuilder
./configure
make
sudo make install

3. Oh, make sure you have a couple of GB of spare disk space, because you're going to need it :-)

4. Download some data, for this example I'm using the Puget Sound data at:

http://www.cc.gatech.edu/projects/large_models/ps.html
Download Elevation Map: 16385 × 16385 PNG: 188MB
Download Texture Map: 16384 × 16384 PNG: 268MB

5. To avoid aliasing artifacts when accessing data I use GDAL utilitiy programs to generate overviews (basically mip maps stored in the .tiff format) via:

gdal_translate ps_height_16k.png ps_height_16k.tif
gdaladdo -r average ps_height_16k.tif 2 4 8 16 32

gdal_translate ps_texture_16k.png ps_texture_16k.tif
gdaladdo -r average ps_texture_16k.tif 2 4 8 16 32

6. Now its time to run the osgdem example to generate your PagedLOD database, the more levels you generate the longer it will take (exponentially so). 'osgdem' is just a front end to osgTerrain::DataSet where all the hard work happens. Here's what to run :

osgdem --xx 10 --yy 10 -t ps_texture_16k.tif \ 
--xx 10 --yy 10 -d ps_height_16k.tif \ 
-l 8 -v 0.1 -o puget.ive -a pegout.osga

Then go away for lunch, afternoon and tea, as generating this much data takes a while... If you don't wish to wait for the full database then reduce the number of levels it generates by setting the -l option to a lower value such as 3.
The command line options used above are:
The first part the --xx and --yy is specifying the size of the pixels in meters, since these png/tif don't have any geospatial data of their own, if you have geospatialised files then you won't need this.

The second part -t <filename> is the option for specificing the texture maps to use, you can use as many times as you wish, osgTerrain::DataSet will moziac them into a single database.

The third part -d is the option for specifying the digital elevation maps to use, as with the textures you can use as many as you like.

The -l option specificies the maximum number of levels to generate. If you use a large number then the database generation will stop once the max resolution of your source data is matched by the resulting database. The database generation will decend further where there is high res source data, decend less where there is lower res data.

The -v option specifies the scaling factor which the height is multiplied by.

] The -o <filename> is the output format to generate the databases in. This will be the name of the topmost file in the one you should load. It can be a .ive or a .osg. The .ive is faster and has embedded files.

And finally the -a <filename> tells the osgdem to write all tiles to a single archive, in this a the OpenSceneGraph native archive format, which uses the extension .osga to disguinish itself. The use of archives is not required, but is recommend since it makes managment of the whole database much more convinient - you have a single file to manage rather than what could be 10's of thousands as is the case of large databases.

7. Time to play. Simply load the database in your app, and if you've based it on osgViewer::Viewer or CompositeViewer all the paging support is already built in. The standard osgviewer works just fine so, here goes:

osgviewer pegout.osga

8. If your imagery and DEMs have geospatial coords associated with them then the -xx, --yy and -v options will not be required, making it much simplier to specify - you just need to specifiy options such as -t imge.tif and -d terran.dt0 without any need to set the coordinate system.

9. osgdem can automatically handle mosaicing of sets of files. These can be specified via a sequence of -t <filename> and -d <filename> pairs on the commandline, or via -t <directoryname> and -d <directoryname>.

Commandline options

Parameter Description Default
General
-h or --help Display commandline arguments information
--task
-s <filename> Specify a VPB source file containing all commandline options.
--so <filename> Output the VPB source file for the current run.
--report
--cache <filename> Read the cache file to use a look up for locally cached files.
--version Print out version
--version-number Print out version number only.
--comment Added a comment/description string to the top most node in the dataset empty
--split Set the distributed build split level.
--splits Set the distributed build primary and secondary split levels.
--run-path Set the path that the build should be run from.
--notify-level Set the notify level when logging messages.
Input
-d <filename> Specify the digital elevation map input file to process
-t <filename> Specify the texture map input file to process
--building <filename> Specify building outlines using shapefiles.
--forest <filename> Specify forest outlines using shapefiles
--levels <begin_level> <end_level> Specify the range of levels that the next source Texture or DEM will contribute to.
--layer <layer_num> Specify the layer that the next source Texture will contribute to..
Coordinate system
--cs <coordinates system string> Set the coordinates system of source imagery, DEM or destination database. The string may be any of the usual GDAL/OGR forms, complete WKT, PROJ.4, EPS
--wkt <WKT string> Set the coordinates system of source imagery, DEM or destination database in WellKownText form.
--wkt-file <WKT file> Set the coordinates system of source imagery, DEM or destination database by as file containing WellKownText definition.
Geocentric database
--geocentric Build a database in geocentric (i.e. whole earth) database.
--bluemarble-east Set the coordinates system for next texture or dem to represent the eastern hemisphere of the earth.
--bluemarble-west Set the coordinates system for next texture or dem to represent the western hemisphere of the earth.
--whole-globe Set the coordinates system for next texture or dem to represent the whole hemisphere of the earth.
Ellipsoid model
--radius-polar Set the polar radius of the ellipsoid model when building a geocentric database. 6356752.3142
--radius-equator Set the equatorial radius of the ellipsoid model when building a geocentric database. 6378137
--spherical Set the polar and equatorial radius both to the average of the two.
Flat database
--range <xMin> <xMax> <yMin> <yMax> Set the coordinates system for next texture or dem to the given range.
--xx
--xt
--yy
--yt
--zz
--zt
DataType?
--vector Interpret input as a vector data set
--raster Interpret input as a raster data set (default)
Output
--image-ext <ext> Specify the Image format to output to via its plugin name, i.e. rgb, dds, jp2, jpeg. .dds
-o <outputfile> Specify the output master file to generate
-a <archivename> Specify the archive to place the generated database
--ibn <buildname> Specify the intermediate build file name
-l <numOfLevels> Specify the number of PagedLOD levels to generate 30
-e <x> <y> <w> <h> Extents of the model to generate
--skirt-ratio <float> Set the ratio of skirt height to tile size 0.02
-v Set the vertical multiplier 1.0
--no-terrain-simplification Switch off terrain simplification. true
--default-color <r,g,b,a> Sets the default color of the terrain. (0.5, 0.5, 1.0, 1.0)
--radius-to-max-visible-distance-ratio Set the maximum visible distance ratio for all tiles apart from the top most tile. The maximum visible distance is computed from the ratio * tile radius. 7.0
--max-anisotropy Max anisotropy level to use when texturing 1.0
GeometryType?
--HEIGHT_FIELD Create a height field database
--POLYGONAL Create a height field database (default)
--TERRAIN Create a osgTerrain::Terrain database
DatabaseType?
--LOD Create a LOD'd database
--PagedLOD Create a PagedLOD'd database (default)
TextureType?
--compressed Use OpenGL compression on RGB destination imagery (default)
--RGBA-compressed Use OpenGL compression on RGBA destination imagery
--RGB-16 Use 16bit RGB destination imagery
--RGBA-24 Use 24bit RGB destination imagery
--RGB-16 Use 16bit RGBA destination imagery
--RGBA Use 32bit RGBA destination imagery
MipMappingMode?
--no-mip-mapping Disable mip mapping of textures
--mip-mapping-hardware Use mip mapped textures, and generate the mipmaps in hardware when available.
--mip-mapping-imagery Use mip mapped textures, and generate the mipmaps in imagery. (default)
--BuildOverlays [True/False] Switch on/off the building of overlay within the source imagery. Overlays can help reduce texture aliasing artifacts. false
--ReprojectSources [True/False] Switch on/off the reprojection of any source imagery that aren't in the correct projection for the database build. true
--GenerateTiles [True/False] Switch on/off the generation of the output database tiles. true
--tile-image-size Set the tile maximum image size 256
--tile-terrain-size Set the tile maximum terrain size 64
-O string option to pass to write plugins, use "" for multiple options
--subtile <LOD> <X> <Y> Set the subtile to begin the build from.
--record-subtile-on-leaf-tiles Enable the setting of the subtile file name of the leaf tiles. false
--type-attribute Set the type name which specify how the shapes should be interpreted in shapefile/dbase files. (empty signifies no type attribute has been defined) NAME
--height-attribute Set the attribute name for height attributes used in shapefile/dbase files. HGT
--height Set the height to use for associated shapefiles. (negative signifies that no height has been defined) -1.0
--mask Set the mask to assign indivual shapefile/model. 0xffffffff
--terrain-mask Set the overall mask to assign terrain. 0xffffffff
--read-threads-ratio <ratio> Set the ratio number of read threads relative to number of cores to use. 0.0
--write-threads-ratio <ratio> Set the ratio number of write threads relative to number of cores to use. 0.0
--build-options <string> Set build options string.
DEM interpolation
--interpolate-terrain Enable the use of interpolation when sampling data from source DEMs. (default)
--no-interpolate-terrain Disable the use of interpolation when sampling data from source DEMs.
Imagery interpolation
--interpolate-imagery Enable the use of interpolation when sampling data from source imagery. (default)
--no-interpolate-imagery Disable the use of interpolation when sampling data from source imagery.

Usage of VPB source file

Write all the osgdem options to a VPB source file, and then use this source file in subsequent runs, this makes means you can avoid all the long winded options when you are experimenting. i.e

// Create the build.source file
osgdem --bluemarble-west -t ../land_shallow_topo_west.tif \
           --bluemarble-east -t ../land_shallow_topo_east.tif \
           --geocentric \
           -o earth/earth.ive \
           --so build.source

// run the build
osgdem -s build.source

// have a look at the file - it's just an extended form of a .osg file
cat build.source

// override the number of levels
osgdem -s build.source -l 4

// run build adding your extra imagery
osgdem -s build.source -t MyOrthoImage.tif

Coordinate System Tips

WKT coordinate system definition format is a very comprehensive, but difficult to use as a "human enter-able" specifier for coordinate systems. osgdem uses GDAL under the hood which also allows definition of the --cs flag in PROJ4 format. PROJ4's definition format is much more human friendly.
Examples:

  • For a Latitude (Y Axis), Longitude (X Axis) and Altitude coordinate system in units of degrees use: osgdem ... --cs "+proj=latlong +datum=WGS84" -o ...
  • For a UTM coordinate system referenced to zone 47 (in this example) in units of meters use: osgdem ... --cs "+proj=utm +zone=47" -o ...
  • For a Geocentric system, with the origin being the center of the earth and units in meters use: osgdem ... --geocentric -o ...