做3D视觉的人应该都绕不过ScanNet这个词尤其是做室内场景理解、语义分割、3D重建、点云处理或者NeRF/Gaussian Splatting这几类方向的朋友。ScanNet是目前学术界用得最广的室内RGB-D数据集之一包含1513个采集场景的彩色图、深度图、相机位姿、语义标签和网格模型官方还提供了完整的评测工具。问题在于这套数据集的申请和下载流程做得相当原始注册、审批、脚本参数、数据格式每一步都藏着坑。网上资料虽然不少但大多是零散吐槽很少有把整个流程从头到尾理顺的。这篇文章就是我亲身把ScanNet完整下载一遍之后踩坑踩出来的实操记录从申请到验证可用尽量一次说透。1. 先搞清楚ScanNet到底是个什么东西1.1 一分钟看懂这个数据集ScanNet由斯坦福大学等机构在2017年前后发布是一个面向室内三维场景理解的大规模RGB-D视频数据集。它用iPhone和Structure Sensor之类的设备采集了超过1500个真实室内场景覆盖办公室、卧室、卫生间、教室、餐厅等各种常见环境。每个场景记录了一段连续的视频流逐帧包含彩色图像和对应深度图同时提供了每帧的相机内参、外参位姿以及最终重建出的带语义标签的三维网格模型。这里要强调一个容易混淆的点ScanNet不只是“一个数据集”而是分成了两大部分。原始RGB-D视频序列是给SLAM、位姿估计、视频级三维重建方向用的重建后的带标签三维网格是给语义分割、实例分割、场景理解方向用的。两类数据的使用场景完全不同下载方式也有区别后面我会专门说怎么按需选择避免下载回来才发现一大半用不上。1.2 哪些人需要它能拿来干什么我个人接触ScanNet的原因是在做室内语义分割模型的训练数据准备后来发现它几乎成了这个领域的默认benchmark。如果你跑过一些论文的开源代码会发现很多仓库默认就用ScanNet做训练或测试比如当前热门的3D Gaussian Splatting相关方法、室内语义占用预测、点云语义分割等方向都经常用ScanNet作为标准数据源。从实际用途来看ScanNet被引用最多的工作方向有四类RGB-D SLAM与位姿估计原始视频序列自带IMU信息和准确位姿真值非常适合做相机跟踪精度评估。三维语义/实例分割带标注的网格模型是主流训练集S3DIS、Structured3D虽然在部分任务上也很常用但ScanNet的规模和数据多样性更均衡。多视图三维重建密集的RGB-D序列加上高精度位姿用来做TSDF融合、表面重建的输入输出对比。神经渲染近年的NeRF和3DGS论文经常用ScanNet的某个场景做定性展示因为它的相机轨迹连续、场景尺度适合室内渲染任务。这里我建议你在申请之前先明确自己的任务到底需要哪部分数据别像我第一次那样全量下载结果光下载就花了两天最后真正用到的只有几十个场景的网格和标签。2. 申请这一步最磨人2.1 官网注册与提交申请ScanNet的下载入口不是公开的直接下载链接而是需要先到官方网站提交申请填写一份问卷式的表单等待人工审核。网址是scan-net.org打开之后找到Download或Request Access页面填入姓名、机构、邮箱、所属单位、研究用途这些信息。这里有几个细节第一次很容易写错邮箱必须使用机构邮箱也就是学校的.edu或公司域名邮箱Gmail、Outlook等个人邮箱大概率会被直接打回。研究用途的描述要具体一些别只写研究使用四个字。我建议写清楚要做什么方向比如for semantic segmentation on indoor RGB-D scenes或者for 3D reconstruction evaluation审核人员看到具体用途通过率会高不少。机构信息要与邮箱域名匹配你要是填了个学校A邮箱却是学校B的审核那边可能觉得可疑。2.2 等待审核与常见卡点提交之后就是等邮件。官方说法是几个工作日但实测下来快则一两天慢则一两周。我有朋友遇到过提交两次都没回复的情况最后换了机构邮箱重新提交才通过。所以如果你超过一周没收到任何邮件别干等检查一下垃圾箱然后把申请再提交一次。还有一点要提醒审核通过的通知邮件和后续下载账号信息是从不同邮箱发出来的。通过通知一般来自项目组下载信息则是一个自动回复式的邮件里面包含你的下载用户名、密码或者token。这两封邮件我建议都标记为重要邮件别顺手删了。2.3 邮件里的下载账号和Key长什么样审核通过后收到的邮件大致包含一个下载地址前缀、你的专属用户名、一段口令或者key文件以及简单的使用说明。这个key是你后续运行下载脚本的身份凭证有效期不确定有些人反馈半年后失效所以拿到key立刻开始下载别拖太久。如果你换了电脑或者同事也要下同一批数据记得把key文件保存到一个安全的位置避免重复申请。这里给一个小建议把你的key文件名、用户名、下载地址这三样信息记录在一个txt里放在数据集根目录旁边。不要尝试记住它下载脚本报401错误的时候你一定会回来找这条记录的。3. 三种下载方式对比与实操记录3.1 官方脚本 download_scannet.py 的正确打开方式ScanNet官方GitHub仓库里提供了下载脚本文件名是download_scannet.py。这个脚本是整个下载流程的核心工具但你直接双击运行它肯定会报错因为它依赖Python 2的环境。实测Python 3也可以跑但需要手动调整部分依赖不推荐新手折腾最省事的做法是直接用官方给定的Python 2环境或者用系统自带的Python 2解释器。脚本的基础用法如下python download_scannet.py -o [输出目录] --username [你的用户名] --password [你的口令]第一次运行时会在目标目录创建scans、scans_test等子目录并按照场景编号逐个下载。如果你只是测试环境通不通这里我的建议是先指定一个极小范围来试跑python download_scannet.py -o ./test --username xxx --password yyy --id scene0000_00只下载一个场景确认脚本能正常认证、解压、组织目录再跑全量这个习惯能省下很多排查时间。3.2 按任务选择性下载-o 参数比你想的更重要这是整个下载流程里最值得展开的一个参数因为很多人下载完才发现自己根本不需要那么多东西。脚本的--type参数控制下载内容常见取值包括参数值对应内容适用任务-o加--type scenetype原始RGB-D视频序列.sensSLAM、重建、渲染-o加--type labeled带语义标签的网格模型.ply以及标签文件语义、实例分割--type mesh无标签的网格模型几何处理--type intrinsics/--type extrinsics相机内参/外参文件需要标定数据的任务如果你做语义分割实际上只需要labeled类型对应的场景列表也会小很多。-v控制是否下载验证集-d控制是否下载测试集。默认情况下训练集、验证集、测试集可能都会尝试下载但测试集的标签是不公开的部分任务对测试集的需求其实很低可以跳过以节省大量时间。这里我最想强调的一点是先确认自己的任务需要原始视频还是只需网格标签。原始视频每个场景动辄几个GB网格和标签往往只有几十MB。你如果只是做分割模型的训练数据却把1513个场景的视频全部下下来不仅磁盘吃紧下载时间也会拉到几天相当不划算。3.3 浏览器直接下载 vs 脚本下载官方也提供网页端的直接下载方式登录后每个场景以压缩包的形式列在页面上可以点按下载。这个方式适合只需要少量场景、或者脚本一直报错的情况。但实测下来网页批量下载非常痛苦浏览器下载多文件容易中断而且没有断点续传机制一次中断就得重新下整个场景压缩包。我个人的建议是优先用脚本脚本支持跳过已下载文件半路失败后重跑一次会接着下载。如果脚本持续报认证错误检查一下密码是否包含特殊字符被shell转义了实在不行再转到网页端一次只下需要的场景别图省事全选。下载过程还有一个现实层面的问题需要注意ScanNet的数据服务器在境外高峰期下载速度非常不稳定。我实测凌晨时段速度明显更快白天的下载速度经常掉到几十KB/s。这个没有太好的办法只能错峰下载、耐心等待脚本级别的重试可以缓解但无法根治速度问题。4. 下载完之后别急着开心数据组织和格式才是重头戏4.1 目录结构和文件名含义下载并解压完成后ScanNet的目录结构大概长这样scans/ scene0000_00/ scene0000_00.sens scene0000_00.txt scene0000_00_vh_clean.ply scene0000_00_vh_clean_2.ply scene0000_00_vh_clean_2.labels.ply scene0000_00_vh_clean_2.ply.ply scene0000_00.aggregation.json scene0000_00_vh_clean_2.0.010000.segs.json scene0000_01/ ...每个场景一个文件夹命名规则是scene加四位场景编号下划线再加两位序号。后缀含义要记一下.sens原始RGB-D视频流包含彩色图、深度图、相机位姿、IMU等。_vh_clean.ply经过体积融合重建的表面网格也就是重建结果。_vh_clean_2.ply进一步清理过的小面片网格很多任务用这个做几何输入。_vh_clean_2.labels.ply每个顶点带语义标签的网格语义分割任务的基础数据。.aggregation.json实例级标注把物体实例的聚集关系记录下来。.segs.json过分割片段信息配合aggregation使用。.txt每帧的位姿等信息但更完整的位姿还在.sens内部。4.2 sens文件到底是什么.sens是ScanNet自己的容器格式把图像序列、深度图、位姿、IMU数据打包在一起。不要试图用普通解压工具打开它官方提供了配套的读取脚本SensReader在GitHub仓库的SensReader目录下。它的使用方式大致是# 官方SensReader的python版本 from SensReader import SensorData data SensorData(scene0000_00.sens) data.export_depth(/output/depth) data.export_color(/output/color) data.export_poses(/output/pose)导出后就能看到每一帧的彩色图、深度图以及对应的pose文件。pose文件是一个4x4的变换矩阵把该帧相机坐标系下的点变换到世界坐标系。这个格式理解起来比较直接但有一个细节容易忽略深度图单位是毫米加载后使用前记得除以1000换算成米彩色图一般是jpg格式深度图则是16位PNG。4.3 标签与真值文件语义分割方向最关心的_vh_clean_2.labels.ply本质上是一个带顶点属性的ply网格文件。每个顶点除了xyz坐标和法线还多了一个label属性代表语义类别ID。ScanNet定义了自己的类别映射表比如墙壁、地板、桌子、椅子等共20类依次映射到0~19。加载时一定要用官方提供的类别映射文件不要自己猜。很多开源代码里都有scannetv2_labels.py这类文件里面定义了颜色映射和类别名称直接拿来用就行。aggregation.json则记录了实例级信息比如某个柜子是哪些顶点构成的哪些片段属于同一个对象。做实例分割或者需要物体级监督的任务会用到这个文件。它和segs.json配合使用segs.json先给出过分割片段aggregation.json再把这些片段聚合成对象实例。这两个json文件结构都不复杂但字段含义需要对照README理解不要靠猜。5. 避坑实录我踩过的坑和解决办法5.1 申请邮箱填错和垃圾邮件拦截第一次申请ScanNet的时候我填了学校邮箱但当时用的是拼音姓名和论文署名不一致结果审核被拒了一次。后来我把姓名改成论文里的标准拼写研究用途也写了更具体的句子第二次才通过。另外很多高校邮箱的垃圾邮件过滤很激进ScanNet的自动回复邮件很可能被归类为垃圾邮件所以申请后一定要去垃圾邮件目录翻一下别等几天没消息就重复提交反而可能拖慢审核进度。5.2 下载中断、401认证失败和文件校验脚本下载最大的敌人是网络不稳定。官方脚本默认没有特别完善的断点续传机制但实测它能够跳过已存在的文件。如果你的下载中断了直接重新运行同一条命令即可已经下好的文件不会被重下。但前提是你没有启用--unzip参数这个参数会在下载后自动解压解压了一半的场景目录结构不完整重跑时可能误判为已完成这时候就需要删除对应文件夹重新下载非常痛苦。401错误是另一个高频问题。大部分情况是用户名或密码不对或者口令文件复制时混入了多余空格。我建议你把用户名和密码先用文本编辑器确认一遍再粘贴到命令行结合单引号包裹参数避免shell特殊字符干扰。另外脚本可能会从环境变量读取凭据如果你之前设置过相关环境变量记得排查一下。5.3 磁盘空间与文件数量这个坑比网络问题更隐蔽。ScanNet完整原始数据集的体积在1TB级别即使只下载训练集也是几百GB。很多人在申请时没考虑磁盘下载到一半才发现空间不足。这里我强烈建议先执行一次小范围的下载再决定全量策略。如果只是做分割任务每个场景的labeled数据很小几十GB就能扛住但如果做渲染或者SLAM每个场景的.sens都可能超过2GB1513个场景全下完全是另一个量级。在开始全量下载前用du -sh或Windows资源管理器看好剩余容量然后按场景数量估算总大小这个习惯能避免最尴尬的中途失败。文件数量也是一个容易被低估的点。全量下载会产生数十万个文件在Windows上如果路径过长或者文件名包含特殊字符解压或读取阶段都会报错。我实测发现Windows对超长路径支持不好建议在Linux或macOS环境下组织数据集。如果只能用Windows至少把数据集放在磁盘根目录不要嵌在深层文件夹里。另外部分学术机构的共享存储对文件数量有限制大量小文件会影响整个集群的inode使用这类问题等你拷数据到服务器时才会发现最好提前规划好只保留需要的子集。5.4 杀毒软件、权限和小文件卡顿杀毒软件拦截下载脚本的情况也有尤其某些安全软件会把批量下载行为判定为异常流量。如果你发现脚本卡在某个场景反复重试先看一眼杀毒软件的日志。还有一种情况是场景文件夹在解压过程中被安全软件占用导致脚本误以为该场景已存在直接跳过了。解决思路是给数据集目录加上白名单或者至少在下载期间暂时关闭实时扫描。5.5 常见问题速查现象快速排查思路解决办法申请邮件迟迟不来是否用了个人邮箱垃圾箱是否被拦截换机构邮箱重新提交检查垃圾邮件目录脚本提示401用户名、密码、key是否复制完整用编辑器确认凭据用单引号包裹参数下载一半停止网络不稳定重跑同一条命令避免使用--unzip参数场景文件夹0字节或内容不全上一次解压中断被误判删除该场景文件夹重新下载.sens无法读取未使用SensReader从官方仓库获取读取脚本.ply加载后顶点为空ply版本或库不兼容使用新版本open3d或pymeshlab加载标签ID和官方不一致未加载类别映射文件确认使用scanNet官方labels映射6. 快速验证数据集是否可用的三个小动作6.1 检查文件大小和文件数量下载完成后第一件事不是直接训练而是理性抽查。用下面的命令统计每个场景的文件大小du -sh scans/*你可以对比几个场景的大小如果同一个类型的数据大小差异巨大就要注意是否有文件缺失。find统计文件数量也是一个好办法find scans/scene0000_00 -type f | wc -l一只场景正常应该有数百个文件如果只有几十个说明下载不完整。另外.sens文件的大小通常在百MB到几GB之间明显过小可能意味着该场景被服务器端处理过或者文件损坏。6.2 用SensReader导出并查看一帧数据这是最直接的验证。选一个已下载的场景运行SensReader导出彩色图、深度图和位姿。导出成功后用Python加载一张深度图查看数值分布import cv2 import numpy as np depth cv2.imread(depth/000000.png, cv2.IMREAD_UNCHANGED) print(depth.shape, depth.dtype, depth.min(), depth.max())如果深度图最大值明显异常或者全是零说明这个场景的数据不完整。如果一切正常你就能确认.sens文件没有被网络传输损坏。6.3 加载带标签的网格并渲染一帧对于语义分割任务还需要验证标签网格是否可用import open3d as o3d import numpy as np mesh o3d.io.read_triangle_mesh(scene0000_00_vh_clean_2.labels.ply) vertices np.asarray(mesh.vertices) labels mesh.vertex_colors # 注意有些版本读出来的是颜色实际label要看属性名 print(vertices.shape, labels.shape)注意一个常见混淆点_vh_clean_2.labels.ply的标签信息在不同读取库里的表现方式不同。用Open3D读出来时默认会当成三角网格标签可能不在vertex_colors中而是存储为顶点标量属性。如果发现读出来全是黑色或者颜色不对改用pymeshlab或者直接用代码解析ply顶点属性把名为label的字段读出来。我个人在实际操作中最快的验证方式是写一个小脚本统计一个场景里标签类别的数量是否在合理范围内。跑到这一步就说明数据集已经真正落到了硬盘上并且结构完整可以进入后续训练或渲染流程了。最后再分享一个经验ScanNet虽然下载麻烦但这份数据本身的组织逻辑很清晰花一次功夫把流程跑通、脚本参数摸透之后无论是分享给实验室的同学还是迁移到新机器都会很省心。建议你把下载脚本、SensReader、类别映射这三个工具一起打包存档它们是你用好ScanNet的起点。
