terraingenpy 0.1.1.dev82__tar.gz → 0.1.1.dev91__tar.gz

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/CHANGELOG.md

@@ -23,10 +23,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
+- 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.

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/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.dev82")
+set(TERRAINGEN_FULL_VERSION "0.1.1.dev91")
 string(REGEX MATCH "^[0-9]+\\.[0-9]+\\.[0-9]+" TERRAINGEN_VERSION "${TERRAINGEN_FULL_VERSION}")
 
 project(

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: terraingenpy
-Version: 0.1.1.dev82
+Version: 0.1.1.dev91
 Summary: Scientific terrain generation for planetary surfaces
 Keywords: terrain,moon,mars,craters,planetary science,simulation
 Author: Alex Maietta

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/examples/config/boulders/example_boulders_max_slope.json

@@ -21,7 +21,7 @@
             },
             "min_diameter": 0.2,
             "max_diameter": 3,
-            "max_slope_deg": 20.05352282957881
+            "max_slope_deg": 20.0
         }
     ],
     "outputs": [

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/examples/config/boulders/example_boulders_rolling.json

@@ -21,7 +21,7 @@
             },
             "min_diameter": 0.2,
             "max_diameter": 3,
-            "max_slope_deg": 20.05352282957881,
+            "max_slope_deg": 20.0,
             "roll_distance": 15
         }
     ],

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/examples/config/boulders/example_boulders_shapes.json

@@ -25,7 +25,7 @@
             "max_height_ratio": 0.9,
             "min_burial": 0.0,
             "max_burial": 0.1,
-            "max_lean_deg": 28.64788975654116,
+            "max_lean_deg": 30.0,
             "relief": "shape",
             "models": {
                 "min_diameter": 0.6

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/examples/config/planets/example_planets_mars_pavement.json

@@ -18,7 +18,7 @@
             "crack_width": 0.04,
             "crack_depth": 0.08,
             "edge_rounding": 0.02,
-            "max_tilt_deg": 3.437746770784939,
+            "max_tilt_deg": 3.5,
             "max_step": 0.04,
             "octaves": 3,
             "gain": 0.55,

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/examples/config/planets/example_planets_mars_sand_shadows.json

@@ -24,7 +24,7 @@
         },
         {
             "type": "sand_shadow",
-            "wind_azimuth_deg": 28.64788975654116,
+            "wind_azimuth_deg": 30.0,
             "length_ratio": 2.0
         }
     ],

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/examples/config/planets/example_planets_mars_strata.json

@@ -16,8 +16,8 @@
             "type": "strata",
             "bed_thickness": 4,
             "thickness_variation": 0.5,
-            "dip_deg": 1.7188733853924696,
-            "dip_azimuth_deg": 45.83662361046586,
+            "dip_deg": 1.5,
+            "dip_azimuth_deg": 45.0,
             "sharpness": 5,
             "cliff_share": 0.3
         },

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/examples/config/planets/example_planets_mars_ventifacts.json

@@ -24,8 +24,8 @@
             "relief": "shape",
             "ventifacts": {
                 "share": 0.39,
-                "wind_azimuth_deg": 45.83662361046586,
-                "second_wind_azimuth_deg": 246.371851906254,
+                "wind_azimuth_deg": 45.0,
+                "second_wind_azimuth_deg": 245.0,
                 "keel_share": 0.31
             }
         }

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/examples/python/albedo/example_albedo_options.py

