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 python3.11 conda activate worldrecon推荐 Python 3.11 及以上配合 CUDA 12.8 使用体验最佳。如果你的显卡较老也至少保证 PyTorch 能正常调用 GPU否则推理速度会让你怀疑人生。第 2 步装好基础依赖和两个关键加速库pip install -r requirements.txt这一步会把项目主体依赖装完。接着是两件容易被忽略的事gsplat如果你只跑重建WorldMirror 2.0直接装官方版本即可pip install githttps://github.com/nerfstudio-project/gsplat.gitFlashAttention 后端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.ply3D高斯、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_pathscan_result)完整实战把一段环绕拍摄的客厅视频变成可漫游的点云下面我们走一个贯穿始终的真实任务用手机围绕客厅慢速环绕拍摄一段视频重建出能自由缩放浏览的3D点云。建议保持画面平稳、光照均匀绕场一圈大约 30~60 秒。第 1 步让模型自动抽帧视频输入不需要你手动截帧Pipeline 自带运动感知抽帧逻辑python -m hyworld2.worldrecon.pipeline \ --input_path livingroom.mp4 \ --output_path livingroom_scan \ --video_max_frames 24video_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与原始深度NPYframes_*/normal/法线可视化图points.ply彩色点云gaussians.ply3D高斯模型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 15confidence_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_node4 -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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考