osgEarth Developers Guide (Version 2.x)

osgEarth was designed with ease of application integration as one of its main goals. There are really two ways to go about integrating osgEarth. You can create an Earth File and load it into your application or you can programmatically create a map at runtime using the osgEarth API.

Topics:

• Working with maps
• The utilities library
• Shader composition
• Building your own driver?

---

Loading a Map

Because much of the functionality of osgEarth is wrapped up in OpenSceneGraph plugins, it is possible to load a map from an Earth File with a single line of code:

osg::Node* globe = osgDB::readNodeFile("myglobe.earth");

You now have an OpenSceneGraph Node that can be added to your scene graph and displayed. Seriously, it really is that simple! :)

This method of loading a Map is more often than not all that an application will need to do. If your application already supports VirtualPlanetBuilder terrain databases, then you should have very little work in integrating osgEarth as the scene graphs are extremely similar. Both are based on osgTerrain and the !PagedLOD system and both are decorated with an osg::CoordinateSystemNode. The only real difference between the two is that an osgEarth database is built on the fly rather than pre-generated.

---

Programmatic Map Creation

osgEarth also provides an API for creating Maps at runtime. This is very useful if your application allows a use to select from various layers to display at runtime.

The basic steps to creating a Map with the API are:

1. Create a Map object
2. Add imagery and elevation layers to the Map as you see fit
3. Create a MapNode that will render the Map object
4. Add your MapNode to your scene graph.

You can add layers to the map at any time. However, once you add a layer to the map, it makes a copy of the options and you can no longer change them.

#include <osgEarth/Map>
#include <osgEarth/MapNode>
#include <osgEarthDrivers/tms/TMSOptions>
#include <osgEarthDrivers/gdal/GDALOptions>

using namespace osgEarth;
using namespace osgEarth::Drivers;
...

// Create a Map and set it to Geocentric to display a globe
Map* map = new Map();

// Add an imagery layer (blue marble from a TMS source)
{
    TMSOptions tms;
    tms.url() = "http://labs.metacarta.com/wms-c/Basic.py/1.0.0/satellite/";
    ImageLayer* layer = new ImageLayer( "NASA", tms );
    map->addImageLayer( layer );
}

// Add an elevationlayer (SRTM from a local GeoTiff file)
{
    GDALOptions gdal;
    gdal.url() = "c:/data/srtm.tif";
    ElevationLayer* layer = new ElevationLayer( "SRTM", gdal );
    map->addElevationLayer( layer );
}

// Create a MapNode to render this map:
MapNode* mapNode = new MapNode( map );
...
viewer->setSceneData( mapNode );

---

Working with a MapNode at runtime

Whether the Map was loaded from an Earth File or created at run time, the Map can modified at runtime. If a Map was loaded from an Earth File, you will first need to get a reference to the MapNode to work with. Use the !Map::findMapNode utility function:

//Load the map
osg::Node* loadedModel = osgDB::readNodeFile("mymap.earth");

//Find the MapNode
osgEarth::MapNode* mapNode = MapNode::findMapNode( loadedModel );

Once you have a reference to the MapNode, you can add image or elevation layers:

// Add an OpenStreetMap image source
TMSOptions driverOpt;
driverOpt.url() = "http://tile.openstreetmap.org/";
driverOpt.tmsType() = "google";

ImageLayerOptions layerOpt( "OSM", driverOpt );
layerOpt.profile() = ProfileOptions( "global-mercator" );

ImageLayer* osmLayer = new ImageLayer( layerOpt );
mapNode->getMap()->addImageLayer( osmLayer );

You can also remove or re-order layers:

// Remove a layer from the map.  All other layers are repositioned accordingly
mapNode->getMap()->removeImageLayer( layer );

// Move a layer to position 1 in the image stack
mapNode->getMap()->moveImageLayer( layer, 1 );

---

Back to Documentation