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 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. 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.