PSD2Live

English | 日本語

PSD2Live 是一个自动化的 Live2D 模型生成流水线与桌面应用。输入分层 PSD 文件，系统自动完成图层语义识别、连通域双侧拆分、自适应三角网格剖分、九轴面部经纬网与解耦变形器层级构建、头发多摆物理与果冻眼动力学模拟及循环待机动作生成，一键导出可编辑的 .cmo3 编辑器工程与运行时 .moc3 文件族。

端到端全自动建模、实时视线追踪与动态预览

• 自适应网格剖分：基于可分离高斯平滑滤波与 95th 百分位自适应二值化消除边缘噪点；采用带物理窗口角点识别的周期三次 Bézier 曲线拟合与曲率加权加密采样（最高 12 倍）；执行受约束 Delaunay 剖分结合拓扑动态收敛 Lawson 翻边与超长内部边中点二分细分。

  
  网格间距 22 / 64 / 115 px：从精细轮廓到轻量拓扑的密度对比

• 变形器 (Warp) 生成：

  • 眼/口 变形：眼睛与眉毛共享透视平面约束，瞳孔自动反向补偿防止挤压，睫毛沿 Alpha 权重中线弯曲生成平滑闭眼 U 形曲线；嘴部以最大张口为基准向中线平滑向心压缩闭合，牙齿与舌头自动以嘴部为剪切蒙版。
  • 九轴构建：建立 AngleX (±45°) × AngleY (±30°) 8×8 面部经纬网，结合 C1 连续水平展开/压缩曲线（近侧展开、近眼宽平台保持、远侧透视压缩）、垂直 V/^ 仰俯曲率及四角 $C_{xy} = \text{yaw} \times \text{pitch}$ 交叉修正项。

• 动画：自动生成 6 秒无缝循环 idle.motion3.json 平滑待机动作，涵盖胸腔呼吸起伏、轻微头部/身体倾斜摇摆及自然眨眼；桌面 GUI 支持可选接入官方 Cubism 5-r.5 SDK 原生着色器离屏渲染引擎以获得 100% 官方渲染与物理一致性验证（Ground Truth）（本项目不包含且不分发官方 SDK 二进制，详见 SDK配置指南；未配置时无缝自动回退为纯 CPU 高精度软件光栅化渲染），支持实时鼠标视线追踪（Mouse Look）与动作回放。

• 物理：前后发完全解耦独立跟随头壳，基于发根固定与 $v^3$ 立方发梢摆幅梯度的多摆物理系统；左右眼开合速度物理驱动二阶阻尼弹簧振子输出果冻眼挤压/回弹动力学（ParamEyeBallForm）。

• Agent / MCP 可编辑工作区：应用启动后在本机提供带 Bearer Token 的 Streamable HTTP MCP。ChatGPT/Codex、Gemini/Antigravity 或其他 MCP 宿主可读取工程与参数、渲染带可逆画布映射的 PNG View、导入透明素材、增删参数，以及针对 ArtMesh、Warp、Rotation、Part、Glue 写入、复制或删除多参数 K 帧。每次修改都会进入追加式分支历史；版本树、长任务检查点和素材均可持久化恢复。

• 工程文件/运行时文件导出：一键同步导出可在 Live2D Cubism Modeler 5 中二次编辑的 .cmo3 完整工程与运行时 .moc3 文件族（包含 .model3.json、.cdi3.json、physics3.json、idle.motion3.json 及纹理贴图集）；内置中立姿态保真、极限姿态完整性与变形器镜像对称性三道几何自检闸门。

Agent 添加发卡的案例：读取 Skill 与 MCP 工具、查看模型、生成并添加素材、检查其他参数姿态。该案例不代表下列更复杂任务已可用。

• 添加其他头饰或装饰物，再从多个参数姿态检查遮挡关系、位置和变形效果。

预计实现难度按以下顺序逐渐增加：

1. 生成表情和动作差分，并附加参数或动画控制，例如 @v@ 表情、挥手、双臂交叉动画。
2. 将角色口腔拆分为嘴唇、口腔内部、牙齿和舌头等可独立编辑的图层。
3. 将头发拆分为前发、侧发、后发、呆毛或其他可独立绑定的发束，并补全被遮挡的区域。
4. 添加阴影，包括头发阴影图层、侧脸阴影图层的生成与绑定。

• 对部件进行合理、精确的变形：这需要 AI 逐点操作 Warp/Mesh，并正确控制各点的形变。目前 Agent 尚不具备可靠完成这种操作的能力。

最终效果受模型、图像生成器、Agent harness、提示词和原始 PSD 分层质量共同影响。底层工具的回归测试通过，不等于上述待实现任务已具备可靠性。

征求 Prompt 工程与 Agent 工作流相关 Pull Request。 目前尤其需要有相关经验的贡献者协助改进工具发现与选择、拆分对象的深度/遮挡理解、生成约束、定位与修正流程，以及 token 预算和停止条件。欢迎提交可复现案例、有效的提示词或 Skill 改进、工作流实现与评测用例；请尽量附上所用模型和宿主、实际消耗、成功与失败结果，帮助验证改进是否能提高完成率并减少无效重试。单次成功演示不足以将这些能力标记为已完成。

