From f67d43a43f6c3e58922e3c2f457dd9caafebfc67 Mon Sep 17 00:00:00 2001
From: shuishen <1109946754@qq.com>
Date: Fri, 14 Aug 2026 14:20:22 +0800
Subject: [PATCH] feat:具体能力实现处理

---
 capabilities/01-object-detection/README.md |  103 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 99 insertions(+), 4 deletions(-)

diff --git a/capabilities/01-object-detection/README.md b/capabilities/01-object-detection/README.md
index 8a90073..4bb47f7 100644
--- a/capabilities/01-object-detection/README.md
+++ b/capabilities/01-object-detection/README.md
@@ -1,6 +1,101 @@
-# Object Detection
+# 地物目标检测
 
-- 输入：无人机照片或视频帧。
-- 输出：目标框、类别、置信度和位置。
-- 首个 Demo：10–30 张图片的预训练模型推理与 JSON 导出。
+## 目标
 
+先做一个可在本机 CPU 运行的预训练模型 Demo：输入无人机照片，输出带目标框、类别和置信度的标注图片，以及结构化 JSON。第二阶段再支持正射 GeoTIFF 切片，并把像素坐标转换为经纬度后输出 GeoJSON，便于接入现有 Cesium 地图和算法管理模块。
+
+本能力使用 [opengeos/geoai](https://github.com/opengeos/geoai) 发布的 `geoai-py` 作为 GeoAI 工作流层。它负责把地理影像处理、AI 推理、地理结果和可视化串起来；PyTorch、Rasterio、GeoPandas 等仍是它和本 Demo 的底层运行依赖。
+
+## 当前范围
+
+首版优先识别人员、车辆。`geoai-py` 自带的 NWPU-VHR10 预训练模型面向航空影像，并提供统一的 `vehicle` 类，但不包含人员和树木；因此当前采用“切片 YOLO 检人员 + GeoAI NWPU 检车辆”的分支方案。树木通常需要专门的树冠/单木数据集和模型微调。
+
+## 需要你准备的内容
+
+1. **目标清单**：请先确定最关心的 3–5 类目标，例如人员、车辆、挖掘机、船只、建筑物。
+2. **样例图片**：准备 10–30 张无人机 JPG/PNG，尽量包含不同高度、角度、天气和目标大小。不要使用涉密或未经授权的照片。
+3. **正射样例（第二阶段）**：准备 1–2 份 GeoTIFF，并记录坐标系、分辨率和拍摄时间。
+4. **输出接入约定**：确认结果需要保存为 JSON/GeoJSON，还是还要生成 Cesium 可加载的 GeoJSON/KML。
+5. **验收样例**：从图片中挑选 5 张作为固定验收集，不参与后续调参。
+
+## 目录约定
+
+```text
+01-object-detection/
+|-- README.md
+|-- requirements.txt
+|-- src/                 # 推理和结果转换代码
+|-- scripts/             # 一键运行脚本
+|-- tests/               # 单元测试
+shared/
+|-- data/raw/01-object-detection/       # 原始图片，只存本地
+|-- data/processed/01-object-detection/ # 切片或预处理结果
+|-- models/01-object-detection/         # 模型权重，不提交 Git
+`-- outputs/01-object-detection/        # 标注图、JSON、GeoJSON
+```
+
+## 环境与硬件
+
+- 使用 Python 3.12 专用环境：`.venvs/01-object-detection`。
+- 当前电脑是 AMD RX 590 GME 8GB，不具备 NVIDIA CUDA；首版使用 CPU 推理。
+- 64GB 内存足够运行 10–30 张图片的 Demo。大尺寸正射影像需要切片，不能一次性全部载入内存。
+- 模型权重和 Python 包必须记录版本与许可证，产品使用前检查是否允许商用。
+- `geoai-py` 项目本身为 MIT 许可证；它依赖的模型权重、数据集和第三方库仍需分别核查许可证。`ultralytics` 等可选底层组件的许可证不能由 GeoAI 的 MIT 许可证自动覆盖。
+
+## 预期输入输出
+
+输入：JPG/PNG 图片，或第二阶段的 GeoTIFF。
+
+输出：
+
+- `annotated/`：画出检测框和标签的图片；
+- `detections.json`：图片名、类别、置信度、像素框坐标；
+- `detections.geojson`：正射影像场景下的地理框或中心点；
+- `run_metadata.json`：模型版本、阈值、运行时间、设备（CPU/DirectML）。
+
+## 首版验收标准
+
+- 能通过命令行处理单张图片和一个图片目录；
+- 输出图片能看到检测框、类别和置信度；
+- JSON 字段固定且可被前端读取；
+- 对固定 5 张验收图片，结果可重复生成；
+- 无 GPU 时能正常运行，并对超大图片给出清晰错误提示或自动缩放；
+- 运行日志包含模型、置信度阈值、输入数量、输出路径和耗时。
+
+## 预计开发顺序
+
+1. 创建专用环境并安装 PyTorch、torchvision、Ultralytics；
+2. 下载并登记一个允许研究/商用核查的预训练权重；
+3. 完成单图推理；
+4. 完成目录批处理、标注图和 JSON 导出；
+5. 用你的无人机图片验证并调整阈值；
+6. 增加 GeoTIFF 切片和 GeoJSON 坐标转换；
+7. 最后再做 FastAPI 接口和现有前端接入。
+
+## 当前 Demo 运行命令
+
+在项目根目录执行人员/通用车辆切片基线：
+
+```powershell
+.\.venvs\01-object-detection\Scripts\python.exe .\capabilities\01-object-detection\run_detection.py
+```
+
+默认使用 CPU、`yolo11n.pt`、1024 像素切片、20% 重叠和置信度阈值 0.20。
+结果写入 `shared/outputs/01-object-detection/`。
+
+执行 GeoAI NWPU-VHR10 航拍车辆检测：
+
+```powershell
+.\.venvs\01-object-detection\Scripts\python.exe .\capabilities\01-object-detection\run_geoai_vehicle_detection.py
+```
+
+该脚本默认使用 CPU、512 像素滑窗、128 像素重叠和置信度阈值 0.30，结果写入
+`shared/outputs/01-object-detection/geoai-vehicles/`。首次运行会自动下载约 98 MB
+的模型权重。
+
+## 当前验证结论
+
+- `DJI_20260810092727_0001_V_10.jpeg`：通用 YOLO 检出 2–3 辆车；GeoAI NWPU 检出 33 个车辆候选，CPU 推理约 90 秒，明显改善俯视小车辆漏检。
+- `DJI_20260713102047_0001_V_19.jpeg`：切片 YOLO 检出多个人员，但两种模型均未检出右上角红色汽车；该近景车顶外观仍需要更匹配的航拍数据或本项目样本微调。
+- NWPU 会产生少量其他航拍类别误检，正式 Demo 只保留 `vehicle`；脚本还会过滤被高置信度整车框大部分包含的重复局部框。
+- 树木不属于当前两个模型的有效类别，必须单独建设树冠检测/分割分支。

--
Gitblit v1.9.3