terraingenpy 0.1.1.dev77__tar.gz → 0.1.1.dev82__tar.gz

terraingenpy-0.1.1.dev82/.pre-commit-config.yaml

@@ -0,0 +1,59 @@
+# Vendored code in third_party/ directories stays byte-identical to upstream.
+exclude: (^|/)third_party/
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+      - id: pretty-format-json
+        args: ["--autofix", "--indent=4", "--no-sort-keys"]
+        files: ^examples/
+
+  - repo: https://github.com/pre-commit/mirrors-clang-format
+    rev: v22.1.8
+    hooks:
+      - id: clang-format
+        types_or: [c++, c]
+        exclude: (^|/)third_party/
+
+  - repo: https://github.com/pocc/pre-commit-hooks
+    rev: v1.3.5
+    hooks:
+      - id: cppcheck
+        exclude: (^|/)third_party/
+        additional_dependencies: ["cppcheck==1.5.1"]
+        args:
+          - "--language=c++"
+          - "--std=c++17"
+          - "--enable=warning,performance,portability"
+          - "--suppress=missingInclude"
+          - "--include=terraingen/util/portable.h"
+          - "-U__SLANG__"
+          - "--suppress=passedByValue:terraingen/noise/*"
+          - "--suppress=normalCheckLevelMaxBranches"
+          - "--suppress=floatConversionOverflow:terraingen/python/src/noise.cpp"
+          - "--suppress=floatConversionOverflow:terraingen/python/src/mesh.cpp"
+          - "--suppress=assignBoolToPointer:terraingen/python/src/*"
+          - "--suppress=syntaxError:terraingen/gpu/metal.cpp"
+          - "--suppress=returnByReference:terraingen/raster/raster.h"
+          - "--error-exitcode=1"
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.1
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format
+
+  - repo: https://github.com/cheshirekow/cmake-format-precommit
+    rev: v0.6.13
+    hooks:
+      - id: cmake-format
+        additional_dependencies: ["pyyaml>=5.1"]

