VisDrone转COCO格式完整指南：从标注解析到训练验证

简介面向需要将 VisDrone 数据集用于目标检测训练的研究者与开发者资源直接提供由官方 VisDrone 标注转换出的 COCO 格式 JSON 文件省去自行编写格式转换脚本的时间也避免不同标注体系对接时的常见错误。压缩包共 4 个文件、约 10.18MB其中 2 个 JSON 分别为训练集与验证集标注1 个 TXT 记录类别标签1 张 JPG 说明图片下载与目录放置方法。整理时发现 10 张训练集图片标注有误已删除这些错误标注保留可用图片使用者只需从 VisDrone 官网下载原始图片并放入对应目录即可直接用于 YOLOX 等模型训练。该数据集格式经过 YOLOX 完整训练与测试验证也支持导入百度 EasyDL 进行二次检查。目前已有 765 人学习下载适合需要直接获得干净、可用且标注已被验证的 COCO 格式 VisDrone 数据用于检测实验、算法对比或项目预训练的中初级开发者。1. 为什么 visdrone 转 COCO 格式是道绕不过去的坎做过无人机目标检测的应该都有同感VisDRONE 数据集本身质量不错但它的标注格式和主流的 COCO 格式差别很大。原始标注是 txt 文本每行代表一个目标字段顺序是target_id, bbox_x, bbox_y, bbox_w, bbox_h, score, category_id, truncation, occlusion而 COCO 格式要求的是 json 文件包含images、annotations、categories三个顶层数组bbox 的坐标含义也略有不同。最直接的影响就是你拿到的预训练模型、开源训练代码绝大多数默认读 COCO 格式的 json你没法直接把 visdrone 的 txt 塞进去训练。我最早接触这个转换是因为复现一个基于 Faster R-CNN 的无人机视角检测实验数据是 VisDrone2019代码里 hardcode 了 COCO 格式的数据加载。当时我手动写脚本转第一版跑完发现检测框全偏了后来一步步排查才发现是坐标精度和类别映射的问题。这篇文章就把我后来沉淀下来的转换脚本、参数设计和踩坑经验讲清楚保证你照着做能一次转对。适合正在做无人机视角目标检测、用 COCO API 或 mmdetection 训练但手里只有 VisDRONE 原始标注的从业者。2. 认识 visdrone 原始标注和 COCO 格式先把两个黑匣子拆开2.1 visdrone 的 txt 标注里每个字段到底是什么意思VisDRONE 的标注文件放在VisDrone2019-DET-train/annotations目录下每个图像对应一个同名 txt 文件。打开看每一行是 10 个数字用逗号分隔。格式是bbox_left, bbox_top, bbox_width, bbox_height, score, category, truncation, occlusion这里有个关键点前四个数字是目标框的左上角坐标和宽高单位是像素。score在检测任务的标注里通常是 -1 或者 1表示这个标注是否有效。category是类别编号VisDRONE 里1是pedestrian2是people3是bicycle4是car5是van6是truck7是tricycle8是awning-tricycle9是bus10是motor11是others。truncation是截断程度0表示无截断1表示部分截断2表示严重截断。occlusion是遮挡程度同样0/1/2。注意最后一个字段ignore有的版本会写成 10 个数字有的版本是 9 个。官方发布的数据里有的文件末尾多余一个逗号有的没有这种脏数据很常见。转换的第一步是把这些字段拆对并且区分哪些目标是要参与训练的、哪些应该被过滤掉。2.2 COCO json 的顶层结构images、annotations、categories 三件套COCO 格式的 json 文件本质是一个嵌套字典顶层有三个 keyimages一个列表每个元素代表一张图片包含id、file_name、width、height。annotations一个列表每个元素代表一个目标实例包含id、image_id、category_id、bbox四个浮点数[x, y, width, height]、area、iscrowd。categories一个列表定义类别 ID 到类别名称的映射关系。这里的bbox同样是[x, y, width, height]从表面上看和 visdrone 标注一致但坑在于category_id的编号体系。visdrone 的类别编号从1到11但中间有跳号而 COCO 类别 ID 要求从1开始连续递增。如果你直接把 visdrone 的category字段传给 COCO json就会出现类别对应错乱的问题。另外 COCO 的area字段是width * height这个值在评估mAP时会用到不能省。iscrowd在 visdrone 里没有对应概念统一写0就行。2.3 为什么不能直接拿现成脚本改改就用网上确实能找到一些 visdrone 转 COCO 的脚本但大多数存在几个通病一是硬编码了路径换台机器就得改一堆二是没处理图片尺寸字段导致 COCO API 在加载时拿不到width和height跑评估直接报错三是把ignore目标也写进 annotations导致训练时把大量遮挡目标当成正样本mAP 虚高或者训练不稳定。我见过一个项目用这样的脚本转换后训练 loss 一直在 0.8 上下波动后来发现是负样本数据被污染了。所以别迷信现成代码自己把转换逻辑吃透按需求调整过滤规则才是可靠的做法。3. 编写 visdrone 转 COCO 格式的转换脚本从零开始可复现3.1 准备数据目录和标注文件清单在写转换脚本之前先把数据目录结构理顺。我一般这样组织data/ VisDrone2019-DET-train/ images/ 0000001_00000_d_0000010.jpg 0000001_00000_d_0000011.jpg annotations/ 0000001_00000_d_0000010.txt 0000001_00000_d_0000011.txt output/ train_coco.json脚本需要遍历images目录找到所有 jpg 文件然后去annotations目录找同名 txt。如果某个图片没有对应的 txt 文件说明这张图片没有标注要不要保留看你的训练需求。如果做检测通常建议过滤掉因为空白图片不提供正样本信息。如果做鲁棒性测试可以保留。import os import json from glob import glob def build_image_list(image_dir, annotation_dir): image_paths sorted(glob(os.path.join(image_dir, *.jpg))) image_list [] skipped [] for img_path in image_paths: base_name os.path.splitext(os.path.basename(img_path))[0] anno_path os.path.join(annotation_dir, base_name .txt) if not os.path.exists(anno_path): skipped.append(img_path) continue image_list.append((img_path, anno_path)) print(fTotal images: {len(image_paths)}, with annotation: {len(image_list)}, skipped: {len(skipped)}) return image_list这段代码的作用是建立图片和标注文件的一一对应关系。glob排序保证了后续生成的image_id是稳定递增的不会因为文件系统顺序不同而错乱。打印统计信息能帮你快速判断数据是否完整——如果跳过的数量巨大说明路径配错了。3.2 定义 visdrone 类别映射表和过滤规则类别映射是整个转换里最容易出错的地方visdrone 的类别编号和 COCO 类别 ID 不是一回事。我建议在脚本里显式定义一个映射字典VISDRONE_CATEGORIES { 1: pedestrian, 2: people, 3: bicycle, 4: car, 5: van, 6: truck, 7: tricycle, 8: awning-tricycle, 9: bus, 10: motor, 11: others, } def build_coco_categories(): categories [] for idx, (vis_id, name) in enumerate(VISDRONE_CATEGORIES.items(), start1): categories.append({ id: idx, name: name, supercategory: object, }) return categories这里我们把 visdrone 的原始类别编号作为字典的 key转换后的 COCOcategory_id从1到11连续编号。为什么不用 visdrone 原始编号作为 COCO 的category_id因为 COCO API 内部会按category_id建索引跳号会引发评估时类别错位尤其是当你只训练其中几个类别时逻辑会乱套。过滤规则方面我一般会过滤掉score 0的标注。VisDRONE 的注释里有特殊标记score为0表示该目标属于“忽略”区域不应该参与训练。另外truncation为2且occlusion为2的目标通常被认为是极度困难样本除非你要做难度递增的实验否则建议过滤。这个规则要写成一个独立的函数方便你按实验需求调整。def should_ignore(annotation_values): score float(annotation_values[4]) truncation float(annotation_values[6]) occlusion float(annotation_values[7]) if score 0: return True if truncation 2 and occlusion 2: return True return False把过滤规则独立出来是值得的因为你可能会需要做消融实验比如保留全部目标看看在困难样本上的表现。这时候只需要改这个函数其他逻辑不用动。3.3 解析 txt 并生成 COCO 格式的 json 文件核心的转换函数需要逐行解析 txt把 visdrone 的字段映射成 COCO 的annotation字典def convert_visdrone_to_coco(image_list, output_path): coco { images: [], annotations: [], categories: build_coco_categories(), } annotation_id 1 for image_id, (img_path, anno_path) in enumerate(image_list, start1): from PIL import Image im Image.open(img_path) width, height im.size coco[images].append({ id: image_id, file_name: os.path.basename(img_path), width: width, height: height, }) with open(anno_path, r) as f: for line in f: line line.strip() if not line: continue parts line.split(,) if len(parts) 8: continue parts [p.strip() for p in parts] if should_ignore(parts): continue x float(parts[0]) y float(parts[1]) w float(parts[2]) h float(parts[3]) vis_cat int(parts[5]) coco_cat list(VISDRONE_CATEGORIES.keys()).index(vis_cat) 1 if w 0 or h 0: continue area w * h coco[annotations].append({ id: annotation_id, image_id: image_id, category_id: coco_cat, bbox: [x, y, w, h], area: area, iscrowd: 0, }) annotation_id 1 with open(output_path, w, encodingutf-8) as f: json.dump(coco, f, indent2) print(fConverted {len(image_list)} images, {annotation_id - 1} annotations - {output_path})这段代码有几个关键参数需要说明image_id从1开始和文件名排序对应不要用0因为部分框架将0视为无效 ID。category_id通过list(VISDRONE_CATEGORIES.keys()).index(vis_cat) 1计算这里利用了 Python 字典保持插入顺序的特性确保映射稳定。area直接算w * h没有乘任何缩放系数。如果你做的是切图后的数据集比如把大图切成 512x512 的小图area也要相应地基于小图坐标计算不能直接用原值。过滤掉w 0 or h 0的边界框这类脏标注虽然少但一旦存在会导致训练时 loss 变成 NaN。3.4 执行转换单卡跑通全流程运行转换脚本时建议先处理一个子集验证正确性再跑全量。我习惯加一个--max-images参数方便快速调试python visdrone2coco.py \ --image-dir data/VisDrone2019-DET-train/images \ --anno-dir data/VisDrone2019-DET-train/annotations \ --output data/output/train_coco.json \ --max-images 100上面这个命令只处理前 100 张图片大约几秒就跑完。打开生成的 json肉眼检查几个关键字段file_name是否带.jpg后缀、anno的坐标是否在图像宽高范围内、category_id是否落在1~11区间。确认无误后去掉--max-images参数跑全量。全量转换 VisDrone2019-DET-train 大约有 6500 张图片如果PIL逐张读图取尺寸会比较慢瓶颈在磁盘 IO 和图片解码。想提速的话可以预先用缓存图片尺寸表或者直接用os.path.getsize之外的方法从文件名提取——但代价是你要保证数据源没有修改过。我一般直接读图虽然慢一点但最可靠。生成 json 之后下一步通常是用官方 COCO API 做加载验证确认格式没问题再进训练管线。4. 验证转换出的 json 是否可用COCO API 和可视化双保险4.1 用 pycocotools 加载 json确定没有结构性错误转换完成并不代表 json 一定符合 COCO 规范最容易出问题的是缺失字段或类型不对。用pycocotools做一次权威校验是最快的做法from pycocotools.coco import COCO coco COCO(data/output/train_coco.json) print(fLoaded {len(coco.imgs)} images) print(fLoaded {len(coco.anns)} annotations) print(fCategories: {[coco.cats[i][name] for i in sorted(coco.cats)]})COCO类的构造函数会检查images、annotations、categories三个基础结构如果 json 缺字段或类型不匹配它会直接抛异常。这里能通过的 json 在结构上基本没问题。但COCO加载通过不代表坐标数据合理。一个常见情况是 visdrone 的标注是左上角坐标加宽高而某些到手的脚本把它当成中心点坐标加宽高导致全部框位置错误。这种错误COCOAPI 不会报因为坐标值本身合法。所以必须做第二层验证可视化。4.2 随机抽几张图画出检测框直观验证坐标对齐可视化虽然是土办法但却是最有效的验证手段。用matplotlib把图片画出来然后把 bbox 画上去肉眼就能看出坐标是否对齐import matplotlib.pyplot as plt import matplotlib.patches as patches from PIL import Image import random def visualize_random(coco, num_samples5): image_ids list(coco.imgs.keys()) sample_ids random.sample(image_ids, min(num_samples, len(image_ids))) fig, axes plt.subplots(1, num_samples, figsize(15, 5)) for ax, image_id in zip(axes, sample_ids): img_info coco.imgs[image_id] img_path fdata/VisDrone2019-DET-train/images/{img_info[file_name]} im Image.open(img_path) ax.imshow(im) ann_ids coco.getAnnIds(imgIdsimage_id) anns coco.loadAnns(ann_ids) for ann in anns: bbox ann[bbox] rect patches.Rectangle( (bbox[0], bbox[1]), bbox[2], bbox[3], linewidth1, edgecolorred, facecolornone, ) ax.add_patch(rect) ax.text( bbox[0], bbox[1] - 5, coco.cats[ann[category_id]][name], fontsize8, coloryellow, ) plt.show() visualize_random(coco)可视化的时候注意两点一是确认框的边界是否和目标贴合如果框明显偏到一边大概率是坐标定义不对二是看类别标签是否和框内目标匹配特别是pedestrian和people这两个类别容易混淆visdrone 里pedestrian是站立行人people是群体或非站立的人转换以后不要试图改变类别定义。4.3 在 mmdetection 里直接验证训练数据流是否畅通如果你用的是 mmdetection转换完的 json 还可以直接用它自带的browse_dataset.py脚本验证。这个脚本会加载数据并可视化样本它内部走的是和训练一样的数据管线如果它能正常跑通说明你的 json 能被训练框架接受。python tools/misc/browse_dataset.py \ configs/faster_rcnn/faster-rcnn_r50_fpn_1x_coco.py \ --output-dir browse_output \ --show-dir browse_output注意这里需要把你的数据集配置先改好data_root指向你的数据目录train_ann_file指向生成的 jsontrain_img_prefix指向图片目录。如果 browse 出来的图片上标注位置正确说明数据管线没问题接下来就能直接开训了。5. visdrone 转 COCO 挺身而出的避坑指南这些坑我替你踩过了5.1 坑一图片尺寸读取错误导致 area 计算和归一化全部错乱现象转换后的 json 里width和height字段和实际图片尺寸不一致有的甚至直接写成[0, 0]训练时数据加载直接报错。原因脚本地读取的图片尺寸是从 label 文件里猜的或者干脆写死了固定值1920x1080。VisDRONE 数据集的图片分辨率确实多为1360x765或类似的宽高比但不是每张都完全一致尤其是在裁剪后的子集里更不统一。解决不要信任何先验尺寸用PIL.Image.open(img_path).size实时读取每一张图的实际尺寸。前面 3.3 节里的代码已经采用这个做法如果你接手的是别人的转换脚本第一时间检查这部分逻辑。5.2 坑二类别 ID 映射错位训练时类别标签全乱了现象训练时 loss 能收敛但验证集的 mAP 断崖式下跌查看预测结果的类别名发现car被预测成了bus所有类别整体错位。原因visdrone 原始category字段是1~11但中间没有编号0。有些转换脚本直接把这个编号赋给 COCOcategory_id而 COCO 要求类别 ID 从1开始连续。更隐蔽的问题是如果你只选择 visdrone 的car、bus、truck三类做训练但是映射表写成了按原编号取值最终categories列表里的顺序和annotation的category_id对不上。解决按 3.2 节的做法用字典做显式映射先定义 visdrone 原始编号到 COCO 新编号的对应关系再生成categories列表。转换后写一个小测试脚本统计每个category_id的样本数量和源数据对应类别数量做对比能快速发现错位。5.3 坑三过滤了 score0 的目标但忘了同步过滤图片现象转换后的 json 里存在某些图片完全没有任何 annotationCOCO API 在评估时会报错或者跳过这些图导致 mAP 计算图片数量不一致。原因有的 txt 文件里所有目标都是score0过滤后该图片的annotations列表为空但images列表里仍然保留了这条记录。COCO 的评估代码通常假设每张图片至少有一个目标遇到零目标图片会直接崩溃。解决在生成images条目时做一个后检查——如果一张图片过滤后没有剩余任何 annotation就把它的images条目也删掉。或者反过来先解析所有 annotation再统一构建没有重叠的images列表。同时打印跳过图片的数量确保这个比例在合理范围内。5.4 坑四坐标值没有保留浮点精度检测框在降采样后偏移现象训练时数据增强里的随机裁剪、缩放一切正常但最终检测时小目标的框位置有系统性偏移。原因转换脚本里用int()而不是float()处理 visdrone 的坐标和宽高。visdrone 原始标注是小数坐标精度转成整数后在图像缩放到更小分辨率时误差被放大尤其是小目标本来就只有十几个像素宽损失几像素就可能导致 IoU 骤降。解决bbox字段保留浮点类型不要在转换时取整。pycocotools 本身支持浮点 bbox很多检测框架在数据增强时也会把坐标转成 float 处理所以完全没有取整的必要。这个坑在验证阶段很难发现因为可视化时框差一两个像素肉眼分辨不出来只有看定量 mAP 才会暴露。5.5 坑五json 文件编码问题COCO API 在 Windows 下读不了现象json 文件在 Linux 下转换正常但拷贝到 Windows 机器上用 COCO API 加载就报UnicodeDecodeError或 keyError。原因Linux 下默认utf-8Windows 默认gbk。json.dump如果不指定ensure_asciiFalse所有中文字符串都会转成\uXXXX的 ASCII 编码虽然在 Linux 下能正常读但 Windows 下如果文件头没有 UTF-8 BOM就可能出问题。解决json.dump(coco, f, ensure_asciiFalse, indent2)并在打开文件时指定encodingutf-8写入。这样生成的 json 是纯 UTF-8 编码跨平台不会出乱码。此外看 json 文件里类别名称是否可读也是判断编码正确与否的最直观方法。6. 进阶把 COCO json 用起来训练前再做一次数据体检6.1 按类别统计样本数和 bbox 面积分布排查长尾问题数据集转换完之后别急着开训。先跑一个数据统计脚本看看每个类别的实例数量、bbox 面积分布、以及长尾效应from pycocotools.coco import COCO import numpy as np import matplotlib.pyplot as plt coco COCO(data/output/train_coco.json) cat_ids list(coco.cats.keys()) instances_per_cat {} area_ranges {small: 0, medium: 0, large: 0} for cat_id in cat_ids: ann_ids coco.getAnnIds(catIds[cat_id]) anns coco.loadAnns(ann_ids) instances_per_cat[coco.cats[cat_id][name]] len(anns) for ann in anns: area ann[area] if area 32 * 32: area_ranges[small] 1 elif area 96 * 96: area_ranges[medium] 1 else: area_ranges[large] 1 print(Instances per category:, instances_per_cat) print(Area distribution:, area_ranges)这一步能让你看到 visdrone 里pedestrian和car的样本量远大于awning-tricycle训练时就需要考虑类别重采样或损失函数加权。另外如果 small 目标占比过高在无人机视角下这是常态你的模型结构里针对小目标的检测头设计就得多花心思。6.2 把 json 转成 mmdetection 能直接用的数据集配置模板如果你最终要在 mmdetection 里训练可以用下面的配置模板替换 COCO 数据集路径dataset_type CocoDataset data_root data/visdrone/ metainfo { classes: [ pedestrian, people, bicycle, car, van, truck, tricycle, awning-tricycle, bus, motor, others, ], } train_dataloader dict( batch_size4, num_workers4, datasetdict( typedataset_type, data_rootdata_root, ann_fileannotations/train_coco.json, data_prefixdict(imgimages/), metainfometainfo, ), )注意metainfo里的类别名称顺序要和 json 的categories列表顺序严格一致否则 mmdetection 在显示类别名时会错乱。这里classes名称本身并不影响训练因为训练只认category_id但影响日志和可视化结果的解读。6.3 最后一步检查完整训练集、验证集划分是否合理VisDRONE 官方数据集本身提供了train、val、test划分每个部分都有独立的 images 和 annotations 目录。转换时要分开转换生成三个独立的 json 文件。不要用一个 json 既做训练又做验证因为目标检测领域交叉验证的常规做法是保持域一致不让同分布的图片出现在训练和验证两个集合里。我建议转换后记录一组基线数据训练集图片数、实例总数、每张图平均实例数。VisDrone2019-DET-train 这些指标大概是 6500 张图、约 30 万个实例、平均每张图 40 多个目标。如果你的统计结果和这个量级差距过大先查转换逻辑哪里有问题别直接开训。我每次转换完都会随机抽 20 张图过一遍可视化确认坐标、类别没问题才进训练。这个习惯帮我挡过不少数据质量的暗坑。希望这篇能帮你少走一段弯路祝转换顺利。本文还有配套的精品资源点击获取