terraingenpy 0.1.1.dev13__tar.gz → 0.1.1.dev17__tar.gz

terraingenpy-0.1.1.dev17/CHANGELOG.md

@@ -0,0 +1,53 @@
+# 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.
+
+### 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.
+- 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.dev17}/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.dev17")
 string(REGEX MATCH "^[0-9]+\\.[0-9]+\\.[0-9]+" TERRAINGEN_VERSION "${TERRAINGEN_FULL_VERSION}")
 
 project(

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: terraingenpy
-Version: 0.1.1.dev13
+Version: 0.1.1.dev17
 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.dev17}/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.dev17/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.dev17/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.dev17}/terraingen/config/build.cpp

@@ -462,6 +462,14 @@ BoulderLayerOptions BuildBoulderOptions(const BoulderLayerSpec& spec, const std:
         options.densityMap =
             BuildDensityMap(*spec.densityMap, Child(path, "density_map"), directory);
     }
+    if (spec.slopeMap) {
+        const SizeSlopeMapSpec& s = *spec.slopeMap;
+        const std::string at = Child(path, "slope_map");
+        options.slopeMap =
+            SizeSlopeMap{BuildField(s.field, Child(at, "field"), directory), s.measure,
+                         s.referenceDiameter, s.minExponent, s.maxExponent};
+        At(at, [&] { ValidateSizeSlopeMap(*options.slopeMap); });
+    }
     for (Crater boulder : spec.manual) {
         boulder.manual = true;
         options.manual.push_back(boulder);

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/config/config.h

@@ -102,6 +102,17 @@ struct DensityMapSpec {
     bool operator==(const DensityMapSpec&) const = default;
 };
 
+/// A size slope map (`SizeSlopeMap`) of a boulder population.
+struct SizeSlopeMapSpec {
+    FieldSpec field{};
+    SizeSlopeMeasure measure = SizeSlopeMeasure::Exponent;
+    double referenceDiameter = 1.0;  ///< Metres.
+    double minExponent = 1.0;
+    double maxExponent = 6.0;
+
+    bool operator==(const SizeSlopeMapSpec&) const = default;
+};
+
 struct ChainSourceSpec;
 
 /// The starting heights of a terrain, its base, named in JSON by its "type".
@@ -273,7 +284,7 @@ using SimpleProfileSpec = std::variant<FassettThomsonSpec, MartinParkesDunstanSp
 /// morphometry, and complex craters, with flat floors and central peaks, from it
 /// (`ComplexCraterProfile` with `LunarComplexCraterShape` or `MarsComplexCraterShape`).
 struct ComplexProfileSpec {
-    SimpleProfileSpec simple{};
+    SimpleProfileSpec simple{MartinParkesDunstanSpec{}};
     bool operator==(const ComplexProfileSpec&) const = default;
 };
 /// A crater profile, named in JSON by its "type".
@@ -299,7 +310,7 @@ struct CraterLayerSpec {
     std::size_t maxCraters = 0;  ///< Keep at most this many generated craters; 0 keeps all.
     /// Manual craters, in the surface's coordinates; parsing sets their `manual` flag.
     std::vector<Crater> manual{};
-    ProfileSpec profile{};
+    ProfileSpec profile{MartinParkesDunstanSpec{}};
     DegradationSpec degradation{};
     CraterApplyOptions apply{};
     std::optional<DensityMapSpec> densityMap{};  ///< Gives `CraterLayerOptions::densityMap`.
@@ -348,6 +359,7 @@ struct BoulderLayerSpec {
     /// `BoulderShapeOptions::library`; relative to the configuration's folder.
     std::vector<std::string> shapeFiles{};
     std::optional<DensityMapSpec> densityMap{};  ///< Gives `boulders.densityMap`.
+    std::optional<SizeSlopeMapSpec> slopeMap{};  ///< Gives `boulders.slopeMap`.
     /// Catalog boulders in the surface's coordinates, as `boulders.manual`.
     std::vector<Crater> manual{};
     std::optional<FieldSpec> completeness{};  ///< Gives `boulders.completeness`.

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/config/fields/boulders.h

@@ -414,6 +414,11 @@ template <typename IO> void Fields(IO& io, BoulderLayerSpec& spec) {
        "Steepest ground, across a boulder's diameter, that boulders stay on, in radians; steeper "
        "ground has none, models and drawn boulders alike. Unset keeps boulders on any slope.",
        "rad", Inside(0.0, 0.5 * std::numbers::pi));
+    io("roll_distance", pose.rollDistance,
+       "With max_slope, boulders on steeper ground roll down it and rest where it is gentle "
+       "enough, gathering at the foot of slopes; those that would roll farther than this many "
+       "metres are left out. Unset leaves out every boulder on steeper ground.",
+       "m", Above(0.0));
     io("burial_by_wear", pose.burialByWear,
        "How far wear sets burial, from 0 to 1: blocks of fresh craters sit near the smallest "
        "burial and those of worn ones sink toward the largest, while boulders between craters "
@@ -444,6 +449,10 @@ template <typename IO> void Fields(IO& io, BoulderLayerSpec& spec) {
     io("density_map", spec.densityMap,
        "Map that sets the abundance of boulders between craters point by point, scaling the "
        "sizes to what it measures; unset keeps the abundance the sizes set everywhere.");
+    io("slope_map", spec.slopeMap,
+       "Map of how steeply boulder counts fall with size, such as a mean diameter map, bending the "
+       "sizes into a local power law through their count at its reference diameter; needs a size "
+       "distribution. Unset keeps the sizes' shape everywhere.");
     io("manual", spec.manual,
        "Catalog boulders placed as given and never thinned or left out; x, y and diameter are "
        "read.");

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/config/fields/craters.h

@@ -218,7 +218,7 @@ template <typename IO> void Fields(IO& io, CraterTexture& texture) {
 
 template <typename IO> void Fields(IO& io, CraterSlopeResponse& slope) {
     io("enabled", slope.enabled,
-       "Shapes craters on sloping ground asymmetrically, as their datum plane slopes; off keeps "
+       "Shapes craters asymmetrically along the slope of the ground beneath the layer; off keeps "
        "them the same on any slope.");
     io("seed", slope.seed, "Varies how far each crater's floor is offset.");
     io("floor_offset", slope.floorOffset,
@@ -232,6 +232,14 @@ template <typename IO> void Fields(IO& io, CraterSlopeResponse& slope) {
        "Slope at which the asymmetry is complete, in radians; it rises from none on level "
        "ground.",
        "rad", Above(0.0));
+    io("critical_gradient", slope.criticalGradient,
+       "Critical gradient Sc, rise over run, toward which downslope transport grows without bound: "
+       "a crater on a regional gradient S wears 1 / (1 - (S / Sc)^2) times as fast (Roering et al. "
+       "1999). Unset wears craters alike on any slope; no lunar value is published.",
+       "", Above(0.0));
+    io("max_wear_rate", slope.maxWearRate,
+       "Fastest a slope makes craters wear, over level ground: a numerical cap as S nears Sc.", "",
+       AtLeast(1.0));
 }
 
 template <typename IO> void Fields(IO& io, CraterApplyOptions& apply) {

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/config/fields/enums.h

@@ -344,6 +344,16 @@ template <> struct EnumNames<DensityMeasure> {
     }};
 };
 
+template <> struct EnumNames<SizeSlopeMeasure> {
+    static constexpr std::array<EnumEntry<SizeSlopeMeasure>, 2> kValues{{
+        {"exponent", SizeSlopeMeasure::Exponent,
+         "The cumulative exponent alpha, counts falling as D^-alpha."},
+        {"mean_diameter", SizeSlopeMeasure::MeanDiameter,
+         "The mean diameter in metres of the features from the reference diameter up, from which "
+         "alpha = mean / (mean - D0)."},
+    }};
+};
+
 template <> struct EnumNames<TiffCompression> {
     static constexpr std::array<EnumEntry<TiffCompression>, 4> kValues{{
         {"none", TiffCompression::None, "Uncompressed: the largest files."},

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/config/fields/maps.h

@@ -43,4 +43,20 @@ template <typename IO> void Fields(IO& io, DensityMapSpec& map) {
        "of it first; off when it counts only what the layer generates.");
 }
 
+template <typename IO> void Fields(IO& io, SizeSlopeMapSpec& map) {
+    io("field", map.field, "The map.");
+    io("measure", map.measure, "What the map's values measure.");
+    io("reference_diameter", map.referenceDiameter,
+       "Diameter D0 in metres where the local power law meets the layer's own count, as N(>=D) = "
+       "N(>=D0) (D / D0)^-alpha; for a mean diameter map, the smallest diameter averaged.",
+       "m", Above(0.0));
+    io("min_exponent", map.minExponent,
+       "Smallest exponent alpha the map's values are clamped to; with the largest it bounds the "
+       "boulders drawn, so generous bounds draw more to thin.",
+       "", Above(0.0));
+    io("max_exponent", map.maxExponent,
+       "Largest exponent alpha the map's values are clamped to; above the smallest.", "",
+       Above(0.0));
+}
+
 }  // namespace terraingen::config

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/layers/boulders/abundance.cpp

@@ -242,6 +242,9 @@ BoulderAbundance BoulderLayer::Abundance(double x, double y, const Ground* groun
         EjectaAbundance(x, y, ejecta, abundance);
     }
     abundance.background = BackgroundAbundance(x, y, ground, abundance.ejecta);
+    if (options_.slopeMap) {
+        abundance.exponent = SizeSlopeAt(*options_.slopeMap, x, y);
+    }
     return abundance;
 }
 
@@ -251,10 +254,18 @@ BoulderAbundance BoulderLayer::AbundanceAt(double x, double y, const Ground* gro
 
 double BoulderLayer::Density(double diameter, const BoulderAbundance& abundance) const {
     const BoulderSizes& sizes = options_.sizes;
-    double density = sizes.distribution
-                         ? abundance.background * sizes.distribution->Incremental(diameter)
-                         : GolombekRappDensity(diameter, sizes.coverage * abundance.background,
-                                               sizes.qConstant, sizes.qCoverageCoefficient);
+    double density = 0.0;
+    if (abundance.exponent) {
+        const double alpha = *abundance.exponent;
+        const double d0 = options_.slopeMap->referenceDiameter;
+        density = abundance.background * referenceCount_ * alpha * std::pow(d0, alpha) *
+                  std::pow(diameter, -alpha - 1.0);
+    } else {
+        density = sizes.distribution
+                      ? abundance.background * sizes.distribution->Incremental(diameter)
+                      : GolombekRappDensity(diameter, sizes.coverage * abundance.background,
+                                            sizes.qConstant, sizes.qCoverageCoefficient);
+    }
     if (abundance.ejecta > 0.0) {
         density += abundance.ejecta * ejectaSizes_->Incremental(diameter);
     }

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/layers/boulders/boulder_layer.cpp

@@ -137,6 +137,10 @@ BoulderLayer::BoulderLayer(BoulderLayerOptions options, std::shared_ptr<const Cr
         mapAbundance_.emplace(options_);
         patchMean_ = MeanPatchAbundance(options_.patches);
     }
+    if (options_.slopeMap) {
+        referenceCount_ =
+            options_.sizes.distribution->Cumulative(options_.slopeMap->referenceDiameter);
+    }
     if (options_.clusters.share > 0.0) {
         clusterMean_ = options_.clusters.model == BoulderClusterModel::Thomas
                            ? MeanThomasField(options_.clusters, surface_.IsBody())
@@ -402,11 +406,8 @@ std::optional<Boulder> BoulderLayer::DrawBoulder(const Crater& candidate, double
                     candidate.id};
     boulder.wear = wear;
     boulder.model = options_.rendering.models.IsModel(boulder.diameter, spacing);
-    if (pose.maxSlope && ground != nullptr && !candidate.manual) {
-        const std::optional<Vec2d> g = GroundGradient(boulder, *ground);
-        if (g && std::hypot(g->x, g->y) > std::tan(*pose.maxSlope)) {
-            return std::nullopt;
-        }
+    if (pose.maxSlope && ground != nullptr && !candidate.manual && !Roll(boulder, *ground)) {
+        return std::nullopt;
     }
     if (ground != nullptr) {
         const double height =
@@ -475,6 +476,30 @@ BoulderShape BoulderLayer::Abraded(const BoulderShape& shape, const BoulderPlace
     return cut;
 }
 
+bool BoulderLayer::Roll(Boulder& boulder, const Ground& ground) const {
+    constexpr double kMaxSteps = 128.0;
+    const BoulderPose& pose = options_.pose;
+    const double limit = std::tan(*pose.maxSlope);
+    const double reach = pose.rollDistance.value_or(0.0);
+    const double step = std::fmax(boulder.diameter, reach / kMaxSteps);
+    double rolled = 0.0;
+    for (;;) {
+        const std::optional<Vec2d> g = GroundGradient(boulder, ground);
+        const double gradient = g ? std::hypot(g->x, g->y) : 0.0;
+        if (!(gradient > limit)) {
+            return true;
+        }
+        if (rolled + step > reach) {
+            return false;
+        }
+        const Vec2d to = surface_.Locate({boulder.x, boulder.y},
+                                         {-g->x / gradient * step, -g->y / gradient * step});
+        boulder.x = to.x;
+        boulder.y = to.y;
+        rolled += step;
+    }
+}
+
 std::optional<Vec2d> BoulderLayer::GroundGradient(const Boulder& boulder,
                                                   const Ground& ground) const {
     const double step = 0.5 * boulder.diameter;
@@ -521,20 +546,28 @@ std::vector<Boulder> BoulderLayer::Boulders(const Bounds2d& region, double spaci
     if (exposure_) {
         RequireGround(ground, "Boulders that read the exposure field");
     }
-    const CraterList candidates = ScatterBoulderCandidates(region, spacing);
+    const double roll = ground != nullptr ? options_.pose.rollDistance.value_or(0.0) : 0.0;
+    const Bounds2d from = roll > 0.0 ? surface_.Expand(region, roll) : region;
+    const auto rests = [&](const Boulder& boulder) {
+        const double own = 0.5 * boulder.diameter * OwnMarginRadii();
+        return roll == 0.0 ||
+               surface_.Contains(surface_.Expand(region, own), {boulder.x, boulder.y});
+    };
+    const CraterList candidates = ScatterBoulderCandidates(from, spacing);
     if (!options_.fragmentation.Enabled()) {
-        const CraterList ejecta = EjectaCraters(region);
+        const CraterList ejecta = EjectaCraters(from);
         std::vector<Boulder> boulders;
         for (std::size_t n = 0; n < candidates.Size(); ++n) {
-            if (const std::optional<Boulder> boulder =
-                    DrawBoulder(candidates.At(n), spacing, ground, ejecta)) {
+            const std::optional<Boulder> boulder =
+                DrawBoulder(candidates.At(n), spacing, ground, ejecta);
+            if (boulder && rests(*boulder)) {
                 boulders.push_back(*boulder);
             }
         }
         return boulders;
     }
     const double reach = 0.5 * options_.sizes.maxDiameter * (OwnMarginRadii() + BreakMarginRadii());
-    const CraterList ejecta = EjectaCraters(surface_.Expand(region, reach));
+    const CraterList ejecta = EjectaCraters(surface_.Expand(from, reach));
     std::vector<Boulder> boulders;
     for (std::size_t n = 0; n < candidates.Size(); ++n) {
         const std::optional<Boulder> parent =

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/layers/boulders/boulder_layer.h

@@ -30,6 +30,8 @@ struct BoulderAbundance {
     double ejecta = 0.0;
     /// Wear of the crater the ejecta share comes from, from 0 (fresh) to 1 (its blocks gone).
     double ejectaWear = 0.0;
+    /// The size exponent a size slope map gives here (`SizeSlopeAt`); none keeps the sizes' shape.
+    std::optional<double> exponent;
 
     bool operator==(const BoulderAbundance&) const = default;
 };
@@ -126,6 +128,9 @@ class BoulderLayer final : public Layer, public BoulderPlacer, public MaterialSo
     /// The rise east and north (m/m) of `ground` across `boulder`'s diameter; none where the
     /// ground is missing.
     std::optional<Vec2d> GroundGradient(const Boulder& boulder, const Ground& ground) const;
+    /// Rolls `boulder` down ground steeper than `maxSlope` until it rests, as `rollDistance`
+    /// allows; false when it would roll farther, or with no roll distance on steep ground.
+    bool Roll(Boulder& boulder, const Ground& ground) const;
     /// The pieces `parent` breaks into at its wear, those resolved at `spacing`; `parent` alone
     /// when it is too small or too fresh to break.
     std::vector<Boulder> Break(const Boulder& parent, double spacing, const Ground* ground) const;
@@ -212,6 +217,7 @@ class BoulderLayer final : public Layer, public BoulderPlacer, public MaterialSo
     double minCraterDiameter_ = 0.0;
     double maxBackground_ = 1.0;
     double clusterMean_ = 1.0;
+    double referenceCount_ = 0.0;  ///< N(>=D0) of the sizes at a size slope map's D0, per m^2.
     std::optional<BoulderMapAbundance> mapAbundance_;
     double patchMean_ = 1.0;  ///< Under a map, what the patches are divided by.
     Vec2d meanOrigin_{};      ///< Corner of the bedrock mean lattice, in surface units.

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/layers/boulders/boulder_options.cpp

@@ -1,6 +1,7 @@
 #include "terraingen/layers/boulders/boulder_options.h"
 
 #include "terraingen/distribution/golombek_rapp.h"
+#include "terraingen/distribution/power_law.h"
 #include "terraingen/distribution/summed.h"
 #include "terraingen/noise/worley.h"
 #include "terraingen/util/checks.h"
@@ -149,6 +150,11 @@ void ValidateBoulderPose(const BoulderPose& pose) {
     if (pose.maxSlope && !(*pose.maxSlope > 0.0 && *pose.maxSlope < 0.5 * std::numbers::pi)) {
         throw std::invalid_argument("Boulder maxSlope must be in (0, pi / 2)");
     }
+    if (pose.rollDistance &&
+        !(pose.maxSlope && *pose.rollDistance > 0.0 && std::isfinite(*pose.rollDistance))) {
+        throw std::invalid_argument("Boulder rollDistance must be positive and finite, with a "
+                                    "maxSlope");
+    }
 }
 
 void ValidateBoulderFillet(const BoulderFillet& fillet) {
@@ -312,6 +318,13 @@ void ValidateBoulderLayerOptions(const BoulderLayerOptions& options) {
     if (options.densityMap) {
         ValidateDensityMap(*options.densityMap);
     }
+    if (options.slopeMap) {
+        ValidateSizeSlopeMap(*options.slopeMap);
+        if (!options.sizes.distribution) {
+            throw std::invalid_argument(
+                "A boulder size slope map needs a size distribution, not Golombek-Rapp sizes");
+        }
+    }
     ValidateBoulderPatches(options.patches);
     ValidateBoulderClusters(options.clusters);
     ValidateBoulderFragmentation(options.fragmentation);
@@ -458,6 +471,16 @@ BoulderCandidates(const BoulderLayerOptions& options) {
     std::vector<WeightedSfd> terms;
     if (sizes.distribution) {
         terms.push_back({richest, sizes.distribution});
+        if (options.slopeMap) {
+            const SizeSlopeMap& map = *options.slopeMap;
+            const double d0 = map.referenceDiameter;
+            const double count = richest * sizes.distribution->Cumulative(d0);
+            const double low = map.minExponent;
+            const double high = map.maxExponent;
+            terms.push_back(
+                {1.0, std::make_shared<PowerLawSfd>(count * std::pow(d0, low) * high / low, low)});
+            terms.push_back({1.0, std::make_shared<PowerLawSfd>(count * std::pow(d0, high), high)});
+        }
     } else {
         terms.push_back(
             {1.0, std::make_shared<GolombekRappSfd>(sizes.coverage * richest, sizes.qConstant,

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/layers/boulders/boulder_options.h

@@ -224,6 +224,11 @@ struct BoulderPose {
     /// so which boulders exist does not depend on the spacing. Unset keeps boulders on any slope;
     /// needs the ground.
     std::optional<double> maxSlope{};
+    /// With `maxSlope`, boulders on steeper ground roll down it instead, in steps along the
+    /// steepest descent, and come to rest where it is no steeper than `maxSlope`, gathering at the
+    /// foot of slopes; those that would roll farther than this many metres are left out. Unset
+    /// leaves out every boulder on steeper ground.
+    std::optional<double> rollDistance{};
 
     bool operator==(const BoulderPose&) const = default;
 };
@@ -325,6 +330,11 @@ struct BoulderLayerOptions {
     /// it measures first. Patches, clusters and bedrock still spread boulders within it. Unset
     /// keeps the abundance `sizes` sets everywhere.
     std::optional<DensityMap> densityMap{};
+    /// A map of how steeply boulder counts fall with size (`SizeSlopeMap`), such as a mean
+    /// diameter map, bending the sizes between craters into a local power law through their count
+    /// at its reference diameter; needs a size distribution rather than Golombek-Rapp sizes. Unset
+    /// keeps the sizes' own shape everywhere.
+    std::optional<SizeSlopeMap> slopeMap{};
     /// Boulders from a catalog, placed as given and never thinned or left out; `x`, `y` and
     /// `diameter` are read, and IDs come from position and size (`AppendManualCraters`).
     std::vector<Crater> manual{};
@@ -458,7 +468,8 @@ double MaxBackgroundAbundance(const BoulderLayerOptions& options);
 std::shared_ptr<const SizeFrequencyDistribution> EjectaSizes(const BoulderLayerOptions& options);
 
 /// The distribution per m^2 candidate boulders are drawn from before thinning: the boulders
-/// between craters at their richest plus fresh crater blocks when enabled.
+/// between craters at their richest, with a size slope map the power laws at its bounding
+/// exponents too, plus fresh crater blocks when enabled.
 /// @throws std::invalid_argument as `ValidateBoulderLayerOptions`.
 std::shared_ptr<const SizeFrequencyDistribution>
 BoulderCandidates(const BoulderLayerOptions& options);

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/layers/craters/crater_layer.cpp

@@ -82,6 +82,7 @@ CraterLayer::CraterLayer(CraterModels models, CraterLayerOptions options)
         throw std::invalid_argument("Taking secondaries out of a density map needs every crater, "
                                     "not the maxCraters largest");
     }
+    options_.generation.spacing.outrankFrom = throwFrom_;
 }
 
 CraterKeepShare CraterLayer::KeepShare(const Bounds2d& region) const {

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/layers/craters/crater_layer.h

@@ -56,7 +56,8 @@ struct CraterLayerOptions {
     /// The secondaries `SecondaryCraterLayer`s throw from these craters. A `total` count or areal
     /// fraction map counts them too, so craters too small to throw secondaries the map measures
     /// are drawn at the map less those secondaries' density there; larger craters, which throw
-    /// them, follow the map alone. Not with `generation.maxCraters`.
+    /// them, follow the map alone; with spacing they also take precedence over smaller craters, so
+    /// the throwers never depend on what they throw at. Not with `generation.maxCraters`.
     std::vector<SecondaryCraterOptions> secondaries{};
 };
 

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/layers/craters/degradation/degradation_model.cpp

@@ -8,6 +8,12 @@
 
 namespace terraingen {
 
+CraterState DegradationModel::WornState(const Crater& crater, double rate) const {
+    Crater older = crater;
+    older.ageGyr *= rate;
+    return State(older);
+}
+
 NoDegradation::NoDegradation(FreshMorphometry fresh, std::optional<double> depthRatio)
     : fresh_(std::move(fresh)), depthRatio_(depthRatio) {
     if (!fresh_) {

{terraingenpy-0.1.1.dev13 → terraingenpy-0.1.1.dev17}/terraingen/layers/craters/degradation/degradation_model.h

@@ -18,6 +18,13 @@ class DegradationModel {
     /// @throws std::domain_error if the crater's diameter is not positive and finite, or the model
     /// is not defined for it.
     virtual CraterState State(const Crater& crater) const = 0;
+
+    /// The crater's state had it worn `rate` times as fast as on level ground, as on a steep
+    /// regional slope. By default it is `State` of the crater `rate` times older, which suits
+    /// models whose wear follows age alone.
+    /// @param rate At least 1.
+    /// @throws std::domain_error as `State`.
+    virtual CraterState WornState(const Crater& crater, double rate) const;
 };
 
 /// Every crater stays as `fresh` makes it, optionally with one depth/diameter ratio for all.