照片转 3D 点云快速上手：WorldMirror 2.0 新手完整教程，一次跑通你的第一次重建

照片转 3D 点云快速上手WorldMirror 2.0 新手完整教程一次跑通你的第一次重建【免费下载链接】HY-World-2.0项目地址: https://ai.gitcode.com/tencent_hunyuan/HY-World-2.0腾讯混元团队开源的 WorldMirror 2.0是一个把一叠普通照片或一段随手拍的视频直接重建为 3D 点云的开源模型。它不需要激光扫描仪也不需要你掌握摄影测量理论一次前向传播就能同时输出点云、深度图、法线图和相机参数。这篇文章从零开始带你搭环境、跑通第一次推理再学会用参数和先验把结果调到可用。认识 WorldMirror 2.0一次推理到底产出什么WorldMirror 2.0 是 HY-World 2.0 世界模型体系中负责重建的一环模型权重约 12 亿参数。它做的事可以类比成拼图每张照片是一块散落的拼图模型在这一次前向传播里同时完成拼出立体关系、标出景深、画好表面朝向整套活儿不需要你手动对齐任何东西。你可以喂给它的输入有两种一个装有多视角照片的文件夹建议 8~32 张视角要分散相邻照片要有重叠区域一段视频模型会自动按运动幅度抽帧默认最多 32 帧不用你手动截帧跑完一次推理你的硬盘上会多出下面这五类结果输出文件是什么能拿来做什么points.ply带颜色的 3D 点云拖进 Blender、MeshLab、CloudCompare 继续加工gaussians.ply3D 高斯泼溅模型高质量实时渲染depth/每张照片的深度图PNG 可视化 NPY 原始值查看远近关系也能作为先验复用normal/每张照片的表面法线图查看墙面、地面等表面朝向camera_params.json每张照片的相机位姿与内参供其他 3D 工具对齐使用注意一个关键点这些结果是一次前向传播同时预测出来的不是五个模块分别算完再拼的所以端到端一步到位。搭好环境从克隆仓库到装完依赖先决条件很简单CUDA 12.8 以上、Python 3.11 以上、一张 N 卡。然后按下面几步走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 pip install -r requirements.txt装完基础依赖重建功能WorldMirror 2.0就已经可用了。接着补一个 FlashAttention 后端能明显加快注意力计算pip install flash-attn --no-build-isolation如果你以后还想跑世界生成文字/图片生成可漫游 3D 世界那条链路还需要额外装requirements_git.txt和几个子模块这一步现在可以先跳过——先把重建跑通后面按需再加。跑通第一次推理三行代码生成你的第一份点云先把手机拿出来绕着一个小物件或一个房间角落拍上 8~32 张照片放进一个文件夹。然后打开终端跑这段代码from hyworld2.worldrecon.pipeline import WorldMirrorPipeline pipeline WorldMirrorPipeline.from_pretrained(tencent/HY-World-2.0) # 首次运行会自动下载权重 result pipeline(你的照片文件夹路径) # 默认输出到 inference_output/不想写 Python同样的事一条命令搞定python -m hyworld2.worldrecon.pipeline --input_path 你的照片文件夹路径如果你输入的是视频直接把视频文件路径传给 pipeline 就行模型会自动抽帧默认最多 32 帧连截帧这一步都省了。 读懂输出硬盘上多出来的每一样东西跑完后结果按inference_output/场景名/时间戳/的目录结构存放里面长这样inference_output/ └── 你的场景名/ └── 时间戳/ ├── depth/ # depth_0000.png 可视化 depth_0000.npy 原始深度 ├── normal/ # 每张图的法线图 ├── camera_params.json # 相机外参c2w 内参 ├── gaussians.ply # 3D 高斯泼溅 ├── points.ply # 带颜色点云 └── pipeline_timing.json # 各阶段耗时统计两个.ply文件都能直接拖进 Blender、MeshLab 这类软件里打开。这里有个小伏笔camera_params.json的格式和项目文档里先验注入要求的格式完全一致也就是说你这次推理的输出可以直接当下一次推理的先验用。按需调参省显存、提分辨率、出渲染视频同一份代码不同硬件、不同目标调法也不同。下面是几个最常用的旋钮参数默认值什么时候动它target_size952显存紧张就调低追求细节就调高支持 5 万~50 万像素的灵活分辨率disable_heads无只想要部分输出时关掉用不上的预测头可释放约 2 亿参数apply_confidence_maskFalse点云里飞点太多时打开剔除模型置信度最低的那部分点save_renderedFalse打开后自动渲染一段绕场景飞行的视频汇报演示很加分save_colmapFalse需要把结果送进 COLMAP 格式工作流时打开比如你只想省显存、只要点云和相机参数pipeline WorldMirrorPipeline.from_pretrained( tencent/HY-World-2.0, disable_heads[normal, gs], # 关掉法线和 3DGS 两个预测头 )如果场景大、想多卡加速换成分布式命令torchrun --nproc_per_node4 -m hyworld2.worldrecon.pipeline \ --input_path 你的照片文件夹路径 \ --use_fsdp --enable_bf16这里有个容易踩的坑多卡模式下输入图像数量必须不小于 GPU 数量——8 卡就至少要 8 张图否则会直接报错。这不是 bug是设计。注入先验精度提升性价比最高的一步如果你手上恰好有相机参数JSON或深度图别浪费把它们作为先验喂给模型精度会立刻上一个台阶。这些数据可以来自上一次推理的输出也可以来自其他工具result pipeline( 你的照片文件夹路径, prior_cam_path相机参数.json, # 4x4 外参 3x3 内参OpenCV 坐标约定 prior_depth_path深度图文件夹/, # .npy / .exr / 16 位 .png文件名需与图片名一致 )先验可以自由组合只给内参、只给深度、或者全部一起给模型会自动检测你提供了哪些。具体格式参考项目里的 DOCUMENTATION.md 的 Prior Injection 一节。上面这张图是官方在 7-Scenes、NRGBD、DTU 三套标准数据上的评测纵轴是重建误差、越低越好。橙色WorldMirror 2.0在无先验 / 内参 / 深度 / 相机位姿 / 全部先验五个档位上的误差都明显低于 Pow3R 和 MapAnything把全部先验和高分辨率组合起来7-Scenes 的精度指标能冲到 0.012 的量级是全部配置里最稳的一档。用浏览器检查结果一条命令打开可视化界面项目自带一个 Gradio Web 界面不用写任何代码就能上传图片或视频在浏览器里直接查看点云、深度图、法线图和相机参数python -m hyworld2.worldrecon.gradio_app默认在0.0.0.0:8081提供服务加上--share参数可以生成一个公网链接方便在远程服务器上使用。 把资产接进你的工作流跑通之后建议按这个顺序往下走先打开可视化界面检查重建效果确认没有明显问题再用手头的深度或相机数据做一次先验注入直观感受精度的变化最后把points.ply和gaussians.ply拖进 Blender 或 Unreal Engine做进一步的加工和渲染。到这里你已经完成了从零基础到能产出可编辑 3D 资产的完整闭环。下一步很简单随手拍一个桌面摆件十几张照片跑一遍代码看看你人生中第一份自己生成的 3D 点云长什么样。【免费下载链接】HY-World-2.0项目地址: https://ai.gitcode.com/tencent_hunyuan/HY-World-2.0创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考