# geoai-py 直接能力目录

版本基准：`geoai-py 0.42.0`（当前项目对象检测环境）。

本文只整理 `opengeos/geoai` 已有模块、接口和官方工作流，不把项目侧的风险规则、
工单、航线或算法组合误称为 `geoai-py` 内置能力。

## 先理解“直接使用”的含义

算法人员交付一个模型，不等于产品已经可以直接使用。真正可接入需要同时交付：

1. 模型权重或模型仓库地址，以及单独的许可证说明。
2. 输入格式、波段顺序、坐标系、分辨率、切片尺寸和归一化方式。
3. 类别清单、阈值、NMS/后处理参数和版本号。
4. 固定的推理入口与输出样例。
5. 一组正常、困难、误报和漏报样本，用于验收。

`geoai-py` 主要负责数据读取、切片、模型调用、地理结果写出和可视化；它不会
自动拥有“安全帽、钢丝绳断丝、矿浆渗漏”等项目领域模型。

## A 类：可以由 geoai-py 直接承接的算法产出

| 能力 | 主要接口/模块 | 算法人员可以交付什么 | geoai-py 可直接产出 | 当前使用边界 |
| --- | --- | --- | --- | --- |
| 目标检测 | `multiclass_detection`、`object_detection`、`object_detection_batch`、`RF-DETR`、`ObjectDetector` | 检测模型、类别表、阈值和切片参数 | 框、类别、置信度、实例掩膜、GeoTIFF/GeoDataFrame/GeoJSON | 内置 NWPU 模型主要是航空目标；人员、安全帽、垃圾等要专项模型。 |
| 语义分割 | `semantic_segmentation`、`semantic_segmentation_batch`、`train_segmentation_model`、`timm_semantic_segmentation` | 分割模型、类别映射、掩膜标签 | 像素类别掩膜、矢量图斑、面积统计 | 沟道、水体、堵塞物和边坡需要项目样本或适配模型。 |
| 实例分割 | `instance_segmentation`、`instance_segmentation_batch`、`GroundedSAM`、`CLIPSegmentation` | 实例分割模型或点/文本提示 | 每个目标的掩膜、类别和实例编号 | Grounded/SAM 类能力依赖额外模型与许可，不能当作零配置模型。 |
| 影像分类 | `classify_image`、`classify_images`、`train_classifier`、`image_classification` | 分类模型、标签和类别定义 | 类别、概率、批量分类结果 | 适合正常/异常、损坏等级等整图或切片分类。 |
| 变化检测 | `ChangeStarDetection`、`changestar_detect`、变化检测模块 | 双期模型、配准影像、变化阈值 | 变化栅格、变化图斑、置信度和矢量结果 | 双期影像必须配准、同坐标系；当前项目正射变化检测已有产品基础。 |
| 水体分割 | `segment_water` | 多光谱 GeoTIFF、波段顺序和水体样本 | 水体掩膜 GeoTIFF、水体 GeoJSON、多边形面积 | 需要 RGB+NIR 等四波段；普通 JPEG 不能直接替代多光谱输入。 |
| 树冠高度 | `canopy_height_estimation`、`CanopyHeightEstimation` | RGB 影像和对应模型权重 | 每像素树冠高度栅格，单位为米 | 这是树高估计，不是单木框选；模型权重较大，精度需现场验证。 |
| 深度估计 | `depth_estimation`、`AutoGeoModel` | 深度模型和 GeoTIFF | 深度 GeoTIFF | 通常是相对深度，不能直接当作测绘高程或工程位移。 |
| 像素回归 | `train_pixel_regressor`、`predict_raster`、`evaluate_regression` | 有目标栅格的回归训练集 | 连续值栅格 | 可用于高度、指数或风险分值，但裂缝宽度等工程量仍需标定。 |
| 特征嵌入与相似度 | `extract_patch_embeddings`、`extract_pixel_embeddings`、`cluster_embeddings`、`embedding_similarity`、`train_embedding_classifier` | 嵌入模型、样本库和相似度/聚类规则 | 特征向量、聚类、相似图、异常候选 | 适合样本稀缺的异常筛查，不能直接代替项目告警规则。 |
| 遥感基础模型 | `PrithviProcessor`、`UniverSatProcessor`、`DINOv3GeoProcessor`、`FOUNDATION_MODELS` | 基础模型权重和下游任务头 | 特征、分类/分割/回归推理结果 | 多数需要额外模型、波段和依赖；更适合作为训练或迁移学习底座。 |

## B 类：库有接口，但必须组合或补充依赖