terraingenpy-0.1.1.dev82/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Piecewise uniform size-frequency distributions: counts per diameter band, given absolutely or as shares of a total.
+- Radial wall marks on craters, ridges and grooves down the wall that are strongest where it is steepest.
+- Thomas cluster process for boulder clusters, with Poisson-scattered centres whose clusters add where they overlap.
+- Craters on slopes: floors offset downslope and rims and ejecta lowered upslope (Plescia et al. 2019), and faster wear toward a critical gradient (Roering et al. 1999).
+- Boulders limited to a maximum slope, optionally rolling down steeper ground to gather at its foot.
+- Density maps from GeoTIFFs or constants: a scale, a count in a diameter range, or an areal fraction such as rock abundance, which set crater and boulder densities point by point.
+- Size slope maps that bend boulder sizes into a local power law, from an exponent or a mean diameter map.
+- Crater and boulder catalogs with a completeness limit, above which they stand in for generated features.
+- Configuration reference in the documentation, generated from the schema at build time, and machine-readable value ranges in the schema.
+- Rock albedo: boulders brighter than the regolith (Holt 1981; Marshal et al. 2023), and a speckle of the share of each sample covered by boulders too small to resolve, with the scatter of randomly placed rocks.
+- Slope albedo: steep ground kept immature by mass wasting, its optical maturity rising with slope beyond 20 degrees (Ikeda et al. 2022; Lucey et al. 2014).
+- Crater shaping and datum fitting on the GPU on spheres, ellipsoids and shape models, not only on planes.
+- Configurations are checked against every field's documented range, and errors name the exact field, such as `layers[2].reach`.
+- Python options classes document every field with its description and unit, and gain `validate()` and a readable `repr`.
+
+### Changed
+
+- Breaking: every angle key in configurations and the Python options classes is now in degrees and ends in `_deg` (`wind_azimuth_deg`, `slip_face_angle_deg`, `heading_deg`, `crease_angle_deg`), azimuths counter-clockwise from +x (local east); the old keys are rejected.
+- Defaults give a plausible lunar terrain at 1 m per pixel in which every height layer shows: craters from a production surface capped below the Trask equilibrium with steady-state ages, diffusion and irregular outlines; Surveyor boulders; noise relief scaled to its wavelength; and visible roughness, bedforms and dunes.
+- Boulder layers default to the nominal NASA SP-8023 intercrater sizes rather than Golombek-Rapp; a `coverage`, `qa`, `qb` or `ejecta.coverage` that no Golombek-Rapp sizes use is now an error that names `"sizes": {"type": "golombek_rapp"}`.
+- Boulder lists and models hold every boulder of the layer's diameter range; only the heightmap leaves out boulders too small to resolve.
+- Boulder ejecta come from every crater layer before the boulder layer, not only the last one.
+- The boulder layer's `exposure_spacing` key is now `ground_spacing` (Python `ground_spacing`), the spacing of every ground read the layer makes.
+- Crater shaping has one implementation, the kernel, on every surface; craters on bodies and custom profiles may differ from before in the last digits.
+- Random streams and hashes are unified, so boulder, albedo, dune, bedform and pavement outputs for a given seed differ from earlier versions; their statistics are unchanged.
+- Every evaluation defaults to all threads, including `EvaluateAt`, `EvaluateTile` and Python `evaluate_tile`.
+- The `materials` module is folded into `pipeline` (material maps) and `albedo` (Hapke photometry); include `terraingen/pipeline/materials.h` and `terraingen/albedo/photometry.h`.
+- Python: `ExposureField.exposure` takes `(x, y, spacing=0.0, terrain=None, layers=0)` like the other ground queries, unbounded options read as `None` instead of infinity, `write_outputs` returns paths, a subclass missing a required method raises `TypeError`, and `CraterFeatures.write` is `write_list`.
+- Python names: `cell_of` is `cell_at`, `point_of` is `coordinates`, `level_for` is `resolving_level`, `outline_of` is `irregular_outline`, `min_diameter_for_count` is `count_limit_diameter`, `singer_range_for_size` is `singer_max_range`, `SplotchOptions` is `SplotchAlbedoOptions` and `SlopeMaturityOptions` is `SlopeAlbedoOptions`.
+- The CI coverage job builds at `-O1` without atomic counters, so it caches and runs several times faster.
+
+- Density maps that count every feature take out the secondaries thrown from a layer's craters and the blocks thrown out around craters, and boulder patches and bedrock keep a map's mean, so nothing is counted twice.
+- Boulder models settle onto a stable face by default instead of balancing on an edge or corner.
+- Boulder generation logs under boulders rather than craters.
+- Crater and boulder generation summaries log at debug level; `terraingen` ends with one line counting the files written instead of listing each, and feature outputs log how long they took.
+- Generation logs each grid as it is evaluated, with the time of every layer, the albedo and the materials, and ends with each step's total and share.
+- Faster boulders: the ground beneath them is read in one batch, outputs over one region share the boulders placed for the first, models are placed in parallel, ejecta craters are found through a spatial index and shapes skip the roughness of fracture planes that cannot reach a vertex. The hero demo runs in about 10 s instead of 276 s.
+- Martin, Parkes and Dunstan is the default crater profile.
+
+### Fixed
+
+- Freshness degradation never makes a crater deeper than fresh: basins shallower than the cutoff keep their fresh shape.
+- Small craters inside larger ones on sloping ground no longer stand as raised mounds: datums are fitted to the slope-shaped relief that is applied.
+- Crater layers over other layers read the ground beneath their slopes and datums in batches rather than point by point, and point batches are evaluated in spatial order: the hero demo went from 433 s to 11 s with the same output.
+- Secondary craters run on the GPU backend the terrain asks for instead of always on the CPU.
+- A crater layer after a boulder layer no longer refits crater datums for every batch of ground reads.
+- Tilted boulders are no longer cut off at tile edges and point queries.
+- Crater and boulder lists honour a spacing finer than the grid.
+- Zero-area regions and crater sizes below the models' range are rejected with a clear error instead of failing during generation.
+
+### Removed
+
+- Python `crater_blend_weight` (use `CraterBlend.weight`), `CraterAgeModel.lifetime_gyr` (use `lifetime_at`) and the flat selection aliases on crater irregularity, crater albedo and secondary options (use `selection`).
+
+## [0.1.0] - 2026-10-18
+
+Initial release.
+
+### Added
+
+- C++20 library with Python bindings (`terraingenpy` on PyPI) for generating terrain from scratch or adding detail to existing DEMs.
+- Craters and boulders from published size-frequency distributions, with crater ages, profiles, degradation, irregularity, secondaries and ejecta.
+- Procedural 3D boulder models, and small boulders baked into the heightmap.
+- Synthetic albedo with crater ejecta and rays that fade with age.
+- Geologic features: dunes and ripples, layered strata, fractured bedrock, ventifacts and sand pooled in lows or behind boulders.
+- Planes, spheres and ellipsoids, whole-body meshes, tiles and point queries.
+- Deterministic output for a seed on any grid, tile or thread count.
+- GPU acceleration on Vulkan, CUDA and Metal, detected at run time.
+- `terraingen` command-line interface driven by JSON configurations.
+- Examples in C++, Python and JSON.
+- Release archives for Linux, macOS and Windows, Debian packages, and a Docker image.
+
+[Unreleased]: https://github.com/alexmaietta/terraingen/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/alexmaietta/terraingen/releases/tag/v0.1.0

