企业官网建设流程全解析

照片和视频秒变3D点云重建：HY-World 2.0 快速上手指南

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

想给老房子做个3D存档、把产品拍成可交互展示，却卡在从照片/视频到3D点云重建这一步——要么上专业扫描设备，要么在传统工具里手动标定相机、配准点云，光看教程就劝退了。好消息是，腾讯混元团队开源的HY-World 2.0把这件事压缩成了一条命令。

HY-World 2.0 是一个多模态3D世界模型框架，其中负责世界重建的WorldMirror 2.0组件是统一的前馈模型：你把多视角照片或随手拍的视频喂进去，它能在一次前向推理中同时预测出3D点云、深度图、表面法线、相机位姿和3D高斯属性——也就是把"拍一圈"直接变成"一份可用的3D资产"。它特别适合零基础用户和初中级开发者，快速完成场景数字化、室内重建、文物扫描这类任务。

⚡ 亮点速览

• 一次推理，五类输出：点云、深度、法线、相机参数、3D高斯一网打尽
• 照片或视频都能喂：图像文件夹、环绕视频两种输入方式
• 先验注入提精度：支持把已知相机位姿、深度图作为先验输入
• 多GPU并行推理：Sequence Parallel + FSDP + BF16，大场景不慌
• 上手门槛低：diffusers 风格的 Python API，另有 Gradio 网页界面

🛠 三步完成环境部署

官方推荐CUDA 12.8 + Python 3.11+，按顺序执行即可。

第1步：克隆仓库并创建环境

git clone https://gitcode.com/tencent_hunyuan/HY-World-2.0 cd HY-World-2.0

克隆项目代码并进入目录。

conda create -n hyworld2 python=3.11.15 conda activate hyworld2

创建 Python 3.11 环境并激活。

第2步：安装基础依赖

pip install -r requirements.txt

安装项目的基础依赖包。

第3步：安装两个关键组件

pip install gsplat

安装 3D 高斯渲染库。如果后续还要跑世界生成（worldgen），官方更推荐安装项目自带的自定义 gsplat 版本，具体见hyworld2/worldgen/third_party目录下的说明。

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

安装 FlashAttention 加速注意力计算；如果你用的是 Hopper 架构 GPU（如 H100），官方推荐改用 FlashAttention-3。

这一步完成后，环境就可以运行WorldMirror 2.0了。

📦 最小可用示例：三行代码跑通重建

from hyworld2.worldrecon.pipeline import WorldMirrorPipeline pipeline = WorldMirrorPipeline.from_pretrained('tencent/HY-World-2.0') result = pipeline('path/to/images')

模型权重会在首次运行时自动下载。跑完后，result指向输出目录，里面已经默认保存了深度图、法线图、相机参数、彩色点云points.ply和3D高斯gaussians.ply。也就是说——你只需要准备一个装照片的文件夹，就能拿到一份完整的3D重建结果。

🚀 实战四步走：从照片到3D点云

第一步：准备输入数据

建议准备8-32张不同视角、彼此有足够重叠区域的照片放进一个文件夹；或者直接传一个手机拍的环绕视频，Pipeline 会自动按需抽帧。

第二步：配置推理参数

result = pipeline( 'path/to/images', output_path='my_reconstruction', # 输出根目录 target_size=952, # 最大推理分辨率（最长边） save_depth=True, # 保存逐视图深度图 save_normal=True, # 保存法线图 save_points=True, # 保存彩色点云 points.ply save_gs=True, # 保存3D高斯 gaussians.ply )

几个常用参数速查：

第三步：运行推理

执行上面的代码即完成推理。也可以换成命令行方式，效果一致：

python -m hyworld2.worldrecon.pipeline --input_path path/to/images --output_path my_reconstruction

第四步：查看输出结果

推理完成后，输出目录结构大致如下：

my_reconstruction/ └── <场景名>/<时间戳>/ ├── depth/ # 深度图（PNG + NPY） ├── normal/ # 法线图 ├── camera_params.json # 相机位姿和内参 ├── points.ply # 彩色3D点云 ├── gaussians.ply # 3D高斯泼溅模型 └── pipeline_timing.json # 各阶段耗时报告

得到的 PLY 文件可以直接导入 Blender、MeshLab、CloudCompare 等软件查看和进一步处理。

🔧 进阶技巧：三个让效果更好的姿势

技巧1：注入相机/深度先验，精度肉眼可见地提升

如果你手里已有相机参数或深度信息（比如来自 SLAM 或结构光扫描），把它们作为先验传给 Pipeline，重建精度会明显提升。官方在 7-Scenes、NRGBD、DTU 基准上的数据很直观：高分辨率 + 完整先验时，7-Scenes 的平均精度从 0.041（低分辨率、无先验）一路提升到0.012。

result = pipeline( 'path/to/images', prior_cam_path='path/to/camera_params.json', # 相机位姿 + 内参先验 prior_depth_path='path/to/prior_depth/', # 先验深度图文件夹 )

技巧2：多GPU并行，大场景提速

torchrun --nproc_per_node=2 -m hyworld2.worldrecon.pipeline \ --input_path path/to/images \ --use_fsdp --enable_bf16

注意一个关键前提：多卡模式下，输入图像数量必须大于等于 GPU 数量（比如用 8 卡，就得准备至少 8 张图片）。

技巧3：显存吃紧？按需裁剪模型

只想要部分输出时，用disable_heads释放不需要的预测头：

pipeline = WorldMirrorPipeline.from_pretrained( 'tencent/HY-World-2.0', disable_heads=["normal", "points"], # 释放约200M参数 )

另外apply_sky_mask、apply_edge_mask默认开启，会自动过滤天空区域和边缘不连续区域，让点云更干净；compress_pts默认开启，会把点云压缩到最多 200 万个点，避免文件过大。

Bonus：不想写代码？试试网页界面

启动 Gradio 应用，在浏览器里上传图片或视频，即可可视化 3DGS、点云、深度、法线和相机参数：

python -m hyworld2.worldrecon.gradio_app

❓ 新手高频问题排查

Q1：多卡推理一直报错怎么办？最常见原因是输入图像数量少于 GPU 数量。多卡模式下要求图像数 ≥ GPU 数，先检查你的图片文件夹够不够。

Q2：显存不够用怎么办？三条路可以组合：调低target_size（默认 952）；用disable_heads关掉用不到的输出头；再加--fsdp_cpu_offload把参数卸载到 CPU。

Q3：输入视频抽帧太密或太稀怎么办？通过fps、video_min_frames、video_max_frames控制抽帧节奏。默认采用运动感知式抽帧（video_strategy="new"），比均匀抽帧更能捕捉关键视角。

🎯 写在最后

HY-World 2.0 把"多视角照片/视频 → 3D点云重建"从需要专业设备和繁琐标定的流程，压缩成了一次前向推理。无论你是想给老建筑留数字档案、把产品拍成可交互的3D展示，还是想入门 3D 重建领域，它都是目前性价比很高的开源选择。现在就去准备一组照片，跑通你的第一条重建命令吧。

更完整的参数说明、先验格式细节和输出格式规范，请参考项目内文档：DOCUMENTATION_zh.md。

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