• 人工智能
• 计算机视觉
• GIS
• 图像处理
• 微调

本文是 GeoAI（GitHub 加速计划 / ge / geoai）中geoai.object_detect模块的技术指南。该模块为多类别目标检测提供了开箱即用的高层封装：覆盖 COCO 格式数据集的训练、评估、滑动窗口推理、结果矢量化与可视化，并内置对 NWPU-VHR-10 遥感基准数据集及其预训练 Mask R-CNN 模型的支持。读完本文，你将掌握从数据集下载、训练拆分、模型训练、COCO 指标评估，到 GeoTIFF 推理与矢量结果导出的完整实战链路。

模块定位与整体架构

geoai.object_detect是 GeoAI 面向"多类别目标检测"的高层 API 模块，其完整实现位于 geoai/object_detect.py。模块文档字符串开宗明义：它提供基于 Mask R-CNN 系列模型、面向 COCO 格式数据集（bounding box 与实例分割 mask 两种标注）的训练、评估与推理便捷函数，并特别支持 NWPU-VHR-10 遥感基准。

从 geoai/init.py 的懒加载导出表可以看到，该模块的 14 个公共符号全部以("object_detect", None)形式注册，因此既可以直接import geoai.object_detect，也可以直接通过geoai.xxx顶层命名空间调用，例如geoai.train_multiclass_detector、geoai.multiclass_detection。

模块的底层计算逻辑复用 geoai/train.py 中的通用训练/推理基础设施：

• train_MaskRCNN_model（train.py）：统一训练入口，支持coco_detection等输入格式；
• get_detection_model（train.py）：按模型名构建检测网络；
• multiclass_detection_inference_on_geotiff（train.py）：GeoTIFF 滑动窗口推理；
• evaluate_coco_metrics（train.py）：COCO 风格 mAP 评估；
• COCODetectionDataset、collate_fn、get_transform等数据管线组件。

NWPU-VHR-10 数据集：类别、下载与训练集准备

NWPU-VHR-10 是模块默认绑定的遥感目标检测基准，包含 800 张超高分辨率（VHR）遥感影像，涵盖 10 个目标类别，共 3,775 个 COCO 格式标注实例（包围框 + 实例分割掩膜）。类别定义见 object_detect.py：

NWPU_VHR10_CLASSES = [ "background", "airplane", "ship", "storage_tank", "baseball_diamond", "tennis_court", "basketball_court", "ground_track_field", "harbor", "bridge", "vehicle", ]

注意索引 0 是"background"，实际目标类别是 10 类，加上背景后num_classes = 11。

下载数据集

import geoai data_dir = geoai.download_nwpu_vhr10(output_dir="NWPU-VHR-10", overwrite=False)

该函数（object_detect.py）从https://data.source.coop/opengeos/geoai/NWPU-VHR-10.zip下载数据，参数含义如下：

标注格式转换与训练/验证拆分

NWPU-VHR-10 原始标注是逐行文本格式(x1,y1),(x2,y2),class_id（左上/右下角点 + 类别 ID）。模块内置两个私有工具完成转换：_parse_nwpu_gt_file（object_detect.py）解析单行标注并转换为 COCO 的(x, y, w, h)格式；_convert_nwpu_to_coco（object_detect.py）遍历图像目录与真值目录，生成包含images、annotations、categories三段的 COCO JSON，并把包围框同时写成多边形 segmentation。

公开入口是prepare_nwpu_vhr10：

splits = geoai.prepare_nwpu_vhr10(data_dir, output_dir=None, val_split=0.2, seed=42)

• output_dir：整理后数据输出目录，默认与data_dir相同；
• val_split：验证集比例，默认0.2；
• seed：随机种子（使用sklearn.model_selection.train_test_split），保证可复现。

函数内部会自适应多种目录结构（如NWPU-VHR-10/NWPU-VHR-10/嵌套目录、positive image set/ground truth等命名变体），返回一个字典，关键键如下：

值得注意的实现细节：仅包含至少一个标注的图像会进入拆分。NWPU-VHR-10 中 150 张"负样本"（无目标对象）图像会被排除在训练/验证集之外（见 object_detect.py 的 docstring）。

