MysteryGodzilla/live2d

从一张画生成Live2D模型

本工具套件可将一个角色的全身插画转化为Live2D模型，供AIRI或Open-LLM-VTuber等应用加载。脚本完成主要工作。您需要按顺序运行步骤，检查每个步骤的结果，并在下一步基于它构建之前修正任何偏差。早期带入的问题（例如图层位置错误）会在后期表现为更难以追踪的缺陷（例如腿被大衣遮挡）。

所有操作均通过一条命令从项目目录内完成：

python <this folder>/live2d.py <step> <name> ...

<name> 是角色的文件夹名称。live2d.py 会选择每个步骤所需的Python并打印所执行的命令。在创建第一个角色之前，请阅读此文件夹中的 README.md：它包含下载说明、设置文件、每个步骤及其命令，以及图层修正表。本文件指导您如何高效完成工作。

还有一个面向用户的GUI（live2d.py gui：相同步骤显示为页面按钮）；代理应使用命令行。

开始之前

1. 执行 live2d.py check。它会列出已安装和缺失的步骤所需组件。如果缺少某个组件，请告知用户缺少什么以及它的来源（README中的“你需要什么”）。下载文件可能有数GB：在开始下载前征询用户同意。如果项目之前未使用过本工具套件（check 显示没有 live2d-kit.json），请先从项目的顶层目录执行 lived.py init。它会创建设置文件、外观文件以及本技能的指针，并且不会更改任何已存在的文件。init --like <another project> 会从已有工具路径的项目中复制路径。
2. 执行 live2d.py status <name>。它会标记已完成步骤并显示下一步命令。每次重新处理一个角色时请使用此命令，而不是从文件中猜测。
3. 在执行需要显卡的步骤（绘制、抠图、放大、拆分）之前询问用户。这些步骤需要独占显卡，用户可能正在使用。split 在空闲显卡上每次大约需要10分钟，如果其他任务占用部分显存则可能需要数小时：请提前告知用户，并在后台运行。
4. draw --runpod 需要付费。仅在用户要求时使用。
5. 仅启动和停止您启动的内容。live2d.py comfy status 显示ComfyUI是否正在运行以及谁启动了它：本项目或其他文件夹（如果是其他文件夹，则属于他人：可以使用它，但不要停止它）。comfy stop 仅停止本项目的 comfy start 启动的实例。在绘制、抠图和放大步骤完成后停止您的实例。

步骤及每步后的检查内容

步骤	命令	判断正确的标准
绘制	comfy start，然后 draw <round> --character <name> --seeds ...	用户选择一个。向他们展示联系表。除非用户要求，否则不要替他们选择
选取	pick <name> <picture>	插画符合README中“适合绑定的插画”要求。如果不符（手臂贴在身体上、双腿并拢、手中拿着道具），请在继续前说明会出现什么问题
抠图、放大	cutout <name>，upscale <name>，comfy stop	full/cutout.png 显示角色的完整身体且无背景。通过 draw 生成的插画自带透明度：pick 已经完成了抠图，因此 cutout 不会执行任何操作，仅需进行 upscale
拆分	split <name> body	它会打印出角色的图层。预计约17个：头发、面部、眼睛、眉毛、鼻子、嘴巴、颈部、衣物、手臂、腿、鞋子
检查图层	layers check <name>	计数应为几千像素的细轮廓。查看其保存的图片。大块红色区域表示图层覆盖了不应覆盖的内容
头部处理	split <name> head，layers scale <name> 2，layers head ...，layers under <name> neck face	再次执行 layers check：计数不应跳跃。她的面部图层应与插画中的脸对齐
部件	parts closed-eyes <name>，parts mouth <name>	图层现在包含 eye_close 和 mouth_open。她使用哪种张嘴形状和腮红取决于用户喜好：创建 parts mouth-sheet <name> 和 parts blush-sheet <name>，向用户展示两张图片，让他们选择一个编号（参见README中的“嘴巴和腮红”）。如果嘴巴过大、过小、过高、过低或倾斜，可在 mouth-sheet 上使用 --size、--down、--right 和 --turn 修复以先展示给用户；腮红同样使用 --size、--in、--down 和 --turn。parts mouth-oh <name> 为她添加恐惧和惊讶时的“O”形嘴。如果她的闭合嘴巴太细或太淡看不清楚，可使用 parts mouth-line <name> --try 显示重绘效果，然后使用 parts mouth-line <name> 生成，再执行一次 parts mouth <name>
构建	build <name>	阅读其打印的内容（见下文）
查看	view，然后检查表（见下文）	查看README中的“尝试她的模型”列表

角色的描述来自项目的外观文件（check 会打印其位置；README中的“外观与风格”包含格式）。在绘制之前，请在此处编写或修改她的外貌：这是描述她模样的唯一位置，以便下一轮和下一个代理绘制相同的角色。外貌仅包含她的头发、眼睛、体型和服装。工具套件会自行添加构图和姿势，如果外貌描述重复这些内容或要求其他姿势，则会对绑定产生负面影响。draw ... --show 会打印完整提示而不进行绘制：在花费显卡资源进行一轮绘制前请先阅读。--look "..." 用于一次性使用。

拆分后，请检查 <characters>/<name>/layers/full/parts/ 中的每个图层图片。您要检查三件事：一个图层包含两个必须分开移动的部分（例如外套的前襟和内侧）；图层顺序错误；一对部件（手臂、腿、眼睛）合并为一个形状。README中的“修复图层”部分说明了每种情况的操作方法。请在角色文件夹的 live2d.json 文件的 "why" 字段中记录每个设置的原因：后续人员无法看到您所发现的问题。

