1. Creating Maps - Primer
    1. Simple Map File
    2. Multiple Image Layers
    3. Elevation Data
    4. Caching

Creating Maps - Primer

This is a basic primer on creating maps for osgEarth. We suggest you peruse the sample .earth files in the source code repository for a wide away of examples.

osgEarth uses an XML based file format called an Earth File to specify exactly how source data turns into an OSG scene graph.

For a detailed view of all the options available when creating an Earth File, please see the Earth File Elements Reference.

At it's core, the Earth File allows you to specify

  • The type of map to create (geocentric or projected)
  • The image, elevation, vector and model sources to use
  • Where the data will be cached

The  samples folder in the repository contains numerous examples of Earth files and how to use them.

Simple Map File

Here is a very simple example that reads data from a WMS server and renders it to a round-earth 3D model: 

<map name="MyMap" type="geocentric" version="2">
    <image name="bluemarble" driver="gdal">
        <url>/data/world.tif</url>
    </image>
</map>

This Earth File creates a geocentric Map named "MyMap?" with a single GeoTIFF image source called "bluemarble". The driver attribute tells osgEarth which of it's drivers to use to load the image. All sub-elements are specific to the selected driver. To learn how to configure each of the drivers in osgEarth, please see the drivers page.

Multiple Image Layers

osgEarth supports maps with multiple image sources. This allows you to create maps such as base layer with a transportation overlay or provide high resolution insets for specific areas while providing a lower resolution base map. To add multiple images to a Earth File, simply add multiple "image" elements to your Earth File. 

<map name="Transportation" type="geocentric" version="2">
    <!--Add a base map of the blue marble data-->
    <image name="bluemarble" driver="gdal">
        <url>c:/data/bluemarble.tif</url>
    </image>

    <!--Add a high resolution inset of Washington, DC-->
    <image name="dc" driver="gdal">
        <url>c:/data/dc_high_res.tif</url>
    </image>
</map>

The above map provides two images from local data sources using the GDAL plugin. osgEarth uses various methods to render the image layers, so the limit on how many image layers you can render depends on your hardware (more info). Order is important when defining multiple image sources: they are applied bottom to top in the order that they specified in the file.

Elevation Data

Adding elevation data to an Earth File is very similar to adding images. Elevation data can be added to an Earth File by adding an elevation element to the XML: 

<map name="Elevation" type="geocentric" version="2">
    <!--Add a base map of the blue marble data-->
    <image name="bluemarble" driver="gdal">
        <url>c:/data/bluemarble.tif</url>
    </image>

    <!--Add SRTM data-->
    <elevation name="srtm" driver="gdal">
        <url>c:/data/SRTM.tif</url>
    </elevation>
</map>

This Earth File has a base blue marble image as well as a elevation grid that is loaded from a local GeoTiff? file. Any number of elevation sources can be added to the Earth File and they will be combined together by osgEarth. As with images, order is important to elevation data as well. For instance, if you had a base elevation datasource that had low resolution coverage of the entire world and a high resolution inset of Denver, CO, you would specify the base data FIRST, followed by the high res data.

Most drivers in osgEarth support reading heightfields as well as imagery. However, it is important to note that only 16 and 32 bit datasources can be used as heightfield datasources.

Caching

osgEarth can cache tiles on disk in order to increase performance to avoid downloading/processing tiles multiple times. 

<map name="TMS Example" type="geocentric" version="2">
    <image name="metacarta blue marble" driver="tms">
        <url>http://labs.metacarta.com/wms-c/Basic.py/1.0.0/satellite/</url>
    </image>

    <options>
        <!--Specify where to cache the data-->
        <cache>
            <path>c:/osgearth_cache</path>
        </cache>
    </options>
</map>

This Earth File shows the most basic way to specify a cache for osgEarth. This tells osgEarth to enable caching and to cache to c:/osgearth_cache. Both absolute and relative paths can be used when specifying the cache path. If a relative path is given for the cache path, it will be relative to the location of the Earth File.

A more detailed description of how to configure caching is available in the caching section.

back to Documentation