UniK3D 推理脚本全攻略：命令参数、相机配置与结果可视化

【免费下载链接】UniK3D[CVPR 2025] UniK3D: Universal Camera Monocular 3D Estimation项目地址: https://gitcode.com/gh_mirrors/un/UniK3D

UniK3D 是 CVPR 2025 提出的单目 3D 估计模型，能够从普通 2D 图像中重建出精准的三维结构。本文将详细介绍如何使用scripts/infer.py脚本进行 3D 推理，包括核心命令参数解析、相机模型配置和可视化结果生成，帮助新手快速上手这一强大工具。

快速开始：基础推理命令

使用 UniK3D 进行单目 3D 估计仅需一行命令，以下是针对不同场景的示例：

标准图像推理

python scripts/infer.py \ --input assets/demo/dl3dv.png \ --output results/dl3dv \ --config-file configs/eval/vitl.json \ --save --save-ply

鱼眼相机图像推理

python scripts/infer.py \ --input assets/demo/kitti360.png \ --output results/kitti360 \ --config-file configs/eval/vitb.json \ --camera-path assets/demo/kitti360.json \ --resolution-level 7 \ --save --save-ply

图 1：使用鱼眼相机模型对城市道路场景进行 3D 估计的输入图像（UniK3D 单目 3D 重建）

核心参数详解

infer.py脚本提供了丰富的参数选项，以下是最常用的关键参数说明：

必选参数

• --input: 输入图像路径（支持 JPG/PNG 格式）
• --output: 结果保存目录（自动创建不存在的目录）
• --config-file: 模型配置文件路径，位于configs/eval/目录下，提供三种预设：
  • vitb.json: 基于 ViT-Base 的轻量模型
  • vitl.json: 基于 ViT-Large 的平衡模型（推荐）
  • vits.json: 基于 ViT-Small 的快速模型

可选参数

技巧：对于低性能设备，可将--resolution-level降低至 5-7 以提高速度；追求高精度时建议使用 8-9 并选择vitl.json配置。

相机模型配置指南

UniK3D 支持多种相机模型，通过--camera-path参数指定 JSON 配置文件实现精准的 3D 重建。项目已提供多个示例配置文件，位于assets/demo/目录下：

相机模型类型

1. 针孔相机（Pinhole）：适用于普通手机/相机拍摄的图像

   { "name": "Pinhole", "params": [1000.0, 1000.0, 512.0, 384.0] // fx, fy, cx, cy }

2. 鱼眼相机（Fisheye624）：适用于广角/全景图像

   { "name": "Fisheye624", "params": [800.0, 800.0, 640.0, 480.0, 0.1, -0.2, 0.05] // 含畸变参数 }

3. 球面相机（Spherical）：适用于 360° 全景图像

   { "name": "Spherical", "params": [0, 0, 0, 0, 1280, 720, 1.57, 0.785] // 宽度,高度,水平FOV,垂直FOV(弧度) }

注意：相机参数可通过相机标定工具获取，或参考assets/demo/scannet.json等示例文件调整。

结果可视化与解析

推理完成后，--output目录将生成以下结果文件（需启用--save和--save-ply参数）：

2D 可视化结果

• *_depth.png: 彩色编码的深度图，近处为红色，远处为蓝色
• *_rays.png: 射线方向可视化，展示每个像素的 3D 方向向量

3D 点云结果

• *.ply: 可在 MeshLab、CloudCompare 等软件中打开的点云文件，包含颜色信息

图 2：办公室场景的 3D 点云重建输入图像（UniK3D 单目深度估计）

可视化示例代码

如需在 Python 中直接查看结果，可使用以下代码片段：

from PIL import Image import matplotlib.pyplot as plt # 显示深度图 depth_img = Image.open("results/dl3dv/dl3dv_depth.png") plt.figure(figsize=(10, 6)) plt.imshow(depth_img) plt.title("UniK3D 深度估计结果") plt.axis("off") plt.show()

高级技巧与性能优化

分辨率与速度平衡

• 快速预览：--resolution-level 5+vits.json，适合快速检查效果
• 精细重建：--resolution-level 9+vitl.json，适合最终结果生成

内存管理

对于高分辨率图像（如 4K），建议：

1. 先将图像缩放到 1920x1080 以下
2. 使用--resolution-level 7降低计算负载
3. 关闭不必要的后台程序释放内存

常见问题解决

• 结果模糊：提高--resolution-level或更换vitl.json配置
• 边缘畸变：使用--camera-path指定正确的相机模型
• 运行缓慢：确保已安装 CUDA 并使用 GPU 推理（需 PyTorch 支持）

总结

通过本文的指南，您已掌握 UniK3D 推理脚本的核心用法，包括命令参数配置、相机模型选择和结果可视化。无论是街景、室内还是自然场景，UniK3D 都能从单张图像中重建出精确的 3D 结构。更多高级功能可参考项目文档 docs/eval.md 和 docs/train.md。

图 3：公园长椅场景的 3D 重建输入图像（UniK3D 单目 3D 估计）

开始您的 3D 重建之旅吧！如需获取项目代码，请使用以下命令：

git clone https://gitcode.com/gh_mirrors/un/UniK3D

【免费下载链接】UniK3D[CVPR 2025] UniK3D: Universal Camera Monocular 3D Estimation项目地址: https://gitcode.com/gh_mirrors/un/UniK3D