terraingenpy 0.1.1.dev95__tar.gz → 0.1.1.dev115__tar.gz

terraingenpy-0.1.1.dev115/.github/workflows/ci.yml

@@ -0,0 +1,514 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # The version's pre-release suffix: .devN on main (N commits since the last release tag), none on
+  # release tags (which must match CMakeLists.txt) or pull requests.
+  version:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      suffix: ${{ steps.version.outputs.suffix }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - id: version
+        run: |
+          project=$(sed -nE 's/^set\(TERRAINGEN_FULL_VERSION "([0-9]+\.[0-9]+\.[0-9]+)"\)$/\1/p' CMakeLists.txt)
+          suffix=""
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            if [[ "${GITHUB_REF_NAME#v}" != "$project" ]]; then
+              echo "::error::Tag $GITHUB_REF_NAME does not match CMakeLists.txt's version $project"
+              exit 1
+            fi
+          elif [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then
+            if last=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null); then
+              suffix=".dev$(git rev-list --count "$last..HEAD")"
+            else
+              suffix=".dev$(git rev-list --count HEAD)"
+            fi
+          fi
+          {
+            echo "version=$project$suffix"
+            echo "suffix=$suffix"
+          } >> "$GITHUB_OUTPUT"
+          echo "Version $project$suffix"
+
+  lint:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+      - run: python -m pip install pre-commit
+      - run: pre-commit run --all-files --show-diff-on-failure
+      - name: Lint workflows
+        run: docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:1.7.12 -color
+
+  # Build and every test, with the GPU tests on Mesa's lavapipe, the software Vulkan driver, which
+  # TerrainGen uses only when TERRAINGEN_DEVICE names it. The runners have no NVIDIA GPU, so the
+  # CUDA kernels are compiled to PTX but not run.
+  test:
+    name: test (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # The oldest supported Ubuntu, compiler and Python.
+          - { name: ubuntu-22.04-gcc-11, os: ubuntu-22.04, cc: gcc-11, cxx: g++-11, python: "3.10" }
+          - { name: ubuntu-22.04-arm-gcc-11, os: ubuntu-22.04-arm, cc: gcc-11, cxx: g++-11 }
+          - { name: ubuntu-24.04-clang-18, os: ubuntu-24.04, cc: clang-18, cxx: clang++-18 }
+          - { name: macos-14, os: macos-14 }
+          - { name: windows-2022-msvc, os: windows-2022 }
+    env:
+      CC: ${{ matrix.cc }}
+      CXX: ${{ matrix.cxx }}
+      CCACHE_DIR: ${{ github.workspace }}/.ccache
+      TERRAINGEN_DEVICE: "0"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python || '3.12' }}
+      - run: python -m pip install numpy pytest ninja
+      # MSVC on the path for the Ninja generator.
+      - uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
+        if: runner.os == 'Windows'
+      - uses: hendrikmuhs/ccache-action@f09c25b45002a07be2955cbe52e8cee55643f89d # v1.2.24
+        if: runner.os != 'Windows'
+        with:
+          key: ${{ matrix.name }}
+          max-size: 500M
+      - name: Install lavapipe
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends mesa-vulkan-drivers libvulkan1
+          icd=$(find /usr/share/vulkan/icd.d -name 'lvp_icd*.json' | head -n1)
+          echo "VK_DRIVER_FILES=$icd" >> "$GITHUB_ENV"
+          echo "VK_ICD_FILENAMES=$icd" >> "$GITHUB_ENV"
+      - name: Install lavapipe
+        if: runner.os == 'Windows'
+        shell: bash
+        run: .github/scripts/install-lavapipe-windows.sh
+      - name: Install lavapipe
+        if: runner.os == 'macOS'
+        run: |
+          brew install mesa vulkan-loader
+          prefix=$(brew --prefix)
+          icd=$(find "$prefix/share/vulkan/icd.d" -name 'lvp_icd*.json' | head -n1)
+          {
+            echo "VK_DRIVER_FILES=$icd"
+            echo "VK_ICD_FILENAMES=$icd"
+            echo "DYLD_FALLBACK_LIBRARY_PATH=$prefix/lib"
+          } >> "$GITHUB_ENV"
+      - name: Configure
+        shell: bash
+        run: >
+          cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DTERRAINGEN_BUILD_BENCHMARKS=OFF
+          "-DPython_EXECUTABLE=$(python -c 'import sys; print(sys.executable)')"
+          ${{ runner.os != 'Windows' && '-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache' || '' }}
+      - name: Build
+        run: cmake --build build --parallel 4
+      - name: Backends
+        shell: bash
+        run: build/bin/terraingen backends
+      - name: Test
+        run: ctest --test-dir build --parallel 4 --output-on-failure --timeout 1200
+
+  # Line coverage of the library, from the tests on lavapipe; GitHub Pages publishes the report from
+  # main (pages job).
+  coverage:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    env:
+      CCACHE_DIR: ${{ github.workspace }}/.ccache
+      TERRAINGEN_DEVICE: "0"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - run: python -m pip install gcovr numpy pytest ninja
+      - uses: hendrikmuhs/ccache-action@f09c25b45002a07be2955cbe52e8cee55643f89d # v1.2.24
+        with:
+          key: coverage
+          max-size: 1G
+      - name: Install lavapipe
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends mesa-vulkan-drivers libvulkan1
+      - name: Configure
+        run: >
+          cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DTERRAINGEN_COVERAGE=ON
+          -DTERRAINGEN_BUILD_BENCHMARKS=OFF
+          "-DPython_EXECUTABLE=$(python -c 'import sys; print(sys.executable)')"
+          -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
+      # Everything first: the coverage target builds only the test programs, not the command and
+      # examples that the integration tests run.
+      - name: Build
+        run: cmake --build build --parallel 4
+      # The tests four at a time (ctest reads CTEST_PARALLEL_LEVEL), the long examples first.
+      - name: Test and report
+        env:
+          CTEST_PARALLEL_LEVEL: "4"
+        run: cmake --build build --target coverage
+      - name: Summary
+        if: always()
+        run: cat build/coverage/summary.md >> "$GITHUB_STEP_SUMMARY" || true
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: coverage-report
+          path: build/coverage/
+          if-no-files-found: ignore
+          retention-days: 7
+
+  # One job per platform and Python (pyproject.toml's [tool.cibuildwheel] has the rest), so each
+  # platform's wheels build side by side.
+  wheel:
+    name: wheel (${{ matrix.os }}, ${{ matrix.python }})
+    needs: version
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm, macos-15-intel, macos-14, windows-2022]
+        python: [cp310, cp311, cp312]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Version
+        shell: bash
+        run: >
+          sed -i.bak -E 's/^set\(TERRAINGEN_FULL_VERSION "([0-9.]+)"\)$/set(TERRAINGEN_FULL_VERSION "\1${{ needs.version.outputs.suffix }}")/'
+          CMakeLists.txt
+      - uses: pypa/cibuildwheel@b3395e271a35f73dad77f21802abe9b986dfe299 # v4.3.1
+        env:
+          CIBW_BUILD: "${{ matrix.python }}-*"
+        with:
+          output-dir: wheelhouse
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: wheel-${{ matrix.os }}-${{ matrix.python }}
+          path: wheelhouse/*.whl
+
+  # The sdist, then a wheel built from it and imported, as pip does for platforms without wheels.
+  sdist:
+    needs: version
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Version
+        run: >
+          sed -i -E 's/^set\(TERRAINGEN_FULL_VERSION "([0-9.]+)"\)$/set(TERRAINGEN_FULL_VERSION "\1${{ needs.version.outputs.suffix }}")/'
+          CMakeLists.txt
+      - run: python -m pip install build
+      - run: python -m build --sdist
+      - name: Install from the sdist
+        run: |
+          python -m pip install dist/*.tar.gz
+          cd "$RUNNER_TEMP" && python -c "import terraingen; print(terraingen.__version__)" && terraingen backends
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  # The documentation, built against the Linux wheel, for every push and pull request; another
+  # platform's wheel failing does not skip it.
+  docs:
+    needs: wheel
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: wheel-ubuntu-24.04-cp312
+          path: wheel
+      - name: Install Doxygen, TerrainGen and the docs requirements
+        run: |
+          sudo apt-get update && sudo apt-get install -y --no-install-recommends doxygen
+          python -m pip install wheel/*.whl -r docs/requirements.txt
+      - name: Build
+        run: make -C docs build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: site
+          path: site
+          retention-days: 3
+
+  # The documentation with the coverage report under coverage/ (and coverage/badge.json for the
+  # README badge), on GitHub Pages from main. A failed coverage run leaves the report out.
+  pages:
+    needs: [docs, coverage]
+    if: ${{ !cancelled() && needs.docs.result == 'success' && github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: site
+          path: site
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        continue-on-error: true
+        with:
+          name: coverage-report
+          path: site/coverage
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+
+  # The CLI, library, headers and CMake package for each platform as an archive, and Debian packages
+  # (terraingen, terraingen-dev) built on the oldest supported Ubuntu.
+  packages:
+    name: packages (${{ matrix.platform }})
+    needs: version
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { platform: linux-x86_64, os: ubuntu-22.04 }
+          - { platform: linux-aarch64, os: ubuntu-22.04-arm }
+          - { platform: macos-arm64, os: macos-14 }
+          - { platform: macos-x86_64, os: macos-15-intel }
+          - { platform: windows-x86_64, os: windows-2022 }
+    env:
+      ARCHIVE: terraingen-${{ needs.version.outputs.version }}-${{ matrix.platform }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - run: python -m pip install ninja
+      - uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
+        if: runner.os == 'Windows'
+      - name: Version
+        shell: bash
+        run: >
+          sed -i.bak -E 's/^set\(TERRAINGEN_FULL_VERSION "([0-9.]+)"\)$/set(TERRAINGEN_FULL_VERSION "\1${{ needs.version.outputs.suffix }}")/'
+          CMakeLists.txt
+      - name: Build
+        shell: bash
+        run: |
+          cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DTERRAINGEN_BUILD_TESTS=OFF \
+            -DTERRAINGEN_BUILD_BENCHMARKS=OFF -DTERRAINGEN_BUILD_EXAMPLES=OFF \
+            -DTERRAINGEN_BUILD_PYTHON=OFF -DTERRAINGEN_INSTALL=ON
+          cmake --build build --parallel 4
+          cmake --install build --prefix "$ARCHIVE"
+          cp LICENSE README.md CHANGELOG.md "$ARCHIVE/"
+      - name: Archive
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: Compress-Archive -Path "$env:ARCHIVE" -DestinationPath "$env:ARCHIVE.zip"
+      - name: Archive
+        if: runner.os != 'Windows'
+        run: tar -czf "$ARCHIVE.tar.gz" "$ARCHIVE"
+      - name: Debian packages
+        if: runner.os == 'Linux'
+        run: cpack --config build/CPackConfig.cmake -G DEB -B debs
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: packages-${{ matrix.platform }}
+          path: |
+            ${{ env.ARCHIVE }}.zip
+            ${{ env.ARCHIVE }}.tar.gz
+            debs/*.deb
+          if-no-files-found: error
+
+  # The Debian packages installed on clean distributions, where the program must run and list its
+  # backends. Only the Linux packages matter here, so another platform's failure does not skip it; a
+  # missing Linux package fails its download.
+  package-test:
+    name: package-test (${{ matrix.image }}, ${{ matrix.arch }})
+    needs: packages
+    if: ${{ !cancelled() }}
+    runs-on: ${{ matrix.arch == 'aarch64' && 'ubuntu-24.04-arm' || 'ubuntu-24.04' }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        arch: [x86_64, aarch64]
+        image: ["ubuntu:22.04", "ubuntu:24.04", "debian:12"]
+    container: ${{ matrix.image }}
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: packages-linux-${{ matrix.arch }}
+      - name: Install
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends ./debs/*.deb
+      - name: Run
+        run: |
+          terraingen --version
+          terraingen backends
+
+  # The Dockerfile's image, built and tested on the oldest supported Ubuntu; pushed to GHCR from main
+  # (dev) and release tags.
+  docker:
+    needs: [version, lint, test]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Build
+        run: docker build --target dev -t terraingen:test .
+      - name: Smoke test
+        run: |
+          docker run --rm terraingen:test terraingen --version
+          docker run --rm terraingen:test terraingen backends
+          docker run --rm terraingen:test python -c "import terraingen; print(terraingen.__version__)"
+      - name: Push
+        if: github.event_name == 'push'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          image=ghcr.io/${GITHUB_REPOSITORY,,}
+          echo "$GH_TOKEN" | docker login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            version=${GITHUB_REF_NAME#v}
+            tags=("$version" "${version%.*}" latest)
+          else
+            tags=(dev)
+          fi
+          for tag in "${tags[@]}"; do
+            docker tag terraingen:test "$image:$tag"
+            docker push "$image:$tag"
+          done
+
+  # Wheels and the sdist to PyPI by Trusted Publishing (no stored token): X.Y.Z.devN from main,
+  # X.Y.Z from release tags, once every platform's build, tests and packages pass.
+  pypi:
+    needs: [lint, test, wheel, sdist, package-test]
+    if: >
+      github.event_name == 'push' &&
+      (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/terraingenpy/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: wheel-*
+          merge-multiple: true
+          path: dist
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: sdist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  # The "dev" pre-release: main's packages and their checksums, replaced on every push to main, like
+  # the dev Docker tag and the PyPI .devN versions. Marked as a pre-release and never as the latest
+  # release, so versioned releases stay the default.
+  dev:
+    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 dev --repo "$GITHUB_REPOSITORY" --cleanup-tag --yes || true
+          gh release create dev assets/* --repo "$GITHUB_REPOSITORY" --target "$GITHUB_SHA" \
+            --prerelease --latest=false --title "Dev (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]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: "wheel-*"
+          merge-multiple: true
+          path: assets
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: sdist
+          path: assets
+      - 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 create "$GITHUB_REF_NAME" assets/*
+          --repo "$GITHUB_REPOSITORY" --title "TerrainGen ${GITHUB_REF_NAME#v}" --generate-notes

terraingenpy-0.1.1.dev115/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Piecewise uniform size-frequency distributions: counts per diameter band, given absolutely or as shares of a total.
+- Radial wall marks on craters, ridges and grooves down the wall that are strongest where it is steepest.
+- Thomas cluster process for boulder clusters, with Poisson-scattered centres whose clusters add where they overlap.
+- Craters on slopes: floors offset downslope and rims and ejecta lowered upslope (Plescia et al. 2019), and faster wear toward a critical gradient (Roering et al. 1999).
+- Boulders limited to a maximum slope, optionally rolling down steeper ground to gather at its foot.
+- Density maps from GeoTIFFs or constants: a scale, a count in a diameter range, or an areal fraction such as rock abundance, which set crater and boulder densities point by point.
+- Size slope maps that bend boulder sizes into a local power law, from an exponent or a mean diameter map.
+- Crater and boulder catalogs with a completeness limit, above which they stand in for generated features.
+- Configuration reference in the documentation, generated from the schema at build time, and machine-readable value ranges in the schema.
+- Rock albedo: boulders brighter than the regolith (Holt 1981; Marshal et al. 2023), and a speckle of the share of each sample covered by boulders too small to resolve, with the scatter of randomly placed rocks.
+- Slope albedo: steep ground kept immature by mass wasting, its optical maturity rising with slope beyond 20 degrees (Ikeda et al. 2022; Lucey et al. 2014).
+- 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 and upsampled 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 `crop` for GeoTIFF sources that reads only the window it needs while giving the same heights there as the whole file.
+- Upsampling on sources (`Upsampler`, config `upsampling`): how a source's posts become heights between them and at any finer sample spacing, deterministically, so points, tiles and grids at one spacing agree; kernels `nearest`, `bilinear`, `cubic` (the default, the same bits as before), `catmull_rom`, `lanczos3` and `cubic_bspline`, and `diamond_square`.
+- `RegisterUpsampler` (Python `register_upsampler`) names upsampler types of your own, C++ or Python subclasses of `Upsampler`, for configurations to use with their settings.
+- Terrain reports (`ReportGrid`, `ReportToJson`, `TerrainReport`, `LayerTimer`; Python `report_grid`, `report_to_json`, `TerrainReport.to_dict`): height and slope statistics of an evaluated grid in the surface's meters, craters per power-of-2 diameter bin against a target distribution's expected counts, boulder counts and cover, and per-layer timings, as JSON, which the config's `report` output produces.
+- `SyntheticSource` (config source `synthetic`): heights generated from a noise stack plus `elevation_m` over an unbounded plane or the whole body, evaluated at every point, or sampled at posts `pixel_size_m` apart and upsampled like a DEM; an empty stack is flat.
+- `effective_pixel_size_m` on raster sources (`effectivePixelSize`), the cell size a DEM upsampled or smoothed before it was saved truly resolves, which `ResolutionAt` and `source_resolves_px` use.
+- Lanczos (three lobes), Catmull-Rom and cubic B-spline kernels for `Resample`, `SampleRaster` and `ResampleMethod`.
+- `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.
+- Diamond-square upsampling (`DiamondSquareUpsampler`, `"upsampling": {"type": "diamond_square"}`): random midpoint displacement of a source's posts to finer spacings, as PANGU expands DEMs (Martin et al. 2014), keeping every coarser node so nested grids share their cells, with bilinear or Catmull-Rom (`interp`) refinement and the scale and fractal dimension estimated from the posts when not given.
+- Spectral continuation layer: detail finer than a DEM that continues its fitted power-law spectrum (radially averaged, Hann-windowed PSD) to shorter wavelengths as sparse Gabor noise, tapered in at the DEM's Nyquist wavelength so resolved scales gain nothing; an alternative to diamond-square upsampling without lattice artifacts, with grids, tiles and points in agreement.
+- Roughness and noise layers that estimate their settings from the base with `estimate_from_base`: the Hurst exponent and RMS height difference of its variogram at its native cells, extrapolated to the roughness baseline or matched at each noise layer's wavelength; explicit values override the estimates.
+- 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.
+- Terrain meshes take `cutouts`, a `skirt` and a frame `site`.
+- Output type `report` (`ReportOutput`) with an optional `path`: `GenerateFromConfig` returns the report (`GeneratedOutputs::report`, Python `GeneratedOutputs.report`) with a `GridReport` per grid with heights, crater bins against the first crater layer's density and boulder counts where a list output placed them, per-layer timings, backend, threads, layer seeds and version, and `WriteOutputs` writes it as JSON.
+- `GetMeshSize` and `FillMesh` (Python `get_mesh_size`, `fill_mesh`) size and write a height mesh into caller buffers laid out as Chrono's ChVector3d and ChVector3i arrays or NumPy (N, 3) float64 and (M, 3) int32 arrays, with no copy; `FillHeights` (Python `fill_heights`) evaluates a terrain into a caller buffer; `TriangleMesh.positions` and `TriangleMesh.triangles` are NumPy views of a mesh without a copy.
+- Configuration keys `crop` (`min_x`, `min_y`, `max_x`, `max_y` in CRS units) on raster sources to read only a window of a DEM.
+- Manual-only boulder layers: `generate_random` off (`BoulderLayerOptions::generateRandom`) places only the `manual` boulders, with no random boulders or crater blocks, draws no candidates and needs no valid sizes or coverage; `CraterLayer::Manual` and `BoulderLayer::Manual` (Python `CraterLayer.manual`, `BoulderLayer.manual`) make layers of only the given craters or boulders.
+- `source_resolves_px` on craters, secondaries, boulders, noise, dunes and bedforms: features at least that many source cells across, by diameter, wavelength or dune width, are already in the source data, so only smaller ones are added at each point, each raster of a chain giving its own limit and none where no raster has data; ignored on synthetic sources, `null` adds them all. It defaults to 4 on craters, secondaries, dunes and bedforms and to none on boulders and noise.
+- `SourceResolvedLimit` and `LayerResolvedLimit` (Python `source_resolved_limit`), the per-point feature size a source already holds, and `sourceResolvesPixels` on `CraterLayerOptions`, `SecondaryCraterOptions`, `BoulderLayerOptions`, `DuneOptions` and `BedformOptions` (Python `source_resolves_px`), applied when the layer is given the source: `CraterLayer`, `SecondaryCraterLayer`, `BoulderLayer`, `DuneLayer`, `BedformLayer` and `NoiseRelief` take an optional `source` (Python `source=`), and `NoiseRelief` its `sourceResolvesPixels`.
+- `fade_px` and `fade_shape` on crater `apply` and boulder layers (Python `fade_px`, `fade_shape`): the resolution fade as a list of its start and end output samples and its curve.
+
+### 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. 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.
+- Boulder ejecta come from every crater layer before the boulder layer, not only the last one.
+- The boulder layer's `exposure_spacing` key is now `ground_spacing` (Python `ground_spacing`), the spacing of every ground read the layer makes.
+- Crater shaping has one implementation, the kernel, on every surface; craters on bodies and custom profiles may differ from before in the last digits.
+- Random streams and hashes are unified, so boulder, albedo, dune, bedform and pavement outputs for a given seed differ from earlier versions; their statistics are unchanged.
+- Every evaluation defaults to all threads, including `EvaluateAt`, `EvaluateTile` and Python `evaluate_tile`.
+- The `materials` module is folded into `pipeline` (material maps) and `albedo` (Hapke photometry); include `terraingen/pipeline/materials.h` and `terraingen/albedo/photometry.h`.
+- Python: `ExposureField.exposure` takes `(x, y, spacing=0.0, terrain=None, layers=0)` like the other ground queries, unbounded options read as `None` instead of infinity, `write_outputs` returns paths, a subclass missing a required method raises `TypeError`, and `CraterFeatures.write` is `write_list`.
+- Python names: `cell_of` is `cell_at`, `point_of` is `coordinates`, `level_for` is `resolving_level`, `outline_of` is `irregular_outline`, `min_diameter_for_count` is `count_limit_diameter`, `singer_range_for_size` is `singer_max_range`, `SplotchOptions` is `SplotchAlbedoOptions` and `SlopeMaturityOptions` is `SlopeAlbedoOptions`.
+- The CI coverage job builds at `-O1` without atomic counters, so it caches and runs several times faster.
+
+- Density maps that count every feature take out the secondaries thrown from a layer's craters and the blocks thrown out around craters, and boulder patches and bedrock keep a map's mean, so nothing is counted twice.
+- Boulder models settle onto a stable face by default instead of balancing on an edge or corner.
+- Boulder generation logs under boulders rather than craters.
+- Crater and boulder generation summaries log at debug level; `terraingen` ends with one line counting the files written instead of listing each, and feature outputs log how long they took.
+- Generation logs each grid as it is evaluated, with the time of every layer, the albedo and the materials, and ends with each step's total and share.
+- Faster boulders: the ground beneath them is read in one batch, outputs over one region share the boulders placed for the first, models are placed in parallel, ejecta craters are found through a spatial index and shapes skip the roughness of fracture planes that cannot reach a vertex. The hero demo runs in about 10 s instead of 276 s.
+- Martin, Parkes and Dunstan is the default crater profile.
+- Breaking: crater layers' `generate` is now `generate_random` (`CraterLayerOptions::generateRandom`, Python `generate_random`): it draws random craters from the size distribution, and manual craters are placed either way; the old key is rejected.
+- Breaking: `HeightMesh` and `HeightMeshOptions` are now `BuildMesh` and `BuildMeshOptions`, and Python `height_mesh` is now `build_mesh`; a height mesh holds at most INT32_MAX vertices.
+- Breaking: the configuration's `base` is now `source` (the old key is rejected), with types `raster`, `chain` and `synthetic`; without one the terrain starts from a flat synthetic source at 0 m. Python `Config.base_grid` is `source_grid`, and `ConfigSummary::base` is `source`; `DescribeSource` gives no grid for a source without bounds.
+- Breaking: sources take the sample spacing, in their own units: `Source::Fill(heights, spacing)` and `Source::HeightAt(x, y, spacing)`, and Python `Source` subclasses define `height_at(x, y, spacing)` and `fill(heights, spacing)`; `Fill(heights)` keeps the grid's cell size. A source without bounds gives a grid without cells (`BoundedGrid`), and `Evaluate(terrain)` needs a grid for it.
+- Breaking: raster sources upsample instead of resampling: `RasterSourceOptions` and `GeoTiffSourceOptions` take an `upsampler` and an `effectivePixelSize` (Python `upsampler=`, `effective_pixel_size=`), the GeoTIFF `region` is `crop`, and a raster source's grid is always its file's; evaluate it over a finer grid for finer cells.
+- Breaking: outputs give their area as `pixel_size_m` and `extent_m` (`extent_deg` on a body), `{"center": [x, y], "size": [w, h]}` or `{"min": [x, y], "max": [x, y]}`, in place of `region` (and of `spacing` on crater lists, boulder lists and boulder models); the grid starts at the extent's min corner, is snapped outward to whole cells and sampled at cell centers. Both default to a raster or chain source's extent and cell size, and are required without one (`OutputAreaSpec`, `ExtentSpec`, `config::SnappedGrid`).
+- Breaking: `terrain_mesh` outputs take `skirt_m`, `site_deg` as [lon, lat] and `cutouts` as `{"min": [x, y], "max": [x, y]}` boxes, for `skirt`, `site_x`/`site_y` and `min_x`/`max_x` boxes.
+- Breaking: every output's `path` is optional; without one the result is returned and nothing is written. `GenerateFromConfig` (Python `generate_from_config`) returns everything the outputs ask for, each computed once: `GeneratedGrid` holds the `grid`, heights, albedo, materials, photometry, placed craters and boulders and the terrain mesh, `GeneratedOutputs` the body mesh or ICQ model, `Grid()` and `Find()`; `WriteOutputs` (Python `write_outputs`) only writes it. Python `GeneratedGrid` values are views without a copy.
+- Breaking: renames, with no aliases: `Terrain` is `TerrainGenerator` (`pipeline/generator.h`), `EvaluateAt` and `EvaluatePoints` are `HeightAt` and `HeightsAt`, `ValidateTerrain` is `ValidateGenerator`, `BuildTerrain` is `BuildGenerator`, `GenerateTerrain` is `GenerateFromConfig` returning `GeneratedOutputs` (its `terrain` is `generator`), `TerrainConfig` is `TerrainGenConfig`, and `pipeline/height_mesh.h` is `pipeline/mesh_build.h`. Python follows C++ names one to one: `TerrainGenerator`, `TerrainGenConfig`, `GeneratedOutputs`, `height_at`, `heights_at`, `build_generator`, `generate_from_config`, `parse_config`, `load_config` and `config_to_json` (for `Config.from_json`, `Config.load` and `to_json`), `get_version`, `get_api_version`, `get_build_info`, `fillet_height`, `perlin_noise3_precise`, `TriangleMesh.subdivide`, `Raster.no_data`, `GeoTiffInfo.no_data`, `ValueDistribution.Kind`, `CraterGenerationOptions.d_min` and `d_max`, and keywords `generator=` (for `terrain=`), `generated=`, `heights=` (`fill_heights`), `random=` (samplers), `d_min=`/`d_max=`, `requested=`, `sink=`, `inner=`, `no_data=`, `lon_deg=`/`lat_deg=`.
+- `NoiseLayersAt` moves to `terraingen/sources/synthetic_terrain.h`, and `HasData`, `Variogram` and `FitDeviogram` to `terraingen/raster/variogram.h`.
+- Breaking: on a raster or chain source, craters, secondaries, dunes and bedforms leave out by default what is at least 4 source cells across (`source_resolves_px`); set it to `null` for the old output.
+- Breaking: crater and boulder size keys carry their units, in configurations and the Python options classes alike; the old keys are rejected. Craters: `min_diameter` is `min_diameter_m`, `max_diameter` is `max_diameter_m`, and `apply.fade` (`start_samples`, `end_samples`, `shape`) is `apply.fade_px` with `apply.fade_shape`. Secondaries: `min_diameter_m`, `max_diameter_m`, `min_primary_diameter_m`, `max_primary_diameter_m`. Density maps: `min_diameter_m`, `max_diameter_m`. Boulders: `min_diameter_m`, `max_diameter_m`, `fade_px` with `fade_shape` (for `fade`), `ground_spacing_m`, `bedrock_mean_size_m`, `roll_distance_m`, `patches.size_m`, `clusters.spacing_m`, `clusters.radius_m`, `ejecta.min_crater_diameter_m`, `ejecta.regolith_thickness_m`, `fragmentation.min_diameter_m`, `models.min_diameter_m`, `models.max_diameter_m`, `models.min_px` (for `min_samples`), `models.max_px` (for `max_samples`), `relief_range.min_diameter_m`, `relief_range.max_diameter_m` and `slope_map.reference_diameter_m`.
+- Breaking: the `region` layer is now `masked` (the old type is rejected), and `RegionLayer` is `MaskedLayer` (`terraingen/layers/masked.h`, Python `MaskedLayer`); `RegionShape::centre` is `center`.
+
+### 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.
+- Crater layers over other layers read the ground beneath their slopes and datums in batches rather than point by point, and point batches are evaluated in spatial order: the hero demo went from 433 s to 11 s with the same output.
+- Secondary craters run on the GPU backend the terrain asks for instead of always on the CPU.
+- A crater layer after a boulder layer no longer refits crater datums for every batch of ground reads.
+- Tilted boulders are no longer cut off at tile edges and point queries.
+- Crater and boulder lists honour a spacing finer than the grid.
+- Zero-area regions and crater sizes below the models' range are rejected with a clear error instead of failing during generation.
+
+### Removed
+
+- `GridRegionSpec`, `config::RegionGrid` and `config::FeatureOutput`; an output's area is an `OutputAreaSpec` and `config::OutputSpacing` takes the source's grid and the surface.
+- Tile schemes, tiles and the tile cache (`TileScheme`, `TileKey`, `EvaluateTile`, `EvaluateTiles`, `TileCache`, in C++ and Python): level of detail belongs to the renderer, and any grid evaluated alone already equals the same cells of a larger one. The tile examples go too; the point query examples move to a `queries` category.
+- Resampling raster sources to a pixel size and low-passing them: `pixelSize`, `resampling` and `lowPass` on `RasterSourceOptions` and `GeoTiffSourceOptions`, and the config keys `pixel_size`, `resampling` and `low_pass` on raster sources; upsampling over a finer grid replaces them.
+- `DetailLayer` and the `dem_detail` layer, which only restored the detail a low-passed source removed.
+- The crater layer key `unresolved_pixels_across` (`CraterLayerSpec::unresolvedPixelsAcross`): `source_resolves_px` replaces it.
+- Python `crater_blend_weight` (use `CraterBlend.weight`), `CraterAgeModel.lifetime_gyr` (use `lifetime_at`) and the flat selection aliases on crater irregularity, crater albedo and secondary options (use `selection`).
+
+## [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