VisDrone转COCO格式JSON实战：无人机目标检测数据标注转换与避坑指南

简介面向无人机目标检测算法开发者的数据集格式转换包将官方标注转换为COCO标准格式免去手动转换与格式校验的麻烦。压缩包共四个文件两份JSON核心标注文件分别对应训练集与验证集、一份类别说明文本、一张图片下载指引图总体积约十点一八MB。数据按COCO标准目录布局目录结构直观下载官方图片放入对应文件夹即可直接参与训练。转换时发现并剔除了十张训练集图片中的错误标注数据经过YOLOX实际训练及模型测试能确保标注可用同时支持导入百度EasyDL平台进行格式验证。整个流程省去自行编写转换脚本的时间。适合需要快速获得标准COCO数据的算法工程师、科研学生及竞赛参与者目前已有七百六十五人学习下载。1. VisDrone 转 COCO 格式 JSON无人机目标检测项目最需要的那份“翻译结果”如果你还没开始玩 VisDrone可能觉得数据集下载下来就是一张张图和一堆 txt 标注直接丢给模型不就行了。真到这一步才会发现从当前最主流的检测框架——MMDetection、Detectron2、YOLOv8 官方代码——没有一个能对 VisDrone 自带的 txt 标注“开箱即食”。大家都是先转成 COCO 格式的 JSON 文件再挂在自定义数据集上训练。这份资源就是把 VisDrone 各子集的 txt 标注整理成标准 COCO JSON省掉的正是那种“写一堆脚本、反复改格式、最后分类不对”的体力活。我拆了一份这类资源会把它能用在哪、怎么验收、最容易踩的坑按实际使用顺序写给你。适合手里已有 VisDrone 数据、或者正准备做无人机视角目标检测的开发者你不需要先学完整个 COCO 协议读完这篇就能把这批 JSON 用起来。2. VisDrone 原始标注与 COCO JSON 的结构差异为什么要倒腾这一趟2.1 VisDrone 的 txt 标注里到底有什么VisDrone 的检测任务标注不是像 VOC 那样的 XML也不是像 COCO 那样的 JSON而是每张图片对应一个同名的 txt 文件。打开一个典型的标注文件你会看到每一行都是八个数字用空格分隔。顺序依次是bbox_left, bbox_top, bbox_width, bbox_height, score, category, truncation, occlusion拿一个真实例子来说523 812 32 58 0 2 0 1这一行的意思是框的左上角在(523, 812)宽度 32 像素高度 58 像素score0表示这是训练标注不是检测器输出的置信度category2对应的是peopletruncation0说明目标没有被截断occlusion1说明目标被部分遮挡。注意这个 bbox 表示方式和 COCO 一样都是x, y, w, h前两列是左上角坐标不是中心点。很多新手拿着 YOLO 的习惯去看这个 txt以为前两列是中心点直接转换后框全飘出去这是第一个坑后面避坑章节再展开。VisDrone 的类别定义官方说明里是从 0 到 11 都有意义0 表示忽略区域1 到 10 是十个真实目标类pedestrian、people、bicycle、car、van、truck、tricycle、awning-tricycle、bus、motor。有些版本还会出现 11others不过实操中大家一般把 0 和 11 都过滤掉只保留十类做训练。不同来源的资源可能对类别编号的处理不一样所以拿到 JSON 后第一步一定要检查 categories 字段而不是想当然认为它和 COCO 的 80 类一样。2.2 COCO 格式 JSON 的五个顶层字段COCO 格式的标注文件顶层是一个 dict里面通常是五个 keyinfo数据集的描述信息纯字典用来记录版本、作者这些模型训练框架一般不会读它。licenses一个列表每个元素是一个 license 字典。这个字段对于学术数据集类似声明用途。images一个 JSON 数组每个元素是一张图的元信息包括id、file_name、width、height。annotations一个 JSON 数组每个元素是一个目标的标注包括bbox、area、segmentation、iscrowd、category_id等。categories一个 JSON 数组每个元素是id和name定义检测目标的类别。JSON 数组这个说法你在处理 COCO 时一定会反复碰到images是数组annotations是数组categories也是数组。数组的长度就等于数据集规模。所以当你用json.load打开这个大文件时如果内存不足常见做法是用json.load配合ijson流式解析或者在转换时按子集分文件而不是一次把所有标注塞进一个json。2.3 这份“visdrone-coco格式json”到底给了你什么按标题来看资源提供的是一份已经转换好的 COCO 格式 JSON 文件。我拿到的这类资源一般解压之后包含train.json、val.json可能还有test.json或者trainval.json同时附带一份简单的转换说明或一个convert.py脚本。文件内部结构就是上面说的五个顶层字段annotations 里面是过滤掉 ignore 区域后的目标框。拿到手别急着用先用一个短脚本把顶层字段和数量打印出来确认它和你手里的图片数量、标注数量对得上。这一步花五分钟能省下训练到一半发现数据加载异常的大麻烦。import json with open(visdrone_train.json, r) as f: coco json.load(f) print(keys:, list(coco.keys())) print(images:, len(coco[images])) print(annotations:, len(coco[annotations])) print(categories:, len(coco[categories])) # 打印 categories 内容看看 id 和 name 映射 for cat in coco[categories]: print(cat[id], cat[name])这里用到的json.load会把整个文件解析成一个 Python 字典也就是一个嵌套的 dict 和 list 结构。len(coco[images])得到的是images这个 JSON 数组的长度也就是图片张数len(coco[annotations])是标注框总数。如果你的训练集有两万多张图、几十万个框这两行打印出来的数字会帮你立刻判断文件是不是被截断或者错误合并。3. 把这份 JSON 接入检测框架MMDetection 与 Detectron2 的具体操作3.1 先做一个校验脚本确认 JSON 没有“看着正常、实际数据坏了”我在把转换好的 JSON 接到训练框架之前会习惯性写一个小校验遍历annotations检查是否每个bbox长度是 4、都是非负数检查image_id是否都能在images中找到检查category_id是否都在categories中。这一步不是形式主义因为我曾在别人的资源里碰到过 image_id 和图片信息对不上的情况一训练就报 KeyError。import json with open(visdrone_train.json, r) as f: coco json.load(f) image_ids {img[id] for img in coco[images]} cat_ids {cat[id] for cat in coco[categories]} legit_bbox_count 0 for ann in coco[annotations]: x, y, w, h ann[bbox] assert w 0 and h 0, f非正宽高: {ann[bbox]} assert ann[image_id] in image_ids, fimage_id 不存在: {ann[image_id]} assert ann[category_id] in cat_ids, fcategory_id 不存在: {ann[category_id]} legit_bbox_count 1 print(f校验通过共 {len(coco[annotations])} 条标注bbox 合法性检查完成)这个脚本用 Python 内置的json.load把 JSON 数组读成列表然后用一个循环加三个断言做检查。assert的作用是在条件为False时直接抛出异常这样你能立刻定位到第一条异常标注。如果是几十万条标注的大文件这里不建议每次都用断言最好换成统计异常并汇总否则一条错就会中断整个校验。不过实际情况下绝大部分资源都能直接通过这类检查。3.2 MMDetection 里注册 VisDrone COCO 数据集MMDetection 识别 COCO 格式是通过CocoDataset这个类你需要提供一个配置文件告诉它data路径、classes列表和ann_file路径。假设你把 JSON 放在了data/visdrone/annotations/目录下对应的简化配置大概是这样的dataset_type CocoDataset data_root data/visdrone/ data dict( traindict( typedataset_type, ann_filedata_root annotations/visdrone_train.json, img_prefixdata_root images/, classes(pedestrian, people, bicycle, car, van, truck, tricycle, awning-tricycle, bus, motor), ), valdict( typedataset_type, ann_filedata_root annotations/visdrone_val.json, img_prefixdata_root images/, classes(pedestrian, people, bicycle, car, van, truck, tricycle, awning-tricycle, bus, motor), ), )配置里ann_file指的就是那份 COCO 格式 JSON 文件。img_prefix是图片的根路径classes是一个元组必须和 JSON 中categories数组的name顺序保持一致。MMDetection 的CocoDataset默认会读categories里的 id 和 name你再在配置里写一遍classes主要是为了测试时类别显示方便。这个配置片段里我用的是旧版 MMDetection 2.x 的写法现在 3.x 换了dataset注册方式核心逻辑不变。你如果用的是 MMYOLO配置里一般会用data_convert工具提前把 JSON 转成底层的内存索引不过输入同样得是 COCO JSON。3.3 Detectron2 注册的方法Detectron2 稍微不一样它要求register_coco_instances来把 JSON 注册到数据集目录中。代码很简单写在训练脚本的入口处即可from detectron2.data.datasets import register_coco_instances register_coco_instances( namevisdrone_train, metadata{thing_classes: [pedestrian, people, bicycle, car, van, truck, tricycle, awning-tricycle, bus, motor]}, json_filedata/visdrone/annotations/visdrone_train.json, image_rootdata/visdrone/images/ )注册完name对应的字符串就是你训练配置里的DATASETS.TRAIN。Detectron2 对metadata里的thing_classes非常看重如果顺序和 JSON 里的id不一致训练不会报错但可视化标签会错位。这里image_root的值要正确Detectron2 会拿images里的file_name拼接这个根路径。VisDrone 原始目录结构是VisDrone2019-DET-train/images/0000001_00000_d_000001.jpg这种你在转换时多少会改目录所以最好先让 JSON 里的file_name保持相对路径然后再设置image_root避免出现盘符或绝对路径的硬编码问题。4. COCO JSON 与 VisDrone 的字段映射细节bbox、area、segmentation 与类别 ID4.1 bbox 字段的映射规则COCO 的 bbox 定义是[x_left, y_top, width, height]坐标是浮点数单位是像素。VisDrone 的 txt 原样就是左上角坐标加宽高数值是整数。所以这个转换在几何上不需要任何变换只需要把整型转成浮点然后放进 annotation 字典里ann { id: ann_id, image_id: image_id, category_id: cat_id, bbox: [float(x), float(y), float(w), float(h)], area: float(w * h), iscrowd: 0, segmentation: [[x, y, x w, y, x w, y h, x, y h]] }这里的float转换是为了贴合 COCO 的数值类型要求。有人会问为什么还要写segmentation因为很多检测框可视化工具、包括 pycocotools 的loadRes在没有 segmentation 时计算 IoU 会有问题。对于矩形框最稳妥的 segmentation 就是把 bbox 的四个顶点按顺时针或逆时针列出来。注意segmentation是一个二维列表内层列表是[x1, y1, x2, y2, x3, y3, x4, y4]扁平坐标要保证这些坐标和 bbox 一致。如果你转换时忘了 area训练框架通常会用 bbox 宽乘高重新算但 pycocotools 在评估时如果发现 area 和 bbox 不一致可能会给你一个不合理的小置信度惩罚。4.2 category ID 映射不能照搬VisDrone 的类别编号从 1 开始但0是 ignore。COCO 的类别 id 也是从 1 开始但名称完全不同。最省事也是最容易翻车的做法是把 VisDrone 的category值直接当作 COCO 的category_id。比如 VisDrone 的4是carCOCO 里4是airplane。如果你的模型预训练权重是 COCO 80 类这种错位会让训练过程混乱最后模型把飞机学到车上。正确做法是新建一个 categories 数组按你的目标类别重新分配 idcategory_mapping [ {id: 1, name: pedestrian}, {id: 2, name: people}, {id: 3, name: bicycle}, {id: 4, name: car}, {id: 5, name: van}, {id: 6, name: truck}, {id: 7, name: tricycle}, {id: 8, name: awning-tricycle}, {id: 9, name: bus}, {id: 10, name: motor} ]如果你想让类别名对应 COCO 预训练权重已有的那些类可以只保留 car、bus、motor、truck、bicycle 这几个与 COCO 重合的大类分别复制 COCO 里的 id 和名称剩下的静默忽略。但更常见的做法是保留 VisDrone 全部十类不加载 COCO 的类别头。用 MMDetection 时加载 COCO 预训练权重会默认只迁移 backbone分类层随机初始化所以不会出错。如果是用 Detectron2 的Base-RCNN-FPN直接加载 COCO 权重你需要把MODEL.ROI_HEADS.NUM_CLASSES改成 10并且在 checkpoint 加载时忽略类别分支的权重。4.3 image_id 与 file_name 的关联COCO 里每张图的id是一个整数annotations里的image_id必须指向这个整数。VisDrone 的文件名是0000001_00000_d_000001.jpg这种直接拿文件名当字符串去关联就很别扭。标准做法是给 images 数组按顺序赋 id比如第一张图 id 为 0然后在写 annotation 时通过一个文件名到 id 的字典来查。很多转换资源为了保证图片顺序不丢会用字典记录每个文件名对应的 idimage_id_map {img[file_name]: img[id] for img in coco[images]}这样在把 txt 转成 annotation 时拿到img[file_name]就能查出整数 id再填到image_id字段。有些框架会把 images 数组当成一个 JSON 数组遍历如果 id 不连续而你把image_id写成了它在数组里的下标索引偏差会在训练时表现为图片与标注错位而且这种错位不报错非常恶心。5. 避坑与排查转换后训练掉点、加载报错的五个常见问题5.1 pycocotools 报 “Invalid parameter, number of points is not the multiple of 2”现象把 JSON 加载进 pycocotools 的loadRes或者跑 COCO eval 的时候报错说点数不是 2 的倍数。原因segmentation里的 polygon 被写成了扁平坐标列表比如[x1, y1, x2, y2, x3, y3]但长度不是偶数。或者内层列表长度不是 2 的倍数少写了一个 y 坐标。尤其是从 VisDrone 的 bbox 转 polygon 时手写公式漏掉一条边就会这样。解决转换后写一段检查代码遍历所有 annotation验证len(segmentation[0]) % 2 0并且点到多边形闭合。最简单的方式是把 segmentation 显式生成四个点不做任何手工压缩。5.2 area 和 bbox 对不上mAP 数值明显偏低现象训练不报错但验证时 mAP 比论文低很多尤其小目标掉点严重。原因COCO 评估时模型预测框的 area 是从 bbox 计算出来的而 GT 标注的 area 如果是照抄 VisDrone 的 bbox 面积一般没问题。问题出在有些转换脚本把 area 写成了(w h) / 2或者漏掉了整数转浮点导致 GT 面积与实际像素数量不一致COCO 在按面积分组计算 mAP 时把小目标分错评估结果自然偏低。解决只要 bbox 是标准的[x, y, w, h]area 一律写float(w * h)。另外转换完可以抽样对比一下输出框的面积拿 PIL 打开图片量一下像素尺寸确认无误。5.3 加载 JSON 时内存直接爆掉现象json.load(open(...))在一个 8GB 内存的机器上直接 OOM。原因VisDrone 全量训练集有几万张图几十万个目标生成的 JSON 文件可能超过 300MB。json.load会把整个文件加载成 Python 对象内存占用是文件体积的 5 到 10 倍。这在大数据集里非常常见。解决要么对 JSON 做分片把标注拆成多个小文件要么用流式解析库ijson逐段读取。如果是训练框架需要完整 JSON建议在服务器上配置 swap 或者把 JSON 转成内存映射格式。但我见过的实际项目里更多人直接只保留部分类别或者只转子集这样文件会小很多。5.4 图片路径带了多余目录导致图片加载为空白现象PyTorch 的数据加载器没有报错但训练 loss 迟迟不降截图可视化发现图像全黑。原因转换时file_name写成了VisDrone2019-DET-train/images/0000001_00000_d_000001.jpg这种带多层目录的路径而框架又在拼接时自动加了img_prefix。我的经验是把file_name只保留图片文件名本身目录结构统一由img_prefix控制。这样在切换数据集根目录时不用改 JSON。解决打开 JSON检查第一个file_name是否包含斜杠如果包含建议重新生成 JSON 或写一段脚本把路径字段清理成纯文件名。5.5 类别 ID 从 0 开始还是从 1 开始和框架默认值冲突现象模型在 epoch 1 开始就加载很多空标签或者 loss 出现奇怪的跳变。原因COCO 惯例中类别 id 从 1 开始而有些资源在转换时保留了 VisDrone 的category值直接把 0ignore也当成了第一个类别造成categories里有 id0而框架内部从 0 开始索引类别但它默认 id≠索引于是发生错位。解决在训练前强制检查categories数组保证没有id0的类别如果有要么从 1 开始重编要么在配置里给类别加一个-1的避开逻辑。更稳妥的是所有转换工作都遵守“忽略框不写入 annotations、有效类别从 1 开始”的约定。6. 进阶验证用可视化脚本确认 JSON 标注的正确性拿到 COCO JSON光看数量不够我通常会画几张图把标注框叠在原始图片上肉眼确认坐标方向、类别名字、遮挡关系对不对。下面这段脚本读入一个 JSON 和对应的图片目录随机抽几张图输出分类别着色的 bboximport json import random import matplotlib.pyplot as plt import matplotlib.patches as patches from PIL import Image with open(visdrone_val.json, r) as f: coco json.load(f) img_id_to_file {img[id]: img[file_name] for img in coco[images]} cat_id_to_name {cat[id]: cat[name] for cat in coco[categories]} ann_grouped {} for ann in coco[annotations]: ann_grouped.setdefault(ann[image_id], []).append(ann) sample_ids random.sample(list(ann_grouped.keys()), k3) for img_id in sample_ids: img Image.open(img_id_to_file[img_id]) plt.figure(figsize(12, 8)) plt.imshow(img) ax plt.gca() for ann in ann_grouped[img_id]: x, y, w, h ann[bbox] rect patches.Rectangle((x, y), w, h, linewidth2, edgecolorred, facecolornone) ax.add_patch(rect) plt.text(x, y - 5, cat_id_to_name[ann[category_id]], coloryellow, fontsize10) plt.axis(off) plt.show()这里用matplotlib画框PIL.Image.open读图。注意代码里ann[bbox]的取值方式——如果运行报错检查ann[bbox]是否被包了一层列表。我见过一些转换脚本把 bbox 写成[[x,y,w,h]]这种错误不会影响训练框架读取但可视化时容易让人误解数据没问题。验证逻辑上至少要看三类图片单目标图、密集小目标图、有遮挡目标的图。VisDrone 的无人机视角下小尺寸的 car 可能只有 20 像素宽画出来很小但不要因此觉得是错的。重点看框是否包住目标主体、类别名是否和目视一致。如果发现框整体偏移多半是坐标参考系错了如果长宽比不对可能是图像被 Resize 过而标注没跟着变。mAP 验证也是一个实用手段。你如果有模型预测结果可以转成 COCO 格式的 JSON然后用 pycocotools 的 COCOeval 跑一遍评估。用 GT JSON 和预测 JSON能直接拿到每个类别的 AP快速发现哪个类别转换异常from pycocotools.coco import COCO from pycocotools.cocoeval import COCOeval gt COCO(visdrone_test.json) dt gt.loadRes(predictions.json) evaluator COCOeval(gt, dt, iouTypebbox) evaluator.evaluate() evaluator.accumulate() evaluator.summarize()这个流程我只在怀疑转换结果时才跑因为生成预测 JSON 本身需要额外写一个推理导出脚本。如果你做的是纯数据资源拆解最直观的验证永远是可视化抽查。讲一个真实翻车事件。我之前拿到一份“已转换好”的 VisDrone COCO JSON当时偷懒没有跑可视化直接丢给 MMDetection训练了十个 epochloss 降得很漂亮但验证时 AP 一直上不去。后来抽查了一张密集街景图发现所有车的框都偏到路面上方原因就是原作者转换时把 VisDrone txt 的 bbox 当成了中心点坐标减去了一个宽高的一半导致视觉上所有框整体往左上偏移。从那以后我每次拿到任何转换好的 JSON第一件事就是跑可视化抽样第二件事才是打印 categories 映射。哪怕时间再紧这两步也一定强制走完。希望这份避坑经验能帮到你省掉你十几个小时无谓的 debug。本文还有配套的精品资源点击获取