argus-survey 0.1.0__tar.gz

argus_survey-0.1.0/.copier-answers.yml

@@ -0,0 +1,21 @@
+# Managed by Copier — do not edit by hand.
+# Run `copier update` in this repo to pull template changes.
+_commit: '9252058'
+_src_path: ../argus-pkg-template
+author: smk762
+cli_name: argus-survey
+description: 'Point-cloud toolkit for land surveyors: QA, ground, DTM/DSM, contours,
+    volumes, change and accuracy with recorded datums'
+dockerfile: Dockerfile
+github_owner: smk762
+has_cli: true
+has_server: true
+image_name: argus-survey
+package_name: argus_survey
+post_test: ''
+project_name: argus-survey
+python_min: '3.11'
+ruff_pin: 0.15.16
+test_extras: dev
+version_build_arg: false
+

argus_survey-0.1.0/.cursor/rules/agent-coding-packs.mdc

@@ -0,0 +1,29 @@
+---
+description: Fetch ai-code-auditor coding packs for argus-survey before changing code
+alwaysApply: true
+---
+
+<!-- ai-audit:agent-packs:start -->
+# Agent coding packs
+
+Do not wait for a pasted brief — fetch the audit packs for `argus-survey` yourself.
+
+The audit API base URL is `$AI_AUDIT_PUBLIC_BASE_URL`. The real host/IP is in the local `.env`
+(see `.env.example`, placeholder `http://<AUDIT_HOST>:8765`); read it there, don't guess.
+
+1. **Bundle (one call):** `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/bundle?repo=argus-survey`
+   (world model + ranked specialist packs + token-capped `briefs_markdown`;
+   optional `&token_budget=2500&q=<keyword>&limit_specialists=5`).
+   CLI equivalent: `ai-audit packs --bundle --repo argus-survey`.
+2. **Claim** the specialist pack you pick:
+   `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>/status` `{"status":"claimed"}`
+   (send `X-API-Token: $AI_AUDIT_API_TOKEN`).
+3. **Fix:** `ai-audit repair --pack-id <id>` (agent-composer repair loop; fetches the pack for you;
+   HTTP: `POST http://127.0.0.1:9150/api/repair/run` `{"pack_id":"<id>","mode":"review"}`),
+   or read `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>` / `.../brief` and implement it yourself.
+4. **Close:** `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/validate_patch` `{"repo":"argus-survey","patch":"<diff>","pack_id":"<id>"}`
+   — a passing run marks the pack `resolved`.
+
+World-model constraints (ownership, boundaries, scan branch `dev`) win over guesswork.
+Full flow: ai-code-auditor `AGENTS.md`.
+<!-- ai-audit:agent-packs:end -->

argus_survey-0.1.0/.dockerignore

