Hunyuan3D-Omni Shape-VAE深度教程:从点云交叉注意力编码到Marching Cubes网格重建
Hunyuan3D-Omni Shape-VAE深度教程:从点云交叉注意力编码到Marching Cubes网格重建
Hunyuan3D-Omni 是腾讯混元团队开源的统一可控 3D 资产生成框架,其中 Shape-VAE 负责把 3D 形状压缩为低维潜变量,再通过点云交叉注意力编码与 Marching Cubes 完成网格重建。本教程面向新手,带你读懂 Shape-VAE 的完整数据流:点云 → 交叉注意力编码 → 隐空间潜变量 → 隐式函数 → 三角网格。
一、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/ |
Shape-VAE 本身由三部分构成(见 shape_vae.py 中的 ShapeVAE 类):
- PointCrossAttentionEncoder(L47):把表面点云压缩成一组潜变量(latents);
- Transformer 解码器:对潜变量做自注意力交互,恢复表达能力;
- 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)非常简洁:
input_proj:线性投影 Query 与 Data;cross_attn:交叉注意力,Query 从 Data 聚合信息;self_attn(可选的 Transformer 层):潜变量之间互相交流。
三、第二步: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):
post_kl把潜变量映射回宽维空间;transformer自注意力层恢复全局几何结构;query_geometry(L505):CrossAttentionDecoder对任意空间坐标做查询,输出一个标量——该点到表面的隐式距离值(SDF/TSDF)。
这一步把"离散的潜变量"变成了"连续空间上的隐式函数",为下一步提取网格做好了准备。
五、第四步:Marching Cubes 网格重建
这是本教程的最后一环:如何从隐式函数得到可以渲染的三角网格?
1. 均匀网格采样(vanilla 方式)
基础实现见 extract_geometry_vanilla.py,流程如下:
- 生成密集网格点:generate_dense_grid_points 在边界框
bounds=[-1.01, -1.01, -1.01, 1.01, 1.01, 1.01]内生成octree_resolution分辨率的均匀坐标格点(如 512³); - 分批前向:按
num_chunks(默认 8000)分批把格点送入geometric_func,得到每个格点的隐式函数值; - Marching Cubes 提取:调用
scikit-image的measure.marching_cubes(method="lewiner",L119),在等值面mc_level(默认 0,表示 TSDF 零平面)处插值出三角形面片; - 输出
trimesh.Trimesh网格对象。
2. 加速版:FlashVDM 多分辨率金字塔
vanilla 方式要查询 512³ ≈ 1.3 亿个点,非常耗时。extract_geometry_fast_v2.py 中的 FastGeometryExtractorV2 采用由粗到细的金字塔策略:
- 先在低分辨率网格上求值;
- 用 3D 膨胀(dilate)找到"表面附近"的体素邻域,只在这些位置继续细化;
- 逐级上采样到目标分辨率,最后只在有效区域内做 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] 六元组。
七、关键参数速查表
| 参数 | 默认值 | 说明 |
|---|---|---|
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/ 目录下的每个模块。




