# 语义分割

状态：首个 CPU Demo 已验证（2026-08-17）。

## 能力边界

当前 Demo 归为 **B（GeoAI 与生态库组合）**，不是 `geoai-py` 内置的预训练语义分割模型。

- `geoai-py 0.42.0` 提供训练/推理 API，但通用 `semantic_segmentation` 需要用户提供匹配的模型权重。
- 首版为了可离线、可重复验收，使用明确的 RGB/HSV 颜色规则区分 `vegetation`、`water`、`impervious` 和 `other`。
- 每个类别的二值掩膜通过 `geoai.masks_to_vector` 转为多边形；Rasterio、GeoPandas、OpenCV 和 Pillow 承担栅格、矢量和图像处理。

这是一条可解释的工程基线，不是训练模型精度基准。蓝色屋顶、蓝色车辆和阴影会造成误分，当前没有人工真值，不能报告 IoU、精确率或召回率。

## 任务类别与控制台选择

任务目录见 [`configs/task-catalog.json`](./configs/task-catalog.json)。控制台类别选择必须
来自这个目录，并且只允许 `selectable=true` 的任务实际运行；项目需要的类别不能通过
前端任意填写后交给不支持它的算法。

| 任务 | 类别 | 当前状态 |
| --- | --- | --- |
| `color_baseline` | other、vegetation、water、impervious | 可运行，只验证工作流，准确率未测 |
| `drainage_blockage` | drainage_channel、culvert_inlet、blockage_material、blockage | planned，需项目掩膜、纯负样本和模型 |
| `slope_change_region` | stable、surface_change、collapse_candidate、crack_region | planned，需配准多期影像和变化真值 |
| `shaft_structure` | shaft_opening、guard、walkway、blockage、visible_damage | blocked，检测范围未明确 |
| `tailings_anomaly` | water_or_slurry_region、spectral_anomaly、temporal_change | blocked，RGB 异常不得直接判定矿浆渗漏 |

这里的 `blockage_material` 是可见物观察，`blockage` 是结合沟道空间关系、覆盖比例和
人工规则后的项目标签；两者不能混为同一个模型类别。

## Demo 契约

输入：单个文件或目录，允许 `JPG/JPEG/PNG/TIF/TIFF`。普通图片没有 CRS；GeoTIFF 只有在含有效 CRS 和仿射变换时才保留地理坐标。

每张影像输出：

| 文件 | 内容 |
| --- | --- |
| `*.mask.png` | 类别编号栅格，0=其他、1=植被、2=水体、3=不透水面 |
| `*.overlay.png` | 可直接检查的原图与类别颜色叠加图 |
| `*.mask.tif` | 单波段 GeoTIFF；普通图片使用像素坐标 |
| `*.segments.geojson` | GeoAI 矢量化的类别多边形 |
| `run_metadata.json` | 版本、方法、阈值、设备、输入数、耗时、类别像素统计和限制 |

脚本拒绝写入非空输出目录，避免覆盖既有结果。

## 环境与运行

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1 -Capability 02-semantic-mapping

$py = '.\.venvs\02-semantic-mapping\Scripts\python.exe'
& $py .\capabilities\02-semantic-mapping\run_semantic_segmentation.py `
  --input .\shared\data\raw\02-semantic-mapping\validation-20260817 `
  --output .\shared\outputs\02-semantic-mapping\my-run
```

本机环境为 Python 3.12.10、`geoai-py 0.42.0`、Rasterio 1.5.1、GeoPandas 1.1.4 和 OpenCV 5.0.0，CPU 运行，`pip check` 通过。

## 验收集与实测

验收输入位于 `shared/data/raw/02-semantic-mapping/validation-20260817/`，来自仓库内已有真实无人机影像的只读副本：

- 正常样例 `DJI_20260713102047_0001_V_19.jpeg`：植被明显，同时包含道路、蓝色屋顶、车辆和阴影。
- 困难样例 `DJI_20260728113653_0001_V_50.jpeg`：几乎全部是不透水道路与人行道，用于检查低类别多样性和小面积误分。

两张图均为 3840 x 2160、无地理参考。CPU 总耗时 15.738 秒，两个结果均实际使用 `geoai.masks_to_vector`，PNG、GeoTIFF、GeoJSON 和元数据均非空并已视觉检查。

正常样例将 1,707,028 个像素标为植被；可见树冠大体连续，但蓝色屋顶被误标为水体。困难样例有 8,167,327 个像素标为不透水面，仅有少量植被/水体误分。该结果只证明数据流与输出契约可用，不证明真实业务精度。

自动验收：

```powershell
$env:PYTHONPATH = (Resolve-Path '.\src')
.\.venvs\02-semantic-mapping\Scripts\python.exe -m unittest discover -s .\capabilities\02-semantic-mapping\tests -v
.\.venvs\02-semantic-mapping\Scripts\python.exe -m unittest discover -s .\tests -v
```

## 本地实验控制台

打开 <http://127.0.0.1:6173/#/capability/02-semantic-mapping>。页面采用“新建运行 -> 案例库 -> 结果工作区”，支持最多 6 张影像上传，并展示原图/栅格叠加、矢量多边形预览、类别像素比例和下载工件。

服务端每次生成新的 `semantic-<UTC时间>-<随机值>`：原始文件位于 `shared/data/raw/02-semantic-mapping/runs/<run-id>/`，处理输入位于 `shared/data/processed/02-semantic-mapping/<run-id>/`，结果位于 `shared/outputs/02-semantic-mapping/runs/<run-id>/`。固定 API 为 `GET/POST /api/semantic-mapping/runs`，只调用固定 Python 3.12 环境和固定脚本。

## 许可与下一步

| 项目 | 当前记录 |
| --- | --- |
| `geoai-py 0.42.0` | MIT |
| Rasterio | BSD 3-Clause；GDAL 等随附组件需分别遵守其许可 |
| GeoPandas / pandas / Shapely | BSD 3-Clause 系列 |
| OpenCV | Apache-2.0 |
| Pillow | HPND |
| 模型权重 | 无 |
| 验收影像 | 用户项目内已有影像副本，授权范围未在本 Demo 中扩展 |

下一步应优先选择项目任务 `drainage_blockage`，准备沟道、箱涵口、堵塞物、畅通和
“有杂物但未堵塞”的人工标注；再选择有独立许可证记录的轻量预训练权重，通过
`geoai.semantic_segmentation` 对比本颜色基线。没有真值前不开放该任务为控制台可运行
选项、不批量运行目录，也不建议产品接入。