terraingenpy 0.1.1.dev77__tar.gz → 0.1.1.dev91__tar.gz

terraingenpy-0.1.1.dev91/.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.dev91/CHANGELOG.md

@@ -0,0 +1,91 @@
+# 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`.
+- `RasterSource`, heights from a raster in memory, shared rather than copied, low-passed and resampled as a GeoTIFF source is; `GeoTiffSource` is now a `RasterSource` of its band.
+- Windowed GeoTIFF reads that decode only the strips or tiles a window meets, and a `region` for GeoTIFF sources that reads only the window it needs while giving the same heights there as the whole file.
+- `Source::ResolutionAt`, the cell size of the data behind each height, and `UnresolvedCraterLimit`, a completeness limit that leaves the craters a DEM already resolves to it and generates only smaller ones; `MinimumField` combines it with a catalog's limit.
+- Midpoint displacement layer: random midpoint displacement (diamond-square) expansion of a DEM or any base lattice to finer spacings, as PANGU expands DEMs (Martin et al. 2014), keeping every coarser node so nested grids share their cells, with the scale and fractal dimension estimated from the base when not given.
+- Manual craters with an explicit rim-to-floor depth and rim height, in place of what the degradation model and age give; diffusion profiles solve for the age that reaches the depth.
+- Manual boulders that fix any of their height, burial, yaw, lean, tilt, rest, wear and shape seed; unset fields are drawn as for generated boulders, and fixed ones are neither re-settled nor broken.
+
+### 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. The rest of the Python API follows: `SyntheticAlbedo(hue_deg=, hue_noise_deg=)`, `hsv_to_rgb(hue_deg)`, `write_models(crease_angle_deg=)`, `TriangleMesh.with_creases(crease_angle_deg)`, `RigidTransform.rotation_x/y/z(angle_deg)`, `CubeSphereCells.direction(face, alpha_deg, beta_deg)`, `SlopeAlbedo.maturity_at(slope_deg)`, `Boulder` `yaw_deg`, `lean_deg`, `tilt_deg` and `tilt_azimuth_deg` (also the boulder table columns and the columns of boulder lists written as CSV or JSON), `BoulderFacet` `azimuth_deg` and `angle_deg`, `CraterImpact` `angle_deg` and `heading_deg`, `CraterOutline.heading_deg` and `RayDirection.azimuth_deg`; the C++ library keeps radians.
+- 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.dev91/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.dev91")
+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.dev91/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.dev91/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.1
+Name: terraingenpy
+Version: 0.1.1.dev91
+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. |