照片和视频秒变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 python3.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_pathmy_reconstruction, # 输出根目录 target_size952, # 最大推理分辨率最长边 save_depthTrue, # 保存逐视图深度图 save_normalTrue, # 保存法线图 save_pointsTrue, # 保存彩色点云 points.ply save_gsTrue, # 保存3D高斯 gaussians.ply )几个常用参数速查参数默认值作用target_size952最大推理分辨率最长边越大越精细、越吃显存save_depthTrue保存深度图PNG 可视化 NPY 原始值save_normalTrue保存逐视图法线图save_pointsTrue保存基于深度的彩色点云save_gsTrue保存3D高斯模型gaussians.plysave_cameraTrue保存相机参数camera_params.json第三步运行推理执行上面的代码即完成推理。也可以换成命令行方式效果一致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_pathpath/to/camera_params.json, # 相机位姿 内参先验 prior_depth_pathpath/to/prior_depth/, # 先验深度图文件夹 )技巧2多GPU并行大场景提速torchrun --nproc_per_node2 -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_strategynew比均匀抽帧更能捕捉关键视角。 写在最后HY-World 2.0 把多视角照片/视频 → 3D点云重建从需要专业设备和繁琐标定的流程压缩成了一次前向推理。无论你是想给老建筑留数字档案、把产品拍成可交互的3D展示还是想入门 3D 重建领域它都是目前性价比很高的开源选择。现在就去准备一组照片跑通你的第一条重建命令吧。更完整的参数说明、先验格式细节和输出格式规范请参考项目内文档DOCUMENTATION_zh.md。【免费下载链接】HY-World-2.0项目地址: https://ai.gitcode.com/tencent_hunyuan/HY-World-2.0创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 照片和视频秒变3D点云重建：HY-World 2.0 快速上手指南
照片和视频秒变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 python3.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_pathmy_reconstruction, # 输出根目录 target_size952, # 最大推理分辨率最长边 save_depthTrue, # 保存逐视图深度图 save_normalTrue, # 保存法线图 save_pointsTrue, # 保存彩色点云 points.ply save_gsTrue, # 保存3D高斯 gaussians.ply )几个常用参数速查参数默认值作用target_size952最大推理分辨率最长边越大越精细、越吃显存save_depthTrue保存深度图PNG 可视化 NPY 原始值save_normalTrue保存逐视图法线图save_pointsTrue保存基于深度的彩色点云save_gsTrue保存3D高斯模型gaussians.plysave_cameraTrue保存相机参数camera_params.json第三步运行推理执行上面的代码即完成推理。也可以换成命令行方式效果一致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_pathpath/to/camera_params.json, # 相机位姿 内参先验 prior_depth_pathpath/to/prior_depth/, # 先验深度图文件夹 )技巧2多GPU并行大场景提速torchrun --nproc_per_node2 -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_strategynew比均匀抽帧更能捕捉关键视角。 写在最后HY-World 2.0 把多视角照片/视频 → 3D点云重建从需要专业设备和繁琐标定的流程压缩成了一次前向推理。无论你是想给老建筑留数字档案、把产品拍成可交互的3D展示还是想入门 3D 重建领域它都是目前性价比很高的开源选择。现在就去准备一组照片跑通你的第一条重建命令吧。更完整的参数说明、先验格式细节和输出格式规范请参考项目内文档DOCUMENTATION_zh.md。【免费下载链接】HY-World-2.0项目地址: https://ai.gitcode.com/tencent_hunyuan/HY-World-2.0创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考