Hunyuan3D-Omni Shape-VAE深度教程:从点云交叉注意力编码到Marching Cubes网格重建

原创2026-11-06 11:50:491,880 阅读
文章标签:人工智能深度学习计算机视觉多模态3D建模媒体生成

Hunyuan3D-Omni Shape-VAE深度教程:从点云交叉注意力编码到Marching Cubes网格重建

Hunyuan3D-Omni 是腾讯混元团队开源的统一可控 3D 资产生成框架,其中 Shape-VAE 负责把 3D 形状压缩为低维潜变量,再通过点云交叉注意力编码与 Marching Cubes 完成网格重建。本教程面向新手,带你读懂 Shape-VAE 的完整数据流:点云 → 交叉注意力编码 → 隐空间潜变量 → 隐式函数 → 三角网格。

Hunyuan3D-Omni 多模态可控3D生成效果展示

一、Shape-VAE 在 Hunyuan3D-Omni 中的位置

Hunyuan3D-Omni 继承了 Hunyuan3D 2.1 的整体结构,并新增了一个统一控制编码器,支持点云(point)、体素(voxel)、骨骼姿态(pose)、边界框(bbox)四种控制信号。整个推理管线由 pipeline_generation_sit_omni.py 串联,核心组件如下:

组件 作用 源码位置
cond_encoder 把图像 + 控制信号编码为条件 omni_encoder.py
model (Shape-DiT) 在潜空间做去噪采样 hunyuan3ddit.py
vae (Shape-VAE) 编码/解码 3D 形状,输出网格 shape_vae.py
scheduler Flow Matching 采样调度 transport/

Hunyuan3D-Omni 整体框架图:多模态条件编码与3D扩散生成流程

Shape-VAE 本身由三部分构成(见 shape_vae.py 中的 ShapeVAE 类):

  1. PointCrossAttentionEncoder(L47):把表面点云压缩成一组潜变量(latents);
  2. Transformer 解码器:对潜变量做自注意力交互,恢复表达能力;
  3. CrossAttentionDecoder(L295):对空间中任意坐标查询,输出隐式函数(SDF/TSDF)值。

训练与推理的入口类是 shape_vae_pl.py 中的 ShapeVAEPL,它把上述模块包装成 LightningModule,并提供 latent2mesh 方法(L211)把潜变量变成三角网格。

二、第一步:点云交叉注意力编码

1. 为什么用交叉注意力而不是卷积?

3D 表面点云是无序的、密度不均匀的点集,无法直接用 3D 卷积处理。Hunyuan3D 的解法是"查询-数据"式的交叉注意力:

  • Query(查询点):从表面点云中按固定比例降采样得到的一小撮"代表点",数量由 num_latents 决定;
  • Data(数据点):随机抽取的表面点云;
  • 每个 Query 通过交叉注意力从 Data 中聚合局部几何信息,最终每个 Query 对应一个潜向量。

这样就实现了"可变数量的点 → 固定长度的潜变量序列",正好匹配后续扩散模型的需求。

2. 傅里叶位置编码

点坐标本身只是 3 个浮点数,直接送入网络难以表达高频细节。Shape-VAE 使用 FourierEmbedder(num_freqs=8)把每个坐标扩展为多频带的 sin/cos 特征,使网络能拟合尖锐边缘和精细纹理。

3. FPS 远点采样与锐边点

编码过程的核心在 sample_points_and_latents:

  • 使用 FPS(Farthest Point Sampling) 从随机表面点中选出分布均匀的查询点,保证潜变量覆盖整个表面;
  • 数据点分为两部分:随机表面点(pc_size)和锐边点(pc_sharpedge_size)。锐边点专门采样自模型的尖锐边缘区域,让编码后对细节的重建更鲁棒;
  • 训练时按 train_num_latents_range 随机改变点数,推理时固定为 num_latents × downsample_ratio。

编码主干的三步计算(_forward)非常简洁:

  1. input_proj:线性投影 Query 与 Data;
  2. cross_attn:交叉注意力,Query 从 Data 聚合信息;
  3. self_attn(可选的 Transformer 层):潜变量之间互相交流。

Bounding Box 控制生成的 3D 模型输入示例:家具图片与3D包围盒约束

三、第二步:VAE 潜变量压缩与 KL 先验

编码出的特征序列会经过 pre_kl 线性层映射到 embed_dim × 2 维,拆成均值和方差,构成分布为 DiagonalGaussianDistribution 的高斯后验(encode):

  • 训练时:从后验中采样,配合 KL 散度损失让潜空间平滑连续;
  • 推理时:直接取后验的 mode(均值),保证结果稳定可复现。

压缩后的潜变量形状为 (num_latents, embed_dim),即 latent_shape。管线中 prepare_latents(pipeline_generation_sit_omni.py L155)正是按这个形状采样初始噪声,交给 Shape-DiT 做条件去噪。

四、第三步:解码为隐式函数

去噪得到的潜变量送入 VAE 的解码端(decode):

  1. post_kl 把潜变量映射回宽维空间;
  2. transformer 自注意力层恢复全局几何结构;
  3. query_geometry(L505):CrossAttentionDecoder 对任意空间坐标做查询,输出一个标量——该点到表面的隐式距离值(SDF/TSDF)。

