# 地物目标检测

## 目标

先做一个可在本机 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`；脚本还会过滤被高置信度整车框大部分包含的重复局部框。
- 树木不属于当前两个模型的有效类别，必须单独建设树冠检测/分割分支。
## 控制台运行入口

本地实验控制台可以直接上传最多 12 张 `JPG/JPEG/PNG` 进行一次 CPU 基线检测。每次运行会把原图保存到 `shared/data/raw/01-object-detection/runs/<run-id>/`，结果保存到 `shared/outputs/01-object-detection/runs/<run-id>/`，不会覆盖既有基线或用户原图。页面默认将同一影像的原图与标注图并列展示，并可在案例库中回看历史运行。

该入口调用固定的 `run_detection.py` 与 `01-object-detection` 虚拟环境，仍然只适用于人员和常见车辆的基线验证；树木、真实准确率、许可审查和生产批处理不在此入口的承诺范围内。