# 变化检测

这是一个可独立运行的 CPU Demo，用 `geoai-py 0.42.0` 的 ChangeStar 接口对双期
影像生成变化概率栅格、二值变化栅格和变化图斑 GeoJSON。能力边界为 **A（直接
GeoAI 能力）**；OpenCV 只负责普通 JPG 的特征配准和尺寸处理，Rasterio/GeoPandas
负责无 CRS 输入的栅格与矢量写出。

## 输入契约

- `--before`：第一期影像（用户样例为 `baseData/07-16.jpg`）。
- `--after`：第二期影像（用户样例为 `baseData/07-19.jpg`）。
- 普通图片模式支持 JPG/PNG 和无 CRS 的 TIFF，先转换为内部 RGB GeoTIFF 并使用
  像素坐标；GeoTIFF 模式要求两期输入都是带相同 CRS 的 RGB GeoTIFF。若像元大小、原点、
  旋转方向或尺寸不同，流程只在处理副本中将第二期双线性重投影到第一期网格；不会改写原始 TIFF。
- 自动模式会在两期输入都具备有效 CRS/仿射变换时启用 GeoTIFF 模式，否则使用普通
  图片模式。带 CRS 的 GeoTIFF 会保留空间参考，普通 JPG/PNG 结果不能解释为米或经纬度。

## 运行

```powershell
& .\.venvs\00-change-detection\Scripts\python.exe `
  .\capabilities\00-change-detection\run_change_detection.py `
  --before .\baseData\07-16.jpg `
  --after .\baseData\07-19.jpg `
  --threshold 0.5 `
  --processing-mode auto `
  --output .\shared\outputs\00-change-detection\validation-real-20260817
```

带空间参考的双期 GeoTIFF 可显式使用 `--processing-mode geotiff --max-dimension 0`；
普通图片可使用 `--processing-mode image --max-dimension 2048`。省略模式时使用
`auto`，省略 `--max-dimension` 时普通图片默认 `1024`，带 CRS 的 GeoTIFF 默认保持原始尺寸。

首次运行会从 Hugging Face 缓存 ChangeStar `s1_s1c1_vitb` 权重；CPU 运行时间与
机器和缩放参数有关。`--max-dimension` 默认 1024，`--tile-size` 默认 512，适合
先做代表性验证；增加尺寸或批量运行前应先人工检查配准和误报。每次运行可单独
选择 `0.01` 到 `0.99` 的变化概率阈值，默认值为 `0.5`；实际阈值会写入
`run_metadata.json` 的 `thresholds.change_probability`。
处理分辨率也可按运行选择长边上限：`1024`（快速预览，默认）、`1536`（标准）、
`2048`（小目标优先）或 `3072`（高细节）。分辨率越高越容易保留车辆等小目标，
但 CPU 耗时和内存占用会增加；实际处理尺寸记录在 `run_metadata.json` 的
`max_dimension` 和 `processed_shape` 中。
GeoTIFF 模式还支持 `0`，表示保持原始像素尺寸和地理分辨率；普通图片的 `0` 会
自动回退到 `1024`。

## 输出

每次运行目录包含：

- `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_features.json`：图斑面积、概率统计和像素边界。
- `run_metadata.json`：版本、模型、阈值、配准、缩放、耗时、坐标和限制说明。

## 验收口径

已验证两类代表性样本：

1. 正常基线：`07-16.jpg` 与自身比较，期望变化比例接近 0，检查管线的空变化
   输出、GeoJSON 和元数据是否完整。
2. 困难真实样本：`07-16.jpg` 对 `07-19.jpg`，检查特征配准、有效区域遮罩、栅格
   和矢量输出是否可读。该样本是近景边坡照片，不是 ChangeStar 训练分布，不能
   据此宣称工程变化检测准确率。

另外对城市停车场双期样本做了分辨率对照：`1024` 档位输出 1 个图斑，`2048`
档位输出 16 个图斑，更多车辆和停车区域变化被覆盖；`2048` 档位 CPU 用时约
84 秒，仍存在误报和漏检，结果不能视为车辆变化检测准确率。

没有人工变化真值，Demo 不报告 precision、recall、IoU 或“变化类型”。后续若要
用于边坡/排洪沟等业务，需要同 CRS 正射影像、人工掩膜、误报/漏报统计和许可审查。

## 许可

- `geoai-py 0.42.0`：MIT。
- `torchange 0.0.4`：Apache-2.0；`ever-beta` 的 PyPI 元数据标为保留权利，需
  单独复核。
- ChangeStar 权重 `EVER-Z/Changen2-ChangeStar1x256`：`CC BY-NC-SA 4.0`，当前
  只能用于非商业验证，不可直接用于商业产品。
- 用户提供的 `baseData` 图片：版权/使用授权未知，需由数据提供方确认。