企业官网建设流程全解析

• 数据集
• 计算机视觉
• 3D视觉

ScanNet 是一个包含 250 万帧视图、覆盖 1500 个以上室内场景的 RGB-D 视频数据集，为每个场景提供 3D 相机位姿、表面网格重建和实例级语义标注。本文以仓库根目录的 README.md 为主体，逐条展开其数据获取方式、场景目录组织、各类文件的数据格式定义，并结合仓库内 SensReader、Segmentator、CameraParameterEstimation、BenchmarkScripts 等模块的源码与配置，说明如何真正读懂和使用 ScanNet 数据。读完本文，你将掌握.sens压缩帧流的解析方式、*.segs.json与*.aggregation.json标注结构的完整含义、从上传到标注的完整处理管线，以及三个基准任务的训练/评测入口。

1. 数据集定位与数据获取

根据 README.md 的界定，ScanNet 的定位是“an RGB-D video dataset containing 2.5 million views in more than 1500 scans, annotated with 3D camera poses, surface reconstructions, and instance-level semantic segmentations”，即：

• 250 万帧视图，来自1500 个以上的 RGB-D 扫描序列；
• 每个场景同时附带3D 相机位姿、表面重建网格、实例级语义分割三类标注。

数据获取走申请流程：需用机构邮箱填写 ScanNet Terms of Use 协议，并发送至官方邮箱申请；README 明确提示，若一周内未收到回复，大概率是邮件被退回（bouncing），请勿向 noreply 邮件回复——回复不会被看到。数据版本更新则以官方 changelog 为准。数据本身受 Terms of Use 约束，而仓库代码按 MIT 协议发布（见 LICENSE）。

2. 场景目录组织（Data Organization）

ScanNet 数据按 RGB-D 序列（sequence）组织，每个序列存放在以scene<spaceId>_<scanId>（即scene%04d_%02d）命名的目录下，其中 spaceId 从 0 开始，对应一个唯一的位置（location）。原始采集数据、相机位姿、表面网格重建与标注元数据都集中存放在该目录中。README 给出的完整目录结构如下（<scanId>为场景目录名）：

<scanId> |-- <scanId>.sens RGB-D sensor stream containing color frames, depth frames, camera poses and other data |-- <scanId>_vh_clean.ply High quality reconstructed mesh |-- <scanId>_vh_clean_2.ply Cleaned and decimated mesh for semantic annotations |-- <scanId>_vh_clean_2.0.010000.segs.json Over-segmentation of annotation mesh |-- <scanId>.aggregation.json, <scanId>_vh_clean.aggregation.json Aggregated instance-level semantic annotations on lo-res, hi-res meshes, respectively |-- <scanId>_vh_clean_2.0.010000.segs.json, <scanId>_vh_clean.segs.json Over-segmentation of lo-res, hi-res meshes, respectively (referenced by aggregated semantic annotations) |-- <scanId>_vh_clean_2.labels.ply Visualization of aggregated semantic segmentation; colored by nyu40 labels (see img/legend; ply property 'label' denotes the nyu40 label id) |-- <scanId>_2d-label.zip Raw 2d projections of aggregated annotation labels as 16-bit pngs with ScanNet label ids |-- <scanId>_2d-instance.zip Raw 2d projections of aggregated annotation instances as 8-bit pngs |-- <scanId>_2d-label-filt.zip Filtered 2d projections of aggregated annotation labels as 16-bit pngs with ScanNet label ids |-- <scanId>_2d-instance-filt.zip Filtered 2d projections of aggregated annotation instances as 8-bit pngs

对照该结构可以归纳出三类文件族：

