Art Center Plugin

面向画师参考图工作流的 Blender 动作应用插件。本项目负责整个 Art Center 流程中的第三阶段：将前置服务返回的动作 JSON 应用到 Blender 中的指定模型骨架上，让画师可以在 3D 场景里继续调整摄像机角度、人体姿态和画面构图。

项目定位

Art Center 的目标是让画师把自己长期收集的大量参考图集转化为可检索、可复用、可微调的专属参考库。整体流程分为三个阶段：

1. 预处理
   客户端项目：art_center-client
   将 bat 文件中的文件夹路径改为参考图集路径后启动，即可在消费级显卡上自动为图片生成向量、进行图片分类，并从动作类图片中提取动作数据，生成动作库。

2. 获取参考
   服务端项目：art_center-server
   画师输入自然语言需求后，Gemini 会将抽象需求转换为适合各类别检索的英文短输入。SigLIP2 再将需求转换为向量并在向量数据库中匹配参考图，最终返回图片路径。动作类别还会额外返回对应动作 JSON 文件。

3. 动作处理
   当前项目。画师在 Blender 中安装并启用本插件，选中符合要求的模型骨架，上传上一步返回的动作 JSON，点击应用后模型姿态会随之改变。由于最终结果是 Blender 中真实骨骼的姿态变化，画师仍然可以手动微调骨骼、摄像机和画面角度。

核心优势

• 使用门槛低：前置流程经测试可在 RTX 3060 等消费级显卡上运行。
• 高度定制：参考库完全来自画师自己的图集，而不是通用素材库。
• 结果可控：不是单纯依靠 AI 生成图片，而是先检索真实参考图，再把参考动作迁移到 3D 模型。
• 可微调、可回溯：动作最终落在 Blender 骨架上，画师可以继续修改姿态、镜头、构图和细节。

插件功能

• 在 Blender 侧边栏提供 SMPLest-X 面板。
• 读取动作 JSON 文件。
• 将 JSON 中的身体、手部和 Root 旋转数据转换为 Blender 骨骼姿态。
• 支持带骨架模型的动作应用和后续手动调整。

环境要求

• Blender。
• 一个带骨架的 3D 人体模型。
• 建议模型初始姿态为 A-POSE。
• 模型骨骼名称最好与插件默认骨骼名称一致。
• 来自 art_center-server 动作类别结果中的动作 JSON 文件。

安装方式

1. 打开 Blender。
2. 进入 Edit > Preferences > Add-ons。
3. 点击 Install...。
4. 选择本项目中的 main.py。
5. 勾选启用 SMPLest-X Loader (Simplified)。
6. 在 3D 视图中按 N 打开右侧侧边栏。
7. 切换到 SMPLest-X 标签页。

使用流程

1. 在 Blender 中导入或打开目标人体模型。
2. 确认模型带有 Armature 骨架。
3. 确认模型处于 A-POSE 或接近 A-POSE 的初始姿态。
4. 打开右侧侧边栏的 SMPLest-X 面板。
5. 在 JSON 字段选择动作 JSON 文件。
6. 在 Target 字段选择目标骨架对象。
7. 点击 Apply Pose。
8. 根据画面需要继续调整骨骼、摄像机角度、焦距和构图。

骨骼命名要求

插件默认匹配以下骨骼名称：

Root
thigh_L, thigh_R
spine_01, spine_02, spine_03
calf_L, calf_R
foot_L, foot_R
foot_sub_L, foot_sub_R
neck_01, head
clavicle_L, clavicle_R
upperarm_L, upperarm_R
lowerarm_L, lowerarm_R
hand_L, hand_R
index_01_L ... index_03_L
middle_01_L ... middle_03_L
pinky_01_L ... pinky_03_L
ring_01_L ... ring_03_L
thumb_01_L ... thumb_03_L
index_01_R ... index_03_R
middle_01_R ... middle_03_R
pinky_01_R ... pinky_03_R
ring_01_R ... ring_03_R
thumb_01_R ... thumb_03_R

如果模型骨骼名称不同，有两种处理方式：

1. 在 Blender 中把模型骨骼重命名为插件默认名称。
2. 修改 main.py 中的 ROOT_BONE、BODY_BONES、HAND_BONES 等映射配置。

动作 JSON 格式

插件会读取以下字段：

{
  "body_root_pose": [[0.0, 0.0, 0.0]],
  "body_pose": [[0.0, 0.0, 0.0]],
  "lhand_pose": [[0.0, 0.0, 0.0]],
  "rhand_pose": [[0.0, 0.0, 0.0]]
}

字段说明：

• body_root_pose：Root 骨骼旋转，通常包含 1 组三维旋转向量。
• body_pose：身体骨骼旋转数组，顺序需与 BODY_BONES 一致。
• lhand_pose：左手手指骨骼旋转数组，顺序需与左手 HAND_BONES 一致。
• rhand_pose：右手手指骨骼旋转数组，顺序需与右手 HAND_BONES 一致。

常见问题

点击 Apply Pose 后没有变化

• 检查是否已经选择正确的动作 JSON。
• 检查 Target 是否选择了 Armature 对象，而不是 Mesh 对象。
• 检查 JSON 中是否包含 body_root_pose、body_pose、lhand_pose 或 rhand_pose。
• 检查模型骨骼名称是否与插件默认名称一致。

姿态方向不对或手臂角度异常

• 确认模型初始姿态是否为 A-POSE。
• 确认骨骼朝向和命名是否与插件默认预期一致。
• 如仅上臂角度存在偏差，可检查 main.py 中的 BODY_OFFSETS。

手部姿态不正确

• 检查手指骨骼命名是否符合 index_01_L、thumb_03_R 这类格式。
• 检查 JSON 中 lhand_pose、rhand_pose 是否存在。
• 如果模型没有完整手指骨骼，身体动作仍可应用，缺失的手指骨骼会被跳过。

项目结构

.
├── main.py      # Blender 插件主文件
└── README.md    # 项目说明

当前限制

• 当前插件固定按默认骨骼名称进行映射，不提供可视化骨骼重映射界面。
• 不同模型的骨骼朝向、初始姿态和绑定方式可能导致应用后的动作存在偏差。
• 插件主要负责动作应用，不负责模型下载、动作提取或参考图检索。

适用场景

本插件适合画师把自然语言检索到的动作参考进一步转化为可调整的 3D 人体姿态。它可以减少人体参考整理和摆姿势的重复工作，同时保留画师对画面、动作和细节的最终控制权。