terraingenpy 0.1.1.dev82__tar.gz → 0.1.1.dev95__tar.gz

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

@@ -23,10 +23,19 @@ 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.
+- Multi-resolution hierarchies: a `hierarchy` section nests squares in a base grid, each level twice as fine (or `factor` times) on its parent's cell centres, writes heightmaps, meshes, lists and maps per grid as `region_{region}_level_{level}` with a JSON manifest, blends each level's edges into its parent's so meshes meet without gaps, cuts meshes out under finer levels and hangs skirts, and rejects overlapping regions.
+- Terrain meshes take `cutouts`, a `skirt` and a frame `site`.
+- Configuration keys `region` (`min_x`, `min_y`, `max_x`, `max_y` in CRS units) on raster bases and `dem_detail` layers to read only a window of a DEM, and `unresolved_pixels_across` on crater layers to generate only the craters the base DEM does not already resolve, combined with any catalog `completeness`.
 
 ### 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.dev95}/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.dev95")
 string(REGEX MATCH "^[0-9]+\\.[0-9]+\\.[0-9]+" TERRAINGEN_VERSION "${TERRAINGEN_FULL_VERSION}")
 
 project(

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: terraingenpy
-Version: 0.1.1.dev82
+Version: 0.1.1.dev95
 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.dev95}/examples/README.md

@@ -54,11 +54,11 @@ Options:
 
 | Category | Config | C++ | Python |
 | --- | --- | --- | --- |
-| terrain | `example_terrain_billow`, `_cellular`, `_domain_warp`, `_fbm`, `_layered`, `_ridged`, `_roughness`, `_voronoi` | `example_terrain_fbm`, `_layered` | `example_terrain_fbm`, `_fractal_types`, `_hurst_sweep`, `_layered`, `_noise_kernels` |
-| craters | `example_craters_datum`, `_degradation_diffusion`, `_degradation_none`, `_interior_replacement`, `_irregular`, `_manual`, `_max_craters`, `_profile_complex`, `_profile_martin_parkes_dunstan`, `_rim_smoothing_soft`, `_secondaries`, `_secondary_rays`, `_simple`, `_smoothed_rims`, `_spacing` | `example_craters_degradation`, `_manual`, `_profiles`, `_secondaries`, `_simple` | `example_craters_age_sweep`, `_apply_options`, `_degradation`, `_irregularity`, `_manual`, `_positioning`, `_profiles`, `_rim_smoothing`, `_secondaries`, `_simple` |
+| terrain | `example_terrain_billow`, `_cellular`, `_domain_warp`, `_fbm`, `_hierarchy`, `_layered`, `_ridged`, `_roughness`, `_voronoi` | `example_terrain_fbm`, `_layered` | `example_terrain_fbm`, `_fractal_types`, `_hurst_sweep`, `_layered`, `_noise_kernels` |
+| craters | `example_craters_datum`, `_degradation_diffusion`, `_degradation_none`, `_interior_replacement`, `_irregular`, `_manual`, `_manual_depth`, `_max_craters`, `_profile_complex`, `_profile_martin_parkes_dunstan`, `_rim_smoothing_soft`, `_secondaries`, `_secondary_rays`, `_simple`, `_smoothed_rims`, `_spacing` | `example_craters_degradation`, `_manual`, `_manual_depth`, `_profiles`, `_secondaries`, `_simple` | `example_craters_age_sweep`, `_apply_options`, `_degradation`, `_irregularity`, `_manual`, `_manual_depth`, `_positioning`, `_profiles`, `_rim_smoothing`, `_secondaries`, `_simple` |
 | distributions | `example_distributions_moore_rough_mare`, `_piecewise_power_law`, `_power_law`, `_tabulated`, `_trask_equilibrium`, `_viper` | `example_distributions_csfd` | `example_distributions_csfd`, `_custom` |
 | ages | `example_ages_fresh`, `_freshness`, `_steady_state`, `_uniform` | `example_ages_models` | `example_ages_models` |
