osgEarth for building C++ 3D maps and terrain applications

Why osgEarth belongs in a native C++ mapping stack

osgEarth solves a specific integration problem: adding a geographically accurate 3D map to a C++ application without implementing terrain, projections, imagery layers, and earth navigation from the ground up. It is aimed at developers of native desktop viewers, simulation interfaces, GIS tools, and similar applications. The README says osgEarth supports multiple geospatial data formats and map projections while building on OpenSceneGraph and GDAL.

This relationship shapes adoption. OpenSceneGraph supplies the scene and viewer foundation used in the integration example, while GDAL is listed among the geospatial dependencies installed by the repository's `Dockerfile`. osgEarth adds the mapping-specific pieces: map layers, earth files, terrain and imagery configuration, and an earth-aware camera manipulator.

It is not presented as a general-purpose map widget for a web page or a standard desktop user-interface toolkit. The README's integration example creates an `osgViewer::Viewer`, configures a graphics realize operation, creates a `MapNode`, and assigns an `EarthManipulator`. Those choices place osgEarth inside an OpenSceneGraph application instead of hiding the graphics stack behind a small component interface. This is appropriate for code that needs direct control of a 3D scene, but it increases the number of systems an integrator must understand.

How osgEarth connects XML maps to the scene graph

The central configuration unit documented by osgEarth is the earth file. The README defines earth files as XML files that describe the contents of a map. Its examples use that same mechanism for different source categories: `readymap.earth` requests online imagery and elevation, `simple.earth` uses local GeoTIFF files, and `osm.earth` presents OpenStreetMap data. An earth file is therefore more than a display preset. It connects configured geospatial sources to the map used by the application.

The C++ example exposes the object flow. A `TMSImageLayer` receives a tile URL, then the layer is added to the map owned by a `MapNode`. The viewer receives that node as its scene data. `EarthManipulator` is installed as the camera manipulator, so camera interaction is connected to the geospatial context rather than being treated as navigation around an ordinary model.

The responsibilities remain separate. `TMSImageLayer` identifies an image source. `MapNode` provides the map's scene-graph representation. `EarthManipulator` handles earth navigation. The viewer joins the pieces and runs the application loop. This structure gives developers direct access to layers and scene organization. The trade-off is that the application owns initialization, viewer configuration, map construction, and camera setup instead of receiving a prepared map widget.

Installing osgEarth and opening its example maps

The README documents installation through vcpkg for 64-bit Windows. The base package installs osgEarth, while the `tools` feature includes the viewer utilities. These are the commands published by the project:

vcpkg install osgearth:x64-windows
vcpkg install osgearth[tools]:x64-windows

After installation, the README directs users to the `tests` directory. It identifies `osgearth_imgui` as the main command-line viewer with a GUI, while `osgearth_viewer` is the stripped-down viewer without one. The documented first-use commands are:

cd tests
osgearth_imgui readymap.earth
osgearth_imgui simple.earth
osgearth_imgui osm.earth

The first command loads the ReadyMap example for online imagery and elevation. The second opens `simple.earth`, which the README associates with local GeoTIFF files. The third opens `osm.earth` for OpenStreetMap. A reader following this path should confirm that the installed viewer is on the command search path and that remote examples have network access. Local examples avoid dependence on a remote tile service, although the README does not state which assets outside the repository, if any, they require.

The README does not provide equivalent package-manager commands for Linux or macOS. For source builds, it links to `https://docs.osgearth.org/en/latest/build.html`. Repository files such as `Dockerfile`, `build.bat`, `configure.bat`, and `bootstrap-vcpkg.bat` indicate additional build-related resources, but the README does not define them as interchangeable installation methods. The clearest documented path is vcpkg on 64-bit Windows, followed by opening an earth file.

Building a CMake application around MapNode and TMSImageLayer

The integration example shows that embedding osgEarth requires only a small set of visible configuration steps, but several parts must already be installed and discoverable. The CMake project requests version 3.20 or newer, finds the osgEarth package configuration, and links the executable to `osgEarth::osgEarth`:

cmake_minimum_required(VERSION 3.20)
project(myApp)
find_package(osgEarth CONFIG REQUIRED)
add_executable(myApp main.cpp)
target_link_libraries(myApp PRIVATE osgEarth::osgEarth)
install(TARGETS myApp RUNTIME DESTINATION bin)

The `CONFIG` requirement means the build depends on finding the installed CMake package metadata. The vcpkg `[tools]` feature is aimed at the example viewers; the application executable itself links the imported `osgEarth::osgEarth` target.