这一步把"离散的潜变量"变成了"连续空间上的隐式函数",为下一步提取网格做好了准备。

Pose 骨骼控制生成的人体 3D 模型示例

五、第四步:Marching Cubes 网格重建

这是本教程的最后一环:如何从隐式函数得到可以渲染的三角网格?

1. 均匀网格采样(vanilla 方式)

基础实现见 extract_geometry_vanilla.py,流程如下:

  1. 生成密集网格点:generate_dense_grid_points 在边界框 bounds=[-1.01, -1.01, -1.01, 1.01, 1.01, 1.01] 内生成 octree_resolution 分辨率的均匀坐标格点(如 512³);
  2. 分批前向:按 num_chunks(默认 8000)分批把格点送入 geometric_func,得到每个格点的隐式函数值;
  3. Marching Cubes 提取:调用 scikit-image 的 measure.marching_cubes(method="lewiner",L119),在等值面 mc_level(默认 0,表示 TSDF 零平面)处插值出三角形面片;
  4. 输出 trimesh.Trimesh 网格对象。

2. 加速版:FlashVDM 多分辨率金字塔

vanilla 方式要查询 512³ ≈ 1.3 亿个点,非常耗时。extract_geometry_fast_v2.py 中的 FastGeometryExtractorV2 采用由粗到细的金字塔策略:

  1. 先在低分辨率网格上求值;
  2. 用 3D 膨胀(dilate)找到"表面附近"的体素邻域,只在这些位置继续细化;
  3. 逐级上采样到目标分辨率,最后只在有效区域内做 Marching Cubes(mask 参数),跳过空区域。

推理脚本中加上 --flashvdm 参数即可启用,速度提升显著。

六、快速上手:运行 Hunyuan3D-Omni 推理

一键安装步骤

环境要求 Python 3.10,依赖见 requirements.txt:

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/hu/Hunyuan3D-Omni
cd Hunyuan3D-Omni

# 安装 PyTorch 2.5.1 (cu124) 与项目依赖
pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

💡 生成一张图约需 10 GB 显存,模型权重默认从 tencent/Hunyuan3D-Omni 仓库自动下载并缓存到 ~/.cache/hy3dgen。

四种控制模式的运行命令

统一入口是 inference.py,通过 --control_type 切换控制方式:

python3 inference.py --control_type point   # 点云控制
python3 inference.py --control_type voxel   # 体素控制
python3 inference.py --control_type bbox    # 边界框控制
python3 inference.py --control_type pose    # 骨骼姿态控制

常用参数组合:

python3 inference.py --control_type point --use_ema    # 使用 EMA 权重,推理更稳定
python3 inference.py --control_type point --flashvdm   # 启用 FlashVDM 加速解码

不同控制模式的演示输入数据都放在 demos/ 目录:点云与体素为 .ply 文件(配合 data.json),姿态数据格式说明见 demos/pose/README.md,包围盒数据为 [x_min, y_min, z_min, x_max, y_max, z_max] 六元组。

Voxel 体素控制与 BBox 控制的演示输入图片

七、关键参数速查表

参数 默认值 说明
num_inference_steps 50 Flow Matching 去噪步数,越大越精细
octree_resolution 512 Marching Cubes 网格分辨率,直接决定面数与细节
mc_level 0 等值面阈值(TSDF 零平面),控制表面偏移
guidance_scale 4.5 无分类器引导强度,越大越贴合条件
--use_ema 关 使用 EMA 权重,结果更稳定
--flashvdm 关 多分辨率金字塔快速解码,大幅提速
box_v 1.01 隐式函数查询边界框大小
num_chunks 8000 隐式函数前向的分批大小,显存不足可调小

八、常见问题

Q1:为什么生成结果有浮空碎面? inference.py 内置了 FloaterRemover 与 DegenerateFaceRemover 两个后处理器(postprocessors.py),分别移除漂浮几何与退化面片,默认已启用。

Q2:如何平衡速度与精度? 提高 octree_resolution 会增加细节但也增加耗时,同时建议开启 --flashvdm;降低 num_inference_steps 可加速但可能损失形状保真度。

Q3:点云输入有什么要求? 参考 infer_point 的处理逻辑:模型会先调用 normalize_mesh 把点云归一化到以原点为中心、[-0.98, 0.98] 范围内的立方体,因此输入点云尺度影响不大,但需与图片中的物体姿态一致。

写在最后

Hunyuan3D-Omni 的 Shape-VAE 用"交叉注意力 + 隐式函数 + Marching Cubes"这一经典组合,把无序点云压缩成扩散模型友好的潜变量,再高效还原为三角网格。理解了本教程的四个步骤——点云交叉注意力编码 → 潜变量压缩 → 隐式函数解码 → 网格重建,你就掌握了 3D 生成模型中最核心的形状表示与重建链路,也能顺藤摸瓜深入 hy3dshape/ 目录下的每个模块。

登录后查看全文
Hunyuan3D-Omni