psd2live README

The project's README from github.com/tsunehimatoi/psd2live. As one markdown file: README.md.

PSD2Live

English | 日本語

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

[!IMPORTANT] 想直接使用桌面程序? Windows 10/11 x64 用户请前往 Releases 下载可执行程序。便携版 ZIP 解压即用,也可选择 EXE 或 MSI 安装包;这些发布包已包含 Java 运行时,无需配置源码构建环境。

PSD2Live 操作演示
端到端全自动建模、实时视线追踪与动态预览


文档索引

文档 描述
Agent / MCP 产品与技术设计 (docs/zh/AGENT_ARCHITECTURE.md) 从 PSD 理解、透明素材生成、可撤销长任务到 Cubism 导出的 Agent 架构、工具契约与实施阶段
用户操作指南 (docs/zh/USER_GUIDE.md) 桌面 GUI、版本历史树、独立日志坞、Agent / MCP 连接、快捷键及 CLI 参数说明
Live2D SDK 配置指南 (docs/zh/CUBISM_SDK_SETUP.md) 官方 Native SDK 许可政策、着色器提取与离屏硬件加速预览配置指南
PSD 图层规范与命名指南 (docs/zh/PSD_LAYER_SPEC.md) 31 种语义标签中日英对照、侧别规则、连通域拆分与五官/头发分层规范
变形器与算法数学规范 (docs/zh/DEFORMER_AND_PARAMETER_SPEC.md) 变形器拓扑树、九轴经纬网数学模型、C1 连续曲线、五官修形与动力学公式
实现对比与设计决策 (docs/zh/IMPLEMENTATION_COMPARISON.md) 逐流程技术选型、格式不变性与自动化几何自检说明

核心特性

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

Agent 能力与实现状态

可用

理论可行,但 Agent 暂时调不好,待实现

[!WARNING] 以下任务仅在理论上可行,当前 Agent 无法可靠调好,端到端执行极度不稳定,仍属于待实现内容。除非出于调试程序的目的,否则建议不要尝试。 已有 MCP 接口不代表 Agent 能完成任务;反复生图、定位和修正可能快速消耗大量 token 与图像生成额度,最终仍无可用结果。

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

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

目前还无法实现

[!IMPORTANT] 这类工作流要求所选模型及 Agent harness 能够实际调用图像生成能力。只有文本或视觉理解能力、但无法生成并返回图片的模型,不能完成素材创建与回填步骤。

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

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


快速上手

环境要求

启动桌面应用 (GUI)

常用快捷键

操作 快捷键 / 鼠标指令
画布缩放 鼠标滚轮(以光标为中心,0.05x ~ 64.0x)
画布平移 鼠标中键拖拽 或 左键拖拽空白
居中适配 F / Home / 0
选择画元 鼠标左键单击画元
打开 PSD Ctrl + O
重新分析 Ctrl + R
生成并导出 Ctrl + G
导出到... Ctrl + Shift + G

连接 AI Agent / MCP

  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 提供模型 View、空间映射和 PNG 导入。素材可按画风与用户偏好选择原图像素、SVG、绘画或可用图像工具;省略 solid_background 时保留原生透明度。通过 agent_get_workflow 按需读取 overview、geometry、hair、variants、face、assets。新增编辑接口与限制见 MCP 编辑指南。


命令行批处理 (CLI)

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

# 进阶参数配置
.\gradlew.bat run --args="--input ./sample.psd --output ./output --atlas 8192 --mesh-spacing 48 --head-strength 1.2 --lang zh"
参数 类型 默认值 说明
--input <path> 路径 (必需) 输入分层 PSD 文件路径
--output <path> 路径 PSD同级/psd2live-output 导出模型文件族的输出目录路径
--lang <zh|en|ja> 字符串 系统语言 界面与日志语言(支持 zh / en / ja)
--atlas <size> 整数 4096 贴图集尺寸(256 ~ 16384)
--mesh-spacing <px> 整数 64 网格基础间距(像素)
--head-strength <val> 浮点数 1.0 头部转动九轴形变幅度(0.0 ~ 4.0)
--body-strength <val> 浮点数 1.0 身体与呼吸动作幅度(0.0 ~ 4.0)
--no-physics 开关 false 不生成物理配置
--no-cmo3 开关 false 跳过 .cmo3 工程导出
--no-moc3 开关 false 跳过 .moc3 运行时导出

PSD 命名速查表

[!TIP] PSD 原画制作与构图核心建议:

  • 嘴巴张开且带描边更佳:原画口部需绘制为最大张口状态(张嘴);嘴唇外缘带有清晰描边/线稿效果更佳,向心压缩闭合时能自然贴合成清晰唇线。
  • 睫毛仅限眼部上半部分:eyelash 图层必须仅绘制上睫毛,严禁混入下睫毛或下眼眶线,以保证平滑闭眼 U 形曲线算法精准运行。
  • 初始头部允许自然倾斜:原画立绘中头部允许带有初始倾斜(歪头),系统会自动识别初始角度并以此作为中立原点展开确认转动范围。
  • 身体须保持正立(过于倾斜不受支持):躯干动作与胸腔呼吸起伏严格基于垂直坐标系构建,过于倾斜、横卧的身体不受支持。

