English | 简体中文
面向 Windows + AMD Radeon RX 5000/6000/7000 系列的 DirectML Image-to-3D 工作流。
Modly-Turnaround 要填补的明确缺口，是主流 Image-to-3D 工具没有完整覆盖的 Windows + AMD GPU 本地生产路径。它把横向排列的 正面 / 左侧 / 背面 图交给本机 Modly API 和 Hunyuan3D 多视图节点生成白模，再以确定性纹理投影完成 UV、颜色图集、PBR GLB 与离线验收预览。
本项目是 Modly 的配套工具，不是 Modly，也不随包分发 Modly、模型权重或完整 Python 运行环境。运行完整流水线前，必须单独安装兼容版本的 Modly，并启动其本地 API。
公开发行边界： 发布脚本会无条件排除整个
third_party/hunyuan3d/。公开 ZIP 不包含 Hunyuan 源码、源码归档、模型权重或上游许可副本；使用者必须自行提供其有权使用的完整 DirectML 兼容source_root。
现有主流 Image-to-3D 工具对 Windows + AMD 用户存在明确缺口：
- Modly 0.4.1 与当前
main：扩展安装器的 GPU 探测路径运行nvidia-smi；Windows AMD 环境无法通过该探测，安装参数会回退到 CPU。 - Linux ROCm 提案（PR #235）：目前仍处于未合并状态，而且 ROCm 检测显式限定为 Linux，不提供 Windows AMD 加速路径。
- ZLUDA：在本项目的 RX 6750 GRE 测试机上可以枚举显卡，但最小 PyTorch 张量加法等待 124 秒仍未完成，未通过扩散模型生产推理门槛。该结果是本机实测，不泛化为所有硬件上的
fp16缺陷结论。 - DirectML：通过 Windows 的 DirectX 12 图形适配器运行。本项目的兼容修改已经在 RX 6750 GRE 上完成模型加载、去噪、几何解码、GLB 导出和完整三视图任务。
因此，DirectML 是本项目目前在 Windows AMD 环境中唯一完成端到端生产验证的 GPU 路径。项目以 RX 5000/6000/7000 系列为兼容性目标；当前生产级实测仍仅覆盖 RX 6750 GRE 10 GB。其他型号、驱动和显存组合必须先运行真实 DirectML 验收，不能仅凭“可枚举 GPU”视为已经兼容。
- 校验三视图尺寸、顺序、可见主体和本机资源。
- 通过
hunyuan3d-mini/turnaround顺序生成 GLB 白模。 - 为批任务保存原子 JSON 清单，支持中断恢复、输出哈希校验和有限重试。
- 清理退化面、修正反向封闭组件，并通过 xatlas 生成 UV。
- 将正面、左侧和背面颜色投影到网格，输出内嵌纹理的 PBR GLB。
- 使用本机 Edge 或 Chrome 渲染固定视角预览并生成验收报告。
- 为已验证的 Windows AMD DirectML 运行栈提供安装、诊断和资产恢复工具。
当前生产验证范围是：
- Windows x64
- AMD Radeon RX 6750 GRE 10 GB
- AMD 驱动
32.0.21030.2001 - Python 3.11.15 模型运行环境
- PyTorch 2.4.1、torchvision 0.19.1、torch-directml 0.2.5.dev240914
- Modly 0.4.1 的本地 API 与
hunyuan3d-mini扩展
其他 AMD 显卡、驱动、Modly 版本和操作系统尚未经过同等级端到端验证。ZLUDA 与 Windows ROCm 在上述机器上的首个真实张量探测失败，因此不属于生产路径。
在 PowerShell 中进入项目根目录：
powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1
.\scripts\doctor.ps1模型资产准备完成后，再使用 -RequireModly -RequireAssets 执行完整诊断；缺失资产的可恢复安装见快速开始和验收。
启动外部 Modly API。路径必须指向你已经安装好的 Modly 和准备好的运行根目录：
.\scripts\start_modly_api.ps1 `
-ApiDir "C:\path\to\Modly\resources\api" `
-Python "C:\path\to\api-venv\Scripts\python.exe" `
-RuntimeRoot ".\runtime" `
-ModelRoot ".\runtime\models\hunyuan3d-mini\turnaround" `
-SourceRoot ".\runtime\models\hunyuan3d-mini\generate\_hy3dgen" `
-OfflineAPI 就绪后运行完整流水线：
& .\.venv\Scripts\python.exe .\src\pipeline.py ".\inputs" `
--output-dir ".\outputs" `
--preset production `
--seed 12345默认生产参数为 30 步、380 网格分辨率、引导强度 5.0、自动解码器、2048 像素纹理图集、1024 像素投影视图和 1024 像素验收预览。首次使用前请完整阅读快速开始和输入规范。
- 输入只有左侧图，没有真实右侧图；右向纹理来自左侧镜像。
- 头顶、脚底和完全遮挡区域使用邻近可见颜色补全，不能恢复不存在的信息。
- 上色是正交视图投影，不是生成式纹理，也不是相机标定或特征重建。
- Hunyuan Paint 依赖 CUDA 原生光栅化扩展，当前 DirectML 路径不支持。
- 投影上色不会增加面部几何。白模脸形错误时，纹理只能贴到错误的曲面上。
- 上色阶段把输入作为静态三角网格处理，不承诺保留骨骼、动画、Morph、相机、灯光、原材质或场景层级。
完整边界见限制与适用范围。
| 文档 | 内容 |
|---|---|
| 快速开始 | 从安装、诊断到生成、上色和导入 Modly |
| 架构 | 组件、数据流、进程边界和产物 |
| 输入规范 | 三视图顺序、尺寸、构图和批量目录 |
| 配置 | 配置文件、CLI 和环境变量优先级 |
| AMD DirectML | 已验证运行栈、显存策略和后端边界 |
| Modly 接入 | 外部安装、API、模型节点和模型导入 |
| 批处理与续跑 | 预设、清单、重试、取消和恢复 |
| 纹理投影 | UV、可见性、视图混合和 PBR 输出 |
| 验收 | 预检、哈希、预览、报告和发布门禁 |
| 故障排查 | 常见错误、诊断顺序和恢复办法 |
| 限制 | 技术、质量、兼容性和数据边界 |
| 发布 | 测试、打包、校验和发布清单 |
| 许可 | 项目、Modly、Hunyuan 与第三方许可边界 |
完整英文文档见 English documentation。
.\scripts\test.ps1 -SkipDirectML测试覆盖批任务状态机、输入校验、GLB 验证、本地 API 启动契约和 PBR 预览。真实 AMD 验收还需单独的 torch-directml 环境，并通过 -DirectMLPython 传入其解释器；完整命令见 AMD DirectML。真实模型生成耗时很长，不属于默认单元测试。
任何人都可以提交 Issue、改进建议和 Pull Request，无需签署 CLA。贡献前请阅读 CONTRIBUTING.md。安全问题请按 SECURITY.md 私下报告。
本项目贡献者有权许可的原创工具代码与文档采用宽松的 MIT License。用户自行提供的 Hunyuan 材料、外部 Modly 和其他第三方依赖不是同一个许可主体，也不因本项目采用 MIT 而被重新许可。尤其是 Tencent Hunyuan 3D 2.0 Community License 存在地域、分发、用途和大规模商业使用限制。本项目不提供法律意见；获取或使用外部 Hunyuan 材料前，请阅读许可说明、第三方声明以及该材料合法来源提供的完整许可文本。