From fbb068ec702338d609c1ca6eddbdb9f182d8f211 Mon Sep 17 00:00:00 2001
From: shuishen <1109946754@qq.com>
Date: Mon, 24 Aug 2026 11:37:16 +0800
Subject: [PATCH] feat: extend local GeoAI capability workflows
---
capabilities/00-change-detection/README.md | 62 ++++++++++++++++++++++++++++---
1 files changed, 56 insertions(+), 6 deletions(-)
diff --git a/capabilities/00-change-detection/README.md b/capabilities/00-change-detection/README.md
index a29f09a..e700838 100644
--- a/capabilities/00-change-detection/README.md
+++ b/capabilities/00-change-detection/README.md
@@ -1,9 +1,9 @@
# 变化检测
这是一个可独立运行的 CPU Demo，用 `geoai-py 0.42.0` 的 ChangeStar 接口对双期
-影像生成变化概率栅格、二值变化栅格和变化图斑 GeoJSON。能力边界为 **A（直接
-GeoAI 能力）**；OpenCV 只负责普通 JPG 的特征配准和尺寸处理，Rasterio/GeoPandas
-负责无 CRS 输入的栅格与矢量写出。
+影像生成变化概率栅格、二值变化栅格和变化图斑 GeoJSON。核心推理的能力边界为
+**A（直接 GeoAI 能力）**；OpenCV 只负责普通 JPG 的特征配准和尺寸处理，Rasterio
+负责网格对齐、栅格写出及清理后掩膜的一对一矢量化。
## 输入契约
@@ -50,9 +50,13 @@
- `before.tif`、`after_registered.tif`：处理输入；GeoTIFF 模式保留 CRS 和仿射变换。
- `change_probability.tif`：模型输出的 float32 变化概率。
- `change_mask_raw.tif`、`change_mask.tif`：阈值前后二值栅格（0/255）。
-- `change_overlay.png`：第二期影像上的红色变化叠加和双期对比。
-- `changes.geojson`：通过 `geoai.masks_to_vector` 导出的变化图斑，附带面积和概率
- 统计；无变化时也会写出空 `FeatureCollection`。
+- `change_overlay.jpg`：左侧为第一期处理图，右侧为配准后的第二期；红色表示
+ ChangeStar 结构变化，青色表示通用 RGB 视觉差异候选。
+- `change_model_overlay.jpg`：只显示 ChangeStar 红色结果，用于与历史输出对照。
+- `generic_difference_mask.tif`：视觉差异候选栅格。它用于补充车辆、人员等移动
+ 目标的漏显，不是 ChangeStar 语义结果，可能包含阴影、边缘和配准残差。
+- `changes.geojson`：从最终清理掩膜逐区导出的变化图斑，附带面积和概率统计；
+ 无变化时也会写出空 `FeatureCollection`。
- `change_features.json`：图斑面积、概率统计和像素边界。
- `run_metadata.json`：版本、模型、阈值、配准、缩放、耗时、坐标和限制说明。
@@ -66,6 +70,14 @@
和矢量输出是否可读。该样本是近景边坡照片，不是 ChangeStar 训练分布，不能
据此宣称工程变化检测准确率。
+控制台必须使用配准后的第二期作为栅格和矢量叠加底图；原始第二期只用于查看
+输入。2026-08-20 的道路样本验证中，青色视觉差异层补充覆盖了车辆与部分人员
+变化，但也出现道路边缘、阴影和局部配准残差，因此只能作为人工复核候选，不能
+合并进 ChangeStar 的变化像素、图斑、Precision、Recall 或工程告警统计。
+参数扫描预览和“转为正式案例”必须继续携带该青色候选层、候选栅格及配准预览；
+正式案例 `change-20260820-032014-615889` 已验证车辆消失位置形成完整青色轮廓，
+人员消失位置也有候选覆盖。
+
另外对城市停车场双期样本做了分辨率对照：`1024` 档位输出 1 个图斑，`2048`
档位输出 16 个图斑，更多车辆和停车区域变化被覆盖；`2048` 档位 CPU 用时约
84 秒，仍存在误报和漏检，结果不能视为车辆变化检测准确率。
@@ -73,6 +85,44 @@
没有人工变化真值，Demo 不报告 precision、recall、IoU 或“变化类型”。后续若要
用于边坡/排洪沟等业务，需要同 CRS 正射影像、人工掩膜、误报/漏报统计和许可审查。
+## 人工真值基准评估
+
+参考文章 `09/25/30/39/40` 的建议不用于直接替换 ChangeStar，而用于补齐数据与验收层。
+新增的 [`evaluate_change_detection.py`](./evaluate_change_detection.py) 只评估已经生成的
+结果，不重跑模型，也不修改任何源影像。开始正式评估前，先复制
+[`benchmark_manifest.example.csv`](./benchmark_manifest.example.csv) 到
+`shared/data/processed/00-change-detection/<基准版本>/pairs.csv` 并填写真实路径。
+
+每个基准样本必须满足：
+
+- `before`、`after` 和 `truth` 都是同宽高、同 CRS、同仿射网格的 GeoTIFF；评估器不会
+ 静默重采样人工真值。
+- `truth` 是单波段栅格，固定使用 `0=未变化`、`1=变化`、`255=忽略/不确定区域`。
+- `output_dir` 指向已有正式运行，至少包含 `change_mask.tif`；有
+ `change_probability.tif` 时可额外比较多个原始概率阈值。
+- 正式 GeoTIFF 基准运行使用 `--processing-mode geotiff --max-dimension 0`，或先裁出
+ 可在 CPU 上保持原始分辨率运行的小区域，确保模型输出与人工真值仍在同一网格。
+- 同一地点或同一原始影像产生的相邻瓦片只能属于同一个 `split`，避免空间泄漏。
+- `change_type`、人工审核状态、采集时间、数据来源和许可应在清单或配套元数据中登记。
+
+运行示例：
+
+```powershell
+& .\.venvs\00-change-detection\Scripts\python.exe `
+ .\capabilities\00-change-detection\evaluate_change_detection.py `
+ --manifest .\shared\data\processed\00-change-detection\benchmark-v1\pairs.csv `
+ --thresholds 0.3,0.4,0.5,0.6,0.7 `
+ --output .\shared\outputs\00-change-detection\benchmark-v1\evaluation.json
+```
+
+输出同时记录基准汇总和逐样本的有效像素数、TP、FP、FN、TN、Precision、Recall、
+F1、IoU 和 Specificity。`cleaned_mask` 指标代表正式输出；`probability_raw` 阈值扫描不包含连通区域
+过滤，只用于选择候选阈值，不能直接当成最终产品参数。普通图片仅可通过显式
+`--allow-pixel-coordinates` 做管线测试，不属于地理配准合格的正式基准。
+
+当前只有合成小栅格单元测试验证了计算和拒绝错位网格的逻辑，尚未获得人工审核的真实
+变化掩膜，因此仍然没有可报告的真实 Precision、Recall、F1 或 IoU。
+
## 许可
- `geoai-py 0.42.0`：MIT。
--
Gitblit v1.9.3