如果你做3D视觉或者室内场景理解ScanNet数据集应该是绕不开的名字。我第一次下载ScanNet的时候光是申请审批就等了一周拿到官方下载脚本后又因为Python版本和网络问题折腾了大半天好不容易下完. sens原始文件结果发现里面还嵌套着一层数据提取流程整个人都不好了。这篇教程就把我从申请、审批、写脚本下载到解析.sens、提取RGB-D序列、读取位姿和语义标签的完整过程梳理一遍顺便把那些官方文档里不会写的坑挨个标出来。这个数据集适合谁简单说凡是做室内SLAM、3D语义分割、实例分割、扫描重建、点云识别方向的研究人员或学生基本都会用到它。官方提供了1513个室内场景的RGB-D采集序列带完整的相机位姿、深度图、语义标注和重建网格是目前室内场景理解领域使用最广的benchmark之一。如果你正在为yolov8或PointNet准备3D训练数据或者想对比KITTI、NuScenes这类数据集在室外和室内场景下的差异这篇都能给你一个相对完整的参考。1. 内容整体设计与思路拆解1.1 为什么室内3D场景数据集偏偏选中ScanNet先聊一个很多人问过的点室内场景理解数据集有SUN RGB-D、NYUv2、ScanNet等好几个为什么ScanNet能成为默认选项关键不在于它数据量最大而在于它的数据完整性。SUN RGB-D主要是单张RGB-D图像级别的标注NYUv2只有1449张深度图而ScanNet提供的是完整序列每个场景有几百到几千帧不等的连续RGB-D流同时附带重建好的网格模型。这意味着你不仅能做单帧预测还能做时序融合、多视角一致性、3D重建这类任务。ScanNet的采集方式是手持Kinect或者Structure Sensor在室内绕一圈记录整段视频流然后把帧与帧之间的位姿解算出来。官方还提供了全局一致的3D重建结果把每个场景变成了一个连续的三维模型。这个结构对于训练3D语义分割、实例分割、目标检测甚至主动SLAM路径规划算法来说非常关键因为你可以在连续数据上构造时间上的样本而不是像单帧数据集那样每张图独立。另外ScanNet的场景覆盖面也算厚道。1513个序列覆盖办公室、卧室、洗手间、厨房、书房、会议室等常见室内空间还有一部分非规则空间如杂物间和走廊。对于做室内机器人落地的团队来说这种多样性比单纯追求数量重要得多因为模型在真实部署时遇到的空间形态不可能只局限在一两种房型里。我见过不少团队拿ScanNet做预训练再用自己的室内扫描数据做fine-tune实际效果比从零训练好不少。1.2 一次下载三条主线权限、脚本、文件格式整个ScanNet获取流程可以拆成三条主线这也是这篇教程安排的逻辑。第一条线是权限。ScanNet的下载不是点击即得的需要去官网填写学术用途申请表等官方邮件回复下载账号和密码。也就是说你拿到的不只是数据链接还有一个需要配合脚本使用的认证信息。很多人在这步就卡住了要么邮箱填错、要么不知道要等审批要么收到邮件后没注意到账号密码在邮件正文里。第二条线是下载脚本。官方没有提供直链打包下载而是给了一个叫download-scannet.py的Python脚本用命令行参数控制下载哪些类型的数据。你需要把访问账号、密码、数据集版本、下载内容类型依次传进去。这个脚本本身逻辑不复杂但它面向的是Python 2/3兼容环境而且对网络稳定性要求不低容易在下载过程中挂掉。第三条线是格式解析。下载完成后你会发现拿到的文件分为两类一类是带.ply后缀的网格文件可以直接用MeshLab或Blender打开另一类是.sens后缀的传感器原始数据需要通过官方配套的SensReader工具把RGB图像、深度图、相机内参和位姿逐帧提取出来。很多人下完. sens以后以为完事了其实真正的解析工作才刚刚开始。后面的内容就按这三条线逐一展开。先讲申请环节的注意事项再讲脚本下载的具体用法和参数选择最后重点拆解.sens和.ply的解析方法。每条线我都会结合自己实际跑通的过程来说而不是照着官方README念一遍。1.3 横向对比ScanNet与KITTI、NuScenes的定位差异做3D视觉的人手头通常不只一个数据集我在自己的项目里就同时使用过KITTI、NuScenes和ScanNet。这里简单对比一下它们的定位差异方便你在选题时快速判断该用哪个。KITTI主打自动驾驶场景数据用车载传感器采集包含双目图像、激光雷达点云、GPS/IMU信息坐标系是车辆为中心的室外大地坐标系场景基本是道路、车辆、行人。NuScenes更进一步提供了多传感器融合数据包括6个相机、5个雷达、激光雷达和毫米波雷达还带完整的3D标注框和地图信息适合做多模态融合研究。ScanNet是完全不同的路线。它不碰自动驾驶专注室内。传感器是手持RGB-D设备没有GPS位姿是通过视觉里程计或者RGB-D SLAM算出来的相对姿态语义标注是逐点或逐面片级别而不是3D框级别。如果你做的是自动驾驶感知KITTI和NuScenes更合适如果做的是机器人抓取、室内导航、AR场景理解ScanNet几乎是最容易获取、标注质量最稳定的室内数据集。这里有个容易被忽视的细节ScanNet的语义标签体系是NYU40类的一部分不是完整的40类而是ScanNet自己整理出的20类常用类别比如墙、地板、桌子、椅子、沙发、门、窗户、书架等。和KITTI那种“Car、Pedestrian、Cyclist”的检测标签不同ScanNet的标签是稠密的面片级/点级标注理解这一点对你处理标签映射关系会很有帮助。2. 申请与下载全流程2.1 官网申请填表技巧与审批等待ScanNet的申请入口在官方网站的Dataset页面不要进错成ScanNet或者ScanNet Annotation Tool的页面这两个是不同的项目。进入后找到申请区域需要填写姓名、单位、邮箱、工作单位性质、用途描述等内容。几个容易踩坑的地方邮箱建议使用学校或研究所的学术邮箱。虽然官方没有强制要求.edu或.ac.cn后缀但我见过用普通个人邮箱申请后审批时间明显变长的情况少数情况下甚至会直接不回复。用途描述尽量写具体比如“用于研究室内3D语义分割算法的跨场景泛化问题”比写“用于学习和科研”要更可信。官方会人工审核用途描述模糊的可能会被退回补充。提交后一般在1到5个工作日内收到回复节假日可能会更慢。如果一周没收到建议发邮件礼貌询问一下我当时就是等了五天有点慌结果第六天早上收到了。审批通过的邮件里会包含你的专属下载账号和密码这个密码不是登录官网用的而是给download-scannet.py脚本做HTTP Basic认证用的别弄混了。官方邮件里那个“password”字段就是脚本参数里要用到的我一开始下意识拿它去登录官网用户中心结果当然登不上去绕了半天才发现需要结合脚本使用这也是我开头提过的那个坑。2.2 下载脚本安装与基础用法拿到账号密码后接下来要准备下载脚本。ScanNet的官方下载脚本托管在GitHub上仓库名字是ScanNet/ScanNet脚本在仓库根目录下文件名是download-scannet.py。它依赖Python的urlopen等标准库但不同分支对Python版本要求不同建议直接用Python 3.6以上的环境跑旧版本Python 2运行时容易出现编码或者SSL证书问题。脚本用法比较直观。下载全部数据用这条命令python download-scannet.py -o /path/to/scannet --type all -u 你的用户名 --password 你的密码其中-o指定输出目录--type指定下载类型-u和--password填邮件里的账号密码。官方还提供了--id参数用于指定场景编号如果你只需要某个特定场景而不是全量数据这个参数能省大量流量和时间。比如只下载场景scene0000_00python download-scannet.py -o /path/to/scannet --id scene0000_00 --type all -u 用户名 --password 密码脚本支持的下载类型在--type里可以组合指定常用的有_vh_clean_2带标签的PLY网格、_vh_clean_2.ply不带标签的网格、_sens传感器原始数据、_txt位姿和内参文本等。如果你想做语义分割至少要下_vh_clean_2.ply带语义标签和_sens前者用于生成真值网格后者用于提取逐帧RGB-D图像。第一次跑脚本建议先用--id加一个场景号测试连通性和账号权限全量下载1513个场景前先跑通一个小样本不然下到一半才发现认证失败就白费时间了。2.3 下载策略断点续传、网络加速与存储规划ScanNet全量数据体积大概在几十GB到一两百GB之间具体取决于你选的压缩类型和分辨率版本。官方提供了不同分辨率的下载选项--type all默认下载的是完整原始数据体积最大如果只做语义分割训练可以只下载_vh_clean_2.ply和_sens总容量会明显下降。下载过程中最常见的问题是网络中断。官方脚本本身支持续传如果你用CtrlC中断再重新执行已下载的文件会跳过不重复下载但前提是之前下载的临时文件没有损坏。我在实际使用中还是建议搭配screen或tmux后台运行避免SSH会话断开的干扰screen -S scannet_download python download-scannet.py -o /data/scannet --type all -u 用户名 --password 密码离开终端时直接关闭窗口重新登录后执行screen -r scannet_download恢复会话。如果你在服务器上下载这个方法能最大限度省心。另外一个容易被忽略的点是磁盘格式。ScanNet的PLY文件属于ASCII或二进制混合格式解压后单场景不算太大但1513个场景累积下来会占不少inode和存储空间。建议提前规划好目录结构比如/data/scannet/scans、/data/scannet/tasks分目录存放并且确保分区至少有两倍于压缩包的剩余空间因为解压过程需要临时的容量。实测下来如果用机械硬盘存储边解压边训练IO可能会成为瓶颈预算允许的话优先放SSD或者NVMe盘。下载完成后你的目录结构大致是这样scannet/ scans/ scene0000_00/ scene0000_00.sens scene0000_00.txt scene0000_00_vh_clean_2.ply scene0000_00_vh_clean_2.labels.ply scene0000_00_vh_clean_2.0.010000.segs.json scene0000_01/ ...其中.sens是之前说的传感器原始数据.txt是位姿和相机内参文本.ply是网格模型.labels.ply是带语义标签的网格模型.segs.json是实例分割的超体素文件这个文件在做实例分割任务时才会用到。3. 核心数据解析与格式详解3.1 .sens文件结构官方SensReader的使用.sens文件本质上是ScanNet团队自定义的二进制容器格式里面装着一整段RGB-D视频流及对应的传感器元数据。直接改后缀名或者用普通解压工具是打不开的必须用官方提供的SensReader工具解析。SensReader有两种使用方式一种是直接命令行运行官方配套的解析脚本另一种是把它作为Python库导入。官方仓库里有一个sens_reader目录里面提供了reader.py和SensorData类。使用前需要先把sens_reader的路径加入Python的环境变量或者直接在该目录下运行你的脚本。最直接的做法是官方仓库里还提供了一个命令行人机交互工具运行后会一次提取所有帧的彩色图、深度图、位姿和内在参数到指定目录。命令如下python reader.py --filename /path/to/scene0000_00.sens --output_path /path/to/output运行后会生成color、depth、pose、intrinsic等子目录。其中彩色图是PNG或JPG格式深度图是16位PNG格式保存的是毫米单位的原始深度值位姿是4x4的变换矩阵文本。但如果你只需要部分帧或者想自己控制帧采样频率就会发现官方命令行不太够用。我建议直接在Python脚本里导入SensorData类来写自己的提取逻辑自由度更高。关于这个的详细代码我在第4章里会给出一个可以直接复制的版本。3.2 PLY网格带标签网格与不带标签网格的区别ScanNet的.ply文件分为几种最容易让人困惑的是_vh_clean_2.ply和_vh_clean_2.labels.ply这两个的区别。前者是几何网格只包含顶点坐标、法线和颜色信息适合做几何重建或点云对齐任务后者在同样的几何网格上附加了每个顶点的语义标签ID适合做3D语义分割任务的训练真值。还有一个_vh_clean.ply是未经过二次抽稀的高精度网格顶点数量明显更多一般做可视化看效果用而_vh_clean_2.ply经过了抽稀和清理面和顶点数更可控也更容易被训练框架加载。所以很多人训练语义分割直接选_vh_clean_2.labels.ply是有道理的它既保留了足够的几何细节又不会让数据量大到无法处理。如果你用MeshLab打开.ply文件会看到网格的顶点颜色信息打开.labels.ply时默认看到的往往是黑白灰或者奇怪的彩色。因为语义标签ID被存成了标量属性MeshLab默认不会把它映射成彩色可视化。需要打开属性表把标量值映射到颜色预览或者自己写代码把标签ID映射成RGB颜色再保存成新的PLY文件。这一点对刚上手的人来说很容易误解总以为下载的文件坏了或者官方没给颜色其实只是查看方式不对。3.3 位姿、内参和语义标签的组织方式ScanNet位姿存储相对简洁。每个场景的.txt文件里以帧号为索引每帧一行或一个块记录了相机在世界坐标系下的4x4齐次变换矩阵。这个矩阵把相机坐标系的点变换到世界坐标系即世界坐标 位姿矩阵 × 相机坐标。如果你是做点云融合或者多视角投影这个矩阵就是核心如果你只是提取单帧RGB-D做图像分割那么只需要内参矩阵即可。内参矩阵在.sens文件里也有但官方同时提供了一个固定的经验值彩色相机焦距为fx/fy 1170.187主点坐标为cx/cy 647.75/483.75图像分辨率通常是1296×968。深度图和彩色图的分辨率略有不同但ScanNet的处理流程中已经做了对齐深度图的坐标和彩色图是匹配的直接使用彩色图的内参处理深度图没有大问题。我这里说的只是经验值严谨起见还是要从.sens里读取实际内参特别是如果你用到的是自定义分辨率版本。语义标签的读取需要通过一个额外的映射文件。官方在tasks/scannetv2-labels.combined.tsv里定义了标签ID和类别名称的对应关系比如1对应wall2对应floor3对应cabinet等总共有20个有效类别。做训练时需要把.ply里的顶点标量值映射成这20个类别的索引并且通常会排除无效标签如0表示未标注-1或255表示无效点。很多开源项目比如SparseConvNet、PointNet的ScanNet数据预处理脚本都已经内置了这个映射文件你直接复用即可。4. 实操过程与核心环节实现4.1 从.sens中提取RGB-D序列这一段是我个人认为整个教程里最有价值的实操部分因为官方SensReader虽然能跑但可控性不够强。下面给你一个可以直接运行的Python脚本它读取.sens文件按照指定帧间隔提取彩色图和深度图并保存对应的位姿矩阵与内参。import os import sys import numpy as np import cv2 from PIL import Image # 把SensReader的目录加入环境变量 sys.path.append(/path/to/ScanNet/SensReader/python/) from SensorData import SensorData def extract_rgbd(sens_path, output_path, frame_skip10): os.makedirs(output_path, exist_okTrue) color_dir os.path.join(output_path, color) depth_dir os.path.join(output_path, depth) pose_dir os.path.join(output_path, pose) os.makedirs(color_dir, exist_okTrue) os.makedirs(depth_dir, exist_okTrue) os.makedirs(pose_dir, exist_okTrue) # 从.sens读取传感器数据 sd SensorData(sens_path) # 遍历每一帧 for i in range(0, sd.num_frames, frame_skip): color sd.color_images[i] depth sd.depth_images[i] pose sd.poses[i] intrinsic sd.intrinsic_color color_path os.path.join(color_dir, f{i:06d}.jpg) depth_path os.path.join(depth_dir, f{i:06d}.png) pose_path os.path.join(pose_dir, f{i:06d}.txt) # 注意深度图是16位单通道数值单位是毫米转为16位PNG保存 Image.fromarray(color).save(color_path) Image.fromarray(depth.astype(np.uint16)).save(depth_path) # 保存4x4位姿矩阵 np.savetxt(pose_path, pose) # 保存内参 np.savetxt(os.path.join(output_path, intrinsic.txt), intrinsic) if __name__ __main__: extract_rgbd( sens_pathscans/scene0000_00/scene0000_00.sens, output_pathoutput/scene0000_00, frame_skip10 )脚本里frame_skip10表示每10帧取1帧这样既能保留足够的视觉连贯性又不会让数据量大到爆炸。如果你是做SLAM或者训练视频级模型可以适当减小到5甚至取全部帧如果只是做单帧图像分割或者检测取15到20帧一帧也够用。有一点特别提醒Image.fromarray(depth.astype(np.uint16))这行千万不要去掉astype因为深度图像的原始数据是带符号的整数或者更宽位深的格式直接fromarray会报错或者丢失数据。深度图像里0一般代表无效值实际使用时需要做滤波。4.2 将语义标签文本转换为可视化网格训练语义分割模型时标签文件往往是单个标量ID而做可视化检查时又需要RGB图像。如果你打开.labels.ply发现一眼看不出语义分布可以试试下面的转换脚本把顶点标签ID映射成固定颜色表生成一个新的带颜色的PLY方便用MeshLab检查。import numpy as np from plyfile import PlyData, PlyData, PlyElement # 读取原始PLY网格 ply PlyData.read(scene0000_00_vh_clean_2.labels.ply) vertices ply[vertex].data coords np.stack([vertices[x], vertices[y], vertices[z]], axis1) labels vertices[label] # 每个顶点的语义标签ID # 定义20类ScanNet类别对应的粗略颜色顺序对应scannetv2-labels.combined.tsv label_colors np.array([ [0, 0, 0], # 0: unannotated [128, 128, 128], # 1: wall [60, 60, 60], # 2: floor [128, 0, 0], # 3: cabinet [0, 128, 0], # 4: bed [0, 0, 128], # 5: chair [128, 128, 0], # 6: sofa [0, 128, 128], # 7: table [128, 0, 128], # 8: door [255, 0, 0], # 9: window [0, 255, 0], # 10: bookshelf [0, 0, 255], # 11: picture [255, 255, 0], # 12: counter [0, 255, 255], # 13: desk [255, 0, 255], # 14: curtain [192, 192, 192], # 15: refrigerator [16, 16, 16], # 16: bathtub [32, 32, 32], # 17: shower curtain [64, 64, 64], # 18: toilet [96, 96, 96], # 19: sink [112, 112, 112], # 20: otherfurniture ], dtypenp.uint8) # 根据标签生成顶点颜色 colors label_colors[labels] # 写入新的PLY new_vertex np.empty( len(coords), dtype[(x, f4), (y, f4), (z, f4), (red, u1), (green, u1), (blue, u1)] ) new_vertex[x] coords[:, 0] new_vertex[y] coords[:, 1] new_vertex[z] coords[:, 2] new_vertex[red] colors[:, 0] new_vertex[green] colors[:, 1] new_vertex[blue] colors[:, 2] el PlyElement.describe(new_vertex, vertex) PlyData([el], textTrue).write(scene0000_00_visualized.ply)这份颜色表是我自己整理的一个近似映射不是官方标准色板主要用于人工检查不用过于纠结具体色值。处理完之后用MeshLab打开新生成的PLY就能直观看到桌子是黄色、椅子是紫色、墙是灰色非常好认。4.3 点云清洗与训练集组织拿到网格模型后如果要做点云深度学习或者目标检测还要把网格采样成点云。很多框架比如PointNet和EdgeConv输入都是点云格式。我们可以用Open3D对PLY网格进行均匀采样import open3d as o3d import numpy as np mesh o3d.io.read_triangle_mesh(scene0000_00_vh_clean_2.ply) pcd mesh.sample_points_uniformly(number_of_points50000) # 如果要做语义分割训练可以同时对带标签网格做同样的采样 mesh_label o3d.io.read_triangle_mesh(scene0000_00_vh_clean_2.labels.ply) pcd_label mesh_label.sample_points_uniformly(number_of_points50000) labels np.asarray(pcd_label.colors)[:, 0].astype(np.int32) # 保存为npy文件方便训练时直接加载 np.save(scene0000_00_xyz.npy, np.asarray(pcd.points)) np.save(scene0000_00_label.npy, labels)注意Open3D读取.labels.ply时会把标签ID读到顶点颜色里而且会做归一化到0到1之间所以转回标签时需要用第一通道乘以类别数并取整具体数值取决于标签ID范围建议先打印一下pcd_label.colors[:20]看看范围再确定缩放系数。这个细节容易翻车我调试的时候发现标签值被缩小了200倍后来才发现是Open3D的归一化导致的所以验证数据分布永远比直接喂进网络靠谱。训练目录的组织方式建议按官方benchmark的习惯来组织。ScanNet官方把数据划分为训练集、验证集和测试集测试集标签不公开需要提交到官方服务器评估。如果你只是自用可以对场景手动划分把scene0000_00等前1201个场景作为训练集后312个作为验证集。每个场景目录下放sceneID.txt场景编号和sceneID_vertices.npy点云坐标、sceneID_labels.npy标签ID这样后续写DataLoader就不用来回解析PLY了。5. 常见问题与排查技巧实录5.1 高频问题速查表为了方便排查我把实际踩过的坑和社区里常见的提问整理成一个速查表。问题现象可能原因解决办法下载时提示401 Unauthorized邮箱收到的密码填错、账号复制多了空格检查是否有多余空格确认不是登录官网的密码重新复制邮件里的原始账号密码脚本报错No module named urllib.request使用的是Python 2环境换成Python 3.6以上版本必要时用python3而不是python下到一半文件损坏PLY打开失败网络不稳定导致传输中断删掉损坏文件重新下载指定ID或使用wget -c手动下载PLY后放回对应目录.sens用普通解压工具打不开格式是自定义二进制容器使用官方SensReader不要改后缀名打开.labels.ply没有颜色语义标签存为标量值并非RGB颜色用4.2节的脚本转成带颜色的PLY深度图打开是全黑的深度值是16位毫米精度普通查看器按8位显示使用Open3D或ImageJ查看或者是16位转8位显示需要归一化提取的彩色图和深度图数量不一致.sens帧索引理解有误确认color_images和depth_images都使用同样的索引比对num_frames和数组长度内参错误导致点云错位使用固定经验值但项目本身是自定义分辨率从.txt或.sens中读取真实内参不要拍脑袋填标签类别数和预期不符用的是细分版本标签而非20类紧凑标签确认使用官方scannetv2-labels.combined.tsv的映射必要时转换为20类训练时显存溢出网格顶点太多、点云数量过大降低采样点数如从50000降为20000使用Block-based采样策略想下载测试集标注测试集标签不公开评测需要提交到官方Benchmark网站请阅读tasks/下的说明5.2 独家排错经验那些年我踩过的坑第一个坑发生在申请环节。我当时填的邮箱是个人邮箱审批邮件等了很久才到。后来换用学校邮箱重新提交第二天就收到了反馈。虽然这可能是巧合但多个用户反馈类似情况所以如果你的申请迟迟没动静不妨换个更正式的学术邮箱试试。第二个坑是脚本版本选择。ScanNet仓库分支比较多master分支的download-scannet.py相对稳定但某些旧分支的脚本用Python 3跑会报ssl.SSLCertVerificationError。我的解决方法是直接更新pip的certifi证书或者在脚本URL请求里加一个ssl._create_unverified_context()但生产环境不建议关闭SSL验证最好是升级Python版本和OpenSSL库。这个坑排查起来有点隐蔽因为报错提示和账号密码无关一上来容易把责任推到网络上。第三个坑是磁盘剩余空间判断失误。我一开始以为下载好压缩包后只要腾出一倍的空间就够结果解压后文件体积比预想大了很多因为.ply网格从压缩格式解压成文本/二进制格式后体积会翻倍。而且.sens文件本身没有高压缩率解压后只多了一点提取文件但全量场景累积起来增幅不小。所以我后来都会预留至少两倍于压缩包的存储空间。第四个坑是深度图和彩色图的对齐问题。ScanNet的官方流程中深度图和彩色图已经做了时间戳和空间对齐但在某些特殊帧上深度图可能对应的是下一帧的彩色图像因为采集过程中两路传感器帧率不是严格同步的。如果你用我给的参数一帧一帧地对应提取极少数帧可能会出现几像素的偏移。解决方法是使用官方提供的对齐索引映射但绝大多数训练任务中这种微小的偏移不会有明显影响。5.3 网络与中断应对指南ScanNet数据量不小下载过程中即使是千兆网络也可能花上一段时间。如果你经常在SSH环境中操作建议无论如何都要配合screen或tmux运行脚本。还有一个经验是不要全局靠脚本续传脚本对单个文件断点续传的支持并不可靠一旦某个大文件下载到99%时中断重新运行可能会从头再来。强烈建议按场景分批下载比如用--id参数一次下10个场景下完一批再下一批这样即使中断也只需要重新跑这一小批。如果你所在的网络环境访问国外服务器速度慢可以考虑在服务器上先下载再用内网同步工具拉回到本地工作机。对于必须用代理的情况因为环境差异太大这里就不展开讲了建议优先选择网络延迟低、丢包率低的通道来跑官方脚本。5.4 数据可用性检查下载完成后别急着开训下载完所有文件后强烈建议先做一轮数据体检再投入训练否则训练中途发现部分场景损坏定位问题会非常痛苦。我常用的检查方法很朴素统计scans目录下的场景数量确认和官方标注的训练集、验证集数量一致。对每个场景用Python尝试读取.sens文件头和.ply文件头如果文件头解析失败说明文件没下载完整。抽查几个场景的.txt文件确认位姿矩阵是4x4的数值矩阵而不是乱码。跑一次4.1节的提取脚本确认彩色图、深度图和位姿文件数量一致。这一套流程大概10分钟能跑完却能避免你花几小时训练后才发现数据源有问题的尴尬。我在一次项目中就遇到过一个场景的.sens文件只有几百KB很明显是下载中被截断了当时因为没做检查导致一批训练样本里混入了空数据精度莫名其妙掉了两个点最后排查了两天才发现数据损坏。6. 实战扩展ScanNet数据在常见网络中的适配6.1 点云语义分割训练前的数据预处理拿到解析好的点云和标签后还需要做一次格式适配才能喂给主流网络。PointNet的常用输入格式是xyz, normal, label组合的.npy文件SparseConvNet则需要把点云体素化后生成稀疏张量。不同框架对输入格式要求不同不可能一个格式通吃所有模型。我的建议是维护一个中间格式把每个场景保存成HDF5或者NPZ文件里面同时存点云坐标、RGB颜色、语义标签和实例标签。这样不管以后换什么网络只需要写一个小的数据转换脚本而不用重新解析原始文件。NPZ格式加载速度够快比PLY解析快很多在训练集很大的情况下也能接受。HDF5虽然更复杂但对超大数据的随机读取性能更好看你的实际需求选择。6.2 从ScanNet到mmrotate、yolov8的迁移思路现在很多人把ScanNet的数据迁移到2D检测或者3D检测框架上。mmrotate主要面向遥感图像的旋转框检测本身不是为室内3D设计的但如果你把ScanNet的3D点云投影成俯视图或者BEV特征图就能训练旋转框检测器来做桌面物体检测或室内平面图提取。yolov8这类2D检测器更直接用RGB图像和从3D真值投影出来的2D框做训练即可。需要注意的是ScanNet本身不提供2D边界框标注需要把3D标注框或点云标注投影到图像平面上这个过程要用到从4.1节提取的相机内参和位姿矩阵。先通过位姿把世界坐标的三维点变换到相机坐标再通过内参投影到像素坐标然后计算包含该物体所有点在图像上的最小外接矩形。这套流程在代码上并不复杂但要在时间和空间对齐上谨慎一些因为采样帧的位姿和深度图可能不是严格对应的。6.3 数据增强与跨数据集泛化最后聊一个实用建议ScanNet的标注精度高、语义类别规范但也存在一个室内数据集通病就是场景风格相对单一基本都来自欧美典型民居和办公场所。如果你要做真实场景下的机器人部署强烈建议在ScanNet训练后再用你自己采集的RGB-D数据或者SUN RGB-D做一次小规模微调能显著提升在未见场景上的泛化能力。我自己的一个项目里先用ScanNet训练了3D语义分割模型在ScanNet测试集上mIoU能到60多但迁移到实验室自采场景后直接跌了将近10个点。后来混合了一部分SUN RGB-D的数据做微调迁移性能才拉回来。如果你也遇到类似情况不要怀疑是模型结构的问题大概率是训练数据分布和部署场景差异过大造成的找一个和目标场景更接近的数据集做domain adaptation往往更有效。ScanNet这套流程跑完之后你会发现真正花时间的不是申请和下载而是理解它的数据组织逻辑。只要理解了.sens容器、.ply顶点标签、位姿矩阵这三个核心概念后面无论是改成其他数据集的解析工具还是自己造一套新的RGB-D数据集处理流程都能很快上手。希望这篇教程能帮你把从零到一的过程尽量缩短把时间留给真正重要的模型设计和训练调参上。
ScanNet数据集获取与解析：从申请到提取RGB-D序列全流程
如果你做3D视觉或者室内场景理解ScanNet数据集应该是绕不开的名字。我第一次下载ScanNet的时候光是申请审批就等了一周拿到官方下载脚本后又因为Python版本和网络问题折腾了大半天好不容易下完. sens原始文件结果发现里面还嵌套着一层数据提取流程整个人都不好了。这篇教程就把我从申请、审批、写脚本下载到解析.sens、提取RGB-D序列、读取位姿和语义标签的完整过程梳理一遍顺便把那些官方文档里不会写的坑挨个标出来。这个数据集适合谁简单说凡是做室内SLAM、3D语义分割、实例分割、扫描重建、点云识别方向的研究人员或学生基本都会用到它。官方提供了1513个室内场景的RGB-D采集序列带完整的相机位姿、深度图、语义标注和重建网格是目前室内场景理解领域使用最广的benchmark之一。如果你正在为yolov8或PointNet准备3D训练数据或者想对比KITTI、NuScenes这类数据集在室外和室内场景下的差异这篇都能给你一个相对完整的参考。1. 内容整体设计与思路拆解1.1 为什么室内3D场景数据集偏偏选中ScanNet先聊一个很多人问过的点室内场景理解数据集有SUN RGB-D、NYUv2、ScanNet等好几个为什么ScanNet能成为默认选项关键不在于它数据量最大而在于它的数据完整性。SUN RGB-D主要是单张RGB-D图像级别的标注NYUv2只有1449张深度图而ScanNet提供的是完整序列每个场景有几百到几千帧不等的连续RGB-D流同时附带重建好的网格模型。这意味着你不仅能做单帧预测还能做时序融合、多视角一致性、3D重建这类任务。ScanNet的采集方式是手持Kinect或者Structure Sensor在室内绕一圈记录整段视频流然后把帧与帧之间的位姿解算出来。官方还提供了全局一致的3D重建结果把每个场景变成了一个连续的三维模型。这个结构对于训练3D语义分割、实例分割、目标检测甚至主动SLAM路径规划算法来说非常关键因为你可以在连续数据上构造时间上的样本而不是像单帧数据集那样每张图独立。另外ScanNet的场景覆盖面也算厚道。1513个序列覆盖办公室、卧室、洗手间、厨房、书房、会议室等常见室内空间还有一部分非规则空间如杂物间和走廊。对于做室内机器人落地的团队来说这种多样性比单纯追求数量重要得多因为模型在真实部署时遇到的空间形态不可能只局限在一两种房型里。我见过不少团队拿ScanNet做预训练再用自己的室内扫描数据做fine-tune实际效果比从零训练好不少。1.2 一次下载三条主线权限、脚本、文件格式整个ScanNet获取流程可以拆成三条主线这也是这篇教程安排的逻辑。第一条线是权限。ScanNet的下载不是点击即得的需要去官网填写学术用途申请表等官方邮件回复下载账号和密码。也就是说你拿到的不只是数据链接还有一个需要配合脚本使用的认证信息。很多人在这步就卡住了要么邮箱填错、要么不知道要等审批要么收到邮件后没注意到账号密码在邮件正文里。第二条线是下载脚本。官方没有提供直链打包下载而是给了一个叫download-scannet.py的Python脚本用命令行参数控制下载哪些类型的数据。你需要把访问账号、密码、数据集版本、下载内容类型依次传进去。这个脚本本身逻辑不复杂但它面向的是Python 2/3兼容环境而且对网络稳定性要求不低容易在下载过程中挂掉。第三条线是格式解析。下载完成后你会发现拿到的文件分为两类一类是带.ply后缀的网格文件可以直接用MeshLab或Blender打开另一类是.sens后缀的传感器原始数据需要通过官方配套的SensReader工具把RGB图像、深度图、相机内参和位姿逐帧提取出来。很多人下完. sens以后以为完事了其实真正的解析工作才刚刚开始。后面的内容就按这三条线逐一展开。先讲申请环节的注意事项再讲脚本下载的具体用法和参数选择最后重点拆解.sens和.ply的解析方法。每条线我都会结合自己实际跑通的过程来说而不是照着官方README念一遍。1.3 横向对比ScanNet与KITTI、NuScenes的定位差异做3D视觉的人手头通常不只一个数据集我在自己的项目里就同时使用过KITTI、NuScenes和ScanNet。这里简单对比一下它们的定位差异方便你在选题时快速判断该用哪个。KITTI主打自动驾驶场景数据用车载传感器采集包含双目图像、激光雷达点云、GPS/IMU信息坐标系是车辆为中心的室外大地坐标系场景基本是道路、车辆、行人。NuScenes更进一步提供了多传感器融合数据包括6个相机、5个雷达、激光雷达和毫米波雷达还带完整的3D标注框和地图信息适合做多模态融合研究。ScanNet是完全不同的路线。它不碰自动驾驶专注室内。传感器是手持RGB-D设备没有GPS位姿是通过视觉里程计或者RGB-D SLAM算出来的相对姿态语义标注是逐点或逐面片级别而不是3D框级别。如果你做的是自动驾驶感知KITTI和NuScenes更合适如果做的是机器人抓取、室内导航、AR场景理解ScanNet几乎是最容易获取、标注质量最稳定的室内数据集。这里有个容易被忽视的细节ScanNet的语义标签体系是NYU40类的一部分不是完整的40类而是ScanNet自己整理出的20类常用类别比如墙、地板、桌子、椅子、沙发、门、窗户、书架等。和KITTI那种“Car、Pedestrian、Cyclist”的检测标签不同ScanNet的标签是稠密的面片级/点级标注理解这一点对你处理标签映射关系会很有帮助。2. 申请与下载全流程2.1 官网申请填表技巧与审批等待ScanNet的申请入口在官方网站的Dataset页面不要进错成ScanNet或者ScanNet Annotation Tool的页面这两个是不同的项目。进入后找到申请区域需要填写姓名、单位、邮箱、工作单位性质、用途描述等内容。几个容易踩坑的地方邮箱建议使用学校或研究所的学术邮箱。虽然官方没有强制要求.edu或.ac.cn后缀但我见过用普通个人邮箱申请后审批时间明显变长的情况少数情况下甚至会直接不回复。用途描述尽量写具体比如“用于研究室内3D语义分割算法的跨场景泛化问题”比写“用于学习和科研”要更可信。官方会人工审核用途描述模糊的可能会被退回补充。提交后一般在1到5个工作日内收到回复节假日可能会更慢。如果一周没收到建议发邮件礼貌询问一下我当时就是等了五天有点慌结果第六天早上收到了。审批通过的邮件里会包含你的专属下载账号和密码这个密码不是登录官网用的而是给download-scannet.py脚本做HTTP Basic认证用的别弄混了。官方邮件里那个“password”字段就是脚本参数里要用到的我一开始下意识拿它去登录官网用户中心结果当然登不上去绕了半天才发现需要结合脚本使用这也是我开头提过的那个坑。2.2 下载脚本安装与基础用法拿到账号密码后接下来要准备下载脚本。ScanNet的官方下载脚本托管在GitHub上仓库名字是ScanNet/ScanNet脚本在仓库根目录下文件名是download-scannet.py。它依赖Python的urlopen等标准库但不同分支对Python版本要求不同建议直接用Python 3.6以上的环境跑旧版本Python 2运行时容易出现编码或者SSL证书问题。脚本用法比较直观。下载全部数据用这条命令python download-scannet.py -o /path/to/scannet --type all -u 你的用户名 --password 你的密码其中-o指定输出目录--type指定下载类型-u和--password填邮件里的账号密码。官方还提供了--id参数用于指定场景编号如果你只需要某个特定场景而不是全量数据这个参数能省大量流量和时间。比如只下载场景scene0000_00python download-scannet.py -o /path/to/scannet --id scene0000_00 --type all -u 用户名 --password 密码脚本支持的下载类型在--type里可以组合指定常用的有_vh_clean_2带标签的PLY网格、_vh_clean_2.ply不带标签的网格、_sens传感器原始数据、_txt位姿和内参文本等。如果你想做语义分割至少要下_vh_clean_2.ply带语义标签和_sens前者用于生成真值网格后者用于提取逐帧RGB-D图像。第一次跑脚本建议先用--id加一个场景号测试连通性和账号权限全量下载1513个场景前先跑通一个小样本不然下到一半才发现认证失败就白费时间了。2.3 下载策略断点续传、网络加速与存储规划ScanNet全量数据体积大概在几十GB到一两百GB之间具体取决于你选的压缩类型和分辨率版本。官方提供了不同分辨率的下载选项--type all默认下载的是完整原始数据体积最大如果只做语义分割训练可以只下载_vh_clean_2.ply和_sens总容量会明显下降。下载过程中最常见的问题是网络中断。官方脚本本身支持续传如果你用CtrlC中断再重新执行已下载的文件会跳过不重复下载但前提是之前下载的临时文件没有损坏。我在实际使用中还是建议搭配screen或tmux后台运行避免SSH会话断开的干扰screen -S scannet_download python download-scannet.py -o /data/scannet --type all -u 用户名 --password 密码离开终端时直接关闭窗口重新登录后执行screen -r scannet_download恢复会话。如果你在服务器上下载这个方法能最大限度省心。另外一个容易被忽略的点是磁盘格式。ScanNet的PLY文件属于ASCII或二进制混合格式解压后单场景不算太大但1513个场景累积下来会占不少inode和存储空间。建议提前规划好目录结构比如/data/scannet/scans、/data/scannet/tasks分目录存放并且确保分区至少有两倍于压缩包的剩余空间因为解压过程需要临时的容量。实测下来如果用机械硬盘存储边解压边训练IO可能会成为瓶颈预算允许的话优先放SSD或者NVMe盘。下载完成后你的目录结构大致是这样scannet/ scans/ scene0000_00/ scene0000_00.sens scene0000_00.txt scene0000_00_vh_clean_2.ply scene0000_00_vh_clean_2.labels.ply scene0000_00_vh_clean_2.0.010000.segs.json scene0000_01/ ...其中.sens是之前说的传感器原始数据.txt是位姿和相机内参文本.ply是网格模型.labels.ply是带语义标签的网格模型.segs.json是实例分割的超体素文件这个文件在做实例分割任务时才会用到。3. 核心数据解析与格式详解3.1 .sens文件结构官方SensReader的使用.sens文件本质上是ScanNet团队自定义的二进制容器格式里面装着一整段RGB-D视频流及对应的传感器元数据。直接改后缀名或者用普通解压工具是打不开的必须用官方提供的SensReader工具解析。SensReader有两种使用方式一种是直接命令行运行官方配套的解析脚本另一种是把它作为Python库导入。官方仓库里有一个sens_reader目录里面提供了reader.py和SensorData类。使用前需要先把sens_reader的路径加入Python的环境变量或者直接在该目录下运行你的脚本。最直接的做法是官方仓库里还提供了一个命令行人机交互工具运行后会一次提取所有帧的彩色图、深度图、位姿和内在参数到指定目录。命令如下python reader.py --filename /path/to/scene0000_00.sens --output_path /path/to/output运行后会生成color、depth、pose、intrinsic等子目录。其中彩色图是PNG或JPG格式深度图是16位PNG格式保存的是毫米单位的原始深度值位姿是4x4的变换矩阵文本。但如果你只需要部分帧或者想自己控制帧采样频率就会发现官方命令行不太够用。我建议直接在Python脚本里导入SensorData类来写自己的提取逻辑自由度更高。关于这个的详细代码我在第4章里会给出一个可以直接复制的版本。3.2 PLY网格带标签网格与不带标签网格的区别ScanNet的.ply文件分为几种最容易让人困惑的是_vh_clean_2.ply和_vh_clean_2.labels.ply这两个的区别。前者是几何网格只包含顶点坐标、法线和颜色信息适合做几何重建或点云对齐任务后者在同样的几何网格上附加了每个顶点的语义标签ID适合做3D语义分割任务的训练真值。还有一个_vh_clean.ply是未经过二次抽稀的高精度网格顶点数量明显更多一般做可视化看效果用而_vh_clean_2.ply经过了抽稀和清理面和顶点数更可控也更容易被训练框架加载。所以很多人训练语义分割直接选_vh_clean_2.labels.ply是有道理的它既保留了足够的几何细节又不会让数据量大到无法处理。如果你用MeshLab打开.ply文件会看到网格的顶点颜色信息打开.labels.ply时默认看到的往往是黑白灰或者奇怪的彩色。因为语义标签ID被存成了标量属性MeshLab默认不会把它映射成彩色可视化。需要打开属性表把标量值映射到颜色预览或者自己写代码把标签ID映射成RGB颜色再保存成新的PLY文件。这一点对刚上手的人来说很容易误解总以为下载的文件坏了或者官方没给颜色其实只是查看方式不对。3.3 位姿、内参和语义标签的组织方式ScanNet位姿存储相对简洁。每个场景的.txt文件里以帧号为索引每帧一行或一个块记录了相机在世界坐标系下的4x4齐次变换矩阵。这个矩阵把相机坐标系的点变换到世界坐标系即世界坐标 位姿矩阵 × 相机坐标。如果你是做点云融合或者多视角投影这个矩阵就是核心如果你只是提取单帧RGB-D做图像分割那么只需要内参矩阵即可。内参矩阵在.sens文件里也有但官方同时提供了一个固定的经验值彩色相机焦距为fx/fy 1170.187主点坐标为cx/cy 647.75/483.75图像分辨率通常是1296×968。深度图和彩色图的分辨率略有不同但ScanNet的处理流程中已经做了对齐深度图的坐标和彩色图是匹配的直接使用彩色图的内参处理深度图没有大问题。我这里说的只是经验值严谨起见还是要从.sens里读取实际内参特别是如果你用到的是自定义分辨率版本。语义标签的读取需要通过一个额外的映射文件。官方在tasks/scannetv2-labels.combined.tsv里定义了标签ID和类别名称的对应关系比如1对应wall2对应floor3对应cabinet等总共有20个有效类别。做训练时需要把.ply里的顶点标量值映射成这20个类别的索引并且通常会排除无效标签如0表示未标注-1或255表示无效点。很多开源项目比如SparseConvNet、PointNet的ScanNet数据预处理脚本都已经内置了这个映射文件你直接复用即可。4. 实操过程与核心环节实现4.1 从.sens中提取RGB-D序列这一段是我个人认为整个教程里最有价值的实操部分因为官方SensReader虽然能跑但可控性不够强。下面给你一个可以直接运行的Python脚本它读取.sens文件按照指定帧间隔提取彩色图和深度图并保存对应的位姿矩阵与内参。import os import sys import numpy as np import cv2 from PIL import Image # 把SensReader的目录加入环境变量 sys.path.append(/path/to/ScanNet/SensReader/python/) from SensorData import SensorData def extract_rgbd(sens_path, output_path, frame_skip10): os.makedirs(output_path, exist_okTrue) color_dir os.path.join(output_path, color) depth_dir os.path.join(output_path, depth) pose_dir os.path.join(output_path, pose) os.makedirs(color_dir, exist_okTrue) os.makedirs(depth_dir, exist_okTrue) os.makedirs(pose_dir, exist_okTrue) # 从.sens读取传感器数据 sd SensorData(sens_path) # 遍历每一帧 for i in range(0, sd.num_frames, frame_skip): color sd.color_images[i] depth sd.depth_images[i] pose sd.poses[i] intrinsic sd.intrinsic_color color_path os.path.join(color_dir, f{i:06d}.jpg) depth_path os.path.join(depth_dir, f{i:06d}.png) pose_path os.path.join(pose_dir, f{i:06d}.txt) # 注意深度图是16位单通道数值单位是毫米转为16位PNG保存 Image.fromarray(color).save(color_path) Image.fromarray(depth.astype(np.uint16)).save(depth_path) # 保存4x4位姿矩阵 np.savetxt(pose_path, pose) # 保存内参 np.savetxt(os.path.join(output_path, intrinsic.txt), intrinsic) if __name__ __main__: extract_rgbd( sens_pathscans/scene0000_00/scene0000_00.sens, output_pathoutput/scene0000_00, frame_skip10 )脚本里frame_skip10表示每10帧取1帧这样既能保留足够的视觉连贯性又不会让数据量大到爆炸。如果你是做SLAM或者训练视频级模型可以适当减小到5甚至取全部帧如果只是做单帧图像分割或者检测取15到20帧一帧也够用。有一点特别提醒Image.fromarray(depth.astype(np.uint16))这行千万不要去掉astype因为深度图像的原始数据是带符号的整数或者更宽位深的格式直接fromarray会报错或者丢失数据。深度图像里0一般代表无效值实际使用时需要做滤波。4.2 将语义标签文本转换为可视化网格训练语义分割模型时标签文件往往是单个标量ID而做可视化检查时又需要RGB图像。如果你打开.labels.ply发现一眼看不出语义分布可以试试下面的转换脚本把顶点标签ID映射成固定颜色表生成一个新的带颜色的PLY方便用MeshLab检查。import numpy as np from plyfile import PlyData, PlyData, PlyElement # 读取原始PLY网格 ply PlyData.read(scene0000_00_vh_clean_2.labels.ply) vertices ply[vertex].data coords np.stack([vertices[x], vertices[y], vertices[z]], axis1) labels vertices[label] # 每个顶点的语义标签ID # 定义20类ScanNet类别对应的粗略颜色顺序对应scannetv2-labels.combined.tsv label_colors np.array([ [0, 0, 0], # 0: unannotated [128, 128, 128], # 1: wall [60, 60, 60], # 2: floor [128, 0, 0], # 3: cabinet [0, 128, 0], # 4: bed [0, 0, 128], # 5: chair [128, 128, 0], # 6: sofa [0, 128, 128], # 7: table [128, 0, 128], # 8: door [255, 0, 0], # 9: window [0, 255, 0], # 10: bookshelf [0, 0, 255], # 11: picture [255, 255, 0], # 12: counter [0, 255, 255], # 13: desk [255, 0, 255], # 14: curtain [192, 192, 192], # 15: refrigerator [16, 16, 16], # 16: bathtub [32, 32, 32], # 17: shower curtain [64, 64, 64], # 18: toilet [96, 96, 96], # 19: sink [112, 112, 112], # 20: otherfurniture ], dtypenp.uint8) # 根据标签生成顶点颜色 colors label_colors[labels] # 写入新的PLY new_vertex np.empty( len(coords), dtype[(x, f4), (y, f4), (z, f4), (red, u1), (green, u1), (blue, u1)] ) new_vertex[x] coords[:, 0] new_vertex[y] coords[:, 1] new_vertex[z] coords[:, 2] new_vertex[red] colors[:, 0] new_vertex[green] colors[:, 1] new_vertex[blue] colors[:, 2] el PlyElement.describe(new_vertex, vertex) PlyData([el], textTrue).write(scene0000_00_visualized.ply)这份颜色表是我自己整理的一个近似映射不是官方标准色板主要用于人工检查不用过于纠结具体色值。处理完之后用MeshLab打开新生成的PLY就能直观看到桌子是黄色、椅子是紫色、墙是灰色非常好认。4.3 点云清洗与训练集组织拿到网格模型后如果要做点云深度学习或者目标检测还要把网格采样成点云。很多框架比如PointNet和EdgeConv输入都是点云格式。我们可以用Open3D对PLY网格进行均匀采样import open3d as o3d import numpy as np mesh o3d.io.read_triangle_mesh(scene0000_00_vh_clean_2.ply) pcd mesh.sample_points_uniformly(number_of_points50000) # 如果要做语义分割训练可以同时对带标签网格做同样的采样 mesh_label o3d.io.read_triangle_mesh(scene0000_00_vh_clean_2.labels.ply) pcd_label mesh_label.sample_points_uniformly(number_of_points50000) labels np.asarray(pcd_label.colors)[:, 0].astype(np.int32) # 保存为npy文件方便训练时直接加载 np.save(scene0000_00_xyz.npy, np.asarray(pcd.points)) np.save(scene0000_00_label.npy, labels)注意Open3D读取.labels.ply时会把标签ID读到顶点颜色里而且会做归一化到0到1之间所以转回标签时需要用第一通道乘以类别数并取整具体数值取决于标签ID范围建议先打印一下pcd_label.colors[:20]看看范围再确定缩放系数。这个细节容易翻车我调试的时候发现标签值被缩小了200倍后来才发现是Open3D的归一化导致的所以验证数据分布永远比直接喂进网络靠谱。训练目录的组织方式建议按官方benchmark的习惯来组织。ScanNet官方把数据划分为训练集、验证集和测试集测试集标签不公开需要提交到官方服务器评估。如果你只是自用可以对场景手动划分把scene0000_00等前1201个场景作为训练集后312个作为验证集。每个场景目录下放sceneID.txt场景编号和sceneID_vertices.npy点云坐标、sceneID_labels.npy标签ID这样后续写DataLoader就不用来回解析PLY了。5. 常见问题与排查技巧实录5.1 高频问题速查表为了方便排查我把实际踩过的坑和社区里常见的提问整理成一个速查表。问题现象可能原因解决办法下载时提示401 Unauthorized邮箱收到的密码填错、账号复制多了空格检查是否有多余空格确认不是登录官网的密码重新复制邮件里的原始账号密码脚本报错No module named urllib.request使用的是Python 2环境换成Python 3.6以上版本必要时用python3而不是python下到一半文件损坏PLY打开失败网络不稳定导致传输中断删掉损坏文件重新下载指定ID或使用wget -c手动下载PLY后放回对应目录.sens用普通解压工具打不开格式是自定义二进制容器使用官方SensReader不要改后缀名打开.labels.ply没有颜色语义标签存为标量值并非RGB颜色用4.2节的脚本转成带颜色的PLY深度图打开是全黑的深度值是16位毫米精度普通查看器按8位显示使用Open3D或ImageJ查看或者是16位转8位显示需要归一化提取的彩色图和深度图数量不一致.sens帧索引理解有误确认color_images和depth_images都使用同样的索引比对num_frames和数组长度内参错误导致点云错位使用固定经验值但项目本身是自定义分辨率从.txt或.sens中读取真实内参不要拍脑袋填标签类别数和预期不符用的是细分版本标签而非20类紧凑标签确认使用官方scannetv2-labels.combined.tsv的映射必要时转换为20类训练时显存溢出网格顶点太多、点云数量过大降低采样点数如从50000降为20000使用Block-based采样策略想下载测试集标注测试集标签不公开评测需要提交到官方Benchmark网站请阅读tasks/下的说明5.2 独家排错经验那些年我踩过的坑第一个坑发生在申请环节。我当时填的邮箱是个人邮箱审批邮件等了很久才到。后来换用学校邮箱重新提交第二天就收到了反馈。虽然这可能是巧合但多个用户反馈类似情况所以如果你的申请迟迟没动静不妨换个更正式的学术邮箱试试。第二个坑是脚本版本选择。ScanNet仓库分支比较多master分支的download-scannet.py相对稳定但某些旧分支的脚本用Python 3跑会报ssl.SSLCertVerificationError。我的解决方法是直接更新pip的certifi证书或者在脚本URL请求里加一个ssl._create_unverified_context()但生产环境不建议关闭SSL验证最好是升级Python版本和OpenSSL库。这个坑排查起来有点隐蔽因为报错提示和账号密码无关一上来容易把责任推到网络上。第三个坑是磁盘剩余空间判断失误。我一开始以为下载好压缩包后只要腾出一倍的空间就够结果解压后文件体积比预想大了很多因为.ply网格从压缩格式解压成文本/二进制格式后体积会翻倍。而且.sens文件本身没有高压缩率解压后只多了一点提取文件但全量场景累积起来增幅不小。所以我后来都会预留至少两倍于压缩包的存储空间。第四个坑是深度图和彩色图的对齐问题。ScanNet的官方流程中深度图和彩色图已经做了时间戳和空间对齐但在某些特殊帧上深度图可能对应的是下一帧的彩色图像因为采集过程中两路传感器帧率不是严格同步的。如果你用我给的参数一帧一帧地对应提取极少数帧可能会出现几像素的偏移。解决方法是使用官方提供的对齐索引映射但绝大多数训练任务中这种微小的偏移不会有明显影响。5.3 网络与中断应对指南ScanNet数据量不小下载过程中即使是千兆网络也可能花上一段时间。如果你经常在SSH环境中操作建议无论如何都要配合screen或tmux运行脚本。还有一个经验是不要全局靠脚本续传脚本对单个文件断点续传的支持并不可靠一旦某个大文件下载到99%时中断重新运行可能会从头再来。强烈建议按场景分批下载比如用--id参数一次下10个场景下完一批再下一批这样即使中断也只需要重新跑这一小批。如果你所在的网络环境访问国外服务器速度慢可以考虑在服务器上先下载再用内网同步工具拉回到本地工作机。对于必须用代理的情况因为环境差异太大这里就不展开讲了建议优先选择网络延迟低、丢包率低的通道来跑官方脚本。5.4 数据可用性检查下载完成后别急着开训下载完所有文件后强烈建议先做一轮数据体检再投入训练否则训练中途发现部分场景损坏定位问题会非常痛苦。我常用的检查方法很朴素统计scans目录下的场景数量确认和官方标注的训练集、验证集数量一致。对每个场景用Python尝试读取.sens文件头和.ply文件头如果文件头解析失败说明文件没下载完整。抽查几个场景的.txt文件确认位姿矩阵是4x4的数值矩阵而不是乱码。跑一次4.1节的提取脚本确认彩色图、深度图和位姿文件数量一致。这一套流程大概10分钟能跑完却能避免你花几小时训练后才发现数据源有问题的尴尬。我在一次项目中就遇到过一个场景的.sens文件只有几百KB很明显是下载中被截断了当时因为没做检查导致一批训练样本里混入了空数据精度莫名其妙掉了两个点最后排查了两天才发现数据损坏。6. 实战扩展ScanNet数据在常见网络中的适配6.1 点云语义分割训练前的数据预处理拿到解析好的点云和标签后还需要做一次格式适配才能喂给主流网络。PointNet的常用输入格式是xyz, normal, label组合的.npy文件SparseConvNet则需要把点云体素化后生成稀疏张量。不同框架对输入格式要求不同不可能一个格式通吃所有模型。我的建议是维护一个中间格式把每个场景保存成HDF5或者NPZ文件里面同时存点云坐标、RGB颜色、语义标签和实例标签。这样不管以后换什么网络只需要写一个小的数据转换脚本而不用重新解析原始文件。NPZ格式加载速度够快比PLY解析快很多在训练集很大的情况下也能接受。HDF5虽然更复杂但对超大数据的随机读取性能更好看你的实际需求选择。6.2 从ScanNet到mmrotate、yolov8的迁移思路现在很多人把ScanNet的数据迁移到2D检测或者3D检测框架上。mmrotate主要面向遥感图像的旋转框检测本身不是为室内3D设计的但如果你把ScanNet的3D点云投影成俯视图或者BEV特征图就能训练旋转框检测器来做桌面物体检测或室内平面图提取。yolov8这类2D检测器更直接用RGB图像和从3D真值投影出来的2D框做训练即可。需要注意的是ScanNet本身不提供2D边界框标注需要把3D标注框或点云标注投影到图像平面上这个过程要用到从4.1节提取的相机内参和位姿矩阵。先通过位姿把世界坐标的三维点变换到相机坐标再通过内参投影到像素坐标然后计算包含该物体所有点在图像上的最小外接矩形。这套流程在代码上并不复杂但要在时间和空间对齐上谨慎一些因为采样帧的位姿和深度图可能不是严格对应的。6.3 数据增强与跨数据集泛化最后聊一个实用建议ScanNet的标注精度高、语义类别规范但也存在一个室内数据集通病就是场景风格相对单一基本都来自欧美典型民居和办公场所。如果你要做真实场景下的机器人部署强烈建议在ScanNet训练后再用你自己采集的RGB-D数据或者SUN RGB-D做一次小规模微调能显著提升在未见场景上的泛化能力。我自己的一个项目里先用ScanNet训练了3D语义分割模型在ScanNet测试集上mIoU能到60多但迁移到实验室自采场景后直接跌了将近10个点。后来混合了一部分SUN RGB-D的数据做微调迁移性能才拉回来。如果你也遇到类似情况不要怀疑是模型结构的问题大概率是训练数据分布和部署场景差异过大造成的找一个和目标场景更接近的数据集做domain adaptation往往更有效。ScanNet这套流程跑完之后你会发现真正花时间的不是申请和下载而是理解它的数据组织逻辑。只要理解了.sens容器、.ply顶点标签、位姿矩阵这三个核心概念后面无论是改成其他数据集的解析工具还是自己造一套新的RGB-D数据集处理流程都能很快上手。希望这篇教程能帮你把从零到一的过程尽量缩短把时间留给真正重要的模型设计和训练调参上。