-| boulders | `example_boulders_buried`, `_ejecta`, `_fragments`, `_exposure`, `_layer`, `_models`, `_patches`, `_scene`, `_shapes`, `_sp8023` | `example_boulders_ejecta`, `_layer`, `_shapes` | `example_boulders_exposure`, `_layer`, `_positioning`, `_shapes`, `_size_models` |
+| boulders | `example_boulders_buried`, `_ejecta`, `_fragments`, `_exposure`, `_layer`, `_manual`, `_models`, `_patches`, `_scene`, `_shapes`, `_sp8023` | `example_boulders_ejecta`, `_layer`, `_manual`, `_shapes` | `example_boulders_exposure`, `_layer`, `_manual`, `_positioning`, `_shapes`, `_size_models` |
 | albedo | `example_albedo_blast_zone`, `_crater_rays`, `_fresh_crater`, `_moon_site`, `_new_crater`, `_oblique_rays`, `_rgb`, `_synthetic` | `example_albedo_crater_rays` | `example_albedo_crater_rays`, `_moon_site`, `_options` |
 | layers | `example_layers_regions`, `_roughness`, `_scale_and_clamp` | `example_layers_custom`, `_regions` | `example_layers_custom`, `_regions` |
 | planets | `example_planets_asteroid_body_mesh`, `_mars_bedforms`, `_mars_craters`, `_mars_dunes`, `_mars_exposure`, `_mars_pavement`, `_mars_sand_fill`, `_mars_sand_shadows`, `_mars_strata`, `_mars_ventifacts`, `_mercury_site`, `_moon_body_mesh`, `_moon_site` | `example_planets_moon` | `example_planets_body_mesh`, `_mars`, `_mars_dunes`, `_mars_exposure`, `_mercury`, `_moon_site` |

terraingenpy-0.1.1.dev95/examples/config/boulders/example_boulders_manual.json

@@ -0,0 +1,76 @@
+{
+    "schema_version": 1,
+    "layers": [
+        {
+            "type": "boulders",
+            "seed": 1,
+            "coverage": 0.03,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
+            "min_diameter": 0.1,
+            "max_diameter": 1.0,
+            "models": {
+                "min_diameter": 0.5
+            },
+            "manual": [
+                {
+                    "x": -6,
+                    "y": 4,
+                    "diameter": 1.6,
+                    "id": 101,
+                    "height": 0.9,
+                    "burial": 0.3,
+                    "yaw_deg": 30,
+                    "lean_deg": 5,
+                    "tilt_deg": 15,
+                    "tilt_azimuth_deg": 90,
+                    "wear": 0.2,
+                    "rest": "side",
+                    "shape_seed": 7
+                },
+                {
+                    "x": 5,
+                    "y": 3,
+                    "diameter": 1.2,
+                    "yaw_deg": 90,
+                    "burial": 0.5
+                },
+                {
+                    "x": 0,
+                    "y": -6,
+                    "diameter": 1.0
+                }
+            ]
+        }
+    ],
+    "outputs": [
+        {
+            "type": "heightmap",
+            "path": "example_boulders_manual.tif",
+            "region": {
+                "width": 801,
+                "height": 801,
+                "pixel_size": 0.05
+            }
+        },
+        {
+            "type": "boulder_list",
+            "path": "example_boulders_manual.csv",
+            "region": {
+                "width": 801,
+                "height": 801,
+                "pixel_size": 0.05
+            }
+        },
+        {
+            "type": "boulder_models",
+            "path": "example_boulders_manual.glb",
+            "region": {
+                "width": 801,
+                "height": 801,
+                "pixel_size": 0.05
+            }
+        }
+    ]
+}

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev95}/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.dev95}/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.dev95}/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.dev95/examples/config/craters/example_craters_manual_depth.json

