terraingenpy 0.1.0.dev279__tar.gz → 0.1.1.dev6__tar.gz

{terraingenpy-0.1.0.dev279 → terraingenpy-0.1.1.dev6}/.github/workflows/ci.yml

@@ -451,6 +451,34 @@ jobs:
           path: dist
       - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
 
+  # The "latest" pre-release: main's packages and their checksums, replaced on every push to main.
+  # Marked as a pre-release and never as the latest release, so versioned releases stay the default.
+  latest:
+    needs: [lint, test, packages, package-test]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: "packages-*"
+          merge-multiple: true
+          path: assets
+      - name: Flatten
+        run: find assets -mindepth 2 -type f -exec mv -t assets {} + && find assets -mindepth 1 -type d -empty -delete
+      - name: Checksums
+        run: cd assets && sha256sum -- * > SHA256SUMS
+      - name: Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release delete latest --repo "$GITHUB_REPOSITORY" --cleanup-tag --yes || true
+          gh release create latest assets/* --repo "$GITHUB_REPOSITORY" --target "$GITHUB_SHA" \
+            --prerelease --latest=false --title "Latest (main)" \
+            --notes "Built from main at $GITHUB_SHA. For versioned binaries, use a tagged release."
+
   # A GitHub release for each v* tag, with every wheel, the sdist, the packages and their checksums.
   release:
     needs: [lint, test, wheel, sdist, package-test, docker]

terraingenpy-0.1.1.dev6/CHANGELOG.md

@@ -0,0 +1,29 @@
+# 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]
+
+## [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.0.dev279 → terraingenpy-0.1.1.dev6}/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.0.dev279")
+set(TERRAINGEN_FULL_VERSION "0.1.1.dev6")
 string(REGEX MATCH "^[0-9]+\\.[0-9]+\\.[0-9]+" TERRAINGEN_VERSION "${TERRAINGEN_FULL_VERSION}")
 
 project(

{terraingenpy-0.1.0.dev279 → terraingenpy-0.1.1.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: terraingenpy
-Version: 0.1.0.dev279
+Version: 0.1.1.dev6
 Summary: Scientific terrain generation for planetary surfaces
 Keywords: terrain,moon,mars,craters,planetary science,simulation
 Author: Alex Maietta
@@ -94,7 +94,7 @@ We also provide:
 
 For more information on the concepts behind TerrainGen and the API, see our latest [documentation](https://alexmaietta.github.io/terraingen/).
 
-## Getting Started
+## Quick Start
 
 We recommended getting started by installing `terraingenpy` from PyPi and running the GUI.
 
@@ -103,21 +103,117 @@ pip install terraingenpy
 terraingen --gui
 ```
 
+## Requirements
+
+- Linux (Ubuntu 22.04 or newer), macOS 14 or newer, or Windows 10 or newer, on x86_64 or arm64.
+- Python 3.10 or newer for the Python package.
+- Optional: a Vulkan, CUDA or Metal driver for GPU acceleration. Run `terraingen backends` to see what is available.
+
+## Installation
+
+### Releases
+
+Every [release](https://github.com/alexmaietta/terraingen/releases) has the CLI, library, headers and CMake package for each platform, and `.deb` packages for Ubuntu and Debian. The [latest](https://github.com/alexmaietta/terraingen/releases/tag/latest) pre-release is built from `main` on every push.
+
+### Building from Source
+
+You need CMake 3.22 or newer and a C++20 compiler (GCC 11, Clang 14, Apple Clang 15 or MSVC 2022). CMake fetches everything else.
+
+```sh
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j 8
+cmake --install build --prefix /usr/local
+```
+
+To build the Python package from source, run `pip install .` instead.
+
+### Docker
+
+```sh
+docker run --rm ghcr.io/alexmaietta/terraingen:latest terraingen --help
+```
+
+The `dev` tag follows `main`.
+
+## Getting Started
+
 ### Python
 
+```python
+import terraingen
+
+# A flat 513 x 513 grid with 2 m pixels
+ground = terraingen.FlatSource(513, 513, 2.0)
+
+# Fractal noise 40 m high with an 800 m wavelength
+fractal = terraingen.FractalParams(seed=1, wavelength=800.0, amplitude=40.0)
+noise = terraingen.NoiseLayer(fractal)
+relief = terraingen.NoiseRelief([noise])
+
+terrain = terraingen.Terrain(ground, [relief])
+heights = terraingen.evaluate(terrain)
+terraingen.write_geotiff("terrain.tif", heights)
+```
+
 ### C++
 
+```cmake
+find_package(terraingen REQUIRED)
+target_link_libraries(app PRIVATE terraingen::terraingen)
+```
+
+```cpp
+#include <terraingen/terraingen.h>
+
+int main() {
+    // Fractal noise 40 m high with an 800 m wavelength
+    terraingen::NoiseLayer noise;
+    noise.fractal.seed = 1;
+    noise.fractal.wavelength = 800.0f;
+    noise.fractal.amplitude = 40.0f;
+
+    terraingen::SyntheticTerrainParams relief;
+    relief.layers = {noise};
+
+    // A flat 513 x 513 grid with 2 m pixels, plus the noise
+    terraingen::Terrain terrain;
+    terrain.source = std::make_shared<terraingen::FlatSource>(513, 513, 2.0);
+    terrain.layers.push_back(std::make_shared<terraingen::NoiseRelief>(relief));
+
+    terraingen::Raster<float> heights = terraingen::Evaluate(terrain);
+    terraingen::WriteGeoTiff("terrain.tif", heights);
+}
+```
+
 ### Examples
 
-## Installation
+[examples/](examples/) has the same terrains as JSON configurations, C++ programs and Python scripts, covering basic terrains, craters, boulders, albedo, planets, DEM detail and tiles:
+
+```sh
+terraingen examples/config/craters/example_craters_simple.json
+```
+
+### Demos
 
+[demos/](demos/) has larger showcases, such as terrain over a whole asteroid built from the Itokawa shape model.
 
 ## Contributing
 
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to build, test and submit changes.
+
 ### Documentation
 
+The [documentation](https://alexmaietta.github.io/terraingen/) is built with MkDocs and Doxygen from [docs/](docs/). Run `make -C docs build` to build it locally.
+
 ### Code Coverage
 
+The [coverage report](https://alexmaietta.github.io/terraingen/coverage/) is updated on every push to `main`. To generate it locally:
+
+```sh
+cmake -S . -B build-coverage -DTERRAINGEN_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
+cmake --build build-coverage -j 8 --target coverage
+```
+
 ## Citation
 
 If you use TerrainGen for published research, please cite:
@@ -147,5 +243,5 @@ TerrainGen draws inspiration from existing lunar terrain generation tools:
 | --- | --- | --- | --- | --- |
 | [synthterrain](https://github.com/NeoGeographyToolkit/synthterrain) | NASA Ames | Open source (Apache-2.0) | Crater and boulder populations from size-frequency distributions, crater profiles and DEMs on flat terrain | Doesn't generate surface detail or upscale existing DEMs, not actively contributed to. |
 | [lunasynth](https://github.com/nasa-jpl/lunasynth) | NASA JPL | Open source (Apache-2.0) | Adds craters and boulders to a lunar base DEM, down to 1 cm pixels, and renders images under varying camera and sun positions | Project is not actively-maintained |
-| [DLES Terrain Crafting](https://doi.org/10.1109/AERO63441.2025.11068736) | NASA JSC | Not publicly released (paper) | Enhances LOLA and NAC-derived DEMs of the lunar south pole to 20 cm with synthetic craters and boulders, including hand-placed craters from imagery | Not publicly released, |
-| [PANGU](https://pangu.software/) | University of Dundee / STAR-Dundee | Commercial | Multi-resolution planet and asteroid surfaces from real or fractal DEMs with statistical craters and boulders; GPU camera, LiDAR and thermal sensor simulation | Commercial software |
+| [DLES Terrain Crafting](https://doi.org/10.1109/AERO63441.2025.11068736) | NASA JSC | Not publicly released (paper) | Enhances LOLA and NAC-derived DEMs of the lunar south pole to 20 cm with synthetic craters and boulders, including hand-placed craters from imagery | Not publicly released, relies on manual crater counting, stamps craters from four template shapes, leaves blending rings around craters and smooth interpolated ground between them, and doesn't produce albedo maps. |
+| [PANGU](https://pangu.software/) | University of Dundee / STAR-Dundee | Commercial (free for ESA projects) | Multi-resolution planet and asteroid surfaces from real or fractal DEMs with statistical craters and boulders; GPU camera, LiDAR and thermal sensor simulation | Requires a paid license outside ESA projects, and ships as standalone command-line tools and GUIs rather than a library to integrate into a project. |

{terraingenpy-0.1.0.dev279 → terraingenpy-0.1.1.dev6}/README.md

@@ -38,7 +38,7 @@ We also provide:
 
 For more information on the concepts behind TerrainGen and the API, see our latest [documentation](https://alexmaietta.github.io/terraingen/).
 
-## Getting Started
+## Quick Start
 
 We recommended getting started by installing `terraingenpy` from PyPi and running the GUI.
 
@@ -47,21 +47,117 @@ pip install terraingenpy
 terraingen --gui
 ```
 
+## Requirements
+
+- Linux (Ubuntu 22.04 or newer), macOS 14 or newer, or Windows 10 or newer, on x86_64 or arm64.
+- Python 3.10 or newer for the Python package.
+- Optional: a Vulkan, CUDA or Metal driver for GPU acceleration. Run `terraingen backends` to see what is available.
+
+## Installation
+
+### Releases
+
+Every [release](https://github.com/alexmaietta/terraingen/releases) has the CLI, library, headers and CMake package for each platform, and `.deb` packages for Ubuntu and Debian. The [latest](https://github.com/alexmaietta/terraingen/releases/tag/latest) pre-release is built from `main` on every push.
+
+### Building from Source
+
+You need CMake 3.22 or newer and a C++20 compiler (GCC 11, Clang 14, Apple Clang 15 or MSVC 2022). CMake fetches everything else.
+
+```sh
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j 8
+cmake --install build --prefix /usr/local
+```
+
+To build the Python package from source, run `pip install .` instead.
+
+### Docker
+
+```sh
+docker run --rm ghcr.io/alexmaietta/terraingen:latest terraingen --help
+```
+
+The `dev` tag follows `main`.
+
+## Getting Started
+
 ### Python
 
+```python
+import terraingen
+
+# A flat 513 x 513 grid with 2 m pixels
+ground = terraingen.FlatSource(513, 513, 2.0)
+
+# Fractal noise 40 m high with an 800 m wavelength
+fractal = terraingen.FractalParams(seed=1, wavelength=800.0, amplitude=40.0)
+noise = terraingen.NoiseLayer(fractal)
+relief = terraingen.NoiseRelief([noise])
+
+terrain = terraingen.Terrain(ground, [relief])
+heights = terraingen.evaluate(terrain)
+terraingen.write_geotiff("terrain.tif", heights)
+```
+
 ### C++
 
+```cmake
+find_package(terraingen REQUIRED)
+target_link_libraries(app PRIVATE terraingen::terraingen)
+```
+
+```cpp
+#include <terraingen/terraingen.h>
+
+int main() {
+    // Fractal noise 40 m high with an 800 m wavelength
+    terraingen::NoiseLayer noise;
+    noise.fractal.seed = 1;
+    noise.fractal.wavelength = 800.0f;
+    noise.fractal.amplitude = 40.0f;
+
+    terraingen::SyntheticTerrainParams relief;
+    relief.layers = {noise};
+
+    // A flat 513 x 513 grid with 2 m pixels, plus the noise
+    terraingen::Terrain terrain;
+    terrain.source = std::make_shared<terraingen::FlatSource>(513, 513, 2.0);
+    terrain.layers.push_back(std::make_shared<terraingen::NoiseRelief>(relief));
+
+    terraingen::Raster<float> heights = terraingen::Evaluate(terrain);
+    terraingen::WriteGeoTiff("terrain.tif", heights);
+}
+```
+
 ### Examples
 
-## Installation
+[examples/](examples/) has the same terrains as JSON configurations, C++ programs and Python scripts, covering basic terrains, craters, boulders, albedo, planets, DEM detail and tiles:
+
+```sh
+terraingen examples/config/craters/example_craters_simple.json
+```
+
+### Demos
 
+[demos/](demos/) has larger showcases, such as terrain over a whole asteroid built from the Itokawa shape model.
 
 ## Contributing
 
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to build, test and submit changes.
+
 ### Documentation
 
+The [documentation](https://alexmaietta.github.io/terraingen/) is built with MkDocs and Doxygen from [docs/](docs/). Run `make -C docs build` to build it locally.
+
 ### Code Coverage
 
+The [coverage report](https://alexmaietta.github.io/terraingen/coverage/) is updated on every push to `main`. To generate it locally:
+
+```sh
+cmake -S . -B build-coverage -DTERRAINGEN_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
+cmake --build build-coverage -j 8 --target coverage
+```
+
 ## Citation
 
 If you use TerrainGen for published research, please cite:
@@ -91,5 +187,5 @@ TerrainGen draws inspiration from existing lunar terrain generation tools:
 | --- | --- | --- | --- | --- |
 | [synthterrain](https://github.com/NeoGeographyToolkit/synthterrain) | NASA Ames | Open source (Apache-2.0) | Crater and boulder populations from size-frequency distributions, crater profiles and DEMs on flat terrain | Doesn't generate surface detail or upscale existing DEMs, not actively contributed to. |
 | [lunasynth](https://github.com/nasa-jpl/lunasynth) | NASA JPL | Open source (Apache-2.0) | Adds craters and boulders to a lunar base DEM, down to 1 cm pixels, and renders images under varying camera and sun positions | Project is not actively-maintained |
-| [DLES Terrain Crafting](https://doi.org/10.1109/AERO63441.2025.11068736) | NASA JSC | Not publicly released (paper) | Enhances LOLA and NAC-derived DEMs of the lunar south pole to 20 cm with synthetic craters and boulders, including hand-placed craters from imagery | Not publicly released, |
-| [PANGU](https://pangu.software/) | University of Dundee / STAR-Dundee | Commercial | Multi-resolution planet and asteroid surfaces from real or fractal DEMs with statistical craters and boulders; GPU camera, LiDAR and thermal sensor simulation | Commercial software |
+| [DLES Terrain Crafting](https://doi.org/10.1109/AERO63441.2025.11068736) | NASA JSC | Not publicly released (paper) | Enhances LOLA and NAC-derived DEMs of the lunar south pole to 20 cm with synthetic craters and boulders, including hand-placed craters from imagery | Not publicly released, relies on manual crater counting, stamps craters from four template shapes, leaves blending rings around craters and smooth interpolated ground between them, and doesn't produce albedo maps. |
+| [PANGU](https://pangu.software/) | University of Dundee / STAR-Dundee | Commercial (free for ESA projects) | Multi-resolution planet and asteroid surfaces from real or fractal DEMs with statistical craters and boulders; GPU camera, LiDAR and thermal sensor simulation | Requires a paid license outside ESA projects, and ships as standalone command-line tools and GUIs rather than a library to integrate into a project. |

{terraingenpy-0.1.0.dev279 → terraingenpy-0.1.1.dev6}/cmake/TerrainGenSlang.cmake

@@ -73,24 +73,17 @@ function(terraingen_add_slang_kernel target symbol source)
         spirv_1_3)
 endfunction()
 
-# terraingen_add_kernel(<target> <symbol> <type> <header>): compiles the kernel terraingen::<type>
-# for every GPU backend the build supports and defines `CompiledKernel<type>()` in <target>. <header>,
-# relative to the repository root, is a kernel header (see util/portable.h) declaring the plain
-# struct <type>, `float ApplyCell(<type> kernel, float height, CellPosition position)` and the
-# `CompiledKernel` specialization; the generated entry point (cmake/Kernel.slang.in) applies it to grid
-# cells for RunKernel. A form the build cannot make is embedded empty. TEMPLATE names another
-# entry point, for kernels that bind more buffers (cmake/CraterKernel.slang.in).
-function(terraingen_add_kernel target symbol type header)
-    cmake_parse_arguments(PARSE_ARGV 4 ARG "" "TEMPLATE" "")
-    if(NOT ARG_TEMPLATE)
-        set(ARG_TEMPLATE "${PROJECT_SOURCE_DIR}/cmake/Kernel.slang.in")
-    endif()
+# terraingen_add_kernel(<target> <symbol> <type> <header> <source>): compiles the Slang compute
+# kernel <source> (entry point "main", including terraingen/gpu/kernel.slang) for every GPU backend
+# the build supports and defines `CompiledKernel<type>()` in <target>. <header>, relative to the
+# repository root, is the kernel header (see util/portable.h) declaring the plain struct <type>
+# that <source> binds and the `CompiledKernel` specialization. A form the build cannot make is
+# embedded empty.
+function(terraingen_add_kernel target symbol type header source)
     set(KERNEL_TYPE "${type}")
     set(KERNEL_HEADER "${header}")
     set(KERNEL_SYMBOL "${symbol}")
     set(directory "${CMAKE_CURRENT_BINARY_DIR}/kernels")
-    set(source "${directory}/${symbol}.slang")
-    configure_file("${ARG_TEMPLATE}" "${source}" @ONLY)
     configure_file("${PROJECT_SOURCE_DIR}/cmake/Kernel.cpp.in" "${directory}/${symbol}_program.cpp"
                    @ONLY)
     target_sources(${target} PRIVATE "${directory}/${symbol}_program.cpp")

{terraingenpy-0.1.0.dev279 → terraingenpy-0.1.1.dev6}/terraingen/gpu/kernel.cpp

@@ -24,7 +24,7 @@ constexpr std::size_t kGroupSide = 16;
 /// Most workgroups Vulkan guarantees in one dimension of a dispatch; CUDA and Metal allow more.
 constexpr std::size_t kMaxGroups = 65535;
 
-/// The push constants of kernels (`cmake/Kernel.slang.in`).
+/// The push constants of kernels (`terraingen/gpu/kernel.slang`).
 struct KernelParams {
     std::uint32_t width = 0;
     std::uint32_t rows = 0;

terraingenpy-0.1.1.dev6/terraingen/gpu/kernel.slang

@@ -0,0 +1,37 @@
+// What every TerrainGen compute kernel binds first: the grid strip's heights and its column and
+// row positions, and the layout of the push constants of RunKernel (terraingen/gpu/kernel.cpp).
+// Kernel sources include this, bind their kernel struct at 3 and any extra buffers from 4 on, and
+// declare `params` after every buffer: Metal numbers buffers in declaration order and RunKernel
+// passes the push constants after the last one.
+
+[[vk::binding(0, 0)]] RWStructuredBuffer<float> heights;
+[[vk::binding(1, 0)]] StructuredBuffer<float> xs;
+[[vk::binding(2, 0)]] StructuredBuffer<float> ys;
+
+struct Params {
+    uint width;
+    uint rows;
+    uint noData;
+    float noDataValue;
+    uint firstRow;
+};
+
+namespace terraingen {
+
+static const uint kNoDataNone = 0u;
+static const uint kNoDataNan = 1u;
+
+/// Whether the thread `id` falls inside the strip.
+bool InStrip(Params params, uint3 id) {
+    return id.x < params.width && id.y < params.rows;
+}
+
+/// Whether `height` is the grid's no-data value, which kernels leave as it is.
+bool IsNoData(Params params, float height) {
+    if (params.noData == kNoDataNan) {
+        return isnan(height);
+    }
+    return params.noData != kNoDataNone && height == params.noDataValue;
+}
+
+}  // namespace terraingen

{terraingenpy-0.1.0.dev279 → terraingenpy-0.1.1.dev6}/terraingen/layers/CMakeLists.txt

@@ -58,8 +58,8 @@ terraingen_add_library(
     terraingen_sources
     terraingen_util)
 terraingen_add_kernel(terraingen_layers terraingen_kernel_noise_relief NoiseReliefKernel
-                      terraingen/layers/kernels/noise_relief.h)
-terraingen_add_kernel(
-    terraingen_layers terraingen_kernel_craters CraterShapeKernel
-    terraingen/layers/kernels/craters.h TEMPLATE
-    "${PROJECT_SOURCE_DIR}/cmake/CraterKernel.slang.in")
+                      terraingen/layers/kernels/noise_relief.h kernels/noise_relief.slang)
+terraingen_add_kernel(terraingen_layers terraingen_kernel_craters CraterShapeKernel
+                      terraingen/layers/kernels/craters.h kernels/craters.slang)
+terraingen_add_kernel(terraingen_layers terraingen_kernel_crater_datums CraterDatumKernel
+                      terraingen/layers/kernels/craters.h kernels/crater_datums.slang)

{terraingenpy-0.1.0.dev279 → terraingenpy-0.1.1.dev6}/terraingen/layers/craters/generation/population.cpp

@@ -163,11 +163,12 @@ class Generation {
         CraterList craters;
         craters.Reserve(static_cast<std::size_t>(expected));
         for (const BandPlan& entry : plan) {
+            const BandRegion region = BandRegionOf(entry.band);
             for (const CellIndex& cell : entry.cells) {
                 const std::shared_ptr<const CraterList> drawn = DrawCell(entry.band, cell);
                 for (std::size_t n = 0; n < drawn->Size(); ++n) {
                     const Crater crater = drawn->At(n);
-                    if (InRegion(crater, CandidateMargin(crater.diameter))) {
+                    if (InBandRegion(region, crater)) {
                         craters.Append(crater);
                     }
                 }
@@ -176,6 +177,33 @@ class Generation {
         return craters;
     }
 
+    /// The region expanded by the candidate margins of a band's smallest and largest craters,
+    /// which bound every margin in between since `Expand` and `CandidateMargin` only grow.
+    struct BandRegion {
+        CraterBand band;
+        Bounds2d inner;
+        Bounds2d outer;
+    };
+
+    BandRegion BandRegionOf(const CraterBand& band) const {
+        return {band, surface_.Expand(region_, CandidateMargin(band.low)),
+                surface_.Expand(region_, CandidateMargin(band.high))};
+    }
+
+    /// `InRegion` with the crater's candidate margin, expanding the region only for craters of the
+    /// band between its inner and outer regions.
+    bool InBandRegion(const BandRegion& region, const Crater& crater) const {
+        if (!(crater.diameter >= region.band.low && crater.diameter <= region.band.high)) {
+            return InRegion(crater, CandidateMargin(crater.diameter));
+        }
+        const Vec2d centre{crater.x, crater.y};
+        if (!surface_.Contains(region.outer, centre)) {
+            return false;
+        }
+        return surface_.Contains(region.inner, centre) ||
+               InRegion(crater, CandidateMargin(crater.diameter));
+    }
+
     std::shared_ptr<const CraterList> DrawCell(const CraterBand& band,
                                                const CellIndex& cell) const {
         if (options_.cellCraters) {