ScanNet Server:扫描数据上传、GPU 处理与索引流水线服务全解

原创2026-10-13 12:26:151,393 阅读
文章标签:数据集计算机视觉3D视觉

ScanNet Server:扫描数据上传、GPU 处理与索引流水线服务全解

Server/ 目录是 ScanNet 数据采集基础设施的核心:它把 iPad 扫描器采集到的原始数据(.h264、.depth、.imu、.txt、.camera)经上传、三维重建、网格清理、渲染缩略图到最终建库索引的完整链路串联起来。读完本篇,你将理解上传服务、处理服务、索引监控服务三类组件的职责边界与端口约定,掌握 scan_stages.json 中 12 个流水线阶段与源码的对应关系,并能在自己的环境中按 Server/README.md 的说明部署和运行这套数据服务。

一、系统概览:三类组件的分工

根据 Server/README.md 的说明,ScanNet 数据服务由以下组件构成:

  1. Upload process(上传进程):供 iPad 端上传扫描文件并触发后续处理。为保证扫描可被自动处理,扫描目录需要空间充足且对处理进程可见,官方在 Ubuntu 14.04 的 Linux 机器上完成过测试;
  2. Scan processing scripts(处理脚本):需要配备高端 GPU 的 Windows 机器(官方测试环境为 Windows 10 + GTX Titan X,12GB 显存);
  3. 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 时必须附带毫秒级 UTC timestamp,服务会用 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 中对应一次外部程序调用,关键链路为:

  1. convert:converter.exe 把 iPad 原始文件转为 .uncalibrated.sens;
  2. calibrate:calibrate.exe 结合设备库(devices.csv)输出 .sens;
  3. recons:FriedLiver.exe(带 zParametersScanNet.txt 与 zParametersBundlingScanNet.txt 参数,见 tools/recons/)重建出 .ply;
  4. clean(2 个子步骤):MeshLab 执行 cleanLoRes.mlx 清洗,再 alignment.exe 对齐到 up/x/y 方向(对应 tools/meshclean/ 中的 .mlx 脚本);
  5. improve:DepthSensing.exe(VoxelHashing)生成高分辨率 _vh.ply;
  6. decimate(3 个子步骤):MeshLab 依次执行 clean.mlx 与两次 simplify.mlx,得到 _vh_clean.ply、_vh_clean_1.ply、_vh_clean_2.ply;
  7. freespace:FreeSpace.exe 由 .sens 计算占用体素网格 .grid;
  8. segment:Segmentator.exe(对应 Segmentator/ 工程)对降采样网格输出三档分辨率(10cm/100cm/1m)的 segs.json 分割文件;
  9. render:python mts_render.py <mesh> 用 Mitsuba 渲染预览 PNG;
  10. 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
  1. 分别对 scans/staging 与 scans/checked 执行两次 index.py:一次 CSV(scan-net.csv),一次 --all --format json(scan-net.all.json);
  2. 若存在 annotations/scannet.anns.stats.csv,用 scripts/combine_stats.py 将注释统计合并进 checked 的 CSV/JSON(先备份为 .nostats 文件再覆盖);
  3. 两次 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 侧的二进制/数据目录路径。

七、端到端数据流小结

综合以上源码,一个扫描从采集到入库的完整链路为:

  1. iPad 以 PUT 请求把五类文件逐个发送到 8000 端口上传服务,落盘 tmp/ 后移入 staging/<scan_id>/,客户端可经 /verify 做 MD5 校验;
  2. 五件齐备后(且开启自动处理时),上传服务并行触发:视频转码(经 WebUI 到 monitor 的 /convert-video/)与索引(/scans/index/),并调用处理服务的 /process/<scanid>;
  3. 5000 端口的处理服务在 GPU_LOCK 保护下顺序执行 convert → calibrate → recons → clean → improve → decimate → freespace → segment → render → thumbnail,全部日志写入 process.log;
  4. 处理完成回调索引;index.py 依据 scan_stages.json 核对各阶段产物,把阶段状态、耗时、文件大小汇总进 scan-net.csv / scan-net.all.json;
  5. scripts/index_scannet.sh 周期性批量执行 4,合并注释统计后经 curl 推送 3030 端口的 WebUI 完成展示层落库。

这套“上传即暂存、处理即追加日志、索引即状态机”的设计,使得每个扫描在任何时刻都能被回答出“处于哪个阶段、哪些产物过期、总耗时多少”,为 ScanNet 大规模室内场景数据的持续入库提供了可运维的工程基础。

登录后查看全文
ScanNet