更多分层规则与图层规范请参阅 PSD 图层规范与命名指南 (docs/zh/PSD_LAYER_SPEC.md)。

部件 推荐英文名 常用中文/日文别名 行为说明
头发 front hair, back hair 前发, 后发, 前髪, 後ろ髪 独立头壳跟随 + $v^3$ 发梢物理摆动
脸部 face, facedetail 脸, 脸部, 脸颊, 顔, 肌, 腮红 面部轮廓与细节
眼睛 eyewhite, eyelash, irides, eye_close 眼白, 睫毛, 瞳孔, 闭眼, 目, 瞳 支持自动左右拆分,瞳孔自动剪切,睫毛仅限上睫毛平滑闭眼
眉毛 eyebrow 眉, 眉毛, まゆ 支持自动左右拆分与透视联动
鼻子 nose 鼻, 鼻子 最大立体空间深度位移
嘴巴 mouth, mouth_open 嘴, 口, 嘴巴, 张嘴 最大张口原图(建议带清晰描边),自动向中线向心压缩闭口
口腔内部件 tooth-t, tooth-b, tongue 上牙, 下牙, 舌头, 歯, 舌 可选部件,自动以 mouth 为剪切蒙版
耳朵 ears 耳, 耳朵 随头部转动负深度位移与透视遮挡淡出
身体 neck, topwear, bottomwear, legwear 脖子, 上衣, 裤子, 裙子, 身体 身体偏航、俯仰、倾斜与呼吸膨胀(身体须保持正立)
饰品 headwear, earwear, neckwear, tail, wings 头饰, 耳饰, 项链, 尾巴, 翅膀 挂载于对应父级变形器

变形器层级与参数体系

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
参数 ID 名称 范围 默认值 作用说明
ParamAngleX / Y / Z 头部角度 X / Y / Z [-45..45] / [-30..30] / [-30..30] 0 头部偏航、仰俯与平面旋转
ParamEyeLOpen / ROpen 左/右眼 开闭 [0, 1] 1 睫毛平滑闭眼 U 形线,瞳孔由眼白遮罩隐藏
ParamEyeBallX / Y 视线 X / Y [-1, +1] 0 瞳孔注视追踪
ParamEyeBallForm 果冻眼 [-1, +1] 0 眨眼驱动瞳孔挤压回弹动力学
ParamBrowLY / RY 左/右眉 上下 [-1, +1] 0 眉毛上下移动
ParamMouthForm 嘴 变形 [-1, +1] 0 嘴角抬升/下压与宽度
ParamMouthOpenY 嘴 开闭 [0, 1] 0 完整张口 $\to$ 中线闭口缝平滑插值
ParamBodyAngleX / Y / Z 身体 X / Y / Z [-10, +10] 0 躯干偏航 Roll、S 形俯仰与倾斜
ParamBreath 呼吸 [0, 1] 0 胸腔高斯呼吸起伏
ParamHairFront / Back 前/后发 摇摆 [-1, +1] 0 前后发多摆物理模拟

导出产物

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
.\gradlew.bat clean test distZip

# 运行全套单元测试
.\gradlew.bat test

许可证与致谢


免责声明

psd2live (tsunehimatoi/psd2live)

Searching Database…

What is this?PSD2Live is an automated pipeline and desktop app that turns a layered PSD into an editable Live2D model: it auto-detects layer semantics, builds mesh/deformers, generates physics and idle animation, then exports a .cmo3 project plus the full .moc3 runtime file family.
Is this just a desktop app, or can I script it too?Both — it ships as a GUI desktop app (Windows/Linux/macOS) and also has a command-line batch mode with flags like --input, --output and --mesh-spacing for scripted PSD-to-model conversions.
How do I get it running?On Windows, grab the portable ZIP, EXE or MSI from the Releases page and run it (the Java runtime is bundled), or just double-click run-gui.bat; on other platforms you build and launch it with Gradle.
Do I need to install Java myself?Not if you use the Windows release packages — they already bundle a Java runtime. Building or running from source requires JDK 21 or newer via Gradle.
Do I need the official Live2D SDK for this to work?No — out of the box it uses a built-in CPU software rasterizer for rendering and export. The proprietary Cubism Native SDK is optional and only needed if you want pixel-perfect verification against the official renderer; the project doesn't bundle or distribute it.
Does it only run on Windows?No — Linux and macOS are fully supported through the built-in software rasterizer; Windows 10/11 x64 just has the extra option of configuring the official Cubism SDK for 100% pixel-matched rendering.
Can an AI agent actually edit the model for me?Yes — PSD2Live runs a local MCP server so hosts like ChatGPT/Codex or Gemini/Antigravity can read the project and reliably add simple accessories like hairpins, but tasks such as generating expression differentials or precisely reshaping meshes are still unreliable end-to-end.
Does my source PSD need special layer naming?Yes — layers should follow the recommended semantic names (front hair/back hair, eyewhite, eyelash, mouth, mouthopen, etc.); the mouth layer needs to show a fully open mouth with a clear outline, and eyelash layers must only contain the upper lashes.
What animation comes out of the box?A seamless 6-second idle.motion3.json loop combining chest breathing, slight head/body sway and natural blinking, generated automatically with no manual keyframing needed.
Size
163.9 MB
Stars
666
Age
1mo
Commits · 90 Days