4步上手HY-World 2.0：把手机照片和视频变成可自由浏览的3D点云

4步上手HY-World 2.0：把手机照片和视频变成可自由浏览的3D点云

【免费下载链接】HY-World-2.0项目地址: https://ai.gitcode.com/tencent_hunyuan/HY-World-2.0

做室内设计的人常遇到一个尴尬场景：客户发来十几张房间照片，你只能靠肉眼脑补空间结构，量尺寸、对角度，来回折腾大半天才能拼出一个大概的模型。做文博数字化的人更头疼，实地采集的素材往往要经过漫长的软件处理管线，一步出错就得重来。

有没有一种办法，把一堆照片或一段随手拍的视频直接"喂"给模型，几分钟就拿到带空间坐标的3D点云？腾讯混元团队的HY-World 2.0正是为此而生——它把从多视图图像到3D点云重建这件事压缩成了一次前向推理，无需人工打点、无需迭代优化，开箱即用。本文会带你从零开始，用一条可复现的完整流程跑通它，并解决你大概率会遇到的几个坑。

先聊痛点：传统三维重建为什么让人抓狂

以前想把一组照片变成3D模型，主流的做法是走 COLMAP 这类运动恢复结构（SfM）流程：先做特征匹配，再估计相机位姿，最后生成稀疏点云。听起来不复杂，但实际跑起来全是坑——纹理稀疏的墙面匹配不到特征、图像数量不够位姿解算直接崩、一次处理几十上百张图要等很久。

视频方案也未必省心，许多工具需要你手持设备绕场景缓慢移动，稍有抖动就会引入漂移误差，后期还要手动修。

HY-World 2.0 走的是另一条路：它属于前馈（feed-forward）模型，意思是模型看到输入后一口气预测出所有几何信息，不做逐帧迭代优化。你给它一组多视角图片或一段视频，它在单次前向传播里同时输出：

• 世界坐标系下的3D点云
• 每一帧对应的深度图
• 表面法线图
• 相机外参（位姿）和内参
• 3D高斯泼溅（3DGS）属性

换句话说，几何、相机、渲染所需的全部信息一次到位，这也是它作为"统一模型"的底气所在。

三步搭好环境：从零到能跑

第 1 步：拉取代码并创建虚拟环境

先把仓库克隆到本地（仓库地址为 https://gitcode.com/tencent_hunyuan/HY-World-2.0 ），然后新建一个干净的 Python 环境：

git clone https://gitcode.com/tencent_hunyuan/HY-World-2.0 cd HY-World-2.0 conda create -n worldrecon python=3.11 conda activate worldrecon

推荐 Python 3.11 及以上，配合 CUDA 12.8 使用体验最佳。如果你的显卡较老，也至少保证 PyTorch 能正常调用 GPU，否则推理速度会让你怀疑人生。

第 2 步：装好基础依赖和两个关键加速库

pip install -r requirements.txt

这一步会把项目主体依赖装完。接着是两件容易被忽略的事：

1. gsplat：如果你只跑重建（WorldMirror 2.0），直接装官方版本即可：

   pip install git+https://github.com/nerfstudio-project/gsplat.git

2. FlashAttention 后端：H 系列新卡装 FlashAttention-3，其他卡装 FlashAttention-2 就行：

   pip install flash-attn --no-build-isolation

第 3 步：验证安装

python -c "import torch; print(torch.cuda.is_available())"

输出True就说明环境就绪，可以进入下一步了。

最小可用示例：两条命令跑通重建

HY-World 2.0 提供了类似 diffusers 的 Python API，也有等价的命令行入口。假设你准备了一个图片文件夹my_room/（里面放 8~32 张同一场景不同角度的照片），最简单的命令行调用是这样：

python -m hyworld2.worldrecon.pipeline \ --input_path my_room/ \ --output_path scan_result

首次运行会自动下载模型权重，之后无需联网。跑完后去scan_result/看一眼，你会发现每个子目录里躺着points.ply（带颜色点云）、gaussians.ply（3D高斯）、camera_params.json（相机参数）以及一堆深度图和法线图。points.ply用 MeshLab 或 CloudCompare 打开，你就能直接"走"进这个三维空间了。

用 Python 调用的姿势也差不多：

from hyworld2.worldrecon.pipeline import WorldMirrorPipeline pipeline = WorldMirrorPipeline.from_pretrained('tencent/HY-World-2.0') result = pipeline('my_room/', output_path='scan_result')

完整实战：把一段环绕拍摄的客厅视频变成可漫游的点云

下面我们走一个贯穿始终的真实任务：用手机围绕客厅慢速环绕拍摄一段视频，重建出能自由缩放浏览的3D点云。建议保持画面平稳、光照均匀，绕场一圈大约 30~60 秒。

第 1 步：让模型自动抽帧

视频输入不需要你手动截帧，Pipeline 自带运动感知抽帧逻辑：

python -m hyworld2.worldrecon.pipeline \ --input_path livingroom.mp4 \ --output_path livingroom_scan \ --video_max_frames 24

video_max_frames限制了最多抽多少帧，24 帧既能覆盖全景视角，又不会让显存吃不消。想控制抽帧密度，可以调整fps参数（默认 1，即每秒抽一帧）。