训练多类别检测模型

支持的模型架构

train_multiclass_detector（object_detect.py）支持 5 种 torchvision 检测架构，定义在 train.py 的DETECTION_MODELS集合中：

在get_detection_model（train.py）中，各架构的分类头都会被替换为匹配num_classes的预测器：Faster R-CNN 系替换roi_heads.box_predictor；RetinaNet/FCOS 系按num_anchors * num_classes重建cls_logits卷积层；Mask R-CNN 则委托给get_instance_segmentation_model。非 RGB 输入（如num_channels=4的 RGBN）还会通过_adjust_backbone_channels调整骨干网络首层通道数。

训练函数参数详解

model_path = geoai.train_multiclass_detector( images_dir=splits["images_dir"], # 训练图像目录 annotations_path=splits["train_annotations"], # COCO JSON output_dir="nwpu_output", # 模型输出目录 model_name="fasterrcnn_resnet50_fpn_v2", # 架构，见上表 class_names=splits["class_names"], # 含 background 的类别名 num_channels=3, # 输入通道数（3=RGB） batch_size=4, num_epochs=50, learning_rate=0.005, val_split=0.2, seed=42, pretrained=True, # 是否使用预训练骨干 pretrained_model_path=None, # 自定义预训练权重 device=None, # 自动检测 CUDA/MPS/CPU num_workers=None, verbose=True, )

各参数要点：

• num_classes自动推导：函数读取 COCO JSON 的categories，num_classes = len(categories) + 1（+1 为背景）。若class_names未提供，会自动按类别 ID 排序生成["background", ...]。
• 输出产物：训练结束后在output_dir下生成best_model.pth（最优权重）、class_info.json（记录class_names、num_classes、model_name，供推理时侧车读取）以及training_history.pth（训练历史）。返回值为best_model.pth的路径。
• 底层调用：该函数最终调用train_MaskRCNN_model(..., input_format="coco_detection", ...)（train.py 起），即所有架构统一走这一训练管线。

查看训练历史

训练完成后，可用plot_detection_training_history（object_detect.py）绘制training_history.pth中的曲线，最多三幅子图：训练/验证 Loss、验证 IoU、学习率调度，缺失的键对应的子图会自动跳过：

geoai.plot_detection_training_history( history_path="nwpu_output/training_history.pth", figsize=(15, 4), output_path="training_metrics.png", # 不传则交互显示 )

评估：COCO 风格 mAP

evaluate_multiclass_detector（object_detect.py）加载训练好的权重，在指定数据集上计算 COCO 风格指标：

metrics = geoai.evaluate_multiclass_detector( model_path=model_path, # 训练产出的 .pth images_dir=splits["images_dir"], annotations_path=splits["val_annotations"], num_classes=splits["num_classes"], # 11 class_names=splits["class_names"][1:], # 不含 background batch_size=4, )

其评估核心是 train.py 的evaluate_coco_metrics，默认在 IoU 阈值[0.5, 0.55, ..., 0.95]（共 10 档）上计算各类别 AP，返回字典包含mAP@0.5、mAP@0.75、mAP@[0.5:0.95]以及逐类AP@0.5/<class_name>条目。评估数据管线使用COCODetectionDataset（compute_masks=model_has_masks(model_name)，仅 Mask R-CNN 计算掩膜），Windows/macOS 下默认num_workers=0，Linux 默认 4。

模块自带的 NWPU-VHR-10 预训练 Mask R-CNN（ResNet-50 FPN）在其验证集上的公开指标（记录于 object_detect.py docstring）为：mAP@0.5 ≈ 0.709、mAP@0.75 ≈ 0.518、mAP@[0.5:0.95] ≈ 0.459。

推理：GeoTIFF 滑动窗口检测

单影像推理

multiclass_detection（object_detect.py）是核心推理入口：

result_path, inference_time, detections = geoai.multiclass_detection( input_path="image.tif", # GeoTIFF / JPEG / PNG 均可 output_path="output.tif", model_path=None, # None 则自动下载预训练 NWPU-VHR-10 模型 model_name=None, # 自动探测架构 num_classes=11, class_names=None, # 自动使用 NWPU-VHR-10 类别 window_size=512, # 滑动窗口尺寸 overlap=256, # 相邻窗口重叠像素 confidence_threshold=0.5, # 置信度阈值 nms_threshold=0.3, # NMS IoU 阈值 batch_size=4, num_channels=3, device=None, # 自动选择设备 )

关键行为：

• 预训练模型自动下载：当model_path=None时，自动从 Hugging Face Hub（giswqs/nwpu-vhr10-maskrcnn，文件名best_model.pth，见 object_detect.py）下载权重，并将num_classes设为 11、class_names设为 NWPU-VHR-10 类别、架构回退为maskrcnn_resnet50_fpn。
• 非 GeoTIFF 输入自动转 TIFF：JPEG/PNG 等输入会先转成临时 RGB GeoTIFF 再进入推理，完成后自动清理临时文件。
• 侧车配置与权重自描述：优先读取权重同目录的class_info.json恢复类别与架构；若model_name仍为 None，则通过检查 checkpoint 键自动判别——存在roi_heads.mask_predictor.conv5_mask.weight判定为 Mask R-CNN；存在roi_heads.box_predictor.cls_score.weight判定为 Faster R-CNN；存在head.classification_head.cls_logits.weight时再依据有无anchor_generator.*键区分 RetinaNet（有 anchor）与 FCOS（无 anchor）。num_classes也会从权重形状反推（RetinaNet 的通道数需除以 anchor 数 9）。
• 输出格式：输出为双波段栅格——波段 1 为类别标签，波段 2 为实例 ID（见 train.py 的说明，区别于输出二值 mask 的inference_on_geotiff和只输出实例 ID 的实例分割推理）。
• 返回值：(output_path, inference_time, detections_list)，其中每个 detection 为包含mask、score、box、label的字典。

底层实现multiclass_detection_inference_on_geotiff（train.py 起）以stride = window_size - overlap计算步长，对整幅影像按窗口切块、以batch_size批量前向推理，并过滤低于confidence_threshold的检测；对无 mask 输出的 bbox-only 模型，会生成包围框形状的伪 mask，从而统一下游处理。

批量推理

batch_multiclass_detection（object_detect.py）接收图像路径列表，逐个调用multiclass_detection，输出目录中每个影像生成<basename>_detection.tif，并可选择将各图检测结果绘制成网格图：

results = geoai.batch_multiclass_detection( image_paths=["a.tif", "b.tif"], output_dir="detections", visualize=True, # 绘制结果网格 cols=2, figsize=(16, 16), cleanup=True, # 可视化后清理中间栅格 output_path="grid.png", # 保存网格图 )

每个结果是(result_path, inference_time, detections_list)元组。该函数已由 tests/test_object_detection_batch.py 覆盖测试（geoai.train.object_detection_batch的文件解析与命名生成逻辑）。

检测结果矢量化：像素坐标 → 地理坐标

detections_to_geodataframe（object_detect.py）把像素空间的检测结果转换为带 CRS 的geopandas.GeoDataFrame，是栅格检测结果进入 GIS 工作流的关键一步：

gdf = geoai.detections_to_geodataframe( detections=detections, # multiclass_detection 的返回值 geotiff_path="input.tif", # 源 GeoTIFF，提供 CRS 与 transform class_names=splits["class_names"], use_mask_geometry=False, # True 时用实例 mask 多边形，否则用包围框矩形 simplify_tolerance=0.0, # mask 多边形简化容差（地理单位），0 表示不简化 )

• 输出列：geometry、class_id、class_name、score、instance_id、area_pixels。
• use_mask_geometry=True时，通过rasterio.features.shapes将实例 mask 栅格化为多边形，支持紧凑 mask（mask_offset）裁剪与unary_union合并，并用simplify_tolerance做拓扑保持的简化；失败时回退到包围框矩形。
• 空检测列表会返回仅含上述列的空 GeoDataFrame，保证下游代码健壮性。
• 该函数同样被 tests/test_instance_segmentation.py 引用使用。

可视化工具集

检测结果叠加可视化

visualize_multiclass_detections（object_detect.py）在影像上绘制带类别标签与置信度的彩色包围框，并按得分降序最多绘制max_detections=200个：

geoai.visualize_multiclass_detections( image_path="image.tif", detections=detections, class_names=splits["class_names"], confidence_threshold=0.5, # 低于此分的检测不显示 figsize=(15, 10), output_path="detections.png", # 不传则交互显示 )

COCO 标注预览

visualize_coco_annotations（object_detect.py）在训练前检查标注质量非常实用——加载 COCO JSON，以网格形式展示样本影像与包围框标注：

geoai.visualize_coco_annotations( annotations_path=splits["annotations_path"], images_dir=splits["images_dir"], num_samples=4, random=False, seed=None, figsize=(14, 14), cols=2, output_path="annotations.png", )

Hugging Face Hub 集成：模型发布与远端推理

模块打通了与 Hugging Face Hub 的双向通道，便于模型共享与复现：

发布模型：push_detector_to_hub（object_detect.py）将best_model.pth与config.json（含model_type、model_name、num_classes、num_channels、class_names）上传到指定仓库，仓库不存在时自动创建：

url = geoai.push_detector_to_hub( model_path="nwpu_output/best_model.pth", repo_id="your_name/nwpu-detector", model_name="fasterrcnn_resnet50_fpn_v2", num_classes=11, num_channels=3, class_names=splits["class_names"], private=False, token=None, # token 默认使用 huggingface-cli login 的凭据 )

从 Hub 推理：predict_detector_from_hub（object_detect.py）下载model.pth与config.json，依据 config 自动恢复num_classes、num_channels、class_names与model_name后委托multiclass_detection执行推理；私有仓库可通过token访问。

下载预训练权重：download_nwpu_vhr10_model（object_detect.py）可直接拉取giswqs/nwpu-vhr10-maskrcnn的best_model.pth到本地缓存。

端到端示例脚本

仓库提供了完整可运行的端到端示例 scripts/object_detection_nwpu.py（约 243 行），按 8 步串联上述全部 API，直接python scripts/object_detection_nwpu.py即可执行：

1. 下载数据集：geoai.download_nwpu_vhr10()并打印 11 个类别；
2. 准备拆分：geoai.prepare_nwpu_vhr10(data_dir, val_split=0.2, seed=42)；
3. 标注可视化：手工绘制前 4 张样本的包围框，保存nwpu_sample_annotations.png；
4. 训练：geoai.train_multiclass_detector(..., batch_size=4, num_epochs=20, learning_rate=0.005, val_split=0.15)，输出到nwpu_output；
5. 训练曲线：读取training_history.pth绘制 Loss / Val IoU / LR 三联图；
6. 评估：geoai.evaluate_multiclass_detector(...)输出 COCO mAP；
7. 推理：对验证集首张影像执行geoai.multiclass_detection(window_size=512, overlap=256, confidence_threshold=0.5)，打印推理耗时与检测数；
8. 结果可视化：geoai.visualize_multiclass_detections(...)保存nwpu_detections.png，并清理中间栅格。

小结

geoai.object_detect将遥感多类别目标检测的完整链路收敛为少量高层函数：prepare_nwpu_vhr10解决数据集整理，train_multiclass_detector统一训练 5 种 torchvision 检测架构，evaluate_multiclass_detector输出 COCO mAP，multiclass_detection以滑动窗口处理任意尺寸 GeoTIFF，detections_to_geodataframe完成结果矢量化，配合batch_multiclass_detection与 Hugging Face Hub 的推送/拉取能力，可快速搭建从数据到 GIS 产品的目标检测生产线。相关源码、测试与示例分别位于 geoai/object_detect.py、geoai/train.py、tests/test_object_detection_batch.py 与 scripts/object_detection_nwpu.py，可自行查阅深入研究。

• 人工智能
• 计算机视觉
• GIS
• 图像处理
• 微调