🚧 This project is in active beta development. This means the API is unstable, features may be added or removed, and breaking changes are likely to occur frequently and without notice as the design is refined.

TerrainGen

Blue Moon MK1 SN101 lander at Connecting Ridge near the lunar south pole, with Mons Malapert in the background. Terrain upscaled by TerrainGen from LOLA elevation models.

A high-performance scientific terrain generation tool for interplanetary bodies.

TerrainGen can:

• Generate synthetic terrain from scratch, or add fine detail to existing elevation models.
• Populate craters and boulders from cumulative size-frequency distributions.
• Model each crater's profile, age, degradation, irregularity.
• Bake small boulders into the heightmap, and generate procedural 3D boulder models for the large ones.
• Produce synthetic albedo maps with crater ejecta and rays that fade with crater age.
• Model complex geologic features such as complex and secondary craters, boulder ejecta fields, dunes and wind ripples, layered strata terraced into benches and cliffs, fractured bedrock pavement, wind-carved ventifacts, and sand pooled in lows or trailing behind boulders.
• Be extended through base classes in C++ or Python with custom size-frequency distributions, crater ages, profiles and degradation, albedo, sources, and layers.
• Perform GPU-accelerated operations for generating noise, craters, boulders, albedo, and more.
• Generate deterministic results for the same seed on any grid, tile or thread count.
• Integrate into simulations and other external workflows.

We also provide:

• A modular C++ library with Python bindings and minimal dependencies.
• Smart and tested defaults for various surface features.
• A command-line interface that generates terrain from JSON configuration files.
• A GUI for editing configurations and viewing the results in 3D.
• Examples in C++, Python and JSON.
• A standalone demo that streams TerrainGen detail into a planetary-scale renderer on the GPU while navigating around the Moon.
• Example integrations with third-party tools such as Project Chrono, IsaacLab, and Newton.

For more information on the concepts behind TerrainGen and the API, see our latest documentation.

Quick Start

We recommended getting started by installing terraingenpy from PyPi and running the GUI.

pip install terraingenpy
terraingen --gui

Requirements

• Linux (Ubuntu 22.04 or newer), macOS 14 or newer, or Windows 10 or newer, on x86_64 or arm64.
• Python 3.10 or newer for the Python package.
• Optional: a Vulkan, CUDA or Metal driver for GPU acceleration. Run terraingen backends to see what is available.

Installation

Releases

Every release has the CLI, library, headers and CMake package for each platform, and .deb packages for Ubuntu and Debian. The latest pre-release is built from main on every push.

Building from Source

You need CMake 3.22 or newer and a C++20 compiler (GCC 11, Clang 14, Apple Clang 15 or MSVC 2022). CMake fetches everything else.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j 8
cmake --install build --prefix /usr/local

To build the Python package from source, run pip install . instead.

Docker

docker run --rm ghcr.io/alexmaietta/terraingen:latest terraingen --help

The dev tag follows main.

Getting Started

Python

import terraingen

# A flat 513 x 513 grid with 2 m pixels
ground = terraingen.FlatSource(513, 513, 2.0)

# Fractal noise 40 m high with an 800 m wavelength
fractal = terraingen.FractalParams(seed=1, wavelength=800.0, amplitude=40.0)
noise = terraingen.NoiseLayer(fractal)
relief = terraingen.NoiseRelief([noise])

terrain = terraingen.Terrain(ground, [relief])
heights = terraingen.evaluate(terrain)
terraingen.write_geotiff("terrain.tif", heights)

C++

find_package(terraingen REQUIRED)
target_link_libraries(app PRIVATE terraingen::terraingen)

#include <terraingen/terraingen.h>

int main() {
    // Fractal noise 40 m high with an 800 m wavelength
    terraingen::NoiseLayer noise;
    noise.fractal.seed = 1;
    noise.fractal.wavelength = 800.0f;
    noise.fractal.amplitude = 40.0f;

    terraingen::SyntheticTerrainParams relief;
    relief.layers = {noise};

    // A flat 513 x 513 grid with 2 m pixels, plus the noise
    terraingen::Terrain terrain;
    terrain.source = std::make_shared<terraingen::FlatSource>(513, 513, 2.0);
    terrain.layers.push_back(std::make_shared<terraingen::NoiseRelief>(relief));

    terraingen::Raster<float> heights = terraingen::Evaluate(terrain);
    terraingen::WriteGeoTiff("terrain.tif", heights);
}

Examples

examples/ has the same terrains as JSON configurations, C++ programs and Python scripts, covering basic terrains, craters, boulders, albedo, planets, DEM detail and tiles:

terraingen examples/config/craters/example_craters_simple.json

Demos

demos/ has larger showcases, such as terrain over a whole asteroid built from the Itokawa shape model.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to build, test and submit changes.

Documentation

The documentation is built with MkDocs and Doxygen from docs/. Run make -C docs build to build it locally.

Code Coverage

The coverage report is updated on every push to main. To generate it locally:

cmake -S . -B build-coverage -DTERRAINGEN_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build-coverage -j 8 --target coverage

Citation

If you use TerrainGen for published research, please cite:

@software{maietta_terraingen,
  author  = {Maietta, Alex},
  title   = {{TerrainGen}: An open-source scientific terrain generation suite for planetary surfaces},
  url     = {https://github.com/alexmaietta/terraingen},
  version = {0.1.0},
  license = {BSD-3-Clause},
  year    = {2026}
}

License

TerrainGen is licensed under the BSD 3-Clause License.

Third-party code and assets keep their own licenses, listed in third_party/README.md.

Acknowledgements

TerrainGen draws inspiration from existing lunar terrain generation tools: