Frequently Asked Questions.
Getting Started
Q: What is osgEarth?
osgEarth is an open source software library that enables run-time terrain model generation in an OpenSceneGraph application.
Q: What is the fastest way to try osgEarth?
After downloading and building osgEarth, simply use osgviewer to view one of the sample .earth files in the tests folder, like this:
osgviewer gdal_tiff.earth
Q: How do I integrate osgEarth into my own application?
osgEarth comes with an osgDB::ReaderWriter loader for .earth files. It works "out of the box" with osgviewer or other OSG apps. Simply use osgDB::readNodeFile to load a .earth file from within your custom application. Or, you can link with the osgEarth library and build a Map programmitically by creating a osgEarth::MapNode object, adding it to the scene graph, and adding layers by hand (see the Developers Guide).
Loading your own data
Q: Which data sources does osgEarth support?
osgEarth can access several web-mapping data sources including OGC WMS and OSGeo TMS; various raster/elevation formats like GeoTIFF, and even some public data (like Google and Yahoo! maps) for demonstration purposes. Please refer to the list of osgEarth drivers for a comprehensive overview.
Q: Can I just load a local GeoTIFF file?
Yes. You can use the GDAL driver to incorporate GeoTIFF files (and a variety of other raster formats).
Q: Can I load a whole directory full of geodata?
Yes. The GDAL driver will allow you to specify a directory, and will recursively load all geodata found in that folder and its subfolders. This is an easy way to a load a set of DTED tiles, for example.
Q: Will osgEarth reproject my data?
Yes, osgEarth will automatically reproject your source data into the map's profile if necessary. Of course, if you are willing to do a little data preparation beforehand, you can avoid the need for this operation (which can be expensive in some cases).
Q: Can I load GIS vector data (e.g. shapefiles)?
Yes! The osgEarthFeatures library is a framework for loading and displaying vector data on an osgEarth terrain map. Look into the model drivers for more information.
Finding data
Q: Where can I find sources of data?
Please see this page for a few pointers. The OpenStreetMap? wiki all has a list of potential data sources to peruse.
Q: Can osgEarth load Google/Microsoft/Yahoo?! maps data?
Technically, yes, but these services and others like them are bound by Terms of Use agreements that probably prohibit their legal use unless you have a separate agreement in place. Any drivers designed to access these services exist for educational purposes only.
osgEarth vs. VPB
Q: How does osgEarth compare to VirtualPlanetBuilder (VPB)?
VPB is a tool for building large-scale terrain models. It supports distributed build configurations. You use VPB's tools (osgdem or vpbmaster) to build a terrain model offline, and then load that terrain model into your application at run-time. VPB writes a scene graph to disk that is optimized for load and display speed.
osgEarth generates the terrain scene graph at run-time. It never actually writes a scene graph to disk. Rather, it ingests source data at run-time and generates the geometry on the fly. osgEarth uses the same underlying osgTerrain, PagedLOD, and ReaderWriter mechanisms as a VPB model, so the resulting scene graphs are comparable and support the same run-time features (like skirts, sample ratio, etc.).
Which approach you choose depends on your application and your particular use case. VPB requires an offline build process, but the resulting terrain will run in any OSG application. osgEarth requires no pre-generation, but you do need the osgEarth plugins at run-time.
Q: Can I use osgEarth and VPB together?
Yes indeed. You can use VPB layers in osgEarth; you can replace the imagery in a VPB database with new imagery; you can even overlay new layers on an existing VPB database without having to rebuilt it. See the VPB Driver.
Integration
Q: What coordinate system does osgEarth use?
In a round earth globe, the coordinates will be in a standard geocentric coordinate system. In a flat projected map (UTM, StatePlane?, Mercator, Plate Carre, etc) the coordinate system will be whatever the native coordinates are for the projection (meters, decimal degrees). The important thing to note is that there is NO offsets or scaling going on in osgEarth.
Q: When I position objects in a geocentric scene they seem to jitter and look bad, whats going on?
This usually occurs if you try to position objects at their desired location by simply specifying the raw coordinates in the vertices. The jitter is due to loss of precision when dealing with large coordinates that are far from the origin. (OpenGL currently only supports single-precision floating point values.) The correct way to combat this is to create your objects around a local origin and position them using an osg::MatrixTransform which uses doubles internally which eliminates the jitter. Also consider using the osgEarthUtil::ObjectPlacer or osgEarthUtil::ObjectLocatorNode to help you place your objects.
Q: How do I deploy osgEarth in a browser-based application?
We have a web framework for osgEarth that is not part of the core osgEarth project itself. Contact Pelican Mapping directly for more information.
Q: When I use the osgEarthDrivers API headers (GDALOptions, TMSOptions, etc) to create maps on the fly, things don't work when I'm using g++, what can I do?
The problem is that the typeinfo from the shared objects (so files) isn't carried through to the executable by the linker, so dynamic_casts fail at run time. The solution is to link your application with the -Wl,-E switch when using g++. More information may be found here.
Performance Tips
Q: How can I speed up tile loading?
Because osgEarth utilizes the DatabasePager to generate tiles, having multiple DatabasePager? threads can really improve performance. OpenSceneGraph let you specify how many database threads you want to use by setting the OSG_NUM_DATABASE_THREADS environment variable or calling osg::!DisplaySettings::instance()->setNumOfDatabaseThreadsHint(...) at the beginning of your application.
If you use OSG version 2.9 or newer, osgEarth will take advantage of the new FileLocationCallback in the DatabasePager. This feature gives the pager a hint as to whether a tile is being loaded from the network or from a local cache, allowing it to schedule it more efficiently.
Q: Do I have to load all the intermediate tile levels when I zoom in?
Try preemptive mode, which will prioritize the tiles at your current map scale (i.e., current zoom level). In other words, if you zoom from space to the ground quickly, it will load those ground tiles first without having to load all the LODs in between. Enable this feature with the following tag in your map file:
<loading_policy mode="preemptive"/>
Please refer to the <loading_policy> docs for more information.
Caching
Q: I'm trying to cache an elevation datasource and it doesn't seem to be working, what's wrong?
osgEarth caches elevation data by converting a heightfield to an osg::Image and writing it to disk. Many of the OpenSceneGraph image plugins have problems writing 16 and 32 bit single band images. In OpenSceneGraph 2.6.X, it is recommended to use the DDS format to cache elevation and in OpenSceneGraph 2.8.X onwards it is recommended to use the Tiff plugin. You must specify this in your caching setup in your Earth File using the format option
<cache type="tms"> <path>cache_path</path> <format>tiff</format> <!--Tell osgEarth to cache to the tiff format--> </cache>