@@ -0,0 +1,62 @@
+{
+    "schema_version": 1,
+    "layers": [
+        {
+            "type": "craters",
+            "generate": false,
+            "profile": {
+                "type": "martin_parkes_dunstan"
+            },
+            "degradation": {
+                "type": "freshness"
+            },
+            "manual": [
+                {
+                    "x": -22,
+                    "y": 20,
+                    "diameter": 20,
+                    "depth": 3.0,
+                    "rim_height": 0.8
+                },
+                {
+                    "x": 22,
+                    "y": 22,
+                    "diameter": 16,
+                    "depth": 1.2
+                },
+                {
+                    "x": -20,
+                    "y": -22,
+                    "diameter": 24,
+                    "depth": 2.0,
+                    "rim_height": 0.3
+                },
+                {
+                    "x": 22,
+                    "y": -20,
+                    "diameter": 18
+                }
+            ]
+        }
+    ],
+    "outputs": [
+        {
+            "type": "heightmap",
+            "path": "example_craters_manual_depth.tif",
+            "region": {
+                "width": 401,
+                "height": 401,
+                "pixel_size": 0.25
+            }
+        },
+        {
+            "type": "crater_list",
+            "path": "example_craters_manual_depth.csv",
+            "region": {
+                "width": 401,
+                "height": 401,
+                "pixel_size": 0.25
+            }
+        }
+    ]
+}

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev95}/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.dev95}/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.dev95}/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.dev95}/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.dev95/examples/config/terrain/example_terrain_hierarchy.json

@@ -0,0 +1,53 @@
+{
+    "schema_version": 1,
+    "layers": [
+        {
+            "type": "noise",
+            "stack": [
+                {
+                    "seed": 3,
+                    "wavelength": 600,
+                    "amplitude": 30,
+                    "octaves": 5
+                }
+            ]
+        },
+        {
+            "type": "midpoint_displacement",
+            "pixel_size": 4,
+            "origin_x": -512,
+            "origin_y": 512,
+            "fractal_dimension": 2.3,
+            "scale": 0.4,
+            "base": "source"
+        }
+    ],
+    "hierarchy": {
+        "path": "example_terrain_hierarchy/region_{region}_level_{level}",
+        "base": {
+            "width": 257,
+            "height": 257,
+            "pixel_size": 4
+        },
+        "regions": [
+            {
+                "centre_x": -150,
+                "centre_y": 100,
+                "size": 256,
+                "levels": 3
+            },
+            {
+                "centre_x": 250,
+                "centre_y": -200,
+                "size": 128,
+                "levels": 2
+            }
+        ],
+        "products": [
+            "heightmap",
+            "terrain_mesh"
+        ],
+        "skirt": 2,
+        "manifest": "example_terrain_hierarchy/manifest.json"
+    }
+}

terraingenpy-0.1.1.dev95/examples/cpp/boulders/example_boulders_manual.cpp

