Index Introduction Contents Install Dependencies examples Data Viewer Stereo osgdem Plan Reference Guides

Using osgdem to generate geospatial terrain databases

  1. Quick step by step guide
  2. osgdem options

Quick step by step guide:

What follows are the steps required to get osgTerrain/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.
 
2) Get the latest OSG in CVS.

3) For UNIX 'make' users, make a copy of Make/dependencies and change the GDAL_INSTALL entry to:

set GDAL_INSTALL = true

    Then tell the build to use your custom dependencies by setting the environmental variable OSG_DEPENDENCIES to the absolute path to your file i.e.:

export OSG_DEPENDENCIES=/home/billgates/my_osg_dependencies
 
4) Rebuild the OSG & install (if you haven't already).
 
5) Oh, make sure you have a couple of GB of spare disk space,  because you're going to need it :-)
 
6) 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  

7) 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
 

8) 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.tif \
            --xx 10 --yy 10 -d ../ps_height.tif \
            -l 8 \
           -v 0.1 \
           -o puget.ive

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.

And finally 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. 

9) Time to play. Simply load the database in your app (make sure it supports the osgDB::DatabasePager - see osgsimplepager example for details). The standard osgviewer works just fine so, here goes:
 
   osgviewer output.ive
 

10) You don't actually have to wait for osgdem to complete before you can browse the database, since osgdem generates the topmost tiles first. Its not totally robust since osgviewer can end up loading tiles that are still being written by osgdem, but it doesn't crash here under Linux, so you might be lucky too.

11) 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.

12) 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>.
 

osgdem options

There are of osgdem options to use, to list the full ranges of options do:

osgdem --help

And you should see:


osgdem --help
Usage: osgdem [options] filename ...
Options:
  --HEIGHT_FIELD                          Create a height field database
  --LOD                                   Create a LOD'd database
  --POLYGONAL                             Create a height field database
  --PagedLOD                              Create a PagedLOD'd database
  --RGB-16                                Use 16bit RGB destination imagery
  --RGB-24                                Use 24bit RGB destination imagery
  --comment                               Added a comment/description string to
                                          the top most node in the dataset
  --compressed                            Use OpenGL compression on destination
                                          imagery
  --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
  --max-anisotropy                        Max anisotropy level to use when
                                          texturing, defaults to 1.0.
  --max-visible-distance-of-top-level     Set the maximum visible distance that
                                          the top most tile can be viewed at
  --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.
  --no-mip-mapping                        Disable mip mapping of textures
  --radius-to-max-visible-distance-ratio  Set the maximum visible distance ratio
                                          for all tiles apart from the top most
                                          tile. The maximum visuble distance is
                                          computed from the ratio * tile radius.
  --skirt-ratio <float>                   Set the ratio of skirt height to tile
                                          size
  --tile-image-size                       Set the tile maximum image size
  --tile-terrain-size                     Set the tile maximum terrain size
  --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.
  -d <filename>                           Specify the digital elevation map
                                          input file to process
  -e <x> <y> <w> <h>                      Extents of the model to generate
  -h or --help                            Display this information
  -l <numOfLevels>                        Specify the number of PagedLOD levels
                                          to generate
  -m <filename>                           Specify the 3D database model input
                                          file to process
  -o <outputfile>                         Specify the output master file to
                                          generate
  -t <filename>                           Specify the texture map input file to
                                          process
  -v                                      Set the vertical multiplier