From 91e2fe47a57cd39b612d54177b548e4ec3432783 Mon Sep 17 00:00:00 2001
From: shuishen <1109946754@qq.com>
Date: Mon, 17 Aug 2026 14:50:48 +0800
Subject: [PATCH] feat:语义分割demo处理

---
 capabilities/02-semantic-mapping/README.md |  103 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 99 insertions(+), 4 deletions(-)

diff --git a/capabilities/02-semantic-mapping/README.md b/capabilities/02-semantic-mapping/README.md
index 36bf371..c65c49e 100644
--- a/capabilities/02-semantic-mapping/README.md
+++ b/capabilities/02-semantic-mapping/README.md
@@ -1,6 +1,101 @@
-# Semantic Mapping
+# 语义分割
 
-- 输入：正射影像切片和可选标注。
-- 输出：分割掩膜、GeoJSON 图层和面积统计。
-- 首个 Demo：建筑或水体二选一，使用小区域和轻量预训练模型。
+状态：首个 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` 对比本颜色基线。没有真值前不开放该任务为控制台可运行
+选项、不批量运行目录，也不建议产品接入。

--
Gitblit v1.9.3