feat(pointcloud): complete annotation and result lifecycle workflows

shuishen

5 hours ago 385be2eca72eb3833efa4be0a0088b34e764788a

 apps/workbench-console/README.md

@@ -1,9 +1,9 @@
# GeoAI Workbench 本地实验控制台

这是一个完全独立于无人机产品的本地只读控制台。它只展示本工作区已有能力的
输入说明、运行元数据和结果工件，不上传数据，也不提供删除、覆盖或启动算法的
操作。地图会直接请求公开 ArcGIS 影像切片；配置天地图 token 后还会直接请求
天地图影像和注记切片。
这是一个完全独立于无人机产品的本地实验工作台。它以“新建运行、案例库、结果
工作区”展示能力：允许的能力可以上传受限文件类型并运行固定本地脚本，但不提供
删除、覆盖、任意路径或任意命令执行。地图会直接请求公开 ArcGIS 影像切片；配置
天地图 token 后还会直接请求天地图影像和注记切片。

## 启动

@@ -38,6 +38,23 @@

Vite 开发服务固定使用 `http://127.0.0.1:6174/apps/workbench-console/`，会通过本机代理读取 `6173` 的结果工件。

## CPU and GPU execution

Object detection, ChangeStar change detection, and point-cloud supervised
training/inference expose `auto`, `cpu`, and `cuda` choices. The local service
always invokes only fixed allowlisted virtual environments. `auto` probes the
capability's fixed CUDA interpreter, chooses it only when PyTorch confirms CUDA,
and otherwise uses its retained CPU environment. `cpu` does not probe the GPU.
`cuda` fails explicitly when the probe fails; it never silently becomes a CPU
run. New `run_metadata.json` files record requested/actual device, environment,
PyTorch version, fallback state, and fallback reason. Photo 3D reconstruction,
point-cloud geometry, semantic rule classification, file conversion, exports,
and the console itself remain CPU workflows. The current photo-MVS CUDA tools
are not validated and are not exposed as a console option.

User requests cannot supply an interpreter, device path, or command. This
console remains loopback-only and independent of drone products.

## 地图底图