1. 原始传感器流：<scanId>.sens，一个文件即包含全部彩色帧、深度帧、相机位姿等数据；
2. 多分辨率网格族：_vh_clean.ply（高质量重建网格）、_vh_clean_2.ply（清理、减面后的标注用网格），以及与之对应的两级*.segs.json过分割文件和两级*.aggregation.json实例标注文件；
3. 标注可视化与 2D 投影族：_vh_clean_2.labels.ply是按 NYU40 标签着色的可视化网格（ply属性label存 nyu40 标签 id，配色见 img/legend.png），*_2d-label.zip/*_2d-instance.zip（及其-filt过滤版）则是 3D 聚合标注沿相机轨迹投影到每一帧的 2D 标注。

其中“低分辨率/高分辨率”（lo-res / hi-res）的区分在 README 中表述为：<scanId>.aggregation.json与<scanId>_vh_clean.aggregation.json分别是低、高分辨率网格上的聚合实例标注，各自引用同名网格的*.segs.json过分割结果。

3. 核心数据格式逐一定义

3.1 重建网格文件（*.ply）

README 的定义只有一句：二进制 PLY 格式网格，+Z 轴朝上（upright orientation）。这一约定与管线中的对齐步骤一致——Alignment 工具“将扫描对齐到 z-up，并尽量把墙面转到 x-y 平面”（见 Alignment/README.md），因此读入网格后可直接假设 Z 为竖直方向。

3.2 RGB-D 传感器流（*.sens）

.sens是压缩二进制格式，每帧包含彩色、深度、相机位姿及其他数据。仓库提供了 C++ 工具包 SensReader 与一个极简 Python 导出器 SensReader/python。

SensReader/README.md 直接给出了SensorData结构（对应 SensReader/c++/src/sensorData.h）：

struct SensorData { unsigned int m_versionNumber; std::string m_sensorName; CalibrationData m_calibrationColor; //4x4 intrinsic matrix CalibrationData m_calibrationDepth; //4x4 intrinsic matrix COMPRESSION_TYPE_COLOR m_colorCompressionType; //scannet color frames are typically jpeg encoded COMPRESSION_TYPE_DEPTH m_depthCompressionType; //scannet depth frames are typically zLib encoded unsigned int m_colorWidth, m_colorHeight; unsigned int m_depthWidth, m_depthHeight; float m_depthShift; //conversion from float[m] to ushort (typically 1000.0f) std::vector<RGBDFrame> m_frames; // <= Main data (contains timestamps and rigid transforms) std::vector<IMUFrame> m_IMUFrames; }

读取示例（C++）：

SensorData sd("sensfile.sens"); unsigned int frame = 0; vec3uc* color = sd.decompressColorAlloc(frame); // note: must be freed after use unsigned short* depth = sd.decompressDepthAlloc(frame); // note: must be freed after use const mat4f cameraToWorld = sd.m_frames[frame].getCameraToWorld(); std::free(color); std::free(depth); // if using mlib, can save a frame to a point cloud with: sd.saveToPointCloud("frame" + std::to_string(frame) + ".ply", frame);

从 Python 端源码 SensReader/python/SensorData.py 可以印证二进制布局的关键细节：

• 文件头先读出version，且解析器只支持 version 4（self.version = 4，不匹配即assert失败）；
• 文件头依次存传感器名、color/depth 各自的 4x4 内参与外参矩阵、压缩类型、color/depth 分辨率、depth_shift和帧数；
• 深度值从“米制 float”换算为ushort的系数depth_shift通常为 1000，即导出 PNG 时 1.0 m 存为 1000（README 的 python/README.md 也写明 “depth shift 1000”）；
• 每帧结构RGBDFrame包含camera_to_world（4x4，相机到世界）、color/depth 时间戳与压缩后的帧数据；深度默认zlib_ushort压缩、彩色默认jpeg编码（COMPRESSION_TYPE_COLOR/COMPRESSION_TYPE_DEPTH字典中分别列有 raw/png/jpeg 与 raw/zlib/occi 三类）。

Python 导出器的用法（注意其 README 声明在 Python 2.7 下开发与测试，代码中也使用了print语句与np.fromstring，迁移到 Python 3 需自行修改）：

python reader.py --filename [.sens file to export data from] --output_path [output directory to export data to] Options: --export_depth_images: export all depth frames as 16-bit pngs (depth shift 1000) --export_color_images: export all color frames as 8-bit rgb jpgs --export_poses: export all camera poses (4x4 matrix, camera to world) --export_intrinsics: export camera intrinsics (4x4 matrix)

参数定义与目录约定见 SensReader/python/reader.py：depth 写入<output_path>/depth、color 写入color/、位姿写入pose/、内参写入intrinsic/，帧文件名以帧序号str(f) + '.png'（或.jpg/.txt）命名；导出函数还支持frame_skip抽帧与image_size缩放（深度缩放用最近邻插值）。

3.3 网格分割文件（*.segs.json）

这是过分割（over-segmentation）结果，也是语义标注的“基元单元”。README 给出的完整格式：

{ "params": { // segmentation parameters "kThresh": "0.0001", "segMinVerts": "20", "minPoints": "750", "maxPoints": "30000", "thinThresh": "0.05", "flatThresh": "0.001", "minLength": "0.02", "maxLength": "1" }, "sceneId": "...", // id of segmented scene "segIndices": [1,1,1,1,3,3,15,15,15,15], // per-vertex index of mesh segment }

核心字段是segIndices：一个与网格顶点一一对应的数组，每个元素是该顶点所属的 segment 编号；params记录生成该分割时使用的算法参数（不同网格/不同参数会得到不同的*.segs.json，如_vh_clean_2.0.010000.segs.json文件名中内嵌了kThresh=0.01的取值）。

3.4 聚合语义标注文件（*.aggregation.json）

aggregation.json把若干过分割单元聚合成一个“实例（instance）”，并赋予类别标签。README 的完整格式：

{ "sceneId": "...", // id of annotated scene "appId": "...", // id + version of the tool used to create the annotation "segGroups": [ { "id": 0, "objectId": 0, "segments": [1,4,3], "label": "couch" }, ], "segmentsFile": "..." // id of the *.segs.json segmentation file referenced }

字段含义可结合工具端源码印证：AnnotationTools/common/Aggregation.h 中的loadFromJSONFile会解析sceneId、appId以及segGroups里每个 group 的id（objectId）、label与segments（segment id 列表），并提供getSegIdToAggregatedSegId()把每个 segment 反查回聚合单元。segmentsFile指向该标注所引用的*.segs.json——即“实例 = 一组 segment 的并集 + 类别标签”。

README 同时给出了解析示例的入口：BenchmarkScripts/util_3d.py 演示如何从*.segs.json、*.aggregation.json与*_vh_clean_2.ply中解析语义实例信息；3D 语义分割可视化示例见 BenchmarkScripts/3d_helpers/visualize_labels_on_mesh.py。后者要求预测标签 txt 的行数必须与_vh_clean_2.ply顶点数一致，再按 NYU40 调色板写回顶点颜色输出新的.ply。

3.5 2D 标注投影（*_2d-label.zip/*_2d-instance.zip/-filt版）

README 的定义是：把该扫描的 3D 聚合标注按计算出的相机轨迹投影到其 RGB-D 各帧。仓库 BenchmarkScripts/README.md 进一步区分了两种版本：

• raw 版（*_2d-label.zip、*_2d-instance.zip）：直接投影产物，label 图为带 ScanNet 标签 id 的 16-bit png，instance 图为 8-bit png；
• filt 版（*_2d-label-filt.zip、*_2d-instance-filt.zip）：经过基本图像滤波的投影结果，对应 AnnotationTools/Readme.md 中Filter2dAnnotations工具的职责——“对ProjectAnnotations的原始投影做基础图像滤波”。

生成链条在仓库中有完整对应：AnnotationTools/ProjectAnnotations 负责“把 3D 网格标注沿相机轨迹投影进 2D 帧”（参数见 AnnotationTools/ProjectAnnotations/zParametersScan.txt），Filter2dAnnotations（依赖 CUDA 8.0）负责后续滤波。

2d_helpers 提供了把 ScanNet 标签图转换成 NYU40 40 类 8-bit png、以及把 instance 图转换成[NYUv2 40-label]*1000 + instance_id编码的 16-bit png 的脚本；BenchmarkScripts/README.md 还说明数据发布包中已附带约 25000 帧的预处理好子集，并提示评测依赖scannetv2-labels.combined.tsv标签映射文件。

4. 从上传到标注：数据管线各阶段

README 正文未展开管线细节，但仓库 Server/README.md 与阶段配置文件 Server/config/scan_stages.json 把“场景目录里那些文件是怎么来的”交代得很清楚。scan_stages.json定义了如下阶段序列（${id}即场景 id）：

这段配置同时解释了若干“为什么”：目录里为什么有_vh_clean / _1 / _2三级网格（decimate的三个子步）、为什么存在多个kThresh的segs.json（segment阶段用 0.0001、0.001、0.01 三档参数）、为什么annotation阶段固定引用0.010000这一档过分割。

服务端的部署与运行方式（来自 Server/README.md）：

• 上传服务：install_deps.sh安装依赖，start_upload_server.sh启动（入口 Server/upload.py，经 Server/wsgi.py 包装），flask + gunicorn、10 worker、8000 端口，文件先入tmp再入 staging 目录（在 Ubuntu 14.04 上测试）；
• 扫描处理：需要带高端 GPU 的 Windows 机器（README 记录为 Windows 10 + GTX Titan X 12GB 的测试配置），并依赖 MeshLab、Mitsuba、ImageMagick/pngquant/optipng；入口为 Server/start_process_server.py（内部由 Server/process.py 启动 5000 端口的单请求处理服务），主处理脚本是 Server/scan_processor.py，渲染预览用 Server/mts_render.py，缩略图由thumbnail.sh生成；
• 索引与统计：monitor.py（5001 端口监控/触发索引）、Server/index.py 生成 csv 索引、scripts/index_scannet.sh索引 staging 与已检查场景并更新 WebUI 数据库；compute_annotation_stats.py、compute_timings.py与scripts/combine_stats.py负责标注统计与处理耗时统计。

其他配置文件：Server/config/scannet.json（供 Scene Toolkit 查看器使用的元数据）、Server/config/upload.ini（上传服务配置）。

5. 配套工具链逐一说明

5.1 SensReader（.sens解析）

见第 3.2 节。C++ 工具包位于 SensReader/c++，含Makefile（Linux）与sens.sln/sens.vcxproj（Windows 工程）。README 提示的调用方式是先SensorData sd("file.sens")加载，再按需decompressColorAlloc/decompressDepthAlloc/getCameraToWorld，用毕手动free。

5.2 CameraParameterEstimation（相机标定）

CameraParameterEstimation/README.md 说明其面向 Structure Sensor 结构光深度相机，做两类标定：

1. Depth-To-Color 标定：输入 20–30 组不同角度/距离观测标定网格的 rgb + 红外图像对；输出两相机各自的内参以及把深度对齐到彩色的刚体变换。该步骤依赖 Matlab 的 Single Camera Calibration App；
2. 深度畸变标定：Structure Sensor 深度图畸变严重且随距离加重；输入一段约 400 帧、拍摄贴有标定网格的大平墙的 RGB-D 视频，输出查表表（LUT），仓库附带一个把估计好的标定应用到 16-bit 深度 png 的 C++ 程序。

仓库内 CameraParameterEstimation/scripts 提供estimate_rigid_transform.m、estimate_pairwise_transform.m、estimate_depth_distortion_plane_poses.m、export_calibration_info.m、export_color_and_ir_params.m等 Matlab 脚本，CameraParameterEstimation/apps/calibrate_depth/src 是应用标定校正深度的 C++ 程序，另有calibration_explorer应用用于验证标定结果。README 中它承担的角色是：“估计相机参数与深度去畸变，生成被管线服务器用于深度去畸变的传感器标定文件”——即上文scan_stages.json中calibrate阶段的上游。

5.3 Segmentator（网格过分割）

Segmentator/README.md 说明该工具在“计算出的网格法向量”上执行 Felzenswalb & Huttenlocher 的 Graph Based Image Segmentation 算法：

./segmentator input.ply [kThresh=0.01] [segMinVerts=20]

• 第 1 个参数：输入 PLY 网格路径；
• 第 2 个参数（可选）：聚类阈值kThresh，值越大生成的 segment 越大；
• 第 3 个参数（可选）：每个 segment 的最少顶点数segMinVerts，不足的小簇会被并入更大的 segment。

构建方式为make（或用 cmake 生成 makefile），产物为segmentator可执行文件（见 Segmentator/Makefile、Segmentator/CMakeLists.txt）。从源码 Segmentator/segmentator.cpp 可印证两处关键实现：边权用平滑顶点法向量夹角计算（w = 1 - dot(n1,n2)，凸面区域会平方进一步弱化差异），分割后按segMinVerts合并小段；输出文件名形如<输入名>.<kThresh>.segs.json，writeToJSON写入的正是第 3.3 节的params+sceneId+segIndices结构。这解释了管线为何能产出_vh_clean_2.0.010000.segs.json这类带参数值命名的文件。

5.4 Alignment（z-up 对齐）

Alignment/README.md：把扫描变换到 z-up 对齐，并尽量把墙面对齐到 x-y 平面；在 VS2013 下开发，依赖 DirectX SDK June 2010 与 external/mLib 研究库。运行方式：

alignment.exe [path to directory of scan to align]

5.5 Calibrate（sens 文件标定转换）

Calibrate/README.md：把未标定的.sens转换为已标定的.sens，校正 color/depth 畸变并把深度对齐到彩色空间，使用 CameraParameterEstimation 产出的设备标定输出。运行方式：

calibrate.exe [input sens file] [output sens file] [device calibration map file (from CameraParameterEstimation)] [directory of device calibration map files]

即它是scan_stages.json中calibrate阶段的具体执行工具。

5.6 ScannerApp（iPad 采集端）与 Server / WebUI

• ScannerApp：为“iPad + Structure.io 传感器”设计的采集应用，目标是便捷地采集 RGB-D 序列；
• Server：接收 iPad 上传 RGB-D 序列的服务器代码（组件划分见第 4 节）；
• WebUI：基于 Web 的数据管理界面，用于概览可用扫描数据、控制处理与标注管线。

三者合起来即 README 中“Scanner iPad App / Scanner Data Server / Data Management UI”三个条目的落点。

5.7 语义标注工具（SSTK）

README 指明：语义标注 Web 界面的代码与文档随 SSTK 则包含标注结果的投影（ProjectAnnotations）与 2D 滤波（Filter2dAnnotations）工具，产出第 3.5 节所述的四个 2D 投影 zip 文件；AnnotationTools/common 下的Aggregation.h/Segmentation.h是*.aggregation.json/*.segs.json的 C++ 读写实现。

6. BundleFusion 重建代码与引用

README 明确：ScanNet 使用 BundleFusion 完成重建（即第 4 节recons阶段），引用原文如下：

@article{dai2017bundlefusion, title={BundleFusion: Real-time Globally Consistent 3D Reconstruction using On-the-fly Surface Re-integration}, author={Dai, Angela and Nie{\ss}ner, Matthias and Zoll{\"o}fer, Michael and Izadi, Shahram and Theobalt, Christian}, journal={ACM Transactions on Graphics 2017 (TOG)}, year={2017} }

7. 基准任务（Benchmark Tasks）

README 提供三类场景理解基准的代码：3D 目标分类、3D 目标检索、语义体素标注；train/test 划分在 Tasks/Benchmark（含scannetv1_train/val/test.txt、scannetv2_train/val/test.txt等扫描列表），标签映射与预训练模型随 ScanNet 数据发布下载。Tasks/README.md 给出更具体的用法：

• 环境：训练代码基于 Torch7（含cudnn、cunn、hdf5、xlua包）；数据解压到各任务torch目录下的data文件夹（例如 3D 分类把obj_classification.zip解压到Tasks/ObjectClassification/torch/data）。

• 3D Object Classification：对部分扫描目标做 30x30x30 体素化分类，采用 3D CNN 框架并增加按扫描轨迹编码已知/未知体素的数据通道；类别见 Tasks/Benchmark/classes_ObjClassification-ShapeNetCore55.txt（ShapeNetCore55 标签 id）：

  th train_partial.lua --train_data [path to train h5 file list] --test_data [path to test h5 file list]

• 3D Object Retrieval：基于分类模型特征做最近邻检索，先提取特征、再算最近邻：

  th generate_feat.lua --model [model] --h5_list_path [path to h5 file list to generate features for] --partial_data [use this flag if partial data] --file_label_file [assocation from h5 data to names and labels] --output_file [output file (features)] --output_name_file [output file (names)] --classes_file [optional, defines set of classes to consider] python nearest_neighbor.py --query_feats [feature file from generate_feat] --database_feats [feature file from generate_feat] --database_models [names corresponding to database feats] --output [output file]

• Semantic Voxel Labeling：对扫描表面体素逐列预测类别标签，每列 1x1x62 的中心体素利用 31x31x62 邻域信息；类别见 Tasks/Benchmark/classes_SemVoxLabel-nyu40id.txt（nyu40 标签 id）：

  th train.lua --train_data [path to train h5 file list] --test_data [path to test h5 file list]

评测脚本位于 BenchmarkScripts：2D/3D 语义标签与实例分割评测改编自 CityScapes 评测，分别在 BenchmarkScripts/2d_evaluation 与 BenchmarkScripts/3d_evaluation；场景类型分类评测在 BenchmarkScripts/scene_type_evaluation（其数据侧脚本 BenchmarkScripts/scene_type_helpers/get_scene_type_for_scan.py 可从<scanId>.txt取场景类型 id）。脚本基于 Python 2.7 开发与测试。

7.1 标签映射文件（Labels）

README 的 Labels 一节说明：任务数据发布包中的标签映射文件scannet-labels.combined.tsv把 ScanNet 标注中的标签（id）映射到 NYUv2、ModelNet、ShapeNet 的物体类别集合与 WordNet synsets；可随任务数据（--task_data）或单独（--label_map）下载。从评测脚本源码看，标签与实例 id 的编码约定是instance id = label_id * 1000 + 实例序号——BenchmarkScripts/util_3d.py 中Instance.get_label_id即int(instance_id // 1000)。

8. 引用、帮助与许可证

使用 ScanNet 数据或代码请引用：

@inproceedings{dai2017scannet, title={ScanNet: Richly-annotated 3D Reconstructions of Indoor Scenes}, author={Dai, Angela and Chang, Angel X. and Savva, Manolis and Halber, Maciej and Funkhouser, Thomas and Nie{\ss}ner, Matthias}, booktitle = {Proc. Computer Vision and Pattern Recognition (CVPR), IEEE}, year = {2017} }

问题联系：scannet@googlegroups.com。许可证方面（README 与 LICENSE）：数据按 ScanNet Terms of Use 发布，代码按 MIT 协议发布。

9. 小结：从目录到代码的快速核对清单

• 拿到一个sceneXXXX_XX目录后：先看.sens（原始流）→_vh_clean_2.ply（标注网格）→*_vh_clean_2.0.010000.segs.json+.aggregation.json（过分割 + 实例标注）→_2d-label-filt.zip/_2d-instance-filt.zip（2D 评测标签）。
• 解析.sens：用 SensReader/python/reader.py（Python 2.7）或 SensReader/c++；记住 depth shift 通常为 1000、位姿是 camera-to-world。
• 重建过分割：./segmentator input.ply [kThresh=0.01] [segMinVerts=20]，输出与数据发布格式一致的*.segs.json。
• 理解文件从何而来：对照 Server/config/scan_stages.json 的 11 个阶段（upload → convert → calibrate → recons → clean → improve → decimate → freespace → segment → render/thumbnail → annotation）。
• 跑基准：划分文件在 Tasks/Benchmark，工具在 Tasks 与 BenchmarkScripts，标签映射*.combined.tsv随数据发布包获取。

按上述清单，可以完整复现从原始.sens到 2D/3D 评测标签的数据使用链路，这也是 ScanNet 仓库各模块之间的真实分工。

• 数据集
• 计算机视觉
• 3D视觉