@@ -1,6 +1,6 @@
 """Albedo options: colour, maps with detail, and how bright crater material behaves.
 
-- `SyntheticAlbedo(rgb=True, hue, saturation, ...)` gives three bands from a colour and its noise.
+- `SyntheticAlbedo(rgb=True, hue_deg, saturation, ...)` gives three bands from a colour and its noise.
 - `RasterAlbedo` interpolates an albedo map and adds sub-cell detail carrying the map's measured
   roughness down (`AlbedoDetail`).
 - `CraterAlbedoOptions` sets how much brighter fresh craters, their ejecta and their rays are, how
@@ -37,7 +37,12 @@ class Example(_common.Example):
             terraingen.FractalParams(seed=6, wavelength=600.0, amplitude=0.04, octaves=6)
         )
         colour = terraingen.SyntheticAlbedo(
-            rgb=True, hue=30.0, saturation=0.12, value=0.14, hue_noise=[hue_noise], value_noise=[value_noise]
+            rgb=True,
+            hue_deg=30.0,
+            saturation=0.12,
+            value=0.14,
+            hue_noise_deg=[hue_noise],
+            value_noise=[value_noise],
         )
         self.rgb = np.stack(
             [band.values for band in terraingen.evaluate_albedo(terraingen.Albedo(colour), grid)], axis=-1

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/examples/python/boulders/example_boulders_positioning.py

@@ -56,7 +56,7 @@ class Example(_common.Example):
                 max_height_ratio=1.0,
                 min_burial=0.0,
                 max_burial=0.05,
-                max_lean_deg=34.37746770784939,
+                max_lean_deg=35.0,
                 relief=terraingen.BoulderRelief.SHAPE,
                 models=terraingen.BoulderModelThreshold(min_diameter=0.8),
             ),

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/examples/python/craters/example_craters_irregularity.py

@@ -51,8 +51,8 @@ class Example(_common.Example):
                 roughness=terraingen.ValueDistribution(a=0.0),
                 elongated_share=0.6,
                 ellipticity=terraingen.ValueDistribution(uniform, 1.3, 1.8),
-                heading_deg=28.64788975654116,
-                heading_spread_deg=11.459155902616466,
+                heading_deg=30.0,
+                heading_spread_deg=10.0,
             ),
             "both": terraingen.CraterIrregularity(
                 enabled=True,

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/terraingen/config/build.cpp

@@ -324,6 +324,7 @@ struct LayerInputs {
     const std::vector<std::shared_ptr<const CraterLayer>>& craters;
     const std::shared_ptr<const BoulderLayer>& boulders;
     const Surface& surface;
+    const std::shared_ptr<const Source>& source;  ///< The base; null without one.
     /// The secondaries later layers throw from a crater layer built with these inputs.
     std::vector<SecondaryCraterOptions> thrown{};
 };
@@ -358,6 +359,58 @@ LayerPtr BuildCraterLayer(const CraterLayerSpec& craters, const std::string& pat
               [&] { return std::make_shared<CraterLayer>(std::move(models), std::move(options)); });
 }
 
+/// The roughness of `source` on cells of `pixelSize` centred on its grid with a node at `origin`,
+/// at most `kRoughnessCells` a side.
+MidpointRoughness SourceRoughness(const Source& source, double pixelSize, const Vec2d& origin) {
+    constexpr double kRoughnessCells = 512.0;
+    const Bounds2d bounds = source.Grid().Bounds();
+    const auto cells = [&](double extent) {
+        return std::clamp(std::floor(extent / pixelSize), 3.0, kRoughnessCells);
+    };
+    const double width = cells(bounds.maxX - bounds.minX);
+    const double height = cells(bounds.maxY - bounds.minY);
+    const double col0 =
+        std::round((0.5 * (bounds.minX + bounds.maxX) - origin.x) / pixelSize - 0.5 * width);
+    const double rowTop =
+        std::round((0.5 * (bounds.minY + bounds.maxY) - origin.y) / pixelSize + 0.5 * height);
+    const RasterGrid grid{static_cast<std::size_t>(width), static_cast<std::size_t>(height),
+                          GeoTransform::NorthUp(origin.x + (col0 - 0.5) * pixelSize,
+                                                origin.y + (rowTop + 0.5) * pixelSize, pixelSize)};
+    Raster<float> heights = grid.MakeRaster();
+    source.Fill(heights);
+    return EstimateMidpointRoughness(heights);
+}
+
+/// The options of a midpoint displacement layer, from the base wherever the spec gives none.
+MidpointDisplacementOptions BuildMidpointOptions(const MidpointDisplacementLayerSpec& spec,
+                                                 const Source* source, const Surface& surface) {
+    MidpointDisplacementOptions options;
+    options.minPixelSize = spec.minPixelSize / surface.UnitLength();
+    options.base = spec.base;
+    options.seed = spec.seed;
+    if (!(spec.pixelSize && spec.originX && spec.originY) && !source) {
+        throw std::invalid_argument(
+            "A midpoint displacement layer without a base needs its pixel size and origin");
+    }
+    const RasterGrid grid = source ? source->Grid() : RasterGrid{};
+    options.pixelSize = spec.pixelSize ? *spec.pixelSize / surface.UnitLength() : grid.PixelSize();
+    const Vec2d first = grid.transform.PixelToWorld(0.5, 0.5);
+    options.origin = {spec.originX.value_or(first.x), spec.originY.value_or(first.y)};
+    if (spec.fractalDimension && spec.scale) {
+        options.fractalDimension = *spec.fractalDimension;
+        options.scale = *spec.scale;
+        return options;
+    }
+    if (!source) {
+        throw std::invalid_argument(
+            "A midpoint displacement layer without a base needs its fractal dimension and scale");
+    }
+    const MidpointRoughness roughness = SourceRoughness(*source, options.pixelSize, options.origin);
+    options.fractalDimension = spec.fractalDimension.value_or(roughness.fractalDimension);
+    options.scale = spec.scale.value_or(roughness.scale);
+    return options;
+}
+
 LayerPtr BuildSecondaryLayer(const SecondaryLayerSpec& spec,
                              const std::shared_ptr<const CraterLayer>& primaries) {
     const CraterShapeModels models{
@@ -405,6 +458,10 @@ LayerPtr BuildLayer(const LayerSpec& spec, const std::string& path, const LayerI
             [&](const BedformLayerSpec& s) -> LayerPtr {
                 return std::make_shared<BedformLayer>(s.bedforms, surface);
             },
+            [&](const MidpointDisplacementLayerSpec& s) -> LayerPtr {
+                return std::make_shared<MidpointDisplacementLayer>(
+                    BuildMidpointOptions(s, context.source.get(), surface), surface);
+            },
             [&](const ScaleLayerSpec& s) -> LayerPtr {
                 return std::make_shared<ScaleLayer>(s.scale, s.offset);
             },
@@ -462,6 +519,7 @@ Terrain BuildValidTerrain(const TerrainConfig& config, const std::filesystem::pa
                                   craters,
                                   boulders,
                                   terrain.surface,
+                                  terrain.source,
                                   ThrownSecondaries(config.layers, i)};
         terrain.layers.push_back(BuildLayer(config.layers[i], Element("layers", i), context));
         if (std::holds_alternative<CraterLayerSpec>(config.layers[i])) {
@@ -641,10 +699,7 @@ BoulderLayerOptions BuildBoulderOptions(const BoulderLayerSpec& spec, const std:
             SizeSlopeMap{BuildField(s.field, Child(Child(path, "slope_map"), "field"), directory),
                          s.measure, s.referenceDiameter, s.minExponent, s.maxExponent};
     }
-    for (Crater boulder : spec.manual) {
-        boulder.manual = true;
-        options.manual.push_back(boulder);
-    }
+    options.manual = spec.manual;
     if (spec.completeness) {
         options.completeness =
             BuildField(*spec.completeness, Child(path, "completeness"), directory);

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/terraingen/config/config.h

@@ -25,6 +25,7 @@
 #include "terraingen/layers/craters/shaping/apply.h"
 #include "terraingen/layers/density_map.h"
 #include "terraingen/layers/dunes.h"
+#include "terraingen/layers/midpoint_displacement.h"
 #include "terraingen/layers/pavement.h"
 #include "terraingen/layers/region.h"
 #include "terraingen/layers/roughness.h"
@@ -614,8 +615,8 @@ struct BoulderLayerSpec {
     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{};
+    /// Catalog or hand-placed boulders in the surface's coordinates, as `boulders.manual`.
+    std::vector<ManualBoulder> manual{};
     std::optional<FieldSpec> completeness{};  ///< Gives `boulders.completeness`.
 
     bool operator==(const BoulderLayerSpec& other) const {
@@ -758,6 +759,30 @@ struct DemDetailLayerSpec {
     }
 };
 
+/// Layer "midpoint_displacement": random midpoint displacement expansion of a base lattice
+/// (`MidpointDisplacementLayer`), on the base's grid with its estimated roughness
+/// (`EstimateMidpointRoughness`) wherever a value is not given.
+struct MidpointDisplacementLayerSpec {
+    std::optional<double> pixelSize{};  ///< Metres; unset for the base's cell size.
+    std::optional<double> originX{};    ///< Surface coordinates; unset for the base's first cell.
+    std::optional<double> originY{};    ///< Surface coordinates; unset for the base's first cell.
+    std::optional<double> fractalDimension{};  ///< Unset to estimate from the base.
+    std::optional<double> scale{};             ///< Metres; unset to estimate from the base.
+    double minPixelSize = 0.0;                 ///< Metres; 0 for no limit.
+    MidpointBase base = MidpointBase::DiamondSquare;
+    std::uint32_t seed = 1;
+
+    bool operator==(const MidpointDisplacementLayerSpec& other) const {
+        return pixelSize == other.pixelSize && originX == other.originX &&
+               originY == other.originY && fractalDimension == other.fractalDimension &&
+               scale == other.scale && minPixelSize == other.minPixelSize && base == other.base &&
+               seed == other.seed;
+    }
+    bool operator!=(const MidpointDisplacementLayerSpec& other) const {
+        return !(*this == other);
+    }
+};
+
 /// Layer "scale": height * `scale` + `offset` (`ScaleLayer`).
 struct ScaleLayerSpec {
     double scale = 1.0;
@@ -866,11 +891,11 @@ template <typename T> class Boxed {
 struct RegionLayerSpec;
 
 /// A layer, named in JSON by its "type".
-using LayerSpec =
-    std::variant<NoiseLayerSpec, CraterLayerSpec, BoulderLayerSpec, RoughnessLayerSpec,
-                 BedformLayerSpec, ScaleLayerSpec, ClampLayerSpec, RegionLayerSpec,
-                 SecondaryLayerSpec, DemDetailLayerSpec, DuneLayerSpec, SandFillLayerSpec,
-                 PavementLayerSpec, StrataLayerSpec, SandShadowLayerSpec>;
+using LayerSpec = std::variant<NoiseLayerSpec, CraterLayerSpec, BoulderLayerSpec,
+                               RoughnessLayerSpec, BedformLayerSpec, ScaleLayerSpec, ClampLayerSpec,
+                               RegionLayerSpec, SecondaryLayerSpec, DemDetailLayerSpec,
+                               DuneLayerSpec, SandFillLayerSpec, PavementLayerSpec, StrataLayerSpec,
+                               SandShadowLayerSpec, MidpointDisplacementLayerSpec>;
 
 /// Layer "region": `layer` applied only inside `shape` (`RegionLayer`). Boulder ejecta do
 /// not see crater layers inside regions.

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/terraingen/config/feature_lists.cpp

@@ -58,16 +58,16 @@ const std::array<Column<Boulder>, 16> kBoulderColumns{{
     {"diameter", [](const Boulder& b) { return Cell(b.diameter); }},
     {"height", [](const Boulder& b) { return Cell(b.height); }},
     {"burial", [](const Boulder& b) { return Cell(b.burial); }},
-    {"yaw", [](const Boulder& b) { return Cell(b.yaw); }},
-    {"lean", [](const Boulder& b) { return Cell(b.lean); }},
+    {"yaw_deg", [](const Boulder& b) { return Cell(b.yaw * kRadian); }},
+    {"lean_deg", [](const Boulder& b) { return Cell(b.lean * kRadian); }},
     {"id", [](const Boulder& b) { return Cell(b.id); }},
     {"model", [](const Boulder& b) { return Cell(b.model); }},
     {"wear", [](const Boulder& b) { return Cell(b.wear); }},
     {"parent", [](const Boulder& b) { return Cell(b.parent); }},
     {"piece", [](const Boulder& b) { return Cell(static_cast<std::uint64_t>(b.piece)); }},
     {"rest", [](const Boulder& b) { return Cell(static_cast<int>(b.rest)); }},
-    {"tilt", [](const Boulder& b) { return Cell(b.tilt); }},
-    {"tilt_azimuth", [](const Boulder& b) { return Cell(b.tiltAzimuth); }},
+    {"tilt_deg", [](const Boulder& b) { return Cell(b.tilt * kRadian); }},
+    {"tilt_azimuth_deg", [](const Boulder& b) { return Cell(b.tiltAzimuth * kRadian); }},
 }};
 
 /// A cell as CSV writes it: doubles exactly, an unknown value empty and booleans as 1 or 0.

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/terraingen/config/fields/boulders.h

@@ -469,6 +469,46 @@ template <typename IO> void BoulderRenderingFields(IO& io, BoulderRendering& ren
        "The boulders' 3D boulder shapes, used by shape relief and by models.");
 }
 
+template <typename IO> void Fields(IO& io, ManualBoulder& boulder) {
+    io("x", boulder.x,
+       "Centre along x in the surface's coordinates; the longitude in degrees on a sphere.");
+    io("y", boulder.y,
+       "Centre along y in the surface's coordinates; the latitude in degrees on a sphere.");
+    io("diameter", boulder.diameter, "Length of the long axis, in metres.", "m", Above(0.0));
+    io("id", boulder.id,
+       "Stable ID that seeds what is drawn for the boulder; 0 derives one from its position and "
+       "diameter.");
+    NanField(io, "height", boulder.height,
+             "Vertical extent in metres, buried part included; unset draws it from the height "
+             "ratios.",
+             "m", Above(0.0));
+    NanField(io, "burial", boulder.burial,
+             "Buried share of the height, from 0 to below 1; unset draws it.", "",
+             FromBelow(0.0, 1.0));
+    NanRadianField(io, "yaw_deg", boulder.yaw,
+                   "Rotation about the vertical, degrees counter-clockwise from east; unset "
+                   "draws it.");
+    NanRadianField(io, "lean_deg", boulder.lean,
+                   "Tilt of the boulder's vertical axis from the vertical, degrees; unset draws "
+                   "it.");
+    NanRadianField(io, "tilt_deg", boulder.tilt,
+                   "Angle of the up axis from the vertical after lean, degrees; unset draws it. "
+                   "A followed slope tips it further.");
+    NanRadianField(io, "tilt_azimuth_deg", boulder.tiltAzimuth,
+                   "Direction the up axis tips toward, degrees counter-clockwise from east; unset "
+                   "draws it.");
+    NanField(io, "wear", boulder.wear,
+             "How worn it is, from 0 (fresh) to 1; unset draws it. With burial_by_wear it sets "
+             "a drawn burial.",
+             "", UnitInterval());
+    io("rest", boulder.rest,
+       "Which axis it stands along; unset draws it. A fixed lean, tilt, tilt azimuth or rest "
+       "keeps a model from being tipped over by settle.");
+    io("shape_seed", boulder.shapeSeed,
+       "Seed of its 3D shape, as a generated boulder's derived one; unset derives it from the "
+       "ID.");
+}
+
 /// The fields of the files and maps a boulder layer reads, and its catalog boulders.
 template <typename IO> void BoulderInputFields(IO& io, BoulderLayerSpec& spec) {
     io("shape_files", spec.shapeFiles,
@@ -483,8 +523,8 @@ template <typename IO> void BoulderInputFields(IO& io, BoulderLayerSpec& spec) {
        "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.");
+       "Catalog or hand-placed boulders placed as given and never thinned or left out; fields "
+       "left unset are drawn as for generated boulders. Boulders fixing any field never break.");
     io("completeness", spec.completeness,
        "Where the manual boulders are a complete catalog: the diameter in metres from which they "
        "stand in for generated boulders, infinite or no value where there is no catalog. Unset "

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/terraingen/config/fields/common.h

@@ -175,6 +175,40 @@ void RadianField(IO& io, std::string_view key, std::optional<double>& radians,
     }
 }
 
+/// Whether an `IO` takes an angle stored in radians and unset when NaN as the radians themselves,
+/// through `io.NanRadians(key, radians, description, range)`, such as the Python bindings.
+template <typename IO, typename = void> struct TakesNanRadiansTrait : std::false_type {};
+template <typename IO>
+struct TakesNanRadiansTrait<
+    IO, std::void_t<decltype(std::declval<IO&>().NanRadians(
+            std::string_view{}, std::declval<double&>(), std::string_view{}, FieldRange{}))>>
+    : std::true_type {};
+template <typename IO> inline constexpr bool TakesNanRadians = TakesNanRadiansTrait<IO>::value;
+
+/// `RadianField` for an angle unset when NaN, as an optional field in degrees.
+template <typename IO>
+void NanRadianField(IO& io, std::string_view key, double& radians, std::string_view description,
+                    const FieldRange& range = {}) {
+    if constexpr (TakesNanRadians<IO>) {
+        io.NanRadians(key, radians, description, range);
+    } else {
+        std::optional<double> value;
+        if (!std::isnan(radians)) {
+            value = radians;
+        }
+        RadianField(io, key, value, description, range);
+        radians = value.value_or(std::numeric_limits<double>::quiet_NaN());
+    }
+}
+
+/// Reads or writes a number unset when NaN, as an optional field.
+template <typename IO>
+void NanField(IO& io, std::string_view key, double& value, std::string_view description,
+              std::string_view unit = {}, const FieldRange& range = {}) {
+    OptionalBound(io, key, value, description, unit, std::numeric_limits<double>::quiet_NaN(),
+                  range);
+}
+
 /// The keys of a crater selection's fields.
 struct SelectionKeys {
     std::string_view minDiameter = "min_diameter";

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/terraingen/config/fields/craters.h

@@ -23,6 +23,14 @@ template <typename IO> void Fields(IO& io, Crater& crater) {
        "Gyr", AtLeast(0.0));
     io("id", crater.id,
        "Stable ID that seeds the crater's outline; 0 derives one from its position and diameter.");
+    NanField(io, "depth", crater.depth,
+             "Rim-to-floor depth in metres, in place of the one the degradation model and age "
+             "give; unset keeps the model's.",
+             "m", Above(0.0));
+    NanField(io, "rim_height", crater.rimHeight,
+             "Height of the rim crest above the surface the crater formed on, in metres; needs a "
+             "depth. Unset lowers the fresh rim in proportion to the depth.",
+             "m", AtLeast(0.0));
 }
 
 template <typename IO> void Fields(IO& io, CraterSpacing& spacing) {

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/terraingen/config/fields/enums.h

@@ -164,6 +164,17 @@ template <> struct EnumNames<BlendShape> {
     }};
 };
 
+template <> struct EnumNames<MidpointBase> {
+    static constexpr std::array<EnumEntry<MidpointBase>, 2> kValues{{
+        {"diamond_square", MidpointBase::DiamondSquare,
+         "The ground at the base lattice's nodes, interpolated by square and diamond steps: the "
+         "heights are replaced by the expanded lattice, as when expanding a DEM."},
+        {"source", MidpointBase::Source,
+         "Zero at the base lattice's nodes: only the displacements are added, keeping the source's "
+         "own interpolation between nodes."},
+    }};
+};
+
 template <> struct EnumNames<EjectaProfile> {
     static constexpr std::array<EnumEntry<EjectaProfile>, 2> kValues{{
         {"smoothstep", EjectaProfile::Smoothstep,
@@ -287,6 +298,14 @@ template <> struct EnumNames<CraterMorphometryFit> {
     }};
 };
 
+template <> struct EnumNames<BoulderRest> {
+    static constexpr std::array<EnumEntry<BoulderRest>, 3> kValues{{
+        {"face", BoulderRest::Face, "On its broadest face: its short axis up."},
+        {"side", BoulderRest::Side, "On a side: its intermediate axis up."},
+        {"end", BoulderRest::End, "On an end: its long axis up."},
+    }};
+};
+
 template <> struct EnumNames<BoulderRelief> {
     static constexpr std::array<EnumEntry<BoulderRelief>, 3> kValues{{
         {"dome", BoulderRelief::Dome,

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/terraingen/config/fields/layers.h

@@ -448,6 +448,40 @@ template <typename IO> void Fields(IO& io, DemDetailLayerSpec& spec) {
     io("weight", spec.weight, "Share of the detail added; 1 restores it whole, 0.5 halves it.");
 }
 
+template <> struct SpecName<MidpointDisplacementLayerSpec> {
+    static constexpr std::string_view kName = "midpoint_displacement";
+    static constexpr std::string_view kDescription =
+        "Random midpoint displacement (diamond-square) expansion of the base lattice, as PANGU "
+        "expands DEMs: each level halves the node spacing down to the sample spacing, adding "
+        "fractal detail without changing the nodes before it.";
+};
+template <typename IO> void Fields(IO& io, MidpointDisplacementLayerSpec& spec) {
+    io("pixel_size", spec.pixelSize,
+       "Spacing of the base lattice's nodes in metres. Unset uses the base's cell size.", "m",
+       Above(0.0));
+    io("origin_x", spec.originX,
+       "x of a node of the base lattice, in surface coordinates. Unset uses the base's first "
+       "cell centre.");
+    io("origin_y", spec.originY,
+       "y of a node of the base lattice, in surface coordinates. Unset uses the base's first "
+       "cell centre.");
+    io("fractal_dimension", spec.fractalDimension,
+       "Fractal dimension, from 2 (smooth) to 3 (rough): each square or diamond step scales the "
+       "displacement by 2^-((3 - F) / 2). Unset estimates it from the base's variogram.",
+       "", Between(2.0, 3.0));
+    io("scale", spec.scale,
+       "Standard deviation in metres of the displacement at the base lattice's own last diamond "
+       "step. Unset estimates it from the base as the RMS of each cell minus the mean of its four "
+       "neighbours.",
+       "m", AtLeast(0.0));
+    io("min_pixel_size", spec.minPixelSize,
+       "Finest node spacing in metres the lattice is expanded to; 0 expands down to the sample "
+       "spacing.",
+       "m", AtLeast(0.0));
+    io("base", spec.base, "What is displaced: the ground at the base nodes, or zero.");
+    io("seed", spec.seed, "Seed of the displacements.");
+}
+
 template <> struct SpecName<ScaleLayerSpec> {
     static constexpr std::string_view kName = "scale";
     static constexpr std::string_view kDescription =

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev91}/terraingen/config/generate.h

@@ -70,9 +70,10 @@ std::string Summary(const GeneratedTerrain& terrain);
 void WriteCraterList(const CraterList& craters, const std::filesystem::path& path,
                      ListFormat format, const std::vector<CraterAttributes>& attributes = {});
 
-/// Writes boulders as CSV (columns x, y, ground, diameter, height, burial, yaw, lean, id, model,
-/// wear, parent, piece, rest, tilt and tilt_azimuth) or as JSON ({"boulders": [...]}) with the
-/// same keys, doubles written exactly and an unknown ground left empty (CSV) or null (JSON).
+/// Writes boulders as CSV (columns x, y, ground, diameter, height, burial, yaw_deg, lean_deg, id,
+/// model, wear, parent, piece, rest, tilt_deg and tilt_azimuth_deg, angles in degrees) or as JSON
+/// ({"boulders": [...]}) with the same keys, doubles written exactly and an unknown ground left
+/// empty (CSV) or null (JSON).
 /// @throws std::runtime_error if the file cannot be written.
 void WriteBoulderList(const std::vector<Boulder>& boulders, const std::filesystem::path& path,
                       ListFormat format);