The accompanying `main.cpp` initializes osgEarth, creates an `osgViewer::Viewer`, applies `GL3RealizeOperation`, configures a TMS image layer, attaches a `MapNode`, and uses `EarthManipulator`. The shortened flow below retains the exact configuration calls relevant to integration:

osgEarth::initialize();
osg::ArgumentParser args(&argc, argv);
osgViewer::Viewer viewer(args);
viewer.setRealizeOperation(new osgEarth::GL3RealizeOperation());
auto imagery = new osgEarth::TMSImageLayer();
imagery->setURL("https://readymap.org/readymap/tiles/1.0.0/7/");
auto mapNode = new osgEarth::MapNode();
mapNode->getMap()->addLayer(imagery);
viewer.setSceneData(mapNode);
viewer.setCameraManipulator(new osgEarth::EarthManipulator(args));

This code establishes an imagery layer but does not add an elevation layer in C++. Applications that require both imagery and terrain should start from the documented `readymap.earth` example or consult the external build and reference documentation. The README does not document tile retries, authentication, offline caching, or recovery from a failed network request.

Viewer selection and native dependency constraints

osgEarth provides two documented viewer choices. `osgearth_imgui` is the main command-line viewer and includes a GUI. `osgearth_viewer` is described as a stripped-down viewer without a GUI. Both read earth files, so the selection changes the viewer interface rather than replacing the XML map model. The first is more suitable when an interactive control panel is part of the task. The second avoids that GUI when a simpler map window is enough.

The repository's `Dockerfile` shows a concrete Ubuntu 24.04 build environment. It starts with OpenGL development packages, CMake, a compiler toolchain, OpenSceneGraph, GDAL, GEOS, SQLite, Protocol Buffers, TinyXML, and GLEW. It then creates a `build` directory, configures a `Release` build with CMake, compiles with `make -j$(nproc)`, installs the artifacts, runs `ldconfig`, and removes `/code` from the image. This is a self-contained build recipe, but the Dockerfile does not configure optional features or claim that the resulting image is a supported end-user distribution.

Native dependencies also constrain portability. The C++ program directly constructs OpenSceneGraph classes and uses a graphics realize operation, so graphics drivers and OpenGL support remain part of the deployment problem. The README does not provide a compatibility matrix for operating systems, compilers, OpenSceneGraph releases, or GDAL releases.

Remote earth files create a separate dependency on network availability. The README's ReadyMap and OpenStreetMap examples rely on remote services, while `simple.earth` demonstrates local data. The repository contains `data` and `tests` directories, but the README does not document a complete offline deployment or cache-retention policy.

osgEarth releases, MIT terms, and upgrade work

The repository is not archived, and its recorded last push was on 2026-10-13. Recent releases include `osgEarth-3.8.1` on 2026-06-30, `osgEarth-3.8` on 2026-03-04, and `osgEarth-3.7.2` on 2025-04-04. This release history indicates continued versioned output, but the README does not define a long-term support policy, release cadence, or compatibility matrix for its native dependencies.

The repository uses the `MIT` license. Its standard terms permit use, modification, distribution, sublicensing, and sale under conditions that include retaining the copyright and permission notice. This is not legal advice. An application should also account for the separate terms of OpenSceneGraph, GDAL, GEOS, other linked libraries, map providers, and data assets. The repository description and README do not grant additional rights to third-party imagery or map data.

The main upgrade cost is integration validation. A project must update the osgEarth package, rebuild its native application, review any changed headers or APIs, and confirm compatibility with OpenSceneGraph, GDAL, the compiler, and the graphics environment. Earth files may also need review if supported formats, layer behavior, or remote services change. The README does not include a migration guide or promise automatic handling of those changes. Projects that rely on the sample earth files should therefore treat application builds and data-source checks as separate release tasks.

Editorial conclusion

osgEarth is appropriate for engineers building native C++ applications that need geospatial 3D terrain, tiled imagery, or map layers. It is a poor fit for a lightweight image viewer or a team that wants to avoid OpenSceneGraph, GDAL, XML earth files, and graphics integration. Before adoption, verify the build path for the target operating system, test every required earth-file data source, and confirm that the linked OpenSceneGraph and GDAL versions work with the application. For the documented vcpkg route, begin by checking whether `osgearth_imgui` opens each required local and online map.

Frequently asked questions

Official sources

1. License: MIT
2. pelicanmapping/osgearth on GitHub
3. Project website
4. README
5. Releases