空间测量（计数与空间测量）

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

能力边界

当前 Demo 属于 B：GeoAI 与地理空间生态库组合能力，不是 geoai-py 内置的完整测量产品。

geoai-py 0.42.0 的 masks_to_vector 将每个非零栅格类别转为对象多边形。
Rasterio 读取和保留有效 CRS/仿射变换；GeoPandas/Shapely 计算对象数量、面积、周长、质心和包围盒。
Demo 不负责从普通 RGB 影像识别类别。输入必须是上游检测/分割流程产生的标签栅格。
无有效投影 CRS 时只报告像素或坐标单位，不能表述为米、平方米或工程测量精度。

Demo 契约

输入：单份或目录形式的单波段 PNG/TIF/TIFF 标签栅格，0 为背景，正整数为对象类别。普通 JPEG/RGB 影像不在本 Demo 输入范围内。

每份输入输出：

文件	内容
`*.objects.tif`	保留输入标签值的结果栅格；有效地理参考会被保留
`*.measurement.png`	可直接检查的彩色栅格预览
`*.measurements.geojson`	GeoAI 矢量对象及面积、周长、质心、包围盒等属性
`*.measurements.csv`	每个对象一行的测量表
`run_metadata.json`	版本、设备、输入数、耗时、单位依据、汇总和限制

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

环境与运行

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1 -Capability 04-spatial-measurement

$py = '.\.venvs\04-spatial-measurement\Scripts\python.exe'
& $py .\capabilities\04-spatial-measurement\run_spatial_measurement.py `
  --input .\shared\data\raw\04-spatial-measurement\validation-20260817 `
  --output .\shared\outputs\04-spatial-measurement\my-run

本机已验证 Python 3.12.10、geoai-py 0.42.0、Rasterio 1.5.1、GeoPandas 1.1.4 和 OpenCV 4.14.0；仅使用 CPU，pip check 通过。

验收集与实测

验收输入位于 shared/data/raw/04-spatial-measurement/validation-20260817/，来自语义分割能力对仓库内真实无人机 JPEG 的标签栅格输出副本：

正常样本 normal-vegetation-roads.mask.tif：3840 x 2160，包含植被、水体和不透水面等多类区域。
困难样本 difficult-road.mask.tif：3840 x 2160，大面积道路类别占主导，用于检查低多样性、小区域和噪声对象。

样本	对象数	类别对象数	总面积	总周长	CPU 耗时
正常	1,210	1: 130、2: 548、3: 532	7,780,682 pixel^2	259,430 pixel	25.190 秒
困难	89	1: 18、2: 49、3: 22	8,173,263 pixel^2	36,686 pixel	9.474 秒

两份结果均先使用 geoai.masks_to_vector，再与 Rasterio 参考矢量覆盖面积比较。GeoAI 会丢弃部分复杂无效轮廓，因此三类都触发了完整性修复，最终 GeoJSON 保留栅格图斑及孔洞。栅格预览、GeoTIFF、GeoJSON、CSV 和元数据非空；两张 PNG 已视觉检查。GeoJSON 的对象条数分别为 1,210 和 89，且每条均含测量字段。

自动验收：

.\.venvs\04-spatial-measurement\Scripts\python.exe -m unittest discover `
  -s .\capabilities\04-spatial-measurement\tests -v

测试覆盖像素坐标计数、投影 CRS 测量单位和空标签栅格失败分支。

本地实验控制台

默认入口：http://127.0.0.1:6173/apps/workbench-console/#/capability/04-spatial-measurement。本次为避免占用已有 6173 服务，验证实例运行于 http://127.0.0.1:6175/apps/workbench-console/#/capability/04-spatial-measurement。

页面遵循“新建运行 -> 案例库 -> 结果工作区”，支持最多 4 份标签栅格上传，并列展示栅格预览和矢量对象范围，显示汇总/对象明细并下载 GeoTIFF、GeoJSON、CSV 和元数据。服务端仅调用固定的 04 虚拟环境和能力脚本，每次创建新的 raw、processed 和 output run 目录。

已验证控制台页面 200、运行发现、有效上传、非法扩展、危险文件名清洗、超大请求拒绝和脚本失败消息。当前浏览器控制接口没有可用浏览器，因此控制台页面未完成截图级桌面/移动端视觉验收。

许可与限制

项目	当前记录
`geoai-py 0.42.0`	MIT
Rasterio	BSD 3-Clause；GDAL 等随附组件需分别遵守许可
GeoPandas / pandas / Shapely	BSD 3-Clause 系列
OpenCV	Apache-2.0
Pillow	HPND
模型权重	无；本能力消费上游标签栅格
验收影像/标签	用户项目内已有影像与其派生结果，授权范围未在本 Demo 中扩大

当前对象计数取决于上游标签质量、连通关系和最小对象面积（4 像素）设置。没有人工真值，不能报告计数准确率、误报率或漏报率；真实米制测量还需要带有效投影 CRS、已校准分辨率且精度可追溯的 GeoTIFF。