10分钟跑通SQuadGen:从环境配置到生成第一个四边面网格的快速入门教程
10分钟跑通SQuadGen:从环境配置到生成第一个四边面网格的快速入门教程
SQuadGen 是微软亚洲研究院与清华大学提出的基于扩散模型的 3D 四边面网格(Quad Mesh)生成框架:输入一个三角网格,它就能自动为你规划出整齐的简单四边面布局。本教程带你用 10 分钟完成环境配置、模型下载,并生成你的第一个四边面网格,是面向新手的最快上手指南。
一、SQuadGen 是什么?为什么值得关注
在 3D 建模中,四边面网格相比三角面网格具有布线规整、易于形变和编辑等优点,但传统四边面生成工具(如 QuadriFlow)依赖复杂的全局优化,速度慢且容易失败。
SQuadGen 用了一个巧妙思路——Chart Distance Fields(CDF,图表距离场):
- 它把"四边面布局"表示成一种连续的表面场,让神经网络可以直接学习;
- 模型先编码三角网格,再通过潜空间扩散生成 CDF/DCDF 场,最后从场中提取出简单四边面布局;
- 整个流程是离线批处理,一次生成一个完整布局。
一句话总结:你给它一个三角面 3D 模型,它还你一张布线整齐的四边面网格,非常适合做 3D 建模、CAD 与图形学方向的快速实验。
二、环境要求:动手前 1 分钟检查清单
SQuadGen 推理计算量较大,必须使用带 CUDA 的 NVIDIA GPU,官方速度测试基于 A100。开始前请确认:
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux(推荐) |
| GPU | NVIDIA CUDA 显卡,显存建议 16GB 以上 |
| Python | 3.10 左右,配合官方环境说明安装依赖 |
| 磁盘空间 | 约 10GB+(两个权重文件较大) |
| 网络 | 能访问模型仓库以拉取 LFS 大文件 |
💡 提示:完整的环境依赖、数据准备与训练/评估脚本维护在官方代码仓库中,本仓库是模型发布仓库,只存放预训练权重与配套配置,两边配合使用。
三、下载 SQuadGen 预训练模型权重
本仓库包含官方推理所需的全部权重文件:
# 克隆仓库(若本地已有可跳过)
git clone https://gitcode.com/hf_mirrors/microsoft/SQuadGen
cd SQuadGen
仓库 ckpts/ 目录下的文件构成如下:
| 文件 | 说明 |
|---|---|
| ckpts/sqvae_geomae.safetensors | SQ-VAE(约 112M 参数)+ Geom-AE(约 107M 参数)合并权重 |
| ckpts/sqvae_geomae.yaml | 与上述权重匹配的网络结构配置 |
| ckpts/sqdiffuse.safetensors | SQ-Diffuse 扩散模型权重(约 802M 参数) |
| ckpts/sqdiffuse.yaml | 与扩散模型匹配的结构配置 |
⚠️ 新手最容易踩的坑:这四个文件体积很大(扩散模型权重约 3.2GB),克隆时需要正确启用 Git LFS,否则只会下载到几 KB 的指针文件。若文件异常小,执行 LFS 拉取补齐真实权重即可。
四、配置检查点路径:生成第一个四边面网格
推理脚本位于官方代码仓库中,核心思路是把两个权重文件通过参数指给推理脚本:
--ae_pth:指向 SQ-VAE + Geom-AE 权重(即sqvae_geomae文件)--model_pth:指向 SQ-Diffuse 权重(即sqdiffuse文件)
例如,权重下载在 ./ckpts_hf/ckpts/ 时,把 ./ckpts_hf/ckpts/sqvae_geomae.* 与 ./ckpts_hf/ckpts/sqdiffuse.* 分别传给对应参数即可。
推理的完整流程可以理解为三个阶段:
- Geom-AE 编码:把三角网格编码成 1024 个潜在点特征;
- SQ-Diffuse 生成:在潜空间中扩散生成 CDF 布局场;
- SQ-VAE 解码:还原出每顶点的 CDF/DCDF 场,再从中提取简单四边面布局。
输入要求是三角网格,输出是可直接用于下游建模与编辑的四边面布局。
五、推理速度参考:A100 上要花多久
官方在 NVIDIA A100 上给出的实测数据,方便你估算本地耗时:
| 阶段 | 4096 采样点 | 8192 采样点 |
|---|---|---|
| Geom-AE 编码 | 0.4s | 1.2s |
| SQ-VAE 编码/解码 | 0.4s / 0.4s | 1.3s / 1.2s |
| SQ-Diffuse 生成 | 65.9s | 171.7s |
结论:4096 点规模下,一次完整生成大约 1 分钟左右,与"10 分钟跑通"的节奏完全吻合;采样点翻倍则扩散阶段耗时约翻 2.6 倍。
六、新手常见疑问 FAQ
Q1:生成质量不理想怎么办? 模型在常见物体类别、干净网格上表现最好;对稀有形状、噪声扫描、非流形网格、复杂拓扑等"分布外"输入效果会下降。建议先用简单、干净、封闭的三角网格试跑。
Q2:输出可以直接用于 CAD 或制造吗? SQuadGen 是研究原型,生成结果是"学习到的近似",不保证几何正确性与可制造性。下游使用前请自行校验输入几何与输出质量,重要环节保留人工审核。
Q3:训练数据来自哪里? 模型在公开 3D 几何数据集上训练,包括 Objaverse、Amazon Berkeley Objects(ABO)与 ShapeNet,相关数据集的使用条款仍对使用者适用。
Q4:想修改超参数或复现训练? 所有推理/训练/评估脚本以官方代码仓库为准,本仓库提供的是与之匹配的权重与配置,两者版本需保持一致。
七、总结:你的 SQuadGen 上手路线图
- ✅ 检查环境:Linux + NVIDIA CUDA GPU + 充足磁盘;
- ✅ 克隆本仓库,确认 LFS 权重完整下载;
- ✅ 从官方代码仓库获取推理脚本并安装依赖;
- ✅ 用
--ae_pth/--model_pth指向上文的两个权重文件; - ✅ 喂入一个干净的三角网格,等待约 1 分钟,收获第一个四边面网格 🎉
SQuadGen 用"图表距离场 + 潜空间扩散"把四边面布局生成变成了可学习的端到端任务,是图形学入门者快速体验 AI 驱动 3D 建模的绝佳入口。现在就可以动手跑起来!
更多模型细节(作者、参数量、输入输出格式)可查看 README.md,扩散模型结构参数(如 28 层 Transformer、16 注意力头)定义在 ckpts/sqdiffuse.yaml 中,SQ-VAE 的潜空间维度与注意力深度则配置在 ckpts/sqvae_geomae.yaml。