https://github.com/user-attachments/assets/turntable-preview

💡 解决什么问题

AI 文生 3D（Lux3D 等）产出的模型看似精美，直接送 FDM 打印机却常常翻车：

修复完成后交付可直接切片的 3MF，并附一张人类可读的「缺陷着色诊断图」—— 灰色=正常 · 蓝色=贴床 · 红色=悬垂 · ◆=最薄壁位置，配中文指标与修复步骤说明。

🚀 30 秒接入（MCP）

在任意 MCP 客户端（Claude Desktop / Cursor / OpenCode / 魔搭 MCP 实验场…）配置中添加：

{
  "mcpServers": {
    "PrintGuard_Aholo": {
      "command": "uvx",
      "args": ["printguard-aholo@latest"],
      "env": {
        "AHOLO_API_KEY": ""
      }
    }
  }
}

• 首次调用自动从 PyPI 安装（需先安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh）
• AHOLO_API_KEY 可留空：检测/修复已有模型完全不需要 key；仅生成新模型需要 （免费申请），也可在每次工具调用的 api_key 参数中提供
• 接入后对 Agent 说："帮我做一个能打印的手机支架，高 10 厘米"

☁️ 免安装形态：本服务已上架 魔搭 MCP 广场（hosted）， 由魔搭 MCP 部署服务的平台算力托管运行，社区用户无需安装任何环境。 另有网页 Demo（创空间）正在改造中，见下方部署形态。

🧰 工具一览

推荐工作流：概念先行

用户描述 ──▶ lux3d_concept_image ──▶ 用户看到概念图
                 ▲                        │
                 └── 不满意？新想法重新生成 ┘
                                          │ 满意
                                          ▼
              （可选）lux3d_four_view 锁定四视图
                                          │
                                          ▼
        printguard_start_job(concept_image_url / four_view_urls)
                                          │
                    ▼ 体检 ── ▼ 修复 ── ▼ 摆向 ── ▼ 交付 3MF + GIF + 报告

概念图先行的价值：图片迭代的成本远低于 3D 生成，用户在昂贵的生成步骤前锁定设计。 实测：概念图 ~47s，G1-Turbo 图生 3D ~15s。

两档质量自动适配：fast（G1-Turbo + 100k 面，结构件，端到端 ~2 分钟）/ fine（G1 + 300k 面 + 0.3mm 细体素，手办细节件，~10 分钟）。

📦 交付物

本地 stdio 形态以绝对路径交付；云端/托管形态以 HMAC 签名限时下载链接交付（防篡改、可过期）。

📊 实测数据

🏗️ 技术内核

针对「AI 生成件 = 稀疏拓扑 + 非水密 + 长条面片」这一恶劣输入专门设计：

• 采样体素化：以面积加权的表面采样替代 trimesh 细分式体素化，内存与三角面尺寸 彻底解耦——稀疏网格上一个横跨模型的长三角形不再引发千万级子面爆炸 （实测 130mm/30 万面件从 >7GB OOM 降至 6.2GB 完整修复）
• 棱边采样 + 三明治实心化：面内采样封不住网格棱边接缝，贴边薄洞在经典 closing 下数学上不可封——改用「膨胀 → fill_holes → 腐蚀」，薄壳安全且体积精确
• 中轴 EDT 壁厚：距离变换 → 局部极大（中轴）→ T = 2D − pitch 量化补偿， fail/warn/pass 三级判定自带亚分辨率保护带
• 悬垂三分类：沿重力方向体素下探 10mm，区分真悬空（需支撑）/ 桥接（两层之间）/ 贴材料（下方连续），避免「叠放件全是悬垂」的误报
• 闭环壁厚修复：探测 fail 中轴 → 定向膨胀 → 复检收敛，设膨胀预算上限， 超限如实报告「发丝级细节建议重设计」而非静默糊死
• 自动摆向：以悬垂面积最小化为目标旋转摆放，先于一切检测执行

🌐 部署形态

架构说明：MCP 服务本体运行于魔搭 MCP 部署服务的平台算力；创空间定位为产品 Demo—— 作为 MCP 的调用方提供网页交互，与服务运行解耦。

🔍 质量保障

• python printguard.py selftest：8 个合成用例（补洞/双球/悬垂/薄板/立方/堆叠 + GLB 往返 + 大面片重载），覆盖检测、修复、交付全链路
• GitHub Actions 持续执行上述自测（见 .github/workflows/ci.yml）
• 版本化发布：PyPI · @latest 永远指向最新

🗺️ Roadmap

• 托管实例产物直传对象存储（修复 hosted 模式文件交付）
• 内存二阶段优化（6.2GB → 4GB，EDT float32 化与分块 EDT）
• 图生 3D 深度整合（多图参考）
• 切片参数建议（层高/支撑密度按模型特征推荐）
• 多语言 README

📖 文档

• PrintGuard_Aholo.md —— 技术方案与设计决策（Lux3D 接入、算法选型、工程约束）
• docs/deploy-modelscope.md —— 魔搭创空间部署指南
• mcp_server.py —— MCP 服务实现（stdio / streamable-http 双传输）

📄 License

MIT © PrintGuard_Aholo contributors