lightningpixel/modly

Modly – 基于AI的图像转3D桌面应用

是什么 – Modly 是一个跨平台桌面应用程序（Windows、Linux、Apple-Silicon macOS），可将单张照片转换为3D网格。所有处理均在本地GPU上使用开源AI模型运行，无需依赖云服务。

如何工作 – UI 使用 Electron/Node.js 构建，并与 Python 后端（FastAPI）通信。后端加载选定的基于扩散的3D生成模型（例如 Hunyuan3D、TripoSG、Trellis2），并在您提供的图像上运行推理。生成的网格可进行检查、平滑、简化，并保存为 GLB/OBJ 文件。

主要功能

• 本地GPU推理 – 支持 NVIDIA、AMD（通过 ROCm）和 Apple-Silicon GPU。
• 扩展系统 – 模型和处理步骤以 扩展（包含 manifest.json 的 GitHub 仓库）形式打包。列出了多个前沿3D生成器的官方扩展，用户也可添加自己的扩展。
• 多源模型权重 – 扩展可以从多个 Hugging Face 仓库拉取模型部分，并在下载前进行完整性检查。
• 共享权重组与变体 – 扩展可在多个节点间共享通用文件，并暴露量化变体（如 Q4_K_M、Q5_K_M），附带大小/VRAM 提示。
• 工作流编辑器 – 拖拽式图谱，可连接节点如 图像 → 生成网格 → 添加到场景。
• CLI代理 – 纯Python命令行工具（tools/modly-cli/agent.py）可程序化驱动应用（健康检查、列出模型、运行生成、查询运行状态等）。
• 实时RAM指示器 – 在顶部栏显示当前内存使用情况。
• 应用内网格后处理 – 内置平滑和简化功能。

快速开始

1. 克隆或下载 仓库（或使用发布页面的安装程序）。
2. 安装 JavaScript 依赖：npm install。
3. 设置 Python 后端：

   cd api
   python -m venv .venv
   source .venv/bin/activate   # Windows 上使用 .venv\Scripts\activate
   pip install -r requirements.txt
   

4. 运行开发版本：npm run dev（或使用 launch.bat / launch.sh 启动打包应用）。

平台说明

• AMD GPU – 自动检测；无需单独安装 ROCm，直接使用兼容 ROCm 的 PyTorch 轮子。
• macOS – 仅支持 Apple-Silicon；应用使用原生窗口控制。
• 打包 – 可通过 npm run package:mac 创建 macOS Apple-Silicon 构建版本。

扩展 Modly

• 创建一个包含 manifest.json 和所需入口文件（模型节点、处理节点等）的 GitHub 仓库。
• 通过 UI 安装：模型 → 从 GitHub 安装 → 粘贴仓库 URL。
• 扩展可声明：
  • model_sources 用于从 Hugging Face 下载权重。
  • weight_groups 用于在多个节点间共享文件。
  • weight_variants 用于暴露量化或精度变体，并可选附带大小/VRAM 元数据。

CLI 使用示例

# 检查应用是否运行
python tools/modly-cli/agent.py health

# 列出可用模型
python tools/modly-cli/agent.py model list

# 从图像生成网格
python tools/modly-cli/agent.py generate --image ./cat.png --output ./cat.glb

CLI 输出机器可读的 JSON，包含运行ID、状态和错误信息，适用于自动化脚本或代理。

社区与支持 – 提供 Discord 服务器用于公告、错误报告和用户反馈。

许可证 – MIT。分叉必须根据许可证要求保留对原始 Modly 项目的署名。

---

以上所有细节均直接取自仓库的 README。