1. The Earth File
    1. Simple Map File
    2. Multiple Image Sources
    3. Heightfield Data
    4. Caching
  2. Earth File Reference

The Earth File

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

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

  • The type of map to create (geocentric or projected)
  • The image and elevation 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">

    <image name="vmap0" driver="wms">
        <url>http://labs.metacarta.com/wms-c/Basic.py</url>
        <layers>basic</layers>
        <format>png</format>
        <tile_size>256</tile_size>
    </image>
</map>

This Earth File creates a geocentric Map named "MyMap?" with a single WMS image source called "vmap0". 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 Sources

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">
    <!--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 multitexturing to render the image layers, so you can define as many image layers as you have texture units. Order is important when defining multiple image sources: they are applied bottom to top in the order that they specified in the file.

Heightfield Data

Adding heightfield data to an Earth File is very similar to adding images. Heightfield data can be added to an Earth File by adding a heightfield element to the XML 

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

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

This Earth File has a base blue marble image as well as a heightfield that is loaded from a local GeoTiff? file. Any number of heightfield sources can be added to the Earth File and they will be combined together by osgEarth. As with images, order is important to heightfield 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">
    <image name="metacarta blue marble" driver="tms">
        <url>http://labs.metacarta.com/wms-c/Basic.py/1.0.0/satellite/</url>
    </image>

    <!--Specify where to cache the data-->
    <cache>
        <path>c:/osgearth_cache</path>
    </cache>
</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.

Earth File Reference

  • <map> - Top-level map definition.
  • <image> - Defines an imagery source.
  • <heightfield> - Defines a source of elevation.
  • <sample_ratio>? - Specifies the sample ratio to use when generating terrain.
  • <vertical_scale> - Specifies the vertical scale factor of elevation data.
  • <min_tile_range_factor> - Controls when different layers of the map will be displayed.
  • <skirt_ratio> - Controls how skirts are drawn for the terrain tiles.
  • <proxy_host>,<proxy_port> - Configure a proxy to use when connecting to the Internet.
  • <cache_only> - Controls whether osgEarth should run exclusively off of the cache.
  • <cache> - Configures a cache at either the <map> level or the tile source level.
  • <normalize_edges> - Specifies whether or not to normalize the edges between terrain tiles.

back to Documentation