@@ -0,0 +1,165 @@
+/// Hand-placed boulders on a small flat site, as for a rover test scene: one with its whole pose
+/// and shape fixed, one with only its yaw and burial fixed and one given only its position and
+/// diameter, among a sparse generated population. Fields left unset are drawn as for generated
+/// boulders, and boulders 0.5 m or larger are placed as 3D boulder models. Writes the heights,
+/// the boulder list and the models as a glTF scene. The same terrain as
+/// examples/config/boulders/example_boulders_manual.json.
+///
+///     example_boulders_manual [--output-dir DIR] [--test]
+///     terraingen-examples boulders_manual
+
+#include "common/example.h"
+#include "terraingen/terraingen.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <filesystem>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace {
+
+/// A manual boulder at (`x`, `y`), `diameter` long, fixing nothing else.
+terraingen::ManualBoulder Plain(double x, double y, double diameter) {
+    terraingen::ManualBoulder boulder;
+    boulder.x = x;
+    boulder.y = y;
+    boulder.diameter = diameter;
+    return boulder;
+}
+
+/// The name of `rest` as the configs write it.
+const char* RestName(terraingen::BoulderRest rest) {
+    switch (rest) {
+    case terraingen::BoulderRest::Side:
+        return "side";
+    case terraingen::BoulderRest::End:
+        return "end";
+    default:
+        return "face";
+    }
+}
+
+/// The placed boulder of ID `id`, or null.
+const terraingen::Boulder* Find(const std::vector<terraingen::Boulder>& boulders,
+                                std::uint64_t id) {
+    for (const terraingen::Boulder& boulder : boulders) {
+        if (boulder.id == id) {
+            return &boulder;
+        }
+    }
+    return nullptr;
+}
+
+class BouldersManual : public terraingen::examples::Example {
+  public:
+    using Example::Example;
+
+    void Generate() override {
+        terraingen::ManualBoulder posed = Plain(-6.0, 4.0, 1.6);
+        posed.id = 101;
+        posed.height = 0.9;
+        posed.burial = 0.3;
+        posed.yaw = 30.0 * terraingen::kDegree;
+        posed.lean = 5.0 * terraingen::kDegree;
+        posed.tilt = 15.0 * terraingen::kDegree;
+        posed.tiltAzimuth = 90.0 * terraingen::kDegree;
+        posed.wear = 0.2;
+        posed.rest = terraingen::BoulderRest::Side;
+        posed.shapeSeed = 7u;
+        terraingen::ManualBoulder partly = Plain(5.0, 3.0, 1.2);
+        partly.yaw = 90.0 * terraingen::kDegree;
+        partly.burial = 0.5;
+        manual_ = {posed, partly, Plain(0.0, -6.0, 1.0)};
+
+        terraingen::BoulderLayerOptions options;
+        options.sizes.coverage = 0.03;
+        options.sizes.minDiameter = 0.1;
+        options.sizes.maxDiameter = 1.0;
+        options.rendering.models.minDiameter = 0.5;
+        options.manual = manual_;
+
+        terraingen::Terrain terrain;
+        terrain.source = std::make_shared<terraingen::FlatSource>(801, 801, 0.05);
+        terrain.layers.push_back(std::make_shared<terraingen::BoulderLayer>(options));
+
+        evaluated_ = terraingen::Evaluate(terrain);
+        boulders_ =
+            terraingen::PlacedBoulders(terrain, terraingen::RasterGrid::FromRaster(evaluated_));
+        Out() << boulders_.boulders.size() << " boulders, " << boulders_.models.size()
+              << " of them boulder models\n";
+        for (const terraingen::ManualBoulder& manual : manual_) {
+            const terraingen::Boulder* b =
+                Find(boulders_.boulders, terraingen::ManualBoulderId(manual));
+            if (b == nullptr) {
+                continue;
+            }
+            Out() << "boulder " << b->id << " at (" << b->x << ", " << b->y << "), " << b->diameter
+                  << " m long, " << b->height << " m high, burial " << b->burial << ", yaw "
+                  << b->yaw * terraingen::kRadian << " deg, lean " << b->lean * terraingen::kRadian
+                  << " deg, tilt " << b->tilt * terraingen::kRadian << " deg toward "
+                  << b->tiltAzimuth * terraingen::kRadian << " deg, wear " << b->wear << ", rest "
+                  << RestName(b->rest) << ", shape seed "
+                  << (b->shapeSeed ? std::to_string(*b->shapeSeed) : std::string("from its ID"))
+                  << "\n";
+        }
+        Show("heights", evaluated_);
+    }
+
+    void Save(const std::filesystem::path& dir) override {
+        const auto heights = dir / "example_boulders_manual.tif";
+        const auto list = dir / "example_boulders_manual.csv";
+        const auto models = dir / "example_boulders_manual.glb";
+        terraingen::WriteGeoTiff(heights, evaluated_);
+        terraingen::WriteBoulderList(boulders_.boulders, list, terraingen::ListFormat::Csv);
+        terraingen::WriteBoulderModels(boulders_.models, models);
+        Out() << "Wrote " << heights.string() << ", " << list.string() << " and " << models.string()
+              << "\n";
+    }
+
+    void Test() override {
+        Check(evaluated_.Width() == 801 && evaluated_.Height() == 801, "the heights are 801 x 801");
+        Check(terraingen::ComputeStats(evaluated_).validCount == evaluated_.Size(),
+              "every height is finite");
+        const terraingen::ManualBoulder& posed = manual_[0];
+        const terraingen::Boulder* p = Find(boulders_.boulders, 101);
+        Check(p != nullptr, "the posed boulder keeps its ID");
+        Check(p != nullptr && p->x == posed.x && p->y == posed.y && p->diameter == posed.diameter &&
+                  p->height == posed.height && p->burial == posed.burial && p->yaw == posed.yaw &&
+                  p->lean == posed.lean && p->tilt == posed.tilt &&
+                  p->tiltAzimuth == posed.tiltAzimuth && p->wear == posed.wear &&
+                  p->rest == terraingen::BoulderRest::Side && p->shapeSeed == posed.shapeSeed,
+              "the posed boulder has every field it fixes");
+        const terraingen::ManualBoulder& partly = manual_[1];
+        const terraingen::Boulder* q =
+            Find(boulders_.boulders, terraingen::ManualBoulderId(partly));
+        Check(q != nullptr && q->yaw == partly.yaw && q->burial == partly.burial &&
+                  q->diameter == partly.diameter && !q->shapeSeed,
+              "the partly posed boulder has its yaw and burial");
+        const terraingen::Boulder* r =
+            Find(boulders_.boulders, terraingen::ManualBoulderId(manual_[2]));
+        Check(r != nullptr && r->diameter == 1.0 && r->height > 0.0,
+              "the boulder given only a diameter is drawn the rest of the way");
+        std::size_t manualModels = 0;
+        for (const terraingen::BoulderModel& model : boulders_.models) {
+            for (const terraingen::ManualBoulder& manual : manual_) {
+                if (model.boulder.id == terraingen::ManualBoulderId(manual)) {
+                    ++manualModels;
+                }
+            }
+        }
+        Check(manualModels == manual_.size(), "every manual boulder is a boulder model");
+        Check(boulders_.boulders.size() > 20 && boulders_.boulders.size() < 2000,
+              "a sparse generated population around them");
+    }
+
+  private:
+    std::vector<terraingen::ManualBoulder> manual_;
+    terraingen::Raster<float> evaluated_;
+    terraingen::BoulderFeatures boulders_;
+};
+
+}  // namespace
+
+TERRAINGEN_EXAMPLE(BouldersManual, "Hand-placed boulders with a fixed pose among generated ones")