@@ -0,0 +1,19 @@
+# NOTE: .git is deliberately *not* ignored -- hatch-vcs reads the version from
+# git history at build time.
+.github
+.venv
+venv
+dist
+build
+*.egg-info
+**/__pycache__
+**/*.py[cod]
+.pytest_cache
+.ruff_cache
+.coverage
+htmlcov
+
+# Local data and job output: mounted at run time, never baked into the image
+.env
+data
+jobs

argus_survey-0.1.0/.env.example

@@ -0,0 +1,36 @@
+# Copy to .env. compose.yaml reads it (`cp .env.example .env`); outside compose, export what you need
+# (not by sourcing the whole file: UID is read-only in bash, so `. .env` fails on it).
+
+# ── Compose host ─────────────────────────────────────────────────────
+# Your uid/gid (`id -u`, `id -g`), so job files on the mounts are yours, not root's.
+UID=1000
+GID=1000
+# Host directories compose mounts at /data/in (read-only: point clouds, polygons,
+# check points, design surfaces) and /data/jobs (job output). Defaults: ./data/{in,jobs}.
+#SURVEY_IN_HOST=/srv/survey/incoming
+#SURVEY_JOBS_HOST=/srv/survey/jobs
+# Host address the API binds to (127.0.0.1 keeps it off the network).
+#SURVEY_BIND=127.0.0.1
+# Tag compose gives the image it builds from this checkout.
+#SURVEY_IMAGE=argus-survey:local
+
+# ── Server ───────────────────────────────────────────────────────────
+# Host port (suite: lens 8100, curator 8101, quarry 8102, forge 8103, proof 8104,
+# atlas 8105, safelight/darkroom 8106).
+SURVEY_PORT=8107
+# Browser origins allowed by `argus-survey serve --cors` (comma-separated).
+#SURVEY_CORS_ORIGINS=http://localhost:3000
+
+# ── Safety posture ───────────────────────────────────────────────────
+# The API is read-only unless this is 1/true/yes/on: POST /jobs/{id}/{step}
+# returns 403 and GET /health reports read_only=true. The CLI needs no flag.
+#SURVEY_ALLOW_PROCESS=1
+
+# ── Storage (container paths; the image sets these, compose mounts onto them) ──
+SURVEY_DATA_DIR=/data/in
+SURVEY_JOBS_DIR=/data/jobs
+
+# ── Agent tooling (not read by this service) ──
+# ai-code-auditor audit API base that AGENTS.md tells coding agents to use.
+# Put the real host/IP in your local .env, never here.
+# AI_AUDIT_PUBLIC_BASE_URL=http://<AUDIT_HOST>:8765

argus_survey-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+
+# Standalone rather than the shared smk762/argus-ci python-ci.yml: the suite
+# shells out to PDAL/GDAL/PROJ, which no distro packages consistently any more
+# (PDAL is absent from Ubuntu 24.04/26.04 and Debian). So the tool-backed tests
+# run *inside the image* — the same conda-forge lockfile and datum grids users
+# get — with SURVEY_TEST_REQUIRE_TOOLS=1 turning every tool skip into a failure.
+# The pure-Python suite also runs on the oldest and newest supported Pythons.
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: ruff check
+        run: uvx ruff@0.15.16 check src/ tests/
+      - name: ruff format --check
+        run: uvx ruff@0.15.16 format --check src/ tests/
+
+  unit:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs derives the dev version from git history
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --locked --all-extras --python ${{ matrix.python-version }}
+      - run: uv run --no-sync pytest --tb=short -q
+
+  image-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: docker/setup-buildx-action@v3
+      - name: Build the test image (runs `doctor --strict` inside)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          build-args: EXTRAS=server,cli,dev
+          tags: argus-survey:test
+          load: true
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      # Same container setup as compose's `test` service, but run directly so the image
+      # just built from the GHA layer cache is used (compose's pull_policy: build would rebuild).
+      - name: Full suite against real PDAL/GDAL/PROJ
+        run: |
+          docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/src" -w /src \
+            -e HOME=/tmp -e PYTHONPATH=/src/src -e PYTHONDONTWRITEBYTECODE=1 -e SURVEY_TEST_REQUIRE_TOOLS=1 \
+            argus-survey:test python -m pytest -q -p no:cacheprovider
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, unit, image-test]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 14

argus_survey-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,114 @@
+name: Release to PyPI
+
+# Top-level (non-reusable) on purpose: PyPI trusted publishing cannot run inside
+# a reusable workflow. Keep this file in sync across the suite via `copier update`.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test-install:
+    runs-on: ubuntu-latest
+    needs: build
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Install wheel and smoke-test import
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install dist/*.whl
+          uv run --no-sync python -c "import argus_survey; print(f'argus-survey {argus_survey.__version__} OK')"
+
+  publish-testpypi:
+    runs-on: ubuntu-latest
+    needs: test-install
+    environment: testpypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    # Ordered *after* the TestPyPI rehearsal so its outcome is visible first, but
+    # deliberately not gated on it. A TestPyPI-only fault — a missing trusted
+    # publisher, an index outage — must not silently withhold the real release:
+    # that failure mode shipped argus-proof images for two tags with no wheel on
+    # PyPI, and nothing surfaced it because publish-image is independent.
+    # Only the build + install gate is required; a TestPyPI failure still marks
+    # the whole run failed, so the problem stays loud.
+    needs: [test-install, publish-testpypi]
+    if: "!cancelled() && needs.test-install.result == 'success'"
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-image:
+    runs-on: ubuntu-latest
+    needs: test-install
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs reads the tag from git history
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/argus-survey
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

argus_survey-0.1.0/.github/workflows/suite.yml

@@ -0,0 +1,11 @@
+name: Suite
+on:
+  push:
+    branches: [dev, main]
+    tags: ["v*"]
+  pull_request:
+    branches: [dev, main]
+
+jobs:
+  suite:
+    uses: smk762/argus-ci/.github/workflows/suite-check.yml@v1

argus_survey-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+# hatch-vcs writes this at build time (version derived from git tags)
+src/argus_survey/_version.py
+
+# Local job output
+jobs/
+
+# Docker Compose: host settings and the default mount dirs (kept by their .gitkeep)
+.env
+data/*/*
+!data/*/.gitkeep

argus_survey-0.1.0/AGENTS.md

@@ -0,0 +1,24 @@
+<!-- ai-audit:agent-packs:start -->
+## Agent coding packs (ai-code-auditor)
+
+Do not wait for a pasted brief — fetch the audit packs for `argus-survey` yourself.
+
+The audit API base URL is `$AI_AUDIT_PUBLIC_BASE_URL`. The real host/IP is in the local `.env`
+(see `.env.example`, placeholder `http://<AUDIT_HOST>:8765`); read it there, don't guess.
+
+1. **Bundle (one call):** `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/bundle?repo=argus-survey`
+   (world model + ranked specialist packs + token-capped `briefs_markdown`;
+   optional `&token_budget=2500&q=<keyword>&limit_specialists=5`).
+   CLI equivalent: `ai-audit packs --bundle --repo argus-survey`.
+2. **Claim** the specialist pack you pick:
+   `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>/status` `{"status":"claimed"}`
+   (send `X-API-Token: $AI_AUDIT_API_TOKEN`).
+3. **Fix:** `ai-audit repair --pack-id <id>` (agent-composer repair loop; fetches the pack for you;
+   HTTP: `POST http://127.0.0.1:9150/api/repair/run` `{"pack_id":"<id>","mode":"review"}`),
+   or read `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>` / `.../brief` and implement it yourself.
+4. **Close:** `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/validate_patch` `{"repo":"argus-survey","patch":"<diff>","pack_id":"<id>"}`
+   — a passing run marks the pack `resolved`.
+
+World-model constraints (ownership, boundaries, scan branch `dev`) win over guesswork.
+Full flow: ai-code-auditor `AGENTS.md`.
+<!-- ai-audit:agent-packs:end -->

argus_survey-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/) (tags are the source of truth via hatch-vcs).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-13
+
+First release, published to PyPI and GHCR.
+
+### Changed
+- Accuracy follows the text of ASPRS Positional Accuracy Standards, Edition 2, Version 2 (2024): §7.16.1 statement wording (with the reduced-checkpoint statement below 30 points), min/max/median (§7.16), bias flagged above 25 % of the target RMSE and blunders beyond 3 × it (§7.2), a horizontal-accuracy note for photogrammetry (§7.6) (#3).
+
+### Added
+- `export --points las|e57 [--polygon P] [--thin S]` (and `POST /jobs/{id}/export`): the classified cloud as uncompressed LAS 1.4 (CRS in the header) or double-precision E57 for ReCap / Civil 3D, with a notes file stating the CRS, vertical datum, grid-to-ground factor and ASPRS class counts; streaming, count-reconciled; recorded in `job.json` `exports` (#8).
+- Grid-to-ground: ingest records `scale_factors` (point scale k and convergence from `proj -V`, k's range over the extent, height factor R/(R+h) from the ellipsoidal height via the explicit geoid operation, combined factor); volume and cut/fill reports add ground-scaled areas and volumes (#12).
+- E57 ingest (terrestrial scanners) via `readers.e57`; `--s-srs` required (E57 has no CRS); new source type `terrestrial` (#20).
+- `ground --preset stockpile` (SMRF slope 1.0) keeps piles at the angle of repose as ground (#18).
+- `surfaces --chm-method radius`: highest point within res·√2, for sparse canopy at fine resolution (#19).
+- Wire contract for UIs: `argus-survey schema [--check]` writes `schema/survey-wire.schema.json` (job.json, digests, health, every request body and SSE event) with `argus_cortex.wire`; the API's request bodies moved to `models.py`, and `/health` and the SSE payloads are built from the models. [argus-sightline](https://github.com/smk762/argus-sightline) generates its types from it.
+- `volume` and `cutfill` over the API take a polygon drawn on the map (`polygon_geojson`, a WGS 84 GeoJSON geometry, plus an optional zone `name`) instead of a file, the way `profile` takes a drawn line.
+- `argus-survey synth DIR --kit` (`make demo-kit`): every demo input with known answers: two epochs, check points, stockpile and pad polygons and a design surface, plus `kit-truth.json`.
+- Viewer (`/viewer`): MapLibre map of surfaces, density, change, contours and coverage; the classified cloud streamed from the COPC (copc.js + laz-perf + three.js) coloured by elevation/class/intensity; job CRS and warnings; profile drawing when processing is allowed.
+- Docs: README walkthrough on public USGS 3DEP data (`make sample`), WA datum table, runbook, data sources, argus-atlas showcase. `make demo`/`up`/`down`.
+- Ingest refuses geographic and Web Mercator working CRSs (Mercator metres are not ground metres).
+- API on :8107 (`argus-survey serve`, compose `serve`): health, doctor, inputs, jobs, products by kind with HTTP Range (COPC streams), web map views (Web Mercator PNG + corners, WGS 84 GeoJSON), and `POST /jobs/{id}/{step}` for every step streaming Server-Sent Events. Read-only unless `SURVEY_ALLOW_PROCESS`; inputs are names under `SURVEY_DATA_DIR`.
+- Docs: README API route table, step names and body models (pointing at the wire schema); how check points are split into NVA/VVA; the 0.10 m default LoD; `synth DIR --kit` syntax; which commands take `--job`/`--out`. SPEC.md marked as the historical v0 brief, with where it diverges.
+
+## [0.1.0rc1] - 2026-10-31
+
+First release candidate: a usable CLI (milestones 1–5 of the build plan).
+
+### Added
+- `report`: one self-contained, printable `report.html` per job (no JavaScript, embedded thumbnails), with a red banner when the vertical datum was assumed, every product's SHA256, figures linked to the commands that produced them, and the full command log. `run` now ends with it.
+- Scaffold from argus-pkg-template; Docker image on Ubuntu 26.04 with PDAL 2.10 / GDAL 3.13 / PROJ 9.9 from a pinned conda-forge lockfile, and datum grids (AUSGeoid2020, AUSGeoid09, GDA94→GDA2020 conformal+distortion, AGQG, GEOID18) verified by SHA256.
+- `argus-survey doctor`: tool versions, PDAL/GDAL drivers and algorithms, datum grids, and the surveyor transformations (GDA2020/GDA94 → MGA + AHD, NAD83(2011) → NAVD88) resolved without ballpark fallbacks.
+- One subprocess runner that records every command, and explicit coordinate-operation selection that refuses rather than falling back to a ballpark transform.
+- `info` and `ingest`: CRS records (compound, ellipsoidal, user-supplied, assumed), `--t-srs` through an explicit PROJ operation with axis-order compensation, crop polygons with CRS sanity checks, streaming ingest + untwine COPC for drone-scale clouds, point-count reconciliation, LiDAR/photogrammetry detection.
+- `qa`: density (mean/p5/p50/p95), class and return histograms (ASPRS names), outlier count, coverage boundary, density gaps.
+- `ground`: SMRF (default) or CSF after statistical outlier flagging, per buffered tile with an exact partition check; every point kept.
+- `surfaces`: DTM/DSM/CHM on a snapped grid, void masks and void % of the covered area, optional void fill, hillshade, resolution warning from ground density.
+- `contours`: GPKG + GeoJSON with index contours. `run`: the whole chain.
+- `volume` (stockpiles: plane / lowest-perimeter / surface base), `cutfill` (design vs surface), `change` (DoD with LoD, optional polygon), `accuracy` (ASPRS ed. 2: NVA/VVA RMSE, check-point accuracy, ≥30 rule, transformed check points), `profile` (CSV + SVG). One volume engine with fractional boundary cells; analytic tests (cone on a tilted plane at three resolutions, wedge, cut/fill signs, voids).
+- `synth`: synthetic survey scenes with analytically known answers (used by the tests and for demos).

argus_survey-0.1.0/CLAUDE.md

@@ -0,0 +1,101 @@
+# CLAUDE.md — argus-survey
+
+Guidance for AI agents working in this repo. Human-facing usage lives in [README.md](README.md); this file is the orientation an agent needs to change code safely.
+
+## What this is
+
+A point-cloud toolkit for **land surveyors** (first audience: Western Australian civil surveyors — MGA2020 zones 49–51, PCG2020 and the other WA LSG2020 grids, AHD via AUSGeoid2020). Input is LiDAR, drone photogrammetry or terrestrial-scanner points (LAS/LAZ/COPC, E57); output is what a surveyor hands over: QA report, ground classification, DTM/DSM/CHM, contours, stockpile volumes, cut/fill, profiles, change between epochs and an accuracy statement against check points (ASPRS ed. 2, NVA + VVA). Every run is traceable: every datum, operation, pipeline and argv is recorded in `job.json`.
+
+It is judged on **correct datums, honest accuracy numbers and reproducible outputs**, not visuals. Prefer one deliverable done properly over three done loosely. It is a standalone peer in the Argus suite (port **8107**); its rasters are plain GeoTIFFs that `argus-atlas controls --dem` can consume. No code dependency on atlas.
+
+## Argus suite
+<!-- argus-suite: keep this block; argus-ci checks for it -->
+This repo is part of the Argus suite. The suite map below lists every sibling and what it owns; check it before
+building something a sibling may already do. **On every release, update this repo's row and capabilities in
+argus-cortex's SUITE.md** (a PR to argus-cortex in the same release).
+
+@../argus-core/SUITE.md
+
+Not checked out? Read https://github.com/smk762/argus-cortex/blob/main/SUITE.md
+
+## Toolchain (read before touching Docker/CI)
+
+- **PDAL, GDAL and PROJ come from conda-forge**, pinned by `env/geo-linux-64.lock` (explicit URLs + md5), generated from `env/geo.yml` by `make geo-lock`. PDAL is not packaged by Debian or Ubuntu (24.04 and 26.04 both lack it), so "apt install pdal" is not an option; one conda-forge stack also guarantees PDAL links the same GDAL/PROJ whose CLIs we call. The image is `ubuntu:26.04` + that env at `/opt/geo` + Ubuntu's Python 3.14 in `/opt/venv`.
+- **Never pip-install PDAL/GDAL/rasterio/laspy/pyproj.** The package only shells out to `pdal`, `gdal*`, `ogr2ogr`, `projinfo`. The unified `gdal` CLI (≥ 3.11) supplies `raster calc`, `raster zonal-stats`, `raster pixel-info -r bilinear` and `raster fill-nodata`, so no Python GDAL bindings are needed (the spec's `gdal_calc.py`/`gdallocationinfo` are replaced by these on purpose).
+- **Datum grids** are fetched at image build from cdn.proj.org and verified against `env/proj-grids.sha256` (AUSGeoid2020, AUSGeoid09, GDA94→GDA2020 conformal+distortion, AGQG/AVWS, GEOID18). At run time `PROJ_NETWORK=OFF`, and `tools.run` forces it off for every child.
+- `argus-survey doctor --strict` runs as the last image build step, so an image without a working toolchain cannot be built.
+
+## Layout
+
+`src/argus_survey/`:
+
+- `models.py` — Pydantic v2 wire types. **`JobSidecar` (`job.json`) is the API contract.** `SURVEY_VERSION` is its schema version. The API request bodies, `HealthInfo` and the SSE event payloads live here too; `WIRE_MODELS` → `schema/survey-wire.schema.json` (`argus-survey schema`; `tests/test_wire.py` fails when it is stale). [argus-sightline](../argus-sightline) generates its TypeScript types from that file, so a wire change means: regenerate, commit, then `npm run wire:local ../argus-survey` (or `wire:pull` after a tag) there.
+- `config.py` — `SURVEY_*` env knobs, `process_allowed()`, `resolve_under_root()` (the API's path fence, ported from atlas).
+- `tools.py` — **the one subprocess runner** (`run`, `run_json`, `pdal_pipeline`), `versions()`, PROJ search paths/grid lookup, `doctor()`.
+- `crs.py` — `select_operation()`: explicit coordinate-operation choice (see gotchas); `record_from_projjson()` (compound/3D/BoundCRS/foot units → `CrsRecord`), `pdal_coord_op()` (axis-order compensation), `promote_3d()`, `require_metric()`, `lonlat_bbox()`.
+- `jobs.py` — `JobStore`, strict id charset, and `Job`: `sink` (runner → sidecar, persisted per command), `add_product` (SHA256), `step()` (timings), `require_crs(height=)` (rule 1's refusal).
+- `ingest.py` — `info_report`, `ingest`: pin inputs, resolve source CRS (`--s-srs`, `--assume-vertical EPSG:x|ellipsoidal`), resolve target (`--t-srs`; a 2D target keeps the source heights explicitly), select the operation, then per input a **streaming** PDAL pipeline (projpipeline → crop → stats → LAZ) and **untwine** → `points.copc.laz`; counts reconciled, LiDAR/photogrammetry detected from returns/RGB.
+- `synthetic.py` — seeded analytic scenes (tilted plane, cone stockpile πr²h/3, building, trees; truth in `UserData`) and check points; `argus-survey synth`. The test fixtures *and* the demo data. `write_kit` (`synth DIR --kit`) writes every input the UI's guided demo needs plus `kit-truth.json`. Stockpiles and change are measured on the **DSM**: ground filtering (correctly) removes a pile from the DTM, which then reads ~10 % low on the kit's cone.
+- `grid.py` — `snap()` (origin = floor(min/res)·res, so epochs share cells), `same_grid`/`aligned`, writers.gdal and `-te/-tr` options.
+- `rasters.py` — `gdalinfo -json` facts, exact `stats()` (with `GDAL_PAM_ENABLED=NO`), `read_values()` (ENVI raw → `array`, for modest rasters), `calc()` (`gdal raster calc`), `sample()` (`gdal raster pixel-info -r bilinear`, batch), `set_crs()`.
+- `tiling.py` — buffered tiles for non-streamable PDAL filters; cores are half-open so they partition the plane, and parts **must** add up to the source count before untwine merges them.
+- `qa.py` — streaming stats + hexbin boundary (edge sized from density) + count raster; density percentiles, gaps (25% of median by default), outliers counted per tile (3σ).
+- `ground.py` — per tile: reset classes → outliers (class 7) → SMRF/CSF ignoring 7; photogrammetry returns normalised 1-of-1 (recorded); ground density/spacing.
+- `surfaces.py` — DTM (IDW r=res·√2 of class 2), DSM (binned max; first returns for LiDAR), CHM (tiled hag_nn → binned max), void masks (1/0/255) and void % of coverage, optional fill re-masked to coverage, hillshade.
+- `contours.py` — gdal_contour → GPKG with `idx` (index contours) → GeoJSON.
+- `vectors.py` — polygons/lines into the job CRS (refuses a CRS-less file, or GeoJSON whose "WGS 84" extent is plainly projected), WKT rings/bbox, `densify`, `write_zones` (GPKG for zonal-stats).
+- `volume.py` — `difference_volumes` (the engine: one 6-band `gdal raster calc` + `gdal raster zonal-stats --pixels fractional`), `volume` (stockpile: plane / lowest-perimeter / surface base), `cutfill` (design vs surface; fill = design above), `check_raster_crs`, `align_raster` (exact copy if aligned, else refuse unless `--resample`).
+- `change.py` — DoD later − earlier on the overlap (aligned grids, same CRS), LoD given or 1.96·√(σ₁²+σ₂²), optional polygon; both sidecars pinned by SHA256.
+- `accuracy.py` — ASPRS ed. 2: RMSE only (no 95 %), ≥30 checks, product RMSE = √(data² + checkpoints²), NVA pass/fail vs `--class-cm`, VVA reported as found; check points transformed with `cct` through the selected operation.
+- `profile.py` — densified line → bilinear samples → CSV + pure-Python SVG (voids break the line).
+- `pipeline.py` — `run_all` (`argus-survey run`).
+- `report.py` — self-contained printable `report.html` (no JS; PNG thumbnails as data URIs; figures link to `#cmd-N`).
+- `overlays.py` — web views for the viewer (EPSG:3857 PNG + lon/lat corners; WGS 84 GeoJSON), cached in `<job>/.web/`, **not** recorded in the sidecar (a GET must not change `job.json`).
+- `server/app.py` — FastAPI :8107. `WriteGuard` refuses every POST unless `SURVEY_ALLOW_PROCESS`; steps run in a thread and stream SSE (`start`, `step`, `command`, `warning`, `done`|`error`) via `Job.listeners`; one step per job at a time (409). `server/static/viewer.html` is the viewer (`examples/viewer.html` links to it).
+- `cli.py` — Typer CLI.
+
+`tests/` — `conftest.py` marks tool-backed tests `tools`; they skip without the tools unless `SURVEY_TEST_REQUIRE_TOOLS=1`. `tests/data/` holds captured *text* tool output for pure-Python parser tests (no binary fixtures, ever).
+
+## Commands
+
+```bash
+make install       # uv sync --locked --all-extras; `make lock` after changing dependencies
+make lint          # ruff 0.15.16 check + format --check
+make test          # host pytest: pure-Python tests run, tool tests SKIP (no PDAL on the host)
+make test-docker   # the full suite in the image against this checkout, tools required
+make image         # build the runtime image (doctor --strict inside)
+make geo-lock      # re-resolve env/geo-linux-64.lock after editing env/geo.yml
+```
+
+The dev host has no PDAL/GDAL; `make test-docker` is the real gate. Don't `docker run` the image as root against the checkout (root-owned `__pycache__`); compose runs as `${UID}:${GID}`.
+
+## Conventions (non-negotiable)
+
+1. **No silent datums.** Every job records horizontal CRS, vertical CRS (or `null` + an explicit `vertical_assumed` reason), geoid model, epoch where relevant, and units. Without a vertical CRS, height-dependent steps (volumes, contours, accuracy) refuse unless `--assume-vertical EPSG:xxxx` is given, and the assumption is recorded and shown in red in the report.
+2. **Record, don't assume.** Every PDAL pipeline JSON and every GDAL/PROJ argv goes into the sidecar in run order, with tool versions. Every input is pinned by SHA256 and size.
+3. **Paths from clients are names under a root.** The API resolves inputs under `SURVEY_DATA_DIR` (`resolve_under_root`); artifacts are addressed by `(job_id, kind)`; job ids match `^[A-Za-z0-9][A-Za-z0-9._-]*$`. No route takes a filesystem path.
+4. **Numbers come with their uncertainty.** A volume carries the surface resolution, each surface's void %, and the method. An accuracy statement says how many check points, how many fell outside coverage, and which standard/edition.
+5. **Never overwrite inputs.** Outputs go into the job dir; inputs are read-only (compose mounts `/data/in` read-only).
+6. **One subprocess runner.** All PDAL/GDAL/PROJ calls go through `tools.run` (logs, times, captures stderr, appends to the sidecar — failed commands too); a non-zero exit raises `ToolError` with the argv and stderr tail.
+
+## Gotchas
+
+- **Never let PROJ pick a transformation at run time.** `crs.select_operation` asks `projinfo --hide-ballpark` for candidates, takes the first whose `+grids=` files are all on disk (or the one `--operation` names), and returns its PROJ string; PDAL then runs that exact string through `filters.projpipeline`. `filters.reprojection` with EPSG codes would let PROJ silently fall back to a ballpark operation when a geoid grid is missing (ellipsoidal heights labelled AHD — ~30 m wrong in Perth). `projinfo --grid-check discard_missing` was tested and does **not** reliably drop such candidates; the on-disk check is ours. A `@grid` (optional) marker is treated as required.
+- **GDA94 → GDA2020 has several valid operations.** PROJ ranks the 7-parameter Helmert first; legacy WA cadastral/control-derived data often warrants the ICSM conformal + distortion grid. Record all candidates; let the user pin one (`--operation "GDA94 to GDA2020 (2)"`).
+- **PDAL exits 0 when every point fails to reproject** (it logs "falls outside grid" per point and writes garbage). Ingest passes `fatal_stderr=TRANSFORM_FATAL` to the runner and reconciles counts and bounds afterwards. Keep both.
+- `pdal info --summary` on a `.copc.laz` (readers.copc) has no LAS header block; COPC-ness comes from `reader`.
+- Drone scale: every ingest stage is streamable (`pdal pipeline --stream`); `writers.copc` is **not** used because it buffers the whole cloud — untwine builds the COPC out of core.
+- **writers.gdal's default radius mode smears** each point into neighbouring cells (radius res·√2): fine for IDW, wrong for max/count. DSM, density and CHM use `binmode: true`.
+- `gdal_rasterize -a_srs` drops the vertical part of a compound CRS, and `gdal raster calc` then refuses to mix it with a PDAL raster ("Input spatial reference systems are inconsistent"). Rasters carry the job's full compound CRS; stamp it with `rasters.set_crs` after rasterizing.
+- **`isnodata()` in `gdal raster calc` is always false when the output has no nodata (`--nodata none`)** — voids then count as zero volume, silently. The volume engine writes `--nodata nan` (no band can produce NaN). With an output nodata, nodata *inputs* arrive as NaN in arithmetic, so guard with `isnodata(...) ? … : …` first. And an expression naming no input (`"1"`) is rejected: write `isnodata(U) ? 1 : 1`.
+- Volumes use `--pixels fractional`: the default cell-centre rule got a 5.5 × 4.25 m test polygon's area 28 % wrong at 1 m cells.
+- The DSM defaults to IDW. A binned max reads high on slopes by ~slope × res/2 (≈ +6 % on a 1:2 stockpile at 0.25 m); `--dsm-method max` exists for roofs/canopy.
+- `gdal raster pixel-info` can't always write GeoJSON to `/vsistdout/`; write a temp file.
+- PDAL's automatic hexbin edge can be several times too coarse (coverage area doubled on the test scene); `qa.hexbin_edge` sizes it from density.
+- **Viewer libraries**: MapLibre **5.24.0** UMD, not 6.x — 6 is ESM-only and its separate module worker can't start from a cross-origin CDN (GeoJSON sources silently never render; a blob-import wrapper didn't help). copc 0.0.9 + laz-perf 0.0.7 (web build via jsDelivr `+esm`, `locateFile` for the wasm) + three 0.186.1. Check the viewer in headless Chrome after any bump (`zenika/alpine-chrome` with `--use-angle=swiftshader`, `?points=1` auto-loads the cloud).
+- The `serve` container runs the package installed in the image: `docker compose up -d --build serve` after changing the viewer or server.
+- **Photogrammetry clouds** usually have `ReturnNumber = 0` and no classes: "first returns" selects nothing. Detect and record the source type; use all points for the DSM.
+- The conda lock includes an x86-64-v3 (AVX2) microarch marker; very old CPUs can't run the image.
+- **Branches:** `dev` is the default branch and takes feature PRs; branch from `origin/dev` and never push to `main` directly, which must never be ahead of `dev`. A release fast-forwards `main` to a `dev` commit that passed CI (`git push origin origin/dev:main`), then tags it. If `main` is protected, the release is a reviewed PR from `dev` into `main`; its merge commit stays on `main` alone, one commit ahead of `dev` with an identical tree. That is the one exception to the rule: leave it and don't merge `main` back into `dev`. Anything else on `main` that `dev` lacks is a mistake (`git diff origin/dev origin/main` must be empty), and once `main` carries such a commit, later releases are PRs too. Tags `vX.Y.ZrcN` / `vX.Y.Z`, each with a CHANGELOG heading.
+- Versioning is git-tag-derived (`hatch-vcs`); `_version.py` is generated. `structlog`, Pydantic v2, ruff line-length 120. Scaffolded from `argus-pkg-template`; CI is standalone (`.github/workflows/ci.yml`).
+- Publishing (GitHub repo, PyPI, GHCR) is the owner's (smk762) job — never do it from here. Ask before adding a pip dependency beyond pydantic/structlog/typer/rich/fastapi/uvicorn/argus-cortex, or any network fetch in the server.

argus_survey-0.1.0/Dockerfile

@@ -0,0 +1,87 @@
+# syntax=docker/dockerfile:1
+#
+# argus-survey: Ubuntu 26.04 + one consistent PDAL/GDAL/PROJ stack.
+#
+# PDAL is not packaged by Debian or Ubuntu (24.04 and 26.04 both lack it), so the
+# geospatial toolchain comes from conda-forge, installed from the explicit
+# lockfile env/geo-linux-64.lock (exact URLs + md5) — PDAL links the very
+# GDAL/PROJ whose CLIs the package calls. No Python GIS bindings anywhere: the
+# package only shells out to `pdal`, `gdal*` and `proj*` (CLAUDE.md, rule 6).
+#
+# The datum grids surveyors need are fetched once at build time from the PROJ
+# CDN and checked against env/proj-grids.sha256; at run time PROJ_NETWORK=OFF,
+# so a transform can never silently download (or silently skip) a grid.
+
+# ── Stage 1: the geo toolchain ────────────────────────────────────────────────
+FROM ubuntu:26.04 AS geo
+
+ARG MICROMAMBA_VERSION=2.3.3
+ENV DEBIAN_FRONTEND=noninteractive MAMBA_ROOT_PREFIX=/opt/mamba
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates bzip2 curl \
+    && rm -rf /var/lib/apt/lists/* \
+    && curl -fsSL "https://micro.mamba.pm/api/micromamba/linux-64/${MICROMAMBA_VERSION}" \
+        | tar -xj -C /usr/local bin/micromamba
+
+COPY env/geo-linux-64.lock /tmp/geo.lock
+RUN micromamba create -y -q -p /opt/geo -f /tmp/geo.lock \
+    && micromamba clean -y -a -q \
+    # Headers, static libs and docs are build-time only; conda-meta stays (doctor reads versions from it).
+    && rm -rf /opt/geo/include /opt/geo/share/doc /opt/geo/share/man /opt/geo/man \
+    && find /opt/geo/lib -name '*.a' -delete \
+    # conda-forge's PDAL ships optional plugins (HDF, icebridge) whose libraries the
+    # package doesn't depend on; drop any plugin that can't load so every `pdal` call
+    # isn't prefixed by load errors on stderr.
+    && for so in /opt/geo/lib/libpdal_plugin_*.so; do \
+        if LD_LIBRARY_PATH=/opt/geo/lib ldd "$so" | grep -q 'not found'; then echo "drop $so"; rm "$so"; fi; \
+    done
+
+COPY env/proj-grids.sha256 /tmp/proj-grids.sha256
+RUN cd /opt/geo/share/proj \
+    && cut -d' ' -f3 /tmp/proj-grids.sha256 \
+        | xargs -I{} curl -fsSL --retry 3 -o {} "https://cdn.proj.org/{}" \
+    && sha256sum -c /tmp/proj-grids.sha256 \
+    && cp /tmp/proj-grids.sha256 /opt/geo/share/proj/argus-survey-grids.sha256
+
+# ── Stage 2: runtime ──────────────────────────────────────────────────────────
+FROM ubuntu:26.04
+
+COPY --from=ghcr.io/astral-sh/uv:0.13.5 /uv /uvx /bin/
+
+# hatch-vcs derives the version from git history, so the build context includes
+# .git and the image needs git. Ubuntu's ca-certificates lags: distrust emSign
+# ECC Root CA - G3 and the Comodo AAA cross-sign root, as the rest of the suite does.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends python3 git ca-certificates \
+    && sed -i \
+        -e 's|^mozilla/emSign_ECC_Root_CA_-_G3|!mozilla/emSign_ECC_Root_CA_-_G3|' \
+        -e 's|^mozilla/Comodo_AAA|!mozilla/Comodo_AAA|' \
+        /etc/ca-certificates.conf \
+    && update-ca-certificates --fresh >/dev/null \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=geo /opt/geo /opt/geo
+
+# The conda env is used without activation, so name its data dirs explicitly.
+ENV PROJ_DATA=/opt/geo/share/proj \
+    PROJ_NETWORK=OFF \
+    GDAL_DATA=/opt/geo/share/gdal \
+    PATH="/opt/venv/bin:${PATH}:/opt/geo/bin"
+
+WORKDIR /app
+COPY . .
+
+# Extras baked into the image, synced from uv.lock (--locked fails the build if
+# the lock is stale). The package lives in its own venv on Ubuntu's Python.
+ARG EXTRAS="server,cli"
+ENV UV_PROJECT_ENVIRONMENT=/opt/venv
+RUN uv sync --locked --no-editable --no-cache --python /usr/bin/python3 \
+        $(echo "${EXTRAS}" | tr ',' '\n' | sed 's/^/--extra /') \
+    && argus-survey doctor --strict
+
+ENV SURVEY_DATA_DIR=/data/in \
+    SURVEY_JOBS_DIR=/data/jobs
+
+EXPOSE 8107
+CMD ["argus-survey", "serve", "--host", "0.0.0.0", "--port", "8107"]

argus_survey-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smk762
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.