ubc-vision/solv3r

项目介绍

Solv3R 是一个预训练的 3D 重建模型：输入一组图片（或视频帧），输出相机位姿、深度图、置信度和世界坐标点。它以 Python 包的形式发布，核心是一个模型类，同时附带推理、评测和可视化代码。项目对应论文 Solv3R: 3D Looped Transformer as a Multi-view Solver。

它的特点是把求解过程表示为对隐状态 z 的多次循环调用，而不是一次前向推理。这种设计让几种使用方式都很自然：一次解全部视角（离线）、分批加入图片、按随机顺序加入视角，以及逐帧处理视频流。隐状态可以跨调用复用，因此求解能从已有状态继续，也能在加入新图片后更新。

目标用户是多视图几何、相机位姿估计、稠密重建和视觉定位方向的研究者与工程师。使用需要能跑 PyTorch 推理的环境，以及项目提供的预训练权重。

快速使用

克隆仓库并创建 Python 3.11 环境：

git clone https://github.com/ubc-vision/solv3r.git && cd solv3r
conda create -n solv3r python=3.11 -y && conda activate solv3r
pip install -e .

预训练权重放在 Hugging Face。Solv3R.from_pretrained() 首次调用会下载到 Hugging Face 缓存；也可以把权重放到 checkpoints/solv3r.safetensors 直接使用。

一个最小推理流程：

from solv3r import Solv3R, cameras_from_pose_enc, list_images, load_images

model = Solv3R.from_pretrained()
images = load_images(list_images("path/to/images"))
ctx = model.encode(images)          # 第一张图定义世界坐标系
z = model.solve(ctx, calls=16)      # 循环块调用 16 次
pred = model.decode(z, ctx)         # depth、depth_conf、rays、world_points、pose_enc
c2w, K = cameras_from_pose_enc(pred["pose_enc"], (ctx.H, ctx.W))

图片会缩放到长边 504、两边为 14 的倍数，且不做裁剪。想直接用仓库自带样例数据跑示例：

python examples/offline.py --images examples/data/park --out outputs/offline --sky-mask
python examples/streaming.py --frames examples/data/desk --out outputs/streaming

每个示例会输出相机与深度图（.npz）、点云（.ply）和可在浏览器打开的 .html。结果还能渲染成视频：python examples/render_video.py --input outputs/offline/solve --out outputs/offline/solve.mp4 --aerial，--aerial 适合无人机照片。

继续求解时复用返回的状态：

z = model.solve(ctx, calls=8, z=z)
new_images = load_images(list_images("path/to/more_images"), size=(ctx.H, ctx.W))
z, ctx = model.add_views(z, ctx, new_images)
z = model.solve(ctx, calls=8, z=z)

README 还提供了离线、增量、任意顺序和流式四种示例脚本，以及论文各表格对应的评测入口。

评测与预期结果

评测代码沿用已有协议、未做改动。离线基准覆盖 DTU、ETH3D、7-Scenes、ScanNet++ 和 nuScenes，数据按 DVLT 的脚本准备；流式位姿基准沿用 CUT3R 和 TTT3R 在 Sintel、TUM-dynamics 和 ScanNet 上的设置；基于地图的重定位使用 7-Scenes 和 Cambridge Landmarks。README 给出了预期数值，例如 16 次调用下 DTU AUC@3 为 84.5、ScanNet AUC@3 为 80.7，L8 配置在 Sintel 上的 ATE 为 0.157。这些是论文中的复现目标，不是本站的独立测试结果。

使用约束

• 代码使用 Apache-2.0，但发布的模型权重基于 DVLT，采用 NVIDIA License，仅限非商业的研究与评估用途 DVLT。
• 输入处理假定长边 504、两边为 14 的倍数且不裁剪；第一张图定义世界坐标系。
• 评测需要外部数据集和第三方预处理脚本，只靠仓库本身无法跑通，必须有对应的数据目录。
• 求解器性质示例和 demo 尚未发布；README 把相关演示引向项目主页的视频。

HotRepo 点评

Solv3R 是一次较新的研究发布：仓库创建于 2026-11-02，站内采样显示 Star 从 2026-11-04 的 100 增至 2026-11-06 的 158，Python 新项目榜记录 2026-11-05 至 2026-11-06 新增 48 Star。目前没有 GitHub 全语言日榜记录，现有数据只说明发布阶段有关注度，不足以判断持续趋势。周边信号与一次模型发布相符：arXiv 论文、项目主页、Hugging Face 权重和基准代码与推理代码一起发布。实际使用的主要限制是权重的 NVIDIA 非商业许可，超出研究与评估用途前需要单独考虑。