第 2 步：按需调整推理分辨率

target_size控制最长边的推理分辨率，默认 952。图像会被等比缩放并中心裁剪到 14 的倍数。显存紧张就把值调小，追求精度就调大：

python -m hyworld2.worldrecon.pipeline \ --input_path livingroom.mp4 \ --output_path livingroom_scan \ --target_size 800

第 3 步：检查输出与质量

推理结束后，livingroom_scan/下会生成如下内容：

• frames_*/depth/：每帧的深度可视化图（PNG）与原始深度（NPY）
• frames_*/normal/：法线可视化图
• points.ply：彩色点云
• gaussians.ply：3D高斯模型
• camera_params.json：逐帧位姿与内参
• timing_report.json：各阶段耗时统计

用点云查看器打开points.ply，你应当能看到沙发、茶几、墙壁的清晰轮廓。如果发现点云边缘毛刺多、天空区域被错误重建，多半需要做下面这步清洗。

第 4 步：顺手做一次"去噪"

Pipeline 默认已经开启了天空掩码和边缘掩码过滤，如果你想更激进地清理低质量区域，可以叠加置信度过滤：

python -m hyworld2.worldrecon.pipeline \ --input_path livingroom.mp4 \ --output_path livingroom_scan \ --apply_confidence_mask \ --confidence_percentile 15

confidence_percentile 15的意思是砍掉置信度最低的 15% 的点，适合场景中存在反光、玻璃等难处理材质的情况。

进阶调优：让重建精度再上一个台阶

玩法一：注入相机与深度先验

如果你手里已经有相机位姿或深度图（比如来自雷达扫描或第三方标定），喂给模型能显著提精度。先验文件放在prior/目录，调用时用两个参数指过去即可：

python -m hyworld2.worldrecon.pipeline \ --input_path my_room/ \ --prior_cam_path prior/camera_info.json \ --prior_depth_path prior/depth_maps/

上面的对比图直观展示了先验带来的收益：从"无先验"到"全部先验"，平均精度误差几乎下降了一半以上。注意深度文件的文件名要和输入图片一一对应，格式支持.npy、.exr和 16 位.png。

玩法二：多卡并行加速大场景

场景大、输入帧多时，单卡可能放不下。项目支持 Sequence Parallel + FSDP 的组合，几行命令就能铺开多卡：

torchrun --nproc_per_node=4 -m hyworld2.worldrecon.pipeline \ --input_path my_room/ \ --use_fsdp --enable_bf16

一个硬性规则要记住：输入图像数量必须不小于 GPU 数量，比如 4 卡至少要准备 4 张图，否则会直接报错。

玩法三：按需裁剪输出头省显存

有些场景你只想要点云，法线和3D高斯都属于多余负担。可以在加载模型时禁用对应预测头，一口气释放约两亿参数：

from hyworld2.worldrecon.pipeline import WorldMirrorPipeline pipeline = WorldMirrorPipeline.from_pretrained( 'tencent/HY-World-2.0', disable_heads=["normal", "gs"], )

可选的禁用项包括camera、depth、normal、points、gs，按需取舍即可。

玩法四：浏览器里的可视化

不想写代码看结果？项目内置 Gradio 应用，一条命令启动：

python -m hyworld2.worldrecon.gradio_app

启动后浏览器访问本机端口，上传图片或视频，就能在页面上旋转查看点云、高斯、深度和法线，还可以一键对比不同先验配置的效果。

常见问题与排障手册

Q1：多卡推理报"输入数量不足"错误？答：检查图片数量是否大于等于 GPU 数量，这是项目写死的约束。要么加图，要么减卡。

Q2：显存不够用怎么办？答：先降target_size，再考虑禁用normal、gs等输出头，还不行就开--fsdp_cpu_offload把参数卸载到内存换显存。

Q3：重建出的点云有大量空洞？答：多半是输入视角覆盖不足。绕场景再多拍一些角度，确保相邻照片有 60% 以上的重叠区域；避免大面积纯色墙面，必要时借助先验深度兜底。

Q4：跑出来的深度图整体发灰？答：这是深度值未归一化的正常现象，原始数据在对应的.npy文件里，可视化 PNG 只是便于人眼确认。

Q5：首次加载模型卡了很久？答：正常，权重在自动下载。网速不佳时可以手动下载后放到本地目录，再用from_pretrained(本地路径)加载。

写在最后：从"看视频"到"进场景"

HY-World 2.0 最打动人的地方，是它把"看视频"升级成了"进场景"——输出的不是会消失的像素，而是能导入 Blender、Unity 或 MeshLab 的真实三维资产。配合先验注入，它的重建精度在公开基准上已处于第一梯队，而多卡并行支持又让大场景不至于望而却步。

建议你今天就做两件事：一是按上文流程跑通一个自己的场景，体会从照片到3D点云的完整链路；二是翻一翻项目里的 DOCUMENTATION_zh.md，那里有全部参数表和输出格式的细节说明，能帮你把每一行配置都用到刀刃上。世界重建的大门已经打开，剩下就等你动手了。

【免费下载链接】HY-World-2.0项目地址: https://ai.gitcode.com/tencent_hunyuan/HY-World-2.0