语义分割

状态：首个 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。控制台类别选择必须
来自这个目录，并且只允许 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 -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 个像素标为不透水面，仅有少量植被/水体误分。该结果只证明数据流与输出契约可用，不证明真实业务精度。

自动验收：

$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 对比本颜色基线。没有真值前不开放该任务为控制台可运行
选项、不批量运行目录，也不建议产品接入。