ScanNet Server:扫描数据上传、GPU 处理与索引流水线服务全解
ScanNet Server:扫描数据上传、GPU 处理与索引流水线服务全解
Server/ 目录是 ScanNet 数据采集基础设施的核心:它把 iPad 扫描器采集到的原始数据(.h264、.depth、.imu、.txt、.camera)经上传、三维重建、网格清理、渲染缩略图到最终建库索引的完整链路串联起来。读完本篇,你将理解上传服务、处理服务、索引监控服务三类组件的职责边界与端口约定,掌握 scan_stages.json 中 12 个流水线阶段与源码的对应关系,并能在自己的环境中按 Server/README.md 的说明部署和运行这套数据服务。
一、系统概览:三类组件的分工
根据 Server/README.md 的说明,ScanNet 数据服务由以下组件构成:
- Upload process(上传进程):供 iPad 端上传扫描文件并触发后续处理。为保证扫描可被自动处理,扫描目录需要空间充足且对处理进程可见,官方在 Ubuntu 14.04 的 Linux 机器上完成过测试;
- Scan processing scripts(处理脚本):需要配备高端 GPU 的 Windows 机器(官方测试环境为 Windows 10 + GTX Titan X,12GB 显存);
- Indexing scripts(索引脚本):遍历扫描目录、汇总扫描信息并生成索引。
此外还有两组辅助脚本:统计计算脚本(compute_annotation_stats.py、compute_timings.py、scripts/combine_stats.py)与配置文件(scannet.json、scan_stages.json、upload.ini)。
从目录结构看,各组件的入口文件如下:
| 组件 | 入口/脚本 | 运行方式 | 端口 |
|---|---|---|---|
| 上传服务 | upload.py / wsgi.py | ./start_upload_server.sh(gunicorn) |
8000 |
| 处理服务 | process.py / scan_processor.py | ./start_process_server.sh |
5000 |
| 索引监控服务 | monitor.py / index.py | python monitor.py |
5001 |
| 批量索引 | scripts/index_scannet.sh | 手动/脚本调用 | — |
需要注意:README 中写作 start_process_server.py,但仓库中实际文件是 start_process_server.sh,其内容仅为 python process.py。
二、上传服务:从 iPad 到 staging 目录
2.1 接收的文件与目录流转
上传脚本接收 iPad 发来的五类文件——.h264(视频)、.depth(深度)、.imu(惯性测量)、.txt(元数据)、.camera(相机标定),先写入 tmp 临时目录,再移动到 staging 暂存区,等待后续处理。这一白名单在 upload.py 中定义:
ALLOWED_EXTENSIONS = set(['h264', 'depth', 'imu', 'txt', 'camera'])
当某扫描目录下的文件数量达到五类扩展名数量时(scan_done_uploading 函数),即认为该扫描上传完整。
2.2 部署与启动
- install_deps.sh:安装上传服务所需 Python 依赖,即
flask、gunicorn、paste、pastedeploy、gevent、requests、pytimeparse; - start_upload_server.sh:启动入口,实际执行
gunicorn --paste config/upload.ini,主入口即 upload.py; - wsgi.py:
upload.py的 WSGI 包装器,可直接app.run()调试。
config/upload.ini 是 gunicorn 的 PasteDeploy 配置,关键参数与 README 所述“10 个 worker 线程、8000 端口”一一对应:
[server:main]
use = egg:gunicorn#main
daemon = False
host = 0.0.0.0
port = 8000
workers = 10
backlog = 1024
loglevel = debug
# 6 hours
timeout = 21600
worker_class = gevent
[app:main]
use = call:upload:get_app
其中 worker_class = gevent 配合 10 个 worker 支撑并发大文件写入;timeout = 21600(6 小时)的超时设置正是为了容纳单场扫描动辄数百 MB 的长时间上传。日志配置为 FileHandler 写入 logs/upload.log,root logger 级别 INFO、gunicorn logger 级别 DEBUG。
2.3 核心 HTTP 端点
upload.py 基于 Flask 实现了四个端点:
/upload(PUT/POST):从请求头FILE_NAME取得文件名(代码注释标明“暂时同时接受 PUT 和 POST,PUT 更合适”),经secure_filename清洗后写入tmp/,长度校验通过后shutil.move到staging/<basename>/。若文件已存在则丢弃请求体并直接返回成功(用于断点重传去重)。流式写入函数receive_file以 16KB 为块读取wsgi.input,每 4MB 记录一次上传百分比,收到Content-Range头时会记录分片接收告警。/verify?filename=&checksum=:对 staging 中文件计算 MD5(util.md5)并与客户端提供的校验和比对,不匹配返回 400;/received、/received/<path>:返回 staging 目录的 HTML 文件树,便于人工核对;/process/<scanid>:启动线程回调处理服务的处理触发 URL。
上传完成后的自动化触发逻辑在 upload_file 中:当 scan_done_uploading 判定扫描收齐,且 auto_process_scan 为真时(可由 URL 参数 ?process=true/1 覆盖,默认取 config.py 中 AUTOPROCESS = False),并行启动两个线程——preprocess(触发视频转码 + 索引)与 trigger_processing(调用处理服务)。这三个下游 URL 均由 config.DATA_SERVER(默认 http://localhost:3030,指向 WebUI 后端)拼接:
INDEX_URL = cfg.DATA_SERVER + '/scans/index/'
CONVERT_VIDEO_URL = cfg.DATA_SERVER + '/scans/monitor/convert-video/'
SCAN_PROCESS_TRIGGER_URL = cfg.DATA_SERVER + '/scans/process/'
文件头注释里给出了模拟 iPad 上传的 curl 命令,可直接复现:
curl -v -X PUT -H "FILE_NAME: test.h264" --data-binary "@<path_to_some_file>" \
-H "Content-Type: application/ipad_scanner_data" "http://localhost:8000/upload"
curl -v "localhost:8000/verify?filename=<base_file_name>&checksum=<check_sum>"
三、扫描处理服务:10 级 GPU 流水线
3.1 处理服务的定位
处理服务要求 Windows 机器 + 高端 GPU(Titan X 12GB 测试),并依赖三类第三方工具:
- MeshLab:网格简化与清理(
meshlabserver); - Mitsuba 渲染器:为每个扫描生成预览图(mts_render.py);
- ImageMagick、pngquant、optipng:缩略图生成与 PNG 压缩(thumbnail.sh)。
config.py 集中声明了各二进制的系统路径(MESHLAB_BIN、FREESPACE_BIN、IMG_MAGIC_DIR 等),README 也提醒“编辑 scan_processor.py 查看/更改工具与应用的路径”。
3.2 处理服务器(process.py)
process.py 是一个极简 Flask 服务,app.run(host='0.0.0.0', port=5000, debug=True) 监听 5000 端口,一次只处理一个请求——处理完成前会阻塞。其核心路由 /process/<dirname> 支持如下查询参数:
from:从流水线的哪个阶段开始(与 scan_processor.py 的--from语义一致);actions:显式指定要执行的动作列表;overwrite:覆盖已处理结果。为防重复请求,overwrite 时必须附带毫秒级 UTCtimestamp,服务会用util.checkLastModifiedNewer校验目录自请求发出后是否有变更,若有则返回 400 要求重新提交;- 无
from/actions参数时默认{'all': True},执行全部 10 个阶段。
GPU 资源由模块级 GPU_LOCK = Lock() 串行保护——这是“一次只处理一个请求”设计在代码层面的体现。处理完成后还会通过 trigger_indexing 回调 WebUI 的索引端点刷新状态。
3.3 流水线本体(scan_processor.py)
scan_processor.py 定义了 10 个阶段,与 config/scan_stages.json 中的命名一一对应:
PROCESSES = ['convert', 'calibrate', 'recons', 'clean', 'improve',
'decimate', 'freespace', 'segment', 'render', 'thumbnail']
每个阶段在 process_scan_dir_basic 中对应一次外部程序调用,关键链路为:
- convert:
converter.exe把 iPad 原始文件转为.uncalibrated.sens; - calibrate:
calibrate.exe结合设备库(devices.csv)输出.sens; - recons:
FriedLiver.exe(带zParametersScanNet.txt与zParametersBundlingScanNet.txt参数,见 tools/recons/)重建出.ply; - clean(2 个子步骤):MeshLab 执行
cleanLoRes.mlx清洗,再alignment.exe对齐到 up/x/y 方向(对应 tools/meshclean/ 中的.mlx脚本); - improve:
DepthSensing.exe(VoxelHashing)生成高分辨率_vh.ply; - decimate(3 个子步骤):MeshLab 依次执行
clean.mlx与两次simplify.mlx,得到_vh_clean.ply、_vh_clean_1.ply、_vh_clean_2.ply; - freespace:
FreeSpace.exe由.sens计算占用体素网格.grid; - segment:
Segmentator.exe(对应 Segmentator/ 工程)对降采样网格输出三档分辨率(10cm/100cm/1m)的segs.json分割文件; - render:
python mts_render.py <mesh>用 Mitsuba 渲染预览 PNG; - thumbnail:Git Bash 调用
scripts/thumbnail.sh -v,借助 ImageMagick/pngquant/optipng 生成缩略图。
每一步都会检查前一阶段的输出文件是否存在(如 no ply (recons failed)),缺失即中止并记录日志;全部日志追加到该扫描目录下的 process.log,供后续计时统计使用。
CLI 直接调用时的参数(main 函数中定义):
-i/--input 输入目录或目录清单文件(必填;为文件时逐行读取目录列表)
-b/--batch 批量处理输入目录下的所有子目录
--from 起始阶段(choices 为上述 10 个阶段,默认 convert)
--action 可重复,指定只执行某些动作
--overwrite 覆盖已存在的产物
--novh 去掉 _vh 后缀(跳过高分辨率重建路径)
--test 只打印命令不实际执行
3.4 渲染与缩略图细节
mts_render.py 依赖 MITSUBA_DIR 环境变量(源码中硬编码指向 Python 2.7 扩展目录),基于 RenderQueue 按 CPU 核数注册 worker,相机位置由网格包围盒外接球自动计算。可调参数包括:--integrator(path/mlt/vpl/ao,默认 path)、--samples(每像素采样数,默认 16)、--width/--height(默认 640x480)、--exposure、--theta(方位角)、--bsphere_mult(默认 2.5,控制相机距离),以及 --render_turntable 开启转台渲染——此时按 --frames_per_degree(默认每 5° 一帧)渲染一圈序列帧,并用 ffmpeg 合成 30fps 的 mp4。
thumbnail.sh 把目录下所有非 *_thumb.png 的 PNG 缩放到默认 128x128,再经 pngquant 256 有损量化与 optipng -clobber 二次压缩;-d 关闭优化,--skip-done 跳过已生成缩略图的图片,工具路径可通过 CONVERT/PNGQUANT/OPTIPNG 环境变量覆盖——scan_processor.py 正是以此方式注入 ImageMagick 与压缩工具的绝对路径。
四、索引与监控服务:状态汇总与 WebUI 同步
4.1 monitor.py:5001 端口上的“调度台”
monitor.py 是监控与触发索引的 Web 服务入口,python monitor.py 启动后监听 5001 端口,参数包括 --stages(默认 config/scan_stages.json)与 --port(默认 5001)。它维护两把锁(INDEX_LOCK、CONVERT_VIDEO_LOCK)保证索引与视频转码互斥,路由包括:
/index/<dirname>:对单个扫描调用index.index(...)追加写入 staging 下的scan-net.csv,成功后 POST 结果到 WebUI(http://localhost:3030/scans/populate?group=staging&replace=true);/index:调用 scripts/index_scannet.sh 做全量索引(Windows 下经 Git Bash 执行);/convert-video/<dirname>:依次调用 scripts/h264_to_mp4.sh 与 scripts/h264_thumbnail.sh(均带--skip-done);/health:健康检查。
4.2 index.py:扫描元数据的抽取规则
index.py 把目录扫描成 CSV(或 JSON)索引,关键逻辑:
- 扫描判定(
has_scan):目录下存在非零大小的<id>.imu/.depth/.h264/.sens/.ply任一即视为扫描; - 元数据抽取(
extract_meta):读取processed.txt属性、<id>.txt元数据文件、process.log计时(经 compute_timings.py),从目录名中的2016-07-01_04-29-28模式解析出 ISO8601 的createdAt; - 阶段状态机(
check_stages):以 scan_stages.json 为蓝本,将${id}占位符替换为实际 id 后逐阶段核对输入/输出文件是否存在、checks字段(如recons要求valid=true、clean要求aligned=true)是否满足、输出相对输入是否过期(比较 mtime),最终在 meta 中写入每阶段ok/outdated状态与lastOkStage; - CSV 输出字段:
fullId, source, id, datasets, valid, aligned, hasScreenshot, hasThumbnail, hasCleaned, fileType, fileSize, sceneLabel, sceneName, sceneType, deviceId, deviceName, userName, numDepthFrames, numColorFrames, numIMUmeasurements, lastOkStage, createdAt, updatedAt, path。
命令行参数覆盖完整索引控制:-i 输入目录、-o 输出文件、-s 单条目模式、-a 追加(先读旧文件按 id 合并再整体写出)、--all 纳入未处理完成的扫描、--solr(Solr 索引 URL)、--datasets(默认 ScanNet)、--stages、--source(默认 scan,用于拼 fullId)、--format csv|json、--checkBasic(切换检查基础 ply 还是清理后 ply)。
4.3 index_scannet.sh:批量索引与 WebUI 落库
scripts/index_scannet.sh 把上述能力串成一次完整落库:
SCANNET_DIR=${1:-E:/share/data/scan-net/}
WEBUI=http://localhost:3030
- 分别对
scans/staging与scans/checked执行两次index.py:一次 CSV(scan-net.csv),一次--all --format json(scan-net.all.json); - 若存在
annotations/scannet.anns.stats.csv,用 scripts/combine_stats.py 将注释统计合并进 checked 的 CSV/JSON(先备份为.nostats文件再覆盖); - 两次
curl --data-binary把 JSON 全量推送给 WebUI:/scans/populate?group=staging|checked&replace=group。
五、统计计算脚本
- compute_annotation_stats.py:聚合注释统计(按 AnnotationTools/common/ 产出的
aggregation.json汇总); - compute_timings.py:从
process.log中 grep 出Time=... for ...行,用pytimeparse解析成各阶段耗时;getRecord对带子步骤的阶段(如clean1/clean2、decimate1..3,与scan_stages.json中substeps: 2/3对应)合并求和; - scripts/combine_stats.py:把统计列合并进索引文件,支持
--format csv|json。
这些耗时数据会经 index.py 写回索引的 totalProcessingSecs/totalProcessingTime 字段以及各阶段 secs/time 状态,使 WebUI 能展示每个扫描的处理进度与耗时。
六、配置文件解析
6.1 scan_stages.json:流水线进度追踪的单一事实来源
config/scan_stages.json 声明了 12 个阶段(比 scan_processor.py 的 10 个动作多出起点 upload 与终点 annotation),是索引状态机与进度追踪的依据:
| 阶段 | 输入 → 输出 | 备注 |
|---|---|---|
| upload | — → ${id}.h264/.txt/.depth/.imu |
optional,上传产物 |
| convert | 上述四件 → ${id}.uncalibrated.sens、${id}.sens |
outputCheck: any,任一产出即视为完成 |
| calibrate | .uncalibrated.sens → .sens |
标定 |
| recons | .sens → .ply |
checks: {valid: "true"} |
| clean | .ply → .ply |
substeps: 2;checks: {aligned: "true"} |
| improve | .sens → ${id}_vh.ply |
高分辨率重建 |
| decimate | _vh.ply → _vh_clean.ply、_1.ply、_2.ply |
substeps: 3 |
| freespace | .sens → ${id}.grid |
占用体素网格 |
| segment | _vh_clean_2.ply → 三档 segs.json(100/1000/10000 间隔) |
|
| render | _vh_clean_2.ply → _vh_clean_2.png |
Mitsuba 预览图 |
| thumbnail | PNG → ${id}_vh_clean_2_thumb.png |
|
| annotation | 1m 档 segs.json → ${id}.aggregation.json |
optional,人工注释聚合 |
index.py 的 convert_data 会把 ${id} 替换为实际扫描 id;monitor.py 通过 --stages 参数加载该文件后注入 app.config['stages'] 供索引调用。
6.2 scannet.json:Scene Toolkit 查看器的资产元数据
config/scannet.json 面向 Scene Toolkit 3D 查看器,声明如何从 staging 目录解析每个扫描的展示资源:
{
"source": "scan-staging",
"assetType": "model",
"rootPath": "<DATA_DIR>/scans/staging",
"screenShotPath": "${rootPath}/${path}/${id}_vh_clean_2.png",
"hasThumbnails": true,
"video": "${rootPath}/${path}/${id}.mp4",
"trajectory": "${rootPath}/${path}/${id}.traj.json",
"voxels-labeled": "<DATA_DIR>/voxelizations/vox/${id}.vox",
"formats": [{ "format": "ply", "path": "${rootPath}/${path}/${id}_vh_clean_2.ply",
"defaultUp": [0,0,1], "defaultFront": [0,-1,0],
"useVertexColors": true, "computeNormals": true }],
"surfaces": { "format": "segmentGroups",
"files": { "segmentGroups": "${rootPath}/${path}/${id}.aggregation.json",
"segments": "${rootPath}/${path}/${id}_vh_clean_2.0.010000.segs.json" } }
}
其中默认朝向 defaultUp=[0,0,1] 与 clean 阶段的“对齐到 up 方向”处理相互呼应;surfaces 部分则把分割与聚合 JSON 暴露给查看器做面级可视化。
6.3 upload.ini 与 config.py:服务级配置
除 config/upload.ini(见第 2.2 节参数表)外,config.py 定义服务运行时的关键开关:DATA_SERVER = 'http://localhost:3030'(WebUI 后端基地址)、TEMP_FOLDER = 'tmp'、STAGING_FOLDER = 'staging'、AUTOPROCESS = False(是否上传完成后自动触发处理,可被上传 URL 的 ?process= 参数覆盖),以及 Windows 侧的二进制/数据目录路径。
七、端到端数据流小结
综合以上源码,一个扫描从采集到入库的完整链路为:
- iPad 以 PUT 请求把五类文件逐个发送到 8000 端口上传服务,落盘
tmp/后移入staging/<scan_id>/,客户端可经/verify做 MD5 校验; - 五件齐备后(且开启自动处理时),上传服务并行触发:视频转码(经 WebUI 到 monitor 的
/convert-video/)与索引(/scans/index/),并调用处理服务的/process/<scanid>; - 5000 端口的处理服务在
GPU_LOCK保护下顺序执行 convert → calibrate → recons → clean → improve → decimate → freespace → segment → render → thumbnail,全部日志写入process.log; - 处理完成回调索引;
index.py依据scan_stages.json核对各阶段产物,把阶段状态、耗时、文件大小汇总进scan-net.csv/scan-net.all.json; - scripts/index_scannet.sh 周期性批量执行 4,合并注释统计后经
curl推送 3030 端口的 WebUI 完成展示层落库。
这套“上传即暂存、处理即追加日志、索引即状态机”的设计,使得每个扫描在任何时刻都能被回答出“处于哪个阶段、哪些产物过期、总耗时多少”,为 ScanNet 大规模室内场景数据的持续入库提供了可运维的工程基础。