From 18240a70f69ace40c3408fd5b16bac94e11c37de Mon Sep 17 00:00:00 2001 From: Patrick Leiverkus Date: Sun, 26 Jul 2026 14:52:53 +0200 Subject: [PATCH 1/3] docs: reword README subtitle Describe what the pipeline does (archaeological feature extraction and vectorisation) rather than how it does it. Co-Authored-By: Claude Opus 5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0144e57..1b79a96 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Status: 2.5D track](https://img.shields.io/badge/status-2.5D--track-orange.svg)](#status) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20716606.svg)](https://doi.org/10.5281/zenodo.20716606) -**AI-assisted vectorisation of photogrammetric excavation data.** +**Archaeological feature extraction and vectorisation pipeline.** Structura is the workflow application for the **vectorisation step** of an archaeological excavation pipeline. It ingests georeferenced photogrammetric From 36c384c0f94dc2cdc037f9d52b7b84cb40bd6686 Mon Sep 17 00:00:00 2001 From: Patrick Leiverkus Date: Sun, 26 Jul 2026 14:53:22 +0200 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20correct=20v0.8=20scope=20=E2=80=94?= =?UTF-8?q?=20semantic=20field=20is=20coarse,=20material=20model=20is=20ou?= =?UTF-8?q?rs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The v0.8 entry described `orthophoto_semantic.tif` as a "material-class field" to be consumed from upstream. Effigies now actually ships that raster (2026-07-26), and it is not material classes: the codes are ground/vegetation/structure from OpenPointClass's stock vehicles-vegetation-buildings model, trained for aerial and urban scenes and near-meaningless on a trench. The fine material classes are Structura's own deliverable — a trained 2D image model fused back onto the mesh by the Effigies multi-view blend — which makes v0.8 a research milestone, not a plumbing one. Record that, the guaranteed properties of the field as delivered, and the field-vs- object contract including the one-way runtime flow. Also note the intake prerequisite: `orthophoto_semantic.tif` matches the "ortho" substring in `intake.discover_inputs` and is silently mis-tagged as an RGB orthophoto, so the open intake-layout decision now gates v0.8. Co-Authored-By: Claude Opus 5 --- ROADMAP.md | 44 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index b10b9b6..38953a4 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -67,11 +67,42 @@ no GPU, no model download, no database required. - [ ] Colour / texture stratum segmentation → section boundary polylines. ### v0.8.0 — Semantic-field bridge *(Sub-study E / Effigies)* -- [ ] Consume `orthophoto_semantic.tif` (material-class field) as a prior / - input channel for the vector tracks. -- [ ] Implement the field-vs-object contract (Structura owns vector objects; - the upstream engine owns the geometry-space field). -- Depends on the upstream Effigies `--semantic` output. + +The upstream field exists as of 2026-07-26: Effigies writes +`odm_semantic/orthophoto_semantic.tif` (byte GeoTIFF with colour table, plus +`orthophoto_semantic.legend.json`), pixel-identical to +`odm_orthophoto/odm_orthophoto.tif` and `odm_dem/dsm.tif` — same grid, same +occlusion decisions — with class codes `0` nodata, `1` ground, `2` vegetation, +`3` structure. + +**The mechanism is finished; the content is not.** Those classes come from +OpenPointClass's stock `vehicles-vegetation-buildings` model, trained for aerial +and urban scenes. On a trench, `ground/vegetation/structure` carries almost no +archaeological information, so consuming the field as-is buys little. + +The fine material classes (stone / soil / ceramic / mortar) are **Structura's +deliverable, not an upstream input**: a trained 2D image model, run per view and +fused onto the mesh by the Effigies multi-view blend (`texture_blend.py`). That +reverses the direction — 3D→2D today, 2D→3D planned — and is the only route by +which **vertical section faces** are classified at all; a nadir ortho loses them +by construction. Effigies already ships ONNX Runtime (CPU + CUDA) and the pattern +for versioned, SHA256-pinned weights in `$EFFIGIES_MODEL_DIR`, which is the +intended delivery path. + +- [ ] **Intake prerequisite:** add a `SEMANTIC` `RasterKind` and fix the + discovery heuristic — `orthophoto_semantic.tif` matches `"ortho"` today and + is silently mis-tagged as an RGB orthophoto (see *Open decisions*). +- [ ] Consume the class raster as a prior / input channel for the vector tracks + (e.g. vectorise only where the field says `structure`). +- [ ] Implement the field-vs-object contract: Structura owns vector objects, the + upstream engine owns the geometry-space field; the runtime flow is one-way + (Effigies → Structura, which never reads back). Paving is *not* a field + class — same material as a single stone, differing only in arrangement, so + it is derived in the object layer. +- [ ] Train and ship the fine material-class 2D model. This is a research + deliverable rather than a plumbing task and may warrant its own milestone. +- [ ] Validate the archaeological usefulness of the semantic ortho — Structura's + evaluation, not Effigies'. ### v0.9.0 — Evaluation harness ⛔ *needs real trench data* - [ ] Reproducible evaluation scripts producing the paper's metrics @@ -91,7 +122,8 @@ no GPU, no model download, no database required. ## Open decisions Tracked in [`docs/architecture.md`](docs/architecture.md#open-decisions): the DB sink default (v0.5), the 2D model default (decided by the v0.9 evaluation), and -the intake layout heuristic. +the intake layout heuristic — the last of which now gates v0.8, since the +filename-based discovery cannot tell a semantic class raster from an orthophoto. > This is a living document. Milestone scope and ordering may shift as the > research plan and the upstream Effigies engine evolve. From f2e304c5947e58e7781d3ab98174b29f646edfa1 Mon Sep 17 00:00:00 2001 From: Patrick Leiverkus Date: Sun, 26 Jul 2026 14:54:40 +0200 Subject: [PATCH 3/3] docs: name the intake mis-tagging in the open-decisions entry The intake-layout decision read as a tidy-up ("refine to the actual WebODM layout"). It is now a correctness issue: `RasterKind` has only ORTHO and DEM, and the substring test in `discover_inputs` matches `orthophoto_semantic.tif` on "ortho", so an Effigies output tree feeds the class raster to the 2D segmenter as if it were a photo, silently. State the failure mode, the shape of the fix, and the fact that it gates ROADMAP v0.8. Co-Authored-By: Claude Opus 5 --- docs/architecture.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 7fe953b..9a1b891 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -122,4 +122,10 @@ The active sink is chosen by `STRUCTURA_SINK` (`file` | `postgis` | `api`). comparative evaluation (blocked on real excavation data). - **Intake layout:** the discovery heuristic in `intake.discover_inputs` is filename-based and must be refined to the actual WebODM delivery layout - (e.g. `odm_orthophoto/odm_orthophoto.tif`, `odm_dem/dsm.tif`). + (e.g. `odm_orthophoto/odm_orthophoto.tif`, `odm_dem/dsm.tif`). It is also + lossy in a way that now matters: `RasterKind` knows only `ORTHO` and `DEM`, and + the substring test tags Effigies' `odm_semantic/orthophoto_semantic.tif` as an + RGB orthophoto — the class raster is handed to the 2D segmenter as if it were a + photo, with no error raised. Resolving this (a `SEMANTIC` kind plus + layout-aware rather than name-aware discovery) is a prerequisite for + [ROADMAP](../ROADMAP.md) v0.8.