terraingenpy-0.1.1.dev82/CMakeLists.txt

@@ -0,0 +1,150 @@
+cmake_minimum_required(VERSION 3.22)
+
+# Archives fetched with FetchContent get extraction-time timestamps, so their files rebuild what
+# depends on them; CMake before 3.24 has no such policy and behaves this way already.
+if(POLICY CMP0135)
+    cmake_policy(SET CMP0135 NEW)
+endif()
+
+# The release being worked towards, such as 0.1.0, or for a development build a PEP 440 pre-release of
+# it, such as 0.1.0.dev42, which only the Python package carries.
+set(TERRAINGEN_FULL_VERSION "0.1.1.dev82")
+string(REGEX MATCH "^[0-9]+\\.[0-9]+\\.[0-9]+" TERRAINGEN_VERSION "${TERRAINGEN_FULL_VERSION}")
+
+project(
+    TerrainGen
+    VERSION ${TERRAINGEN_VERSION}
+    LANGUAGES C CXX)
+# The Metal backend (terraingen/gpu/metal.cpp) is Objective-C++ on Apple platforms. It is enabled
+# here, above every target that links the gpu module.
+if(APPLE)
+    enable_language(OBJCXX)
+endif()
+
+# No fused multiply-adds unless the source asks: GCC and Clang contract a * b + c into one rounding on
+# CPUs that have the instruction (ARM, Apple Silicon), so the same seed would give different bits
+# there than on x86.
+add_compile_options(
+    "$<$<COMPILE_LANG_AND_ID:C,GNU,Clang,AppleClang>:-ffp-contract=off>"
+    "$<$<COMPILE_LANG_AND_ID:CXX,GNU,Clang,AppleClang>:-ffp-contract=off>"
+    "$<$<COMPILE_LANG_AND_ID:OBJCXX,AppleClang,Clang>:-ffp-contract=off>")
+
+option(TERRAINGEN_BUILD_TESTS "Build the test suite" ${PROJECT_IS_TOP_LEVEL})
+option(TERRAINGEN_BUILD_BENCHMARKS "Build the benchmarks (Google Benchmark)"
+       ${PROJECT_IS_TOP_LEVEL})
+option(TERRAINGEN_BUILD_EXAMPLES "Build the C++ examples and test every example"
+       ${PROJECT_IS_TOP_LEVEL})
+option(TERRAINGEN_BUILD_PYTHON "Build the Python bindings" ON)
+option(TERRAINGEN_BUILD_APP "Build the terraingen command-line app" ON)
+option(TERRAINGEN_BUILD_GUI
+       "Build `terraingen --gui`, the 3D GUI, with Ernie from TERRAINGEN_ERNIE_DIR, if it is there"
+       ON)
+option(TERRAINGEN_INSTALL "Generate install rules and the CMake package" ${PROJECT_IS_TOP_LEVEL})
+option(TERRAINGEN_COVERAGE "Instrument TerrainGen for code coverage and add a coverage target" OFF)
+
+include(GNUInstallDirs)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+set(CMAKE_CXX_VISIBILITY_PRESET hidden)
+set(CMAKE_VISIBILITY_INLINES_HIDDEN ON)
+
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/bin")
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/lib")
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/lib")
+
+add_library(terraingen_warnings INTERFACE)
+if(MSVC)
+    target_compile_options(terraingen_warnings INTERFACE /W4)
+else()
+    target_compile_options(
+        terraingen_warnings
+        INTERFACE -Wall
+                  -Wextra
+                  -Wpedantic
+                  -Wshadow
+                  -Wconversion
+                  -Wsign-conversion
+                  -Wdouble-promotion)
+endif()
+
+add_library(terraingen_coverage INTERFACE)
+if(TERRAINGEN_COVERAGE)
+    if(NOT CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+        message(FATAL_ERROR "TERRAINGEN_COVERAGE requires GCC or Clang")
+    endif()
+    if(NOT TERRAINGEN_BUILD_TESTS)
+        message(FATAL_ERROR "TERRAINGEN_COVERAGE requires TERRAINGEN_BUILD_TESTS")
+    endif()
+    # -O1 runs the terrain-generating tests several times faster than -O0. The counters are not
+    # atomic: atomic ones made threaded tests about three times slower, a race only loses hits, and
+    # ccache does not cache compiles with -fprofile-update.
+    set(TERRAINGEN_COVERAGE_OPTIMIZATION
+        "-O1"
+        CACHE STRING "Optimization flag for coverage builds")
+    target_compile_options(terraingen_coverage INTERFACE --coverage
+                                                         ${TERRAINGEN_COVERAGE_OPTIMIZATION} -g)
+    target_link_options(terraingen_coverage INTERFACE --coverage)
+endif()
+
+if(TERRAINGEN_BUILD_PYTHON)
+    include("${PROJECT_SOURCE_DIR}/cmake/third_party/nanobind.cmake")
+endif()
+
+include("${PROJECT_SOURCE_DIR}/cmake/third_party/vulkan_headers.cmake")
+include("${PROJECT_SOURCE_DIR}/cmake/third_party/volk.cmake")
+include("${PROJECT_SOURCE_DIR}/cmake/third_party/slang.cmake")
+include("${PROJECT_SOURCE_DIR}/cmake/third_party/nvrtc.cmake")
+include("${PROJECT_SOURCE_DIR}/cmake/TerrainGenSlang.cmake")
+
+# TERRAINGEN_GUI says whether the GUI is built: asked for, with the app, and Ernie found.
+set(TERRAINGEN_GUI OFF)
+if(TERRAINGEN_BUILD_GUI AND TERRAINGEN_BUILD_APP)
+    include("${PROJECT_SOURCE_DIR}/cmake/third_party/ernie.cmake")
+endif()
+
+add_subdirectory(terraingen)
+
+if(TERRAINGEN_BUILD_TESTS)
+    enable_testing()
+    include("${PROJECT_SOURCE_DIR}/cmake/TerrainGenTesting.cmake")
+endif()
+if(TERRAINGEN_BUILD_EXAMPLES)
+    add_subdirectory(examples/cpp)
+endif()
+if(TERRAINGEN_BUILD_TESTS)
+    add_subdirectory(tests)
+endif()
+if(TERRAINGEN_BUILD_BENCHMARKS)
+    add_subdirectory(tests/benchmark)
+endif()
+
+if(TERRAINGEN_INSTALL)
+    include(CMakePackageConfigHelpers)
+    set(TERRAINGEN_INSTALL_CMAKEDIR "${CMAKE_INSTALL_LIBDIR}/cmake/terraingen")
+
+    install(
+        EXPORT terraingenTargets
+        NAMESPACE terraingen::
+        DESTINATION "${TERRAINGEN_INSTALL_CMAKEDIR}"
+        COMPONENT development)
+
+    configure_package_config_file(
+        "${PROJECT_SOURCE_DIR}/cmake/terraingenConfig.cmake.in"
+        "${PROJECT_BINARY_DIR}/terraingenConfig.cmake"
+        INSTALL_DESTINATION "${TERRAINGEN_INSTALL_CMAKEDIR}")
+    write_basic_package_version_file("${PROJECT_BINARY_DIR}/terraingenConfigVersion.cmake"
+                                     COMPATIBILITY SameMinorVersion)
+
+    install(
+        FILES "${PROJECT_BINARY_DIR}/terraingenConfig.cmake"
+              "${PROJECT_BINARY_DIR}/terraingenConfigVersion.cmake"
+        DESTINATION "${TERRAINGEN_INSTALL_CMAKEDIR}"
+        COMPONENT development)
+
+    include("${PROJECT_SOURCE_DIR}/cmake/TerrainGenPackaging.cmake")
+endif()

terraingenpy-0.1.1.dev82/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to TerrainGen
+
+Thank you for helping. Bug reports, questions, references and pull requests are all welcome; for anything larger than a fix, please open an issue first so we can agree on the approach.
+
+## Building and testing
+
+TerrainGen needs CMake 3.22 or newer and a C++17 compiler (tested with GCC 11, Clang 14, Apple Clang 15 and MSVC 2022). Everything else is fetched by CMake. Keep the library, tests and examples C++17: no `std::span` (use `terraingen::Span`), `std::numbers` (use `kPi` from `util/bits.h`), defaulted comparisons, concepts or designated initialisers.
+
+```sh
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j 8
+ctest --test-dir build -j 8 --output-on-failure
+```
+
+The Vulkan compute tests skip on machines without a Vulkan device. The Python bindings build with `pip install .` (or into `build/python` with the CMake build); run their tests with `pytest tests/python`.
+
+Tests are grouped by kind: `tests/unit` mirrors `terraingen/` one folder per module, `tests/statistical` checks sampled distributions against their models, `tests/golden` pins generated values, `tests/integration` runs every example and configuration, and `tests/python` has one file per module. Shared helpers live in `tests/support`.
+
+Coverage needs GCC or Clang; the `coverage` target runs the tests and writes a report to `build-coverage/coverage/`:
+
+```sh
+cmake -S . -B build-coverage -DTERRAINGEN_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
+cmake --build build-coverage -j 8 --target coverage
+```
+
+The 3D GUI (`terraingen CONFIG --gui`) builds with Ernie, the renderer, from a local checkout: `-DTERRAINGEN_ERNIE_DIR=../ernie`. Without one, configuring warns and builds everything else, and `--gui` says how to add it; `-DTERRAINGEN_BUILD_GUI=OFF` leaves the GUI out without the warning.
+
+## Pull requests
+
+- Every change comes with tests, and new code should be covered by them.
+- Run [pre-commit](https://pre-commit.com) before committing (`pre-commit install` once): it formats C++ with clang-format, CMake with cmake-format, Python with ruff and the example JSON configurations, and runs cppcheck and ruff's linter.
+- Keep commits focused, with a one-line message saying what changed.
+- CI must pass on Linux, macOS and Windows.
+
+## Conventions
+
+- **Cite what you model.** Constants, fits and models come from published sources: name the paper, with its DOI or URL, in the doc comment, and keep the rest of the comment to what the code does. If a value has no source, say so rather than guess.
+- **Plain ASCII** in code, comments, docs and commit messages: write "metres", "degrees", "D^-2" and "sigma" rather than Unicode symbols.
+- **Document public headers** with short `///` comments: a `@file` line saying what the header holds, then one sentence per type and function. Add `@param` only for units, ranges or special values, `@return` only when the sentence does not say it, and `@throws` for each exception a function raises on purpose. Leave overrides undocumented, and prefer clear names to inline comments.
+- **Dependencies:** TerrainGen stays light. Please discuss a new third-party library in an issue before adding it; vendored code in `third_party/` stays byte-identical to upstream.
+- **Configuration fields** carry a description and, for numbers, a unit (see the field lists in `terraingen/config/fields/`); a test checks every field has them.
+
+## Reporting bugs
+
+Open an issue with the configuration (or code) that shows the problem, what you expected and what happened, and your platform.
+
+By contributing you agree that your contributions are licensed under the project's [BSD 3-Clause License](LICENSE).

terraingenpy-0.1.1.dev82/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.1
+Name: terraingenpy
+Version: 0.1.1.dev82
+Summary: Scientific terrain generation for planetary surfaces
+Keywords: terrain,moon,mars,craters,planetary science,simulation
+Author: Alex Maietta
+License: BSD 3-Clause License
+         
+         Copyright (c) 2026, Alex Maietta
+         
+         Redistribution and use in source and binary forms, with or without
+         modification, are permitted provided that the following conditions are met:
+         
+         1. Redistributions of source code must retain the above copyright notice, this
+            list of conditions and the following disclaimer.
+         
+         2. Redistributions in binary form must reproduce the above copyright notice,
+            this list of conditions and the following disclaimer in the documentation
+            and/or other materials provided with the distribution.
+         
+         3. Neither the name of the copyright holder nor the names of its
+            contributors may be used to endorse or promote products derived from
+            this software without specific prior written permission.
+         
+         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+         
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: GIS
+Project-URL: Homepage, https://github.com/alexmaietta/terraingen
+Project-URL: Documentation, https://alexmaietta.github.io/terraingen/
+Project-URL: Source, https://github.com/alexmaietta/terraingen
+Project-URL: Issues, https://github.com/alexmaietta/terraingen/issues
+Project-URL: Changelog, https://github.com/alexmaietta/terraingen/blob/main/CHANGELOG.md
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.22
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Description-Content-Type: text/markdown
+
+> 🚧 **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.
+
+[![pipeline](https://img.shields.io/github/actions/workflow/status/alexmaietta/terraingen/ci.yml?branch=main&label=pipeline)](https://github.com/alexmaietta/terraingen/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/endpoint?url=https://alexmaietta.github.io/terraingen/coverage/badge.json)](https://alexmaietta.github.io/terraingen/coverage/)
+[![release](https://img.shields.io/github/v/release/alexmaietta/terraingen)](https://github.com/alexmaietta/terraingen/releases)
+[![pypi](https://img.shields.io/pypi/v/terraingenpy)](https://pypi.org/project/terraingenpy/)
+[![license](https://img.shields.io/badge/license-BSD_3--Clause-blue)](LICENSE)
+
+# TerrainGen
+
+A high-performance scientific terrain generation tool for interplanetary bodies.
+
+![Blue Moon MK1 SN101 lander at Connecting Ridge, with Mons Malapert in the background, split between the source elevation model and TerrainGen's upscaled terrain](https://raw.githubusercontent.com/alexmaietta/terraingen/main/docs/images/hero_mk1_sn101_connecting_ridge_split.jpg)
+
+*Blue Moon MK1 SN101 lander at Connecting Ridge near the lunar south pole, with Mons Malapert in the background. Left: the 5 m/px LOLA elevation models as they are. Right: the same terrain upscaled by TerrainGen.*
+
+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.
+- Read GeoTIFF elevation and albedo maps, and ICQ, OBJ, glTF and STL shape models.
+- Write GeoTIFF heightmaps and albedo, material and photometry maps, crater and boulder lists as CSV or JSON, and terrain, boulder and body meshes as glTF, OBJ or STL.
+- 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](https://alexmaietta.github.io/terraingen/).
+
+## Quick Start
+
+We recommended getting started by installing `terraingenpy` from PyPi and running the GUI.
+
+```sh
+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](https://github.com/alexmaietta/terraingen/releases) has the CLI, library, headers and CMake package for each platform, and `.deb` packages for Ubuntu and Debian. The [latest](https://github.com/alexmaietta/terraingen/releases/tag/latest) pre-release is built from `main` on every push.
+
+### Building from Source
+
+You need CMake 3.22 or newer and a C++17 compiler (tested with GCC 11, Clang 14, Apple Clang 15 and MSVC 2022). CMake fetches everything else.
+
+```sh
+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
+
+```sh
+docker run --rm ghcr.io/alexmaietta/terraingen:latest terraingen --help
+```
+
+The `dev` tag follows `main`.
+
+## Getting Started
+
+### Python
+
+```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++
+
+```cmake
+find_package(terraingen REQUIRED)
+target_link_libraries(app PRIVATE terraingen::terraingen)
+```
+
+```cpp
+#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/](examples/) has the same terrains as JSON configurations, C++ programs and Python scripts, covering basic terrains, craters, boulders, albedo, planets, DEM detail and tiles:
+
+```sh
+terraingen examples/config/craters/example_craters_simple.json
+```
+
+### Demos
+
+[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](CONTRIBUTING.md) for how to build, test and submit changes.
+
+### Documentation
+
+The [documentation](https://alexmaietta.github.io/terraingen/) is built with MkDocs and Doxygen from [docs/](docs/). Run `make -C docs build` to build it locally.
+
+### Code Coverage
+
+The [coverage report](https://alexmaietta.github.io/terraingen/coverage/) is updated on every push to `main`. To generate it locally:
+
+```sh
+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:
+
+```bibtex
+@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](LICENSE).
+
+Third-party code and assets keep their own licenses, listed in [third_party/README.md](third_party/README.md).
+
+## Acknowledgements
+
+TerrainGen draws inspiration from existing lunar terrain generation tools:
+
+| Name | Organization | Availability | Capabilities | Limitations |
+| --- | --- | --- | --- | --- |
+| [synthterrain](https://github.com/NeoGeographyToolkit/synthterrain) | NASA Ames | Open source (Apache-2.0) | Crater and boulder populations from size-frequency distributions, crater profiles and DEMs on flat terrain | Doesn't generate surface detail or upscale existing DEMs, not actively contributed to. |
+| [lunasynth](https://github.com/nasa-jpl/lunasynth) | NASA JPL | Open source (Apache-2.0) | Adds craters and boulders to a lunar base DEM, down to 1 cm pixels, and renders images under varying camera and sun positions | Project is not actively-maintained |
+| [DLES Terrain Crafting](https://doi.org/10.1109/AERO63441.2025.11068736) | NASA JSC | Not publicly released (paper) | Enhances LOLA and NAC-derived DEMs of the lunar south pole to 20 cm with synthetic craters and boulders, including hand-placed craters from imagery | Not publicly released, relies on manual crater counting, stamps craters from four template shapes, leaves blending rings around craters and smooth interpolated ground between them, and doesn't produce albedo maps. |
+| [PANGU](https://pangu.software/) | University of Dundee / STAR-Dundee | Commercial (free for ESA projects) | Multi-resolution planet and asteroid surfaces from real or fractal DEMs with statistical craters and boulders; GPU camera, LiDAR and thermal sensor simulation | Requires a paid license outside ESA projects, and ships as standalone command-line tools and GUIs rather than a library to integrate into a project. |