| 方向 | 已有支持 | 还需要补充 |
| --- | --- | --- |
| 大图处理与地理输出 | GeoTIFF 切片、拼接、掩膜矢量化、框转 GeoJSON、Raster/Vector 工具 | 有效 CRS、仿射变换、统一坐标系和业务字段。 |
| 零样本/提示式识别 | Grounding DINO、OWL、Moondream、CLIP、SAM 等封装入口 | 外部模型、显存/CPU 评估、提示词、领域验证和许可。 |
| 质量与异常筛查 | 掩膜清理、栅格清理、云掩膜、超分辨率、嵌入聚类 | 业务质量规则、阈值和人工复核。 |
| 三维/连续值分析 | 深度估计、树冠高度、像素回归以及点云数据读写/下载辅助 | 摄影测量或 LiDAR、控制点、测量精度和三维重建流程。 |
| ONNX/部署 | `export_to_onnx`、ONNX 分割/分类 | `onnxruntime`、算子兼容、性能压测和部署环境。 |

## C 类：不能直接由 geoai-py 产出

下列结果需要现有产品后端、规则引擎或无人机系统配合：

- 电子围栏、危险区域包含/距离规则和告警等级。
- 自动悬停、喊话、返航、复飞和航线调整。
- 告警推送、工单派发、责任人、处置时限和闭环状态。
- 轨迹跟踪、行为识别、集群调度和飞行资源编排。
- 资产健康评分、预测性维护、知识图谱和汇报报表。

`geoai-py` 的 `Pipeline` 是代码级步骤编排工具，不等同于矿山巡检项目的业务
流程编排或无人机任务调度。

## 与瑶岗仙项目需求的直接对应关系

| 项目算法 | 可直接承接的库能力 | 必须由项目侧补充的部分 |
| --- | --- | --- |
| 人员安全识别 | 人员/安全帽目标检测、可选裁剪分类、GeoJSON 输出 | 安全帽专项模型、人员-安全帽关联、危险区规则、告警流程。 |
| 索道安全感知 | 检测、分割、异常筛查、像素回归 | 钢丝绳/卡扣缺陷模型、近景采集、三维测量和阈值。 |
| 爆破警戒热成像 | 目标检测接口、空间结果输出 | 热成像模型、电子围栏、自动悬停/喊话。 |
| 边坡监测 | 变化检测、分割、深度/回归、矢量统计 | 配准和测量精度、三维重建、位移/裂缝阈值。 |
| 排洪沟/堵塞 | 语义/实例分割、目标检测、变化检测、面积统计 | 沟道/箱涵口类别、堵塞物掩膜、纯负样本、严重度规则。 |
| 尾矿库矿浆渗漏 | 水体分割、分类、异常/变化检测 | 多光谱/热成像、真实渗漏样本、现场复核；RGB 浑浊不能直接证明渗漏。 |
| 竖井堵塞及损坏 | 检测、实例分割、异常筛查、测量 | 设施部位定义、近景样本和三维模型。 |

## 当前环境的可用性提醒

在当前 `01-object-detection` 环境中，已确认：

- 已安装：PyTorch、Rasterio、GeoPandas、Transformers、timm、Lightning、OpenCV。
- 未安装：`torchange`、`omniwatermask`、`rfdetr`、`terratorch`、`segment-geospatial`、`detectron2`、`onnxruntime`。
- 因此当前可以继续验证目标检测及其地理输出；ChangeStar、水体分割、RF-DETR、部分基础模型和 ONNX 部署需要先单独建环境或补充依赖。

## 给算法人员的交付清单

算法人员交付后，项目侧至少需要拿到以下内容，才能接入 `geoai-py` 或项目方案层：

| 交付项 | 最低要求 |
| --- | --- |
| 模型文件 | 权重路径/仓库、版本、许可证、适用输入。 |
| 数据规范 | JPG/PNG/GeoTIFF、波段顺序、CRS、GSD、切片和归一化。 |
| 标签规范 | 类别 ID/名称、框或掩膜格式、背景/无效值定义。 |
| 推理参数 | 置信度、NMS、最小面积、变化阈值或回归单位。 |
| 输出样例 | 至少一张正常样本、一张困难样本和对应 JSON/GeoJSON/栅格。 |
| 评估结果 | 样本数量、漏报、误报、IoU/F1/mAP 或回归误差、运行耗时。 |

这份目录用于判断“算法人员交付的模型能否被现有 GeoAI 工作流承接”，不替代
具体能力的 Demo、数据验收和商业授权审查。