• Java Runtime：从 Releases 下载的 Windows 发布包已包含运行时；仅从源码使用 Gradle 构建或启动时需要 JDK 21 或更高版本。
• 操作系统：Windows 10/11 x64（配置官方 Native SDK 时可实现与官方运行时 100% 像素级渲染与物理一致性对照），亦全面支持 Linux / macOS（内置 CPU 软件光栅化渲染）。
• Live2D 官方 SDK 说明：本项目源码与发布包不包含且不分发 Live2D 官方 SDK 专有二进制文件，开箱即可使用内置渲染与全部导出功能；如需开启官方渲染一致性验证，请参阅 Live2D SDK 配置指南。

• Windows 一键启动：运行根目录下的 run-gui.bat。
• Gradle 启动：

  # Windows
  .\umamo\gradlew.bat -p .\psd2live run
  
  # Linux / macOS
  ../umamo/gradlew -p ./psd2live run

1. 保持 PSD2Live 桌面应用运行，打开顶部 Agent / MCP → Agent / MCP 连接与安装…。
2. 在“连接配置”页复制宿主对应的配置：ChatGPT Desktop / Codex 使用 HTTP TOML，Gemini / Antigravity 使用 HTTP JSON。其他支持 Streamable HTTP 的宿主使用界面显示的端点和 Authorization: Bearer <Token> 请求头；不要改成旧 /sse 地址。
3. 仅当宿主不支持 HTTP MCP 时，复制 Stdio JSON，通过 Python 3 运行仓库根目录的 mcp_proxy.py。代理优先读取 PSD2LIVE_MCP_TOKEN；Windows 上也可读取 PSD2Live 已保存的 Token。
4. 如需领域工作流，把 .agent/skills/psd2live-rigging 与 .agent/skills/hair-separation 复制到宿主官方技能目录。连接后先列出工具并调用 project_get_state。

当前 MCP 支持工程/图层/参数读取、对象与 K 帧编辑、参数 CRUD、模型数据 PNG View、透明素材导入、软删除、可恢复任务，以及追加式分支历史。每个会推进工程 HEAD 的编辑操作都要携带最新的 expected_history_head_node_id；超时或断线后先用 project_get_state 和 history_list 确认是否已经提交，不能盲目重试。

PSD2Live MCP 负责模型 View、空间映射与素材回填，不提供宿主私有的图片生成器。差分、部件拆分、遮挡补全或像素重建应实际调用宿主原生的 Nano Banana Pro/NBP、GPT Image 2（gpt-image-2）或等效图片能力，再把透明 PNG 交给 asset_import_png；不得用 Python、PIL/OpenCV、SVG 或 Canvas 绘制替代素材。详细界面与配置说明见 用户操作指南，工具契约与实施状态见 Agent / MCP 产品与技术设计。

# 基础运行
.\umamo\gradlew.bat -p .\psd2live run --args="--input ./sample.psd --output ./output"

# 进阶参数配置
.\umamo\gradlew.bat -p .\psd2live run --args="--input ./sample.psd --output ./output --atlas 8192 --mesh-spacing 48 --head-strength 1.2 --lang zh"

Root (Canvas Space)
 └─ DeformBodyXY (ParamBodyAngleX, ParamBodyAngleY)
     └─ DeformBodyZBreath (ParamBodyAngleZ, ParamBreath)
         └─ DeformHeadRotation (ParamAngleZ)
             └─ DeformHeadContainer (ParamAngleX, ParamAngleY 头壳跟随)
                 ├─ DeformFaceNinePose (ParamAngleX, ParamAngleY 九轴经纬网)
                 │   ├─ Eye / Iris / Brow / Nose / Mouth / Ear
                 │   └─ FaceDetails
                 ├─ HairFrontFollow → HairFrontPhysics (ParamHairFront)
                 ├─ HairBackFollow  → HairBackPhysics  (ParamHairBack)
                 └─ HeadAccessories

output_dir/
├── sample.cmo3                    # 可在 Live2D Modeler 5 中二次编辑的完整工程
├── sample.moc3                    # 运行时模型文件 (MOC5 基线)
├── sample.model3.json             # 运行时配置文件 (贴图、物理、动作接线)
├── sample.cdi3.json               # 显示名称元数据
├── sample.physics3.json           # 物理模拟配置 (头发多摆 + 果冻眼)
├── sample.idle.motion3.json       # 6 秒无缝循环平滑待机动作
├── sample.4096/texture_00.png     # 纹理贴图集
└── sample.psd2live.json         # 诊断报告与映射元数据

# 编译并打包独立运行 ZIP
.\umamo\gradlew.bat -p .\psd2live clean test distZip

# 运行全套单元测试
.\umamo\gradlew.bat -p .\psd2live test

• 开源许可证：本项目采用 GNU General Public License v3.0 (GPL-3.0)。
• 第三方参考与致谢：本项目运行时通过 Gradle Composite Build 链接了 Umamo 模块，并在语义规范、网格算法与物理设计上参考了 Stretchy Studio。详细说明请参阅 THIRD_PARTY_NOTICES.md。

• PSD2Live 是独立开发的开源项目，与 Live2D Inc. 及其关联方不存在任何隶属、授权或赞助关系。
• Live2D、Cubism、.cmo3、.moc3 等名称与文件扩展名仅用于格式兼容性说明，其商标与知识产权归各自权利人所有。本项目不包含且不分发 Live2D 官方 SDK。
• 本项目按“现状”提供，请在正式生产前备份原始 PSD 文件，并在目标软件中检查生成效果。