terraingenpy-0.1.1.dev95/examples/cpp/craters/example_craters_manual_depth.cpp

@@ -0,0 +1,118 @@
+/// Hand-placed craters given an explicit rim-to-floor depth, one with its rim height as well, on a
+/// small flat site under the Martin-Parkes-Dunstan profile, which honours both; one more crater
+/// gives only its diameter and takes its depth from the degradation model. The same terrain as
+/// examples/config/craters/example_craters_manual_depth.json.
+///
+///     example_craters_manual_depth [--output-dir DIR] [--test]
+///     terraingen-examples craters_manual_depth
+
+#include "common/example.h"
+#include "terraingen/terraingen.h"
+
+#include <cmath>
+#include <cstddef>
+#include <filesystem>
+#include <memory>
+#include <vector>
+
+namespace {
+
+/// A manual crater at (`x`, `y`), `diameter` across, `depth` deep from rim to floor, with its
+/// rim `rimHeight` above the surface (NaN derives it from the depth).
+terraingen::Crater Deep(double x, double y, double diameter, double depth,
+                        double rimHeight = std::nan("")) {
+    return terraingen::Crater{x, y, diameter, 0.0, 0u, true, depth, rimHeight};
+}
+
+class CratersManualDepth : public terraingen::examples::Example {
+  public:
+    using Example::Example;
+
+    void Generate() override {
+        const auto ages = std::make_shared<terraingen::UniformAges>(1.0);
+        const terraingen::CraterModels models{
+            std::make_shared<terraingen::PowerLawSfd>(1e-6, 2.0), ages,
+            std::make_shared<terraingen::FreshnessDegradation>(
+                ages, terraingen::LunarFreshCraterMorphometry),
+            std::make_shared<terraingen::MartinParkesDunstanProfile>()};
+        terraingen::CraterLayerOptions options;
+        options.generate = false;
+        manual_ = {
+            Deep(-22.0, 20.0, 20.0, 3.0, 0.8),
+            Deep(22.0, 22.0, 16.0, 1.2),
+            Deep(-20.0, -22.0, 24.0, 2.0, 0.3),
+            terraingen::Crater{22.0, -20.0, 18.0},
+        };
+        for (const terraingen::Crater& crater : manual_) {
+            options.generation.manual.Append(crater);
+        }
+
+        terraingen::Terrain terrain;
+        terrain.source = std::make_shared<terraingen::FlatSource>(401, 401, 0.25);
+        terrain.layers.push_back(std::make_shared<terraingen::CraterLayer>(models, options));
+
+        evaluated_ = terraingen::Evaluate(terrain);
+        craters_ =
+            terraingen::PlacedCraters(terrain, terraingen::RasterGrid::FromRaster(evaluated_));
+        for (std::size_t i = 0; i < craters_.craters.Size(); ++i) {
+            const terraingen::Crater crater = craters_.craters.At(i);
+            const terraingen::CraterAttributes& attributes = craters_.attributes[i];
+            Out() << crater.diameter << " m crater, ";
+            if (std::isnan(crater.depth)) {
+                Out() << "depth from the model";
+            } else {
+                Out() << "asked " << crater.depth << " m deep";
+            }
+            if (!std::isnan(crater.rimHeight)) {
+                Out() << " with a " << crater.rimHeight << " m rim";
+            }
+            Out() << ": floor " << attributes.floorDepth << " m below and rim "
+                  << attributes.rimHeight << " m above the surface, rim to floor "
+                  << attributes.floorDepth + attributes.rimHeight << " m\n";
+        }
+        Show("heights", evaluated_);
+    }
+
+    void Save(const std::filesystem::path& dir) override {
+        const auto path = dir / "example_craters_manual_depth.tif";
+        terraingen::WriteGeoTiff(path, evaluated_);
+        Out() << "Wrote " << path.string() << "\n";
+    }
+
+    void Test() override {
+        const terraingen::CraterList& craters = craters_.craters;
+        Check(evaluated_.Width() == 401 && evaluated_.Height() == 401, "the heights are 401 x 401");
+        Check(terraingen::ComputeStats(evaluated_).validCount == evaluated_.Size(),
+              "every height is finite");
+        Check(craters.Size() == manual_.size() && craters_.attributes.size() == craters.Size(),
+              "exactly the four hand-placed craters, each with attributes");
+        bool depths = true;
+        bool rims = true;
+        bool modelled = false;
+        for (std::size_t i = 0; i < craters.Size(); ++i) {
+            const terraingen::Crater crater = craters.At(i);
+            const terraingen::CraterAttributes& a = craters_.attributes[i];
+            const double tolerance = 1e-3 * crater.diameter;
+            if (std::isnan(crater.depth)) {
+                modelled = a.floorDepth + a.rimHeight > 1.0;
+                continue;
+            }
+            depths = depths && std::fabs(a.floorDepth + a.rimHeight - crater.depth) < tolerance;
+            rims = rims && (std::isnan(crater.rimHeight) ||
+                            std::fabs(a.rimHeight - crater.rimHeight) < tolerance);
+        }
+        Check(depths, "each crater given a depth is that deep from rim to floor");
+        Check(rims, "each crater given a rim height has that rim");
+        Check(modelled, "the crater given only a diameter takes its depth from the model");
+        Check(terraingen::ComputeStats(evaluated_).min < -1.0, "the craters are cut into the site");
+    }
+
+  private:
+    std::vector<terraingen::Crater> manual_;
+    terraingen::Raster<float> evaluated_;
+    terraingen::CraterFeatures craters_;
+};
+
+}  // namespace
+
+TERRAINGEN_EXAMPLE(CratersManualDepth, "Hand-placed craters of chosen depth and rim height")

{terraingenpy-0.1.1.dev82 → terraingenpy-0.1.1.dev95}/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