解读构建输出

• head: her head turned -9.9 degrees ...：头部自动扶正的旋转角度。"No pair of eyes or brows" 表示眼图层未能分离为左右两部分：需要先修复该图层。
• head turn: 13_face_base as face; 16_accessory as glasses; ...：构建程序将每个头部部件识别为什么。如果部件被错误识别，会导致运动异常：例如眼镜未被列为眼镜，会从眼睛上漂移。
• body: her feet at ..., knees ..., hips ..., neck ...; 2 arms that bend, 2 legs that bend; ...：0条手臂或0条腿表示对应的部件对在图层中合并为一个形状。脚部位置为0.000表示某个图层底部有杂散像素。
• hair: 6 sections that swing each by itself (...): 头发的分区情况。仅有一个前分区和一个后分区说明头发较窄或图层已碎裂：这不是缺陷。
• in the texture at the head pass's own size: face, eyelash, ...: 添加到纹理中的头部部件列表，保持原始分辨率。如果没有此行，表示没有高质量副本：可执行 layers sharp <name> 从保留的头部PSD生成。changed since the head pass 表示在头部处理后编辑过的图层，在模型整体分辨率下使用：这是正确的，并非缺陷。

无需看屏幕即可检查模型

启动查看器（live2d.py view，在后台运行）并在浏览器工具中打开 http://127.0.0.1:8777/live2d/。该页面包含 window.sheets 对象，可用于生成带标签的姿势、动作帧和表情图片，并可保存为可读文件。它读取渲染器的像素，因此在页面隐藏时也能正确工作。隐藏页面的截图不准确：它会显示过时的帧。

const u = "/live2d/models/akane-full/model/model.model3.json";
await sheets.poses([
  ["face", u, /face/i, 2.6, [["rest", {}], ["turn", {ParamAngleX: 30, ParamEyeBallX: 1}],
                              ["half shut", {ParamEyeLOpen: 0.5, ParamEyeROpen: 0.5}], ["tilt", {ParamAngleZ: -30}]]],
  ["body", u, [0.15, 0, 0.85, 1], 0, [["rest", {}], ["sway", {ParamBodyAngleX: 10}],
                                      ["arms", {ParamArmLA: 10, ParamArmLB: -10}], ["knee", {ParamLegLB: 10}]]],
], 200, 300);
await sheets.save("akane-check");                 // -> <out>/live2d/checks/akane-check.png
await sheets.expressions(u, ["(none)", "happy", "tired", "blushing", "angry", "scared"], /face/i, 1.6, 133, 170);
await sheets.save("akane-expressions");
await sheets.motion(u, "TapHead", /face/i, 1.6, 133, 170, 6, 13);
await sheets.save("akane-taphead");
sheets.done();

帧定义为模型框的分数坐标 [x0, y0, x1, y1]，或可绘制对象的名称匹配模式（如 /face/i、/neck/i）并带有缩放。在寻找间隙时可使用绿色背景（将 "#30c060" 作为 poses 的最后一个参数）：间隙会显示为绿色。

仔细查看图片。在可能出现缺陷的位置（下巴、腰部、眼睛）进行放大，而不是从全身缩略图判断：迄今为止发现的大多数缺陷宽度仅为几个像素。检查每个动作的两端，以及两个动作的组合（转头加视线移动、抬手加弯腰），因为这些部位最容易分离。

当向用户展示结果时，请发送图片并明确说明您检查了哪些内容以及未检查哪些内容。查看器并非最终应用：如果您尚未在应用中看到角色，请予以说明。

当发现问题时

1. 确定问题所在部件。使用滑块保持姿势，或生成针对该部位的放大截图。
2. 判断问题根源。如果部件的图片错误、被截断、顺序错误或包含属于其他部件的内容，则问题在图层中。如果图层正确但运动异常，则问题在绑定中。
3. 查阅 references/problems.md。它列出了以前出现过的问题、原因及修复方法。
4. 图层问题通过 layers 命令或角色文件夹中的 live2d.json 修复，然后重新执行 build。
5. 所有角色都可能遇到的绑定问题在 scripts/rig.py 中修复，其中每个数字和表格都附有注释说明其值的原因。修改时请添加您的理由。仅单个角色出现的问题应放入其 live2d.json 文件中，由 rig.py 读取。
6. 重建、重新加载页面，再次生成相同的截图并进行对比。重新加载很重要：页面会保留已加载的模型，因此未重新加载时生成的截图显示的是构建前的模型状态。

小心不要进行超出预期的修改。在全局范围内修改图层之前，请检查其他角色是否也存在相同问题：曾经有一次修复为原本正常的头发添加了深色条纹。

修改动作或可展示内容

README中“修改动作”部分将每个动作映射到 scripts/rig.py 中的名称。表情为 EXPRESSIONS，点击反应为 TAPS，应用播放的情感动作为 EMOTIONS 和 BORROWED。所有角色使用相同的名称，以便应用设置和提示只需编写一次。

移动幅度取决于用户喜好。本工具套件首位用户的指导原则：头部运动用于观察物体，因此特征位置略微滑动，瞳孔承担大部分视线功能；身体运动保持微妙，双脚始终着地。展示图片并让用户决定。

完成

• 告知用户模型位置：<out>/live2d/<name>-full.zip 是应用可以导入的文件。
• 将插画、抠图、放大后的插画以及 layers/full/ 中的所有内容纳入版本控制。<out> 中的所有内容均可重新生成。
• 如果学到了对未来运行有用的经验（例如新型缺陷及其修复方法），请在 references/problems.md 中添加一行。
• 如果启动了查看器和ComfyUI，请停止它们。