osgEarth Documentation

osgEarth is a 3D mapping SDK built for OpenSceneGraph. It is designed to help developers quickly visualize massive amounts of imagery, elevation data, and vector features. Key capabilities include:

• Rapid Prototyping: Get a 2D or 3D map running using a single XML configuration file.
• Data Support: Visualize massive imagery, elevation, and vector data using open standards like WMS, TMS, and GeoTIFF.
• Connectivity: Work with data stored locally or served over the Internet.
• Extensibility: Develop custom applications using a full-featured C++17 API.

GLM (OpenGL Mathematics) is a header-only C++ mathematics library designed for graphics software. It is based on the OpenGL Shading Language (GLSL) specifications, meaning it uses the same naming conventions and functionality as GLSL. This makes it highly intuitive for developers familiar with GLSL to use within C++.

Key features include:

• GLSL Compatibility: Classes and functions mirror GLSL.
• Extension System: Beyond standard GLSL, it provides extensions for matrix transformations, quaternions, data packing, random numbers, and noise.
• Interoperability: While optimized for OpenGL, it works with software rendering (raytracing/rasterisation), image processing, and physics simulations.
• Header-only: Easy to integrate as it requires no compiled binaries.
• Platform Independent: No external dependencies.

osgEarth is a geospatial SDK and terrain engine designed for OpenSceneGraph applications. It is used to build 3D geospatial applications by visualizing terrain models and imagery directly from source data.

Key Use Cases:

• Quickly setting up a terrain base map.
• Accessing open-standard map data services such as WMS or TMS.
• Integrating locally-stored data with web-service-based imagery.
• Incorporating new geospatial data layers at run-time.
• Handling data that changes over time.
• Integrating with commercial data providers.

An Earth File is an XML-based description used to configure an osgEarth map. It specifies how source data (images, elevation, vectors, and models) is transformed into an OpenSceneGraph (OSG) scene graph. Earth Files use the .earth extension.

An Earth File allows you to define:

• The map type (geocentric or projected).
• Data sources for images, elevation, vectors, and models.
• Caching configurations.

Tip: Relative paths within an Earth File are interpreted as being relative to the location of the Earth File itself.

A Spatial Reference (SRS) maps a set of coordinates to a corresponding real location on the earth. It provides the necessary context to interpret raw numbers (coordinates) by defining the coordinate system, datums, and projections.

An SRS consists of four main components:

• Coordinate System Type: Defines the mathematical model (Geographic, Projected, or ECEF).
• Horizontal Datum: The reference point/shape used to measure positions on the earth (e.g., WGS84, NAD83).
• Vertical Datum: The reference used to measure elevation (e.g., Geodetic, EGM96 geoid).
• Projection: The mathematical formula used to transform ellipsoidal points into a 2D plane (e.g., UTM, Mercator).

TMS (Tile Map Service) is an OSGeo standard for tiled geospatial raster data. A TMS repository typically consists of an XML metadata file (often named tms.xml) and a hierarchical directory structure of individual raster tile files.

Because TMS uses pre-tiled data, it is highly efficient to load, particularly when using a global-geodetic profile. The file hierarchy structure also makes TMS data easily streamable over HTTP via a standard web server.

An XYZ layer is a pre-tiled image layer that uses a generic template URL to access raster tiles. Because XYZ layers expose no metadata, you must explicitly tell osgEarth the profile and other data source characteristics.

URL Template Requirements:

• The URL must include the template parameters {z} (tile level), {x} (tile offset), and {y} (tile offset).
• To support datasets that are flipped vertically, the {y} parameter can be used in the form {-y}.
• The template also supports round-robin character sets using square brackets [] to balance requests across multiple servers.

An Earth File is an XML file used to describe the contents of an osgEarth Map.

osgEarth follows a Map/Layer paradigm:

• A Map is a collection of layers.
• The renderer draws visible layers sequentially from bottom to top to compose the final scene.
• Not all layers are visible; some layers (like Viewpoints) exist solely to store data for the map engine.

When using the filesystem cache driver, be aware of the following operational constraints:

• Storage Structure: Data is organized into bin directories under the root path. While osgEarth manages these names, you can influence them using the cache_id property on map layers.
• Size Limits: The cache supports expiration (removing old data), but it does NOT support size limits. You cannot cap the total disk space used by the cache.
• Concurrency & Corruption: Cache access is serialized. Do not access the cache from more than one process at a time, as this may cause data corruption.
• Data Format: The format of the cached files is a "black box" and is subject to change without notice. Do not attempt to use these files for purposes other than osgEarth caching.