nuScenes数据集从下载到验证：多传感器融合感知的完整实战指南

简介面向自动驾驶研究者的nuScenes数据集下载解压配套项目源码帮助初次接触该数据集的使用者快速理清Trainval、Test、Map expansion及CAN bus expansion的存放与解压规范避免因路径或工具选择导致的数据准备耗时。包体共3个文件涵盖HTML说明页、Inscode云端开发配置及gitignore版本控制规则总大小仅6KB易读易维护。目前已有309人学习。HTML页面直观展示数据目录规划与批量解压建议Inscode配置让环境搭建更省心gitignore则帮助规范项目文件管理。对准备训练自动驾驶模型、需要高效完成多模态数据落地的算法工程师和学生来说这份轻量资源可作为数据预处理环节的实用参考。 做自动驾驶感知方向的同学对 nuScenes 数据集应该都不陌生。这个来自 Motional 团队原 nuTonomy 分拆的多模态数据集光摄像头就有 6 个毫米波雷达 5 个激光雷达 1 个官方还把所有传感器标定参数、高精地图、3D 目标框全部打包好。很多刚接触这个数据集的同学在“下载解压”这一步就卡住了要么 AWS CLI 配置不对要么解压到一半磁盘爆了要么好不容易跑起来 sdk 又报版本不兼容。这篇文章我就把从零下载、解压、到用官方项目源码验证数据的完整过程拆开讲清楚里面所有步骤都是我实际跑过的照着做基本能一次走通。这篇文章适合两类人一类是刚进入自动驾驶感知领域需要用真实多模态数据训练模型的算法工程师和研究生另一类是想从 2D 检测扩展到 3D 检测、多传感器融合但受限于设备还没上手过大规模数据的开发者。对于已经在用 Waymo Open Dataset 或 KITTI 的朋友读完也能快速对比出 nuScenes 在数据组织上的独特之处。1. nuScenes数据集到底有多大先算清楚账再动手1.1 全套下载前版本、包类型与磁盘规划很多同学一上来就急着跑官网下载命令结果下到一半才发现硬盘不够或者发现下错了包。先说清楚 nuScenes 目前的版本关系。官网现在维护两个大版本v1.0 完整版包含 1000 个场景scene每个场景约 20 秒涵盖波士顿和新加坡两个城市的复杂路况v1.0-mini 是完整版的一个缩略子集只有 10 个场景数据量小很多主要给开发者做代码调试、pipeline 验证用的。完整版里还得区分 TRAINVAL 和 TEST 两个包。TRAINVAL 包含了训练集和验证集的所有数据大约 850 个场景TEST 是测试集约 150 个场景。两个包加起来体积不小光 TRAINVAL 的原始数据就在 170GB 以上。mini 版相对亲民全部下载下来大概 12GB 左右如果只是想跑通官方 devkit 的 demo 或者先试一下数据格式直接下 mini 完全够用。另外还有一个经常被忽略的包Map expansion地图扩展包。这个包体积不大约 4GB但是包含高精地图的矢量数据车道线、人行道、停车位等做轨迹预测、地图匹配这类任务必须要用。很多同学玩 nuScenes 的 3D 检测只用到了 samples、sweeps 里的点云和图像但一涉及规划预测就被地图卡住就是漏了这个包。磁盘规划上我建议这么算mini 版全套含地图包预留 20GB 空余完整版全套含地图包预留 300GB 以上。另外解压的时候 tar.gz 文件本身和解压后文件是同时存在的也就是说解压过程中瞬时占用的磁盘空间大概是原始包的 1.5 到 2 倍。官方原始包是压缩过的解压后 samples、sweeps 目录会明显变大尤其是 lidar 点云包全是二进制文件不好压缩。我实际操作的时候吃过一次亏下载完完整版 TRAINVAL 后发现磁盘只剩 20GB硬着头皮解压结果解到一半磁盘满了报错最后只能删掉重新来。1.2 准备环境Python版本和两个硬性依赖官方项目源码nuScenes devkit目前托管在 GitHub 的 nutonomy/nuscenes-devkit 仓库。常用的分支是 master基于 Python 3 开发。这里有个容易踩的坑官方 sdk 在 Python 3.8 以上版本时个别依赖的构建方式会不同我推荐直接用 Python 3.8 或 3.10 的干净环境避免不必要的兼容问题。环境方面两个硬性依赖必须提前装好numpy 和 pyquaternion。pyquaternion 是处理四元数旋转的库nuScenes 的位姿数据里大量使用四元数表示旋转所以这个库是绕不开的。装好两个基础库之后再安装 matplotlib、opencv-python、tqdm 这些辅助库。opencv 主要用于图像标注可视化如果只是在服务器上做数据解析和模型推理这一步可以省略但如果要在本地画框看效果opencv 建议提前装。还有一个细节不同版本的 numpy 对后续一些坐标转换函数有影响建议把 numpy 锁在 1.24.x 左右太新的 numpy 有可能在运行 nuscenes.utils.geometry_utils 里的变换函数时报广播维度错误。conda create -n nuscenes python3.8 conda activate nuscenes pip install numpy1.24.3 pyquaternion matplotlib opencv-python tqdm到这里环境准备结束。我们手里的牌是一个能用的 Python 环境一块空余空间足够的磁盘。接下来可以开始真正的下载环节了。2. 下载实操从官网拿到授权命令到断点续传2.1 官网注册与AWS CLI命令获取nuScenes 数据不像很多开源数据集直接给一键 wget 链接它的下载需要先在官网nuscenes.org注册账号登录后进入 Download 页面勾选要下载的版本系统会生成一条对应的下载命令。这里生成的命令实质上是 AWS S3 接口的访问指令因为整个数据集存放在亚马逊 S3 的公开存储桶里。拿到官网给的命令后第一条要求是本地安装 AWS CLI 工具。如果在 Linux 服务器上操作建议用包管理器安装或者用官方 install script。安装完成之后要注意官网提供的命令里一般会带--no-sign-request参数这个参数的意思是走匿名访问不需要配置 Access Key 和 Secret Key。很多同学第一次看到 AWS 就以为要配置密钥其实完全不用千万别卡在这一步。# 安装 AWS CLILinux为例 curl https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip -o awscliv2.zip unzip awscliv2.zip sudo ./aws/install # 测试是否安装成功 aws --versionAWS CLI 装好之后不要急着跑官网的完整下载命令。先跑一个带--dryrun参数的测试命令让它列举一下存储桶里的目录。这样做有两个好处一是验证网络能连通 S3 存储桶二是让你提前看清下载目录的结构避免后面解压的时候对不上路径。如果--dryrun执行后返回一堆以v1.0-*开头的对象路径说明网络没问题。2.2 常见下载方式对比与脚本化下载数据下载常见的方式有三种直接在命令行复制官网命令整包下载、用浏览器端下载器离线下载、或者通过官方 devkit 里的下载脚本。很多人会纠结哪种方式更稳我的经验是整包下载用 AWS CLI 最省心因为 S3 协议天然支持断点续传命令行下载中断之后重新执行同一条命令它会自动跳过已存在的文件。直接整包下载的问题在于不可控的失败率。数据集文件数量极多尤其是samples、sweeps下的传感器数据单个文件几百 KB 到几十 MB 不等数量级上万。如果网络波动频繁即便是断点续传也架不住反复重试。所以更推荐的方案是写一个小的 Shell 脚本循环执行下载命令并在每次执行后检查返回码失败就重试重试次数上限可以设成 5 次。#!/bin/bash # download_nuscenes.sh RETRY_COUNT5 SUCCESS0 for i in $(seq 1 $RETRY_COUNT); do echo Download attempt $i aws s3 sync s3://nuscenes-public/ v1.0-mini ./nuscenes_public/ --no-sign-request --exclude * --include v1.0-mini/* if [ $? -eq 0 ]; then SUCCESS1 break fi done if [ $SUCCESS -eq 1 ]; then echo Download completed else echo Download failed after $RETRY_COUNT attempts fi这个脚本的本质是让aws s3 sync反复执行已经下载好的文件会被自动跳过只有缺失的或半截的文件会继续传输相当于给下载上了双保险。实测下来这个方式比单纯执行一次官网命令的稳定性高很多。另外补充一下有些地域的网络环境访问 S3 公开桶速度不太稳定如果发现下载速度长期徘徊在几 MB/s可以考虑通过第三方镜像站下载预打包的压缩包但镜像站的完整性和安全性需要自己把关不是特别推荐。最稳妥的还是官方通道配合断点续传脚本。3. 解压与目录结构别急着跑代码先把家当摆清楚3.1 解压步骤与磁盘要求下载完成后得到的是一堆.tgz压缩包。mini 版大约有 8 个左右的压缩包完整版更多。解压步骤本身不复杂但有几个细节需要留意。官方压缩包的结构是每个 tar 包解压出来顶层目录都是固定的v1.0-mini或者v1.0-trainval如果解压时不指定统一的顶层目录多个包解压后内容会分散在同一级目录下互相覆盖。正确做法是先建一个总目录然后把所有压缩包都解压到这个总体目录下最终应该得到类似./nuscenes_public/v1.0-mini/这样完整的目录树。解压命令我这里直接给稳妥的写法mkdir -p nuscenes_public mv v1.0-mini*.tgz nuscenes_public/ cd nuscenes_public for f in *.tgz; do tar -xzf $f; done解压过程比较吃磁盘 IO如果是机械硬盘时间和耐心都要备足。完整版解压后占用的空间大概在 250GB 以上mini 版解压后约 15GB。我之前跑完整版解压用了接近一小时如果是 SSD 会好很多。解压完成后建议立即用du -sh检查各目录大小确认没有压缩包解压异常。如果解压过程中途报错可能是磁盘写满或者压缩包下载不完整此时对应的文件需要重新下载。解压类错误排查相对简单关键是及时检查磁盘剩余空间。3.2 maps、samples、sweeps、metadata 各自管什么解压后的v1.0-mini目录下会有一堆 JSON 文件和一个maps子目录稍大一点的版本里还会有samples和sweeps。很多人拿到数据集后只看到 JSON 文件以为数据就这些其实 images、点云都在samples和sweeps里。先解释这两者的区别因为这是理解 nuScenes 数据组织逻辑的关键samples目录存放的是每 2 秒一个的关键帧数据官方称之为 keyframe这是做标注和模型训练的核心数据。sweeps目录存放的是关键帧之间的所有中间帧数据也就是非关键帧这部分数据量大很多主要用于需要连续帧信息的任务比如速度估计、运动预测、时序融合。从数量上看mini 版sweeps下的文件数量是samples的 10 倍都不止。很多同学觉得 mini 版只有 12GB 有点大就是被sweeps撑起来的。maps目录存放的是高精地图的光栅化图像和矢量数据。官方把波士顿和新加坡的区域地图切成若干块每块是一个单独文件具体格式在v1.0-mini的 JSON 数据库文件里有索引。根目录下的 JSON 文件相当于是整个数据集的“数据库索引”比如scene.json记录场景划分sample.json记录所有关键帧sample_data.json记录每个关键帧对应的传感器文件路径ego_pose.json记录自车位姿calibrated_sensor.json记录传感器内外参。官方 devkit 在加载数据时就是通过这些 JSON 文件的关联关系去定位对应的图像和点云文件的。理解了这层关系后面用官方项目源码验证数据时就不会迷茫。4. 项目源码验证用官方devkit把数据真正用起来4.1 安装nuscenes-devkit并初始化数据解压好后我们来到最关键的一步用官方项目源码把数据真正读进内存跑通一个最简单的验证程序。这一步的意义不只是“确认数据没问题”更是后续所有开发工作的起点。官方 devkit 的安装建议直接用 git clone 到本地因为版本迭代比较快用 pip 安装可能装到旧版本导致 API 不兼容。git clone https://github.com/nutonomy/nuscenes-devkit.git cd nuscenes-devkit pip install -e .初始化 Nuscenes 类时有两个参数必须填对dataroot指向解压后的总目录version指定版本字符串。这里有一个最常见的坑如果你下载的是 mini 包version 字符串应该是v1.0-mini如果你下载的是完整版version 字符串是v1.0-trainval。两者不能混用否则初始化时会报数据库文件不存在。如果下载了 Map expansion 包初始化时可以额外指定map_folder参数官方默认值是maps一般不用改。初始化成功后会输出一段版本信息和地图加载信息。from nuscenes import NuScenes nusc NuScenes(versionv1.0-mini, dataroot/path/to/nuscenes_public, verboseTrue)4.2 加载场景、渲染样本跑通第一个可视化程序初始化成功后可以写个简单脚本验证各个核心 API 是否正常。最直接的就是遍历一个场景scene拿到某个关键帧sample再取出对应摄像头图像和 3D 标注框画出来。my_scene nusc.scene[0] first_sample_token my_scene[first_sample_token] first_sample nusc.get(sample, first_sample_token) # 获取 camera 前视图像数据 cam_front_data nusc.get(sample_data, first_sample[data][CAM_FRONT]) img_path os.path.join(nusc.dataroot, cam_front_data[filename]) # 获取该关键帧的所有 3D 标注框 gt_boxes nusc.get_boxes(first_sample[token]) print(fscene {my_scene[name]}, sample {first_sample[token]}) print(fimage path: {img_path}) print(fnumber of 3D boxes: {len(gt_boxes)})如果以上脚本能正确打印出路径和 3D 框数量说明核心数据链路已经完全打通。更多时候我们还想直接看到可视化效果可以用官方提供的render_sample方法把 3D 框渲染在图像上这个函数内部会先加载相机内外参然后把 3D 框投影到图像平面。首次运行会有一个比较耗时的过程因为要加载点云和映射关系。nusc.render_sample(first_sample[token])跑通这个可视化基本就是拿到了继续深入的“入场券”。后续不管是做 3D 目标检测、多传感器融合还是轨迹预测都是在这个数据加载框架上做文章。5. 踩坑实录与排查速查表5.1 我踩过的几个典型坑下载解压 nuScenes 这套流程表面上看着简单实际操作中问题层出不穷。我把遇到过的三类典型问题写在这里希望能帮你省下半天时间。第一个坑是路径不能包含中文字符。官方 devkit 底层在处理文件路径时部分函数用的是 old-style 的字符串操作如果dataroot路径里有中文或者空格加载sample_data时会莫名报错。这个问题在 Windows 上特别常见建议所有数据相关路径一律用纯英文、无空格的路径。第二个坑是可视化依赖 OpenGL 的问题。官方render_sample在渲染点云时会调用pyqtgraph中的 OpenGL 接口如果机器没有图形界面或者显卡驱动不兼容会直接报错。服务器上跑这个函数基本都会遇到推荐做法是服务器上只做数据解析和导出可视化放到本地带显示器的环境去跑。第三个坑是nuscenes.utils.data_classes.LidarPointCloud在新版本 numpy 下的兼容性问题表现为运行点云加载时报ndarray对象没有points属性。这个问题的根源是官方源码里部分代码用了旧版 numpy 的 API解决方式是锁定 numpy 版本到 1.24.3 以下或者手动修改源码中的报错位置。我实际处理时选择了锁定版本省心很多。5.2 常见问题速查表为了方便排查我把下载解压链路上最常见的几个问题整理成一个速查表每个问题都对应一个可直接操作的解决方案。现象可能原因解决办法aws s3命令报 Access Denied没有加--no-sign-request参数在命令末尾加上--no-sign-request下载到一半文件大小为 0网络波动导致 S3 分段传输中断用aws s3 sync重新执行自动补传缺失文件初始化 NuScenes 时报 database not foundversion 参数与实际下载版本不符检查下载的是 mini 还是完整版改成v1.0-mini或v1.0-trainval加载点云时报points属性不存在numpy 版本过高导致 API 变化安装numpy1.24.3render_sample报 OpenGL 错误无图形界面或显卡驱动不兼容服务器上改用数据导出方式可视化放到本地执行tar 解压时报 CRC failed压缩包下载不完整删除该压缩包重新下载用aws s3 sync单独同步该文件这套流程跑完之后你再回头去看官方 GitHub 仓库里那些 example notebook会发现所有 API 调用都变得非常直观。数据已经安安静静躺在磁盘上脚本能正确读取每个传感器的文件3D 框能在图像上准确投影出来接下来无论是开始改模型还是自己写数据加载器都有了扎实的起点。本文还有配套的精品资源点击获取