terraingenpy 0.1.1.dev13__tar.gz → 0.1.1.dev20__tar.gz

terraingenpy-0.1.1.dev20/CHANGELOG.md

@@ -0,0 +1,58 @@
+# 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).
+
+### Changed
+
+- 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.
+
+## [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.dev13 → terraingenpy-0.1.1.dev20}/CMakeLists.txt

@@ -8,7 +8,7 @@ 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.dev13")
+set(TERRAINGEN_FULL_VERSION "0.1.1.dev20")
 string(REGEX MATCH "^[0-9]+\\.[0-9]+\\.[0-9]+" TERRAINGEN_VERSION "${TERRAINGEN_FULL_VERSION}")
 
 project(

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: terraingenpy
-Version: 0.1.1.dev13
+Version: 0.1.1.dev20
 Summary: Scientific terrain generation for planetary surfaces
 Keywords: terrain,moon,mars,craters,planetary science,simulation
 Author: Alex Maietta
@@ -60,7 +60,6 @@ Description-Content-Type: text/markdown
 [![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/)
-[![docs](https://img.shields.io/website?url=https%3A%2F%2Falexmaietta.github.io%2Fterraingen%2F&label=docs&up_message=latest&down_message=offline)](https://alexmaietta.github.io/terraingen/)
 [![license](https://img.shields.io/badge/license-BSD_3--Clause-blue)](LICENSE)
 
 # TerrainGen
@@ -78,7 +77,7 @@ TerrainGen can:
 - 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.
-- GPU-accelerated operations for generating noise, craters, boulders, albedo, and more.
+- 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.
 

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev20}/README.md

@@ -4,7 +4,6 @@
 [![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/)
-[![docs](https://img.shields.io/website?url=https%3A%2F%2Falexmaietta.github.io%2Fterraingen%2F&label=docs&up_message=latest&down_message=offline)](https://alexmaietta.github.io/terraingen/)
 [![license](https://img.shields.io/badge/license-BSD_3--Clause-blue)](LICENSE)
 
 # TerrainGen
@@ -22,7 +21,7 @@ TerrainGen can:
 - 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.
-- GPU-accelerated operations for generating noise, craters, boulders, albedo, and more.
+- 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.
 

terraingenpy-0.1.1.dev20/examples/config/albedo/example_albedo_rocks_and_slopes.json

@@ -0,0 +1,76 @@
+{
+    "schema_version": 1,
+    "layers": [
+        {
+            "type": "noise",
+            "stack": [
+                {
+                    "seed": 1,
+                    "wavelength": 200,
+                    "amplitude": 2.0,
+                    "octaves": 6
+                }
+            ]
+        },
+        {
+            "type": "craters",
+            "seed": 3,
+            "density": {
+                "type": "trask"
+            },
+            "ages": {
+                "type": "fresh"
+            },
+            "min_diameter": 2,
+            "max_diameter": 40
+        },
+        {
+            "type": "boulders",
+            "seed": 5,
+            "coverage": 0.01,
+            "min_diameter": 0.05,
+            "max_diameter": 1.5,
+            "ejecta": {
+                "min_crater_diameter": 10,
+                "coverage": 0.05,
+                "reach": 3
+            }
+        }
+    ],
+    "outputs": [
+        {
+            "type": "heightmap",
+            "path": "example_albedo_rocks_and_slopes_heights.tif",
+            "region": {
+                "width": 401,
+                "height": 401,
+                "pixel_size": 0.25
+            }
+        },
+        {
+            "type": "albedo",
+            "path": "example_albedo_rocks_and_slopes_albedo.tif",
+            "region": {
+                "width": 401,
+                "height": 401,
+                "pixel_size": 0.25
+            }
+        }
+    ],
+    "albedo": {
+        "source": {
+            "type": "synthetic",
+            "value": 0.12
+        },
+        "layers": [
+            {
+                "type": "slopes",
+                "baseline": 2
+            },
+            {
+                "type": "rocks",
+                "seed": 7
+            }
+        ]
+    }
+}

terraingenpy-0.1.1.dev20/examples/config/boulders/example_boulders_rolling.json

@@ -0,0 +1,45 @@
+{
+    "schema_version": 1,
+    "layers": [
+        {
+            "type": "noise",
+            "stack": [
+                {
+                    "seed": 1,
+                    "wavelength": 30,
+                    "amplitude": 6,
+                    "octaves": 4
+                }
+            ]
+        },
+        {
+            "type": "boulders",
+            "seed": 1,
+            "coverage": 0.06,
+            "min_diameter": 0.2,
+            "max_diameter": 3,
+            "max_slope": 0.35,
+            "roll_distance": 15
+        }
+    ],
+    "outputs": [
+        {
+            "type": "heightmap",
+            "path": "example_boulders_rolling.tif",
+            "region": {
+                "width": 401,
+                "height": 401,
+                "pixel_size": 0.1
+            }
+        },
+        {
+            "type": "boulder_list",
+            "path": "example_boulders_rolling_boulders.csv",
+            "region": {
+                "width": 401,
+                "height": 401,
+                "pixel_size": 0.1
+            }
+        }
+    ]
+}

terraingenpy-0.1.1.dev20/examples/config/boulders/example_boulders_slope_map.json

@@ -0,0 +1,56 @@
+{
+    "schema_version": 1,
+    "layers": [
+        {
+            "type": "noise",
+            "stack": [
+                {
+                    "seed": 1,
+                    "wavelength": 40,
+                    "amplitude": 0.5,
+                    "octaves": 6
+                }
+            ]
+        },
+        {
+            "type": "boulders",
+            "seed": 1,
+            "sizes": {
+                "type": "power_law",
+                "coefficient": 0.02,
+                "exponent": 3.0
+            },
+            "min_diameter": 0.2,
+            "max_diameter": 3,
+            "slope_map": {
+                "field": {
+                    "value": 2.2
+                },
+                "measure": "exponent",
+                "reference_diameter": 1.0,
+                "min_exponent": 1.5,
+                "max_exponent": 5.0
+            }
+        }
+    ],
+    "outputs": [
+        {
+            "type": "heightmap",
+            "path": "example_boulders_slope_map.tif",
+            "region": {
+                "width": 401,
+                "height": 401,
+                "pixel_size": 0.1
+            }
+        },
+        {
+            "type": "boulder_list",
+            "path": "example_boulders_slope_map_boulders.csv",
+            "region": {
+                "width": 401,
+                "height": 401,
+                "pixel_size": 0.1
+            }
+        }
+    ]
+}

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev20}/terraingen/albedo/CMakeLists.txt

@@ -6,6 +6,8 @@ terraingen_add_library(
     crater_albedo.cpp
     maturity.cpp
     raster_albedo.cpp
+    rock_albedo.cpp
+    slope_albedo.cpp
     splotches.cpp
     synthetic.cpp
     PUBLIC

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev20}/terraingen/albedo/albedo.cpp

@@ -1,6 +1,7 @@
 #include "terraingen/albedo/albedo.h"
 
 #include "terraingen/util/checks.h"
+#include "terraingen/util/log.h"
 #include "terraingen/util/parallel.h"
 
 #include <algorithm>
@@ -110,8 +111,11 @@ std::vector<Raster<float>> EvaluateAlbedo(const Albedo& albedo, const RasterGrid
         bands.push_back(std::move(raster));
     }
     albedo.source->Fill(bands, context);
-    for (const auto& layer : albedo.layers) {
-        layer->Apply(bands, context);
+    for (std::size_t n = 0; n < albedo.layers.size(); ++n) {
+        const Stopwatch stopwatch;
+        albedo.layers[n]->Apply(bands, context);
+        LogDebug("albedo", "Applied albedo layer ", n + 1, " in ",
+                 FormatDuration(stopwatch.Milliseconds()));
     }
     return bands;
 }

terraingenpy-0.1.1.dev20/terraingen/albedo/rock_albedo.cpp

@@ -0,0 +1,134 @@
+#include "terraingen/albedo/rock_albedo.h"
+
+#include "terraingen/random/philox.h"
+#include "terraingen/random/value_distribution.h"
+#include "terraingen/util/parallel.h"
+
+#include <algorithm>
+#include <bit>
+#include <cmath>
+#include <stdexcept>
+#include <utility>
+
+namespace terraingen {
+
+namespace {
+
+constexpr std::uint32_t kRockStream = 0x524F434Bu;
+
+/// Multiplies every band of `value` by 1 + `share` (`ratio` - 1); NaN stays NaN.
+void Brighten(AlbedoSample& value, std::size_t bands, double share, double ratio) {
+    if (share == 0.0) {
+        return;
+    }
+    const double factor = 1.0 + share * (ratio - 1.0);
+    for (std::size_t band = 0; band < bands; ++band) {
+        if (!std::isnan(value[band])) {
+            value[band] = static_cast<float>(factor * static_cast<double>(value[band]));
+        }
+    }
+}
+
+}  // namespace
+
+void ValidateRockAlbedo(const RockAlbedoOptions& options) {
+    if (!(options.reflectanceRatio > 0.0 && std::isfinite(options.reflectanceRatio))) {
+        throw std::invalid_argument("Rock reflectance ratio must be positive and finite");
+    }
+}
+
+double RockShare(double resolved, const UnresolvedCover& unresolved, double normal) {
+    double drawn = 0.0;
+    if (unresolved.mean > 0.0) {
+        const double s2 = std::log1p(unresolved.variance / (unresolved.mean * unresolved.mean));
+        drawn =
+            std::fmin(1.0, std::exp(std::log(unresolved.mean) - 0.5 * s2 + std::sqrt(s2) * normal));
+    }
+    const double kept = std::clamp(resolved, 0.0, 1.0);
+    return kept + (1.0 - kept) * drawn;
+}
+
+RockAlbedo::RockAlbedo(RockAlbedoOptions options, std::vector<RockSource> sources)
+    : options_(options), sources_(std::move(sources)) {
+    ValidateRockAlbedo(options_);
+    for (const RockSource& source : sources_) {
+        if (!source.layer || !source.ground) {
+            throw std::invalid_argument(
+                "A rock albedo source needs a boulder layer and its ground");
+        }
+    }
+}
+
+double RockAlbedo::Draw(double x, double y, std::size_t source) const {
+    const auto xs = std::bit_cast<std::uint64_t>(x);
+    const auto ys = std::bit_cast<std::uint64_t>(y);
+    const U32x4 bits =
+        Philox4x32({static_cast<std::uint32_t>(xs), static_cast<std::uint32_t>(xs >> 32),
+                    static_cast<std::uint32_t>(ys), static_cast<std::uint32_t>(ys >> 32)},
+                   {options_.seed ^ kRockStream, static_cast<std::uint32_t>(source)});
+    return StandardNormal(std::ldexp(static_cast<double>(bits.x), -32),
+                          std::ldexp(static_cast<double>(bits.y), -32));
+}
+
+double RockAlbedo::ShareAt(double x, double y, const AlbedoContext& context) const {
+    ValidateAlbedoContext(context);
+    double bare = 1.0;
+    for (std::size_t n = 0; n < sources_.size(); ++n) {
+        const RockSource& source = sources_[n];
+        const double resolved =
+            source.layer->MaterialCoverAt(x, y, context.spacing, source.ground.get());
+        const UnresolvedCover unresolved =
+            options_.unresolved
+                ? source.layer->UnresolvedCoverAt(x, y, context.spacing, source.ground.get())
+                : UnresolvedCover{};
+        bare *= 1.0 - RockShare(resolved, unresolved, options_.unresolved ? Draw(x, y, n) : 0.0);
+    }
+    return 1.0 - bare;
+}
+
+void RockAlbedo::ApplyAt(AlbedoSample& value, std::size_t bands, double x, double y,
+                         const AlbedoContext& context) const {
+    Brighten(value, bands, ShareAt(x, y, context), options_.reflectanceRatio);
+}
+
+void RockAlbedo::Apply(std::vector<Raster<float>>& bands, const AlbedoContext& context) const {
+    ValidateAlbedoContext(context);
+    if (bands.empty() || sources_.empty()) {
+        return;
+    }
+    const RasterGrid grid = RasterGrid::FromRaster(bands[0]);
+    std::vector<double> bare(grid.width * grid.height, 1.0);
+    for (std::size_t n = 0; n < sources_.size(); ++n) {
+        const RockSource& source = sources_[n];
+        const Raster<double> resolved = source.layer->MaterialCoverOver(
+            grid, context.spacing, source.ground.get(), context.threads);
+        const std::vector<UnresolvedCover> unresolved =
+            options_.unresolved ? source.layer->UnresolvedCoverOver(
+                                      grid, context.spacing, source.ground.get(), context.threads)
+                                : std::vector<UnresolvedCover>(bare.size());
+        ParallelFor(grid.height, context.threads, [&](std::size_t row) {
+            for (std::size_t col = 0; col < grid.width; ++col) {
+                const std::size_t cell = row * grid.width + col;
+                const Vec2d centre = bands[0].CellCenter(col, row);
+                bare[cell] *=
+                    1.0 - RockShare(resolved(col, row), unresolved[cell],
+                                    options_.unresolved ? Draw(centre.x, centre.y, n) : 0.0);
+            }
+        });
+    }
+    ParallelFor(grid.height, context.threads, [&](std::size_t row) {
+        for (std::size_t col = 0; col < grid.width; ++col) {
+            AlbedoSample value{};
+            for (std::size_t band = 0; band < bands.size(); ++band) {
+                value[band] = bands[band](col, row);
+            }
+            Brighten(value, bands.size(), 1.0 - bare[row * grid.width + col],
+                     options_.reflectanceRatio);
+            for (std::size_t band = 0; band < bands.size(); ++band) {
+                bands[band](col, row) = value[band];
+            }
+        }
+    });
+}
+
+}  // namespace terraingen

terraingenpy-0.1.1.dev20/terraingen/albedo/rock_albedo.h

@@ -0,0 +1,72 @@
+/// @file
+/// @brief Rock albedo: boulders and the rocks too small to resolve, brighter than the regolith.
+#pragma once
+
+#include "terraingen/albedo/albedo.h"
+#include "terraingen/layers/boulders/boulder_layer.h"
+
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+namespace terraingen {
+
+/// How rocks brighten the albedo. Rock reflects more than mature regolith: Holt (1981) measured
+/// normal albedos of 18 to 51% for rocks at the Apollo 16 site against 14 to 15% for its most
+/// mature soils; Marshal et al. (2023) model rock about 2.5 times as reflective as regolith,
+/// within the near 3 times of Apollo 16 fragmental breccias (Clark et al. 2002), and earlier
+/// models took about 1.5 times. Boulders an albedo resolves brighten where their rock stands;
+/// smaller ones brighten each sample by the share of it they cover, drawn per sample about its
+/// expected share with the variance of Poisson-scattered rocks, which unresolved cobbles show as
+/// bright pixels (Marshal et al. 2023).
+struct RockAlbedoOptions {
+    std::uint32_t seed = 0;         ///< Seed of the per-sample draws of unresolved rock.
+    double reflectanceRatio = 2.5;  ///< Rock over regolith reflectance; positive.
+    bool unresolved = true;         ///< Whether rocks too small to resolve brighten samples.
+
+    bool operator==(const RockAlbedoOptions&) const = default;
+};
+
+/// Checks rock albedo options.
+/// @throws std::invalid_argument for a reflectance ratio that is not positive and finite.
+void ValidateRockAlbedo(const RockAlbedoOptions& options);
+
+/// A boulder layer whose rock brightens the albedo, and the ground beneath it.
+struct RockSource {
+    std::shared_ptr<const BoulderLayer> layer;
+    /// The ground the layer was applied to, read under its boulders; must not be null.
+    std::shared_ptr<const Ground> ground;
+};
+
+/// The share of a sample rock covers, from the share its resolved boulders cover and a draw
+/// `normal` (standard normal) of the share unresolved rock covers of the rest: log-normal with
+/// the mean and variance of `unresolved`, at most 1.
+double RockShare(double resolved, const UnresolvedCover& unresolved, double normal);
+
+/// The albedo brightened by the rock of boulder layers: each band times 1 + `share`
+/// (`reflectanceRatio` - 1), for the share of each sample rock covers over every layer.
+class RockAlbedo final : public AlbedoLayer {
+  public:
+    /// @throws std::invalid_argument for options invalid as `ValidateRockAlbedo`, or a source
+    /// without a layer or ground.
+    RockAlbedo(RockAlbedoOptions options, std::vector<RockSource> sources);
+
+    /// Brightens `value` by the rock at (`x`, `y`); NaN stays NaN.
+    void ApplyAt(AlbedoSample& value, std::size_t bands, double x, double y,
+                 const AlbedoContext& context) const override;
+
+    /// `ApplyAt` at every cell centre, the boulders found once per layer.
+    void Apply(std::vector<Raster<float>>& bands, const AlbedoContext& context) const override;
+
+    /// The share of the sample at (`x`, `y`) rock covers, over every layer.
+    double ShareAt(double x, double y, const AlbedoContext& context) const;
+
+  private:
+    /// The standard normal drawn for unresolved rock of source `source` at (`x`, `y`).
+    double Draw(double x, double y, std::size_t source) const;
+
+    RockAlbedoOptions options_;
+    std::vector<RockSource> sources_;
+};
+
+}  // namespace terraingen