Cesium 默认加载公开 ArcGIS World Imagery 底图。要叠加天地图影像和注记，在
@@ -47,6 +64,18 @@
VITE_TIANDITU_TOKEN=<your-token>
```

Change detection also exposes the read-only `GET /api/change-detection/scans` endpoint. The page renders the low-cost parameter scan contact sheet, a selected threshold/area overlay, scan metrics, and downloads for the three materialized candidate GeoJSON results without presenting the scan as a formal model run.

The change-detection page also accepts a user-submitted parameter scan: upload a before/after pair, select threshold and minimum-area combinations (up to 24), choose processing mode/resolution, and start a background job. Poll `GET /api/change-detection/scan-jobs/<job-id>` until it completes; the resulting scan then appears in the read-only scan workspace with overlays, statistics, and GeoJSON artifacts.

普通图片的最小连通区域使用处理后影像的 px 面积，只用于滤除零碎噪声，与 CRS 无关。参数扫描允许该选项留空，留空时自动使用 `256 px`；需要比较保留小目标和过滤噪声的差异时再多选面积组合。变化检测二进制上传会对文件名做 URL 百分号编码，因此中文文件名可以安全通过浏览器请求头，服务端解码后仍会执行扩展名白名单和安全文件名处理。

若某一组合没有检测到变化，结果区会显示 0 个图斑，并提供空 GeoJSON 下载，不会将“无变化”误报成处理失败。

规则四边形与原始图斑都从同一份已清理掩膜逐区生成。最小连通区域仅按像素在掩膜阶段应用一次，避免在 GeoTIFF 地图单位中二次过滤而遗漏图斑；因此新生成的原始图斑数、规则四边形数和对应掩膜区域数一致。旧扫描成果不会被覆盖；修复后会以新的扫描成果供人工复核和转为正式案例。

扫描结果不会自动进入案例库。确认某个组合后，在扫描结果区点击“将当前组合转为正式案例”，控制台会通过 `POST /api/change-detection/scans/<scan-id>/promote` 创建新的正式运行目录；成功后刷新案例库即可查看。正式案例优先展示规则四边形，仍提供原始不规则图斑、掩膜和概率栅格下载。GeoTIFF 结果同时提供源 CRS 和 EPSG:4326 矢量；普通图片结果使用 px 像素坐标。

可先参考同目录的 `.env.example`。`VITE_` 变量会被打包进本地浏览器代码，因此
只应填入适合客户端使用的天地图访问 token，不要填入其他服务密钥。

@@ -54,16 +83,216 @@

- `apps/workbench-console/src/`：Vue 3 组件、路由、Pinia 状态与能力适配层。
- `apps/workbench-console/dist/`：Vite 构建产物（不提交 Git）。
- `scripts/serve_workbench_console.py`：只读本地文件服务；仅暴露构建后的控制台、已有输出和目标检测原图，不暴露仓库其余文件。
- `scripts/serve_workbench_console.py`：本地控制台服务和受限运行 API；仅暴露构建后的控制台、结果工件与必要原图，且只调用固定虚拟环境和能力脚本。
- `shared/outputs/`：能力原始输出；控制台不复制、不修改这些文件。

首版已接入 `01-object-detection` 和 `15-trajectory-analysis`。田墩实飞案例会显示
当前已接入 `00-change-detection`、`01-object-detection`、`02-semantic-mapping`、`04-spatial-measurement`、`09-anomaly-detection` 和 `15-trajectory-analysis`。变化检测案例显示两期原图、变化叠加、像素坐标 GeoJSON 图斑和概率/配准指标；上传接口只接受一对 JPG/JPEG/PNG/TIF/TIFF，服务端固定调用 `.venvs/00-change-detection`。异常检测分别上传正常参考影像和待检测影像，展示原图、方法对比、热力图、候选表和下载工件。田墩实飞案例会显示
实飞轨迹、计划航线、禁飞区与适飞区，并提供轨迹和区域范围的聚焦按钮。其他能力
保留目录和边界状态，待其首个 Demo 产出可检查工件后再接入。
## 本地运行工作台

### 空间规则与风险评分

`07-risk-rule-engine` 已接入独立本地实验控制台。新建运行要求一份带投影 CRS 的观测对象 GeoJSON（唯一 `object_id` 和数值 `confidence`）、一份风险分区 GeoJSON（`zone_type`）和一份规则 JSON。服务端只调用固定的 `.venvs/07-risk-rule-engine/Scripts/python.exe` 及固定能力脚本，并为每次提交创建新的 raw、processed 和 output 目录。

工作区展示风险 GeoTIFF 预览和评分 GeoJSON，并显示逐对象得分、等级、命中规则与建议；可下载 GeoTIFF、GeoJSON、CSV、汇总 JSON 和运行元数据。风险等级是规则计算出的人工复核优先级，不是事件事实、自动处置或产品能力。接口为 `GET/POST /api/risk-rule-engine/runs`，仅在本机 `6xxx` 端口提供服务。

控制台现支持可操作的本地实验运行，并保持与无人机产品完全独立。能力页面提供新建运行入口和可搜索扩展的案例库，案例由本地服务从运行目录自动发现，不再依赖前端硬编码 Tabs。

- 轨迹分析上传 `XLSX`、`KMZ`、禁飞区 `GeoJSON` 和可选适飞区 `Gzip`，原始、处理和输出分别归档在 `shared/data/raw`、`shared/data/processed`、`shared/outputs`。
- 目标检测上传最多 12 张 `JPG/JPEG/PNG`，原图和标注图默认并列对比，每次生成独立运行编号。
- 本地 API 为 `GET/POST /api/trajectory/runs` 和 `GET/POST /api/object-detection/runs`，仅监听回环地址，端口必须是 `6xxx`；服务只调用固定虚拟环境和能力脚本，不接受任意命令或任意路径。
- 语义分割上传最多 6 张 `JPG/JPEG/PNG/TIF/TIFF`，任务预设从能力目录动态读取；当前只有通用颜色流程可运行，排洪沟、边坡、竖井和尾矿库任务在模型与真值齐备前保持禁用。结果展示原图、栅格叠加、GeoJSON 矢量预览、类别比例和可下载工件。
- 空间测量上传最多 4 份 `PNG/TIF/TIFF` 单波段标签栅格，展示彩色栅格、GeoAI 矢量对象、计数、面积、周长和对象明细；只有有效投影 CRS 才使用地图单位。
- 变化检测上传一对 `JPG/JPEG/PNG/TIF/TIFF`，每次运行可选择自动识别、普通图片或 GeoTIFF 地理参考模式；阈值支持 `0.01～0.99`（默认 `0.5`），分辨率支持 GeoTIFF 原始分辨率/自动以及 `1024/1536/2048/3072` 档位。GeoTIFF 模式保留 CRS 和地图坐标，普通图片模式输出像素坐标。单文件最大 `1024 MB`，单次 Base64 JSON 请求最大 `3072 MB`。
- 异常检测分别上传 1～6 张正常参考影像和 1～6 张待检测影像，支持 `JPG/JPEG/PNG/TIF/TIFF`。3 张以上固定机位且全部尺寸一致时自动启用同位置规则和通用局部外观/结构变化通道，否则回退为全局规则；局部通道不使用颜色或物品类别规则。结果页显示实际选择的模式。大文件使用二进制流，后台任务完成后进入案例库；结果展示参考输入、待检测原图、规则/Isolation Forest 对比、热力图、候选区字段与下载工件。案例列表右侧的“复用输入”会把该案例的原始参考图、待检测图和四项可编辑参数回填到新运行表单，不自动启动检测，也不修改历史案例。
- 本地 API 还包括 `GET/POST /api/change-detection/runs` 和 `PUT /api/change-detection/uploads/<upload-id>`；变化检测前端使用二进制流上传，服务端按原字节暂存并复制到独立 raw、processed 和 output 目录，不修改原始 TIFF，也不覆盖既有运行。
- 本地 API 为 `GET/POST /api/trajectory/runs`、`GET/POST /api/object-detection/runs`、`GET/POST /api/semantic-mapping/runs`、`GET/POST /api/spatial-measurement/runs`、`GET/POST /api/anomaly-detection/runs` 和只读的 `GET /api/semantic-mapping/tasks`；异常检测另有二进制上传和后台任务状态端点。服务仅监听回环地址，端口必须是 `6xxx`，只调用固定虚拟环境和能力脚本，不接受任意命令或任意路径。

## 3D Point-cloud Workspace

The `05-3d-pointcloud` console adapter provides `GET/POST /api/3d-pointcloud/runs`.
It accepts two PLY/PCD/XYZ/LAS/LAZ files at most, copies source bytes into a new
raw run directory, records SHA-256, and invokes only the fixed CPU interpreter
and point-cloud script. The workspace shows DSM/elevated-surface raster and
GeoAI footprint vector side by side, plus counts, mesh summary, artifacts, and
run metadata. It remains independent of all drone products and is local-only on
`6xxx` loopback ports.

The same case library also discovers completed photo-SfM and CPU-MVS result
directories. Sparse SfM cases use an interactive `THREE.Points` vertex viewer
with registration statistics, local poses and input manifest; vertices are never
triangulated by the viewer. CPU-MVS cases offer reliable-texture, point-colour,
and complete-geometry views. The reliable-texture atlas pixels are vertically
corrected for browser sampling and faces that reach black atlas background or
the OpenMVS orange no-coverage colour are omitted; visible holes therefore
indicate rejected texture coverage rather than a placeholder colour. Complete
geometry retains all reconstructed mesh faces in a neutral material. Point-colour
uses nearest fused RGB point values on the complete mesh; it does not claim
per-face photo-texture evidence. All views support orbit, zoom, an explicit
local-`+Z` top-down view, reset and wireframe controls, plus dense PLY, mesh
PLY and texture downloads. Both use local SfM coordinates and are not
rendered as DSM or GeoJSON without valid georeferencing.

The top-level `05-3d-pointcloud` workflow switch keeps incompatible inputs
separate. `照片三维重建` accepts 3-1000 JPG/JPEG files from one coherent camera
sequence through bounded binary uploads, preserves the raw bytes, then runs a
background CPU SfM/MVS job and polls `queued`, `sparse_sfm`, `dense_mvs`,
`complete`, or `failed` status. Its GPS/RTK-prior option uses the verified
spatial-neighbour configuration only when every photo has suitable position
metadata; turn it off for ordinary cameras. `既有点云理解` accepts up to two
PLY/PCD/XYZ/LAS/LAZ inputs and produces the DSM/elevated-surface raster and
GeoAI footprint vector workflow. Creating a run or discovering a new case
does not require rebuilding the frontend; `npm run build` is only required
after changing the Vue/TypeScript console source.

The reconstruction job response also reports actual completed workflow
milestones from its fixed scripts: feature extraction, matching, sparse mapping,
RGB preparation, undistortion, dense fusion, meshing, texture export, and final
artifact packaging. The displayed percentage is a weighted stage milestone, not
a remaining-time estimate: COLMAP and OpenMVS do not expose reliable live
sub-stage percentages.

The fixed CPU photo-reconstruction timeout is 24 hours for large sequences. It
is a hard safety limit, not a predicted completion time.

The same workspace also exposes point-cloud semantic classification:
PLY/PCD/XYZ/LAS/LAZ files are sent through bounded binary streaming, retained
byte-for-byte in a new run, and classified on CPU into ground, vegetation,
building/structure, pole/tower candidates, power-line candidates and unknown.
Its case view renders a capped colour point preview and provides semantic LAS,
GeoTIFF, GeoJSON and CSV downloads. The labels are review candidates from
RGB/local-geometry rules, not a trained semantic-model claim. Dense MVS cases
also expose an action that classifies only their fixed local `dense.ply`; the
server never accepts a browser-supplied path.

Semantic cases with a generated RGB annotation source, plus complete
`multiview-feature-*` directories whose ordered original-RGB PLY/NPZ checksum
contract passes, provide a separate manual annotation and supervised-training
area. The fusion source is labelled as a photo-feature review sample and is not
fed into the existing PointNet-style trainer as if it were Point Transformer V3.
After sufficient reviewed labels, its `多视角特征训练` action uses a separate
CPU/CUDA local-attention baseline over the fixed same-order feature NPZ. It
requires each reviewed class to span XY training, validation, and test blocks.
This is not the uninstalled official Pointcept/Point Transformer V3 stack and
is not exposed in the generic arbitrary-cloud model-application workflow.
Brush and rectangle selections become
separate annotation revisions rather than altering source clouds or rule results.
The annotation workspace can also add an independent local PLY/PCD/XYZ/LAS/LAZ
source through its bounded binary upload route. The server preserves its raw
bytes, starts a background CPU preview job, and adds the derived RGB/XYZ preview
to the source list only after successful processing. The taxonomy is local
annotation metadata: users can add a Chinese label, lowercase English key and
RGB colour, and the server assigns an unused LAS-compatible code. Saved
revisions snapshot their class metadata; a custom class referenced by a saved
revision cannot be deleted. These controls do not manufacture semantic truth or
replace reviewed labels required for supervised training.
For a source that is no longer needed, **Remove complete data chain** first
fetches a server-calculated deletion plan, then requires an irreversible
confirmation. It removes only fixed local point-cloud raw/processed/output
directories plus discovered annotation, training, and inference dependents.
`baseData` and external source inputs are excluded from every removal plan.
The annotation point viewer uses sRGB-correct anti-aliased circular points.
Browse mode keeps left-drag rotation; brush/rectangle mode reserves left-drag
for labels, with right-drag rotation, middle-drag panning and wheel zoom.
Middle-button auto-scroll is suppressed inside the point canvas. Its rotate-
centre tool lets a user click a visible point to move the orbit target without
changing annotations.
The model-orientation control provides independent 0-360 degree local X/Y/Z
display rotations about the model centre. It never changes the original point
cloud or stored annotation indices; picking and rectangle selection follow the
currently displayed orientation.
The viewer loads and renders every point contained in the selected annotation
source directly. It does not switch to a zoom-dependent local detail layer, and
point indices stay stable for browsing, manual labels, saved revisions, and
training. Large sources consume correspondingly more browser memory and GPU
resources.
New annotation PLY/PCD/XYZ/LAS/LAZ uploads run a dedicated preview-only CPU
step. It preserves every readable finite XYZ and available vertex RGB point
and does not run the DSM, raster/vector, mesh, or rule-semantic pipeline. A
source without vertex RGB remains viewable with a neutral preview but cannot be
sent to the current RGB semantic-model trainer.
Textured-mesh ZIP bundles are prepared separately: the PLY's face UVs and its
referenced JPG/PNG tiles are baked into sampled face-centre RGB/XYZ points. A
small visual-validation source is exposed in the normal annotation-source list
before a larger training source is materialized.

Sparse point-cloud, semantic-classification, supervised-prediction, and mesh
previews use the same viewer controls: local X/Y/Z orientation, click-to-set
orbit centre, top-down view, and reset. These controls only transform the
centred display wrapper; source PLY/GLB files and downloadable outputs remain
unchanged.
An incorrect revision can be removed after confirmation, but the endpoint only
removes that revision directory and cannot remove LAS/PLY sources, semantic
results, or training outputs. A local training job requires two classes with at
least 500 confirmed points each, then writes a portable model, metrics, and
predicted PLY asynchronously. The server probes only the fixed
`05-3d-pointcloud-gpu` interpreter; when CUDA is available it uses that
environment, otherwise it uses the retained fixed CPU interpreter. Sources,
point indices, class codes, Python interpreters and commands are all server-fixed.
Each job reports the selected device, environment, and PyTorch version.

The supervised area also exposes **Apply trained model**. It discovers only
complete local training directories containing both `model.pt` and `metrics.json`.
Select a discovered model, upload one new RGB PLY/PCD/LAS/LAZ point cloud, and
the server copies its bytes into new `raw` and `processed` inference directories
before starting a background job that automatically selects the verified GPU or
CPU environment. The API accepts neither a browser path nor
an arbitrary model path. Completion shows the classified PLY preview directly in
the workspace and provides downloads for classified LAS, class-count CSV,
prediction JSON, metadata, and model weight. XYZ-only input fails explicitly:
the supervised model requires observed RGB features. Output remains a review
candidate, especially for the current pole/tower class, not asset inventory or
an inspection conclusion.

For an already selected annotation source, **Automatic annotation current
source** uses the selected local model without a second upload. Its asynchronous
candidate artifact records source/model checksums, class predictions, and
per-point confidence after a user-selected threshold. The completed run exposes an in-console, class-coloured prediction preview and predicted/high-confidence per-class counts for review. Brush/rectangle review can reject candidates or correct their classes, saving an independent correction draft. It remains separate from
human truth until **Confirm merge candidates** is pressed; the merge applies candidates, review corrections, then existing human labels as the highest priority, and creates a new annotation revision for
the next training cycle.

The 3D point-cloud capability is presented as four focused workspaces rather
than one long mixed result page:

1. **Photo 3D reconstruction**: JPG/JPEG input, sparse/dense reconstruction,
   mesh, texture, and photo-reconstruction cases only.
2. **Point-cloud geometry processing**: PLY/PCD/XYZ/LAS/LAZ input, DSM,
   elevated-surface raster/vector, approximate mesh, and geometry downloads.
3. **Point-cloud semantic classification**: classification cases, coloured
   point preview, semantic LAS/CSV/GeoJSON and review-only rule outputs.
4. **Annotation, training, and model application**: RGB annotation source,
   annotation revisions, automatic GPU/CPU training, training metrics, and applying a trained
   model to a new RGB cloud.

Each workspace filters the case library to its own purpose. A point-cloud run
may appear in both geometry and semantic workspaces because it has both output
families, but the pages never render the unrelated result bands together. The
model workspace deliberately uses its generated annotation sources and trained
models rather than a general case library.

## Result removal

Every connected capability case library provides a complete-result removal
control. It first reads a server-calculated deletion plan, then requires a
second irreversible confirmation. A removable console run is restricted to the
fixed `shared/outputs/<capability>/runs/<run-id>/` layout and removes only that
output, its console-upload raw copy, processed copy, and known dependent
artifacts. `baseData`, external source inputs, sibling runs, and project
baseline/validation cases are never removed. Baseline and validation cases show
their protected status instead of accepting deletion.

The point-cloud training-model selector has a separate removal control. It
removes the selected locally trained model plus its discovered inference and
automatic-annotation outputs, while preserving annotation revisions, `baseData`,
and external input files.

## Maintenance conventions

Run `npm run build` after changing Vue, TypeScript, CSS, or build-time client
configuration. A new result, a data-processing run, or a server-only API change
does not require a frontend rebuild.

The local console is not visually inspected through browser automation. For a
visual UI, map, image, or 3D acceptance check, the requested interaction is
specified to the user and the user provides the screenshot; build, HTTP,
artifact, and automated checks remain independent evidence.