Nexus/2023/scripts/rigging_tools/skin_api/README.md

Skin API Module

强大的 Maya 蒙皮权重管理工具，支持权重的导出、导入和蒙皮解绑功能。

📁 文件结构

skin_api/
├── __init__.py           # 模块初始化
├── ui.py                 # UI 函数（导出、导入、解绑）
├── apiVtxAttribs.py      # 核心 API 类
├── Skinning.py           # 蒙皮操作函数
├── Utils.py              # 工具函数
└── README.md            # 本文档

🚀 使用方法

从工具架启动

1. 打开 Maya
2. 切换到 Nexus_Rigging 工具架
3. 使用对应的按钮：
   • Export Weights - 导出蒙皮权重
   • Import Weights - 导入蒙皮权重
   • Unbind Skin - 解绑蒙皮

从 Python 调用

导出权重

from rigging_tools.skin_api import WeightExport
WeightExport()

导入权重

from rigging_tools.skin_api import WeightImport
WeightImport()

解绑蒙皮

from rigging_tools.skin_api import UnbindSkin
UnbindSkin()

使用核心 API

from rigging_tools.skin_api import ApiVtxAttribs

# 创建 API 实例
api = ApiVtxAttribs()

# 导出权重
api.exportSkinWeights(selected=True, saveJointInfo=True)

# 导入权重
api.importSkinWeights(selected=False, stripJointNamespaces=False, addNewToHierarchy=True)

✨ 主要功能

• 权重导出 - 导出选中或所有蒙皮物体的权重数据
• 权重导入 - 导入权重到选中或匹配的物体
• 蒙皮解绑 - 快速解绑选中物体的蒙皮
• 关节信息保存 - 可选保存关节方向、世界变换和父级信息
• 智能匹配 - 基于名称和顶点数量自动匹配物体
• 命名空间处理 - 支持剥离关节命名空间

🔧 版本兼容性

支持的 Maya 版本

• 所有 Maya 版本 - 从 Maya 2016 到最新版本

API 兼容性

模块采用双重 API 支持策略：

• PyMEL - 优先使用 PyMEL（如果可用）
• Maya Commands - 自动降级到 maya.cmds（如果 PyMEL 不可用）
• Maya API - 使用 maya.OpenMaya 和 maya.OpenMayaAnim 进行高性能操作

兼容性特性

1. 自动 API 检测 - 运行时检测可用的 API
2. 优雅降级 - PyMEL 不可用时自动使用 cmds
3. 相对导入 - 支持作为包导入或独立模块使用
4. 异常处理 - 完善的错误处理和用户提示

📝 文件格式

权重文件使用 .skinWeights 格式（基于 Python pickle）：

• 包含顶点权重数据
• 包含影响对象（关节）信息
• 可选包含关节变换信息
• 支持多物体批量导出

💡 使用技巧

导出权重

1. 选择需要导出的蒙皮物体
2. 运行 WeightExport()
3. 选择保存位置和文件名
4. 建议启用 saveJointInfo 以保存完整的关节信息

导入权重

1. 选中物体导入 - 选择目标物体后导入（仅导入到选中物体）
2. 自动匹配导入 - 不选择物体导入（自动匹配场景中的所有物体）
3. 确保物体名称和顶点数量匹配
4. 如果关节缺失，可启用 addNewToHierarchy 自动创建

解绑蒙皮

1. 选择需要解绑的物体
2. 运行 UnbindSkin()
3. 确认对话框后执行解绑
4. 支持批量解绑多个物体

⚠️ 注意事项

• 导入权重时，目标物体的顶点数量必须与导出时一致
• 物体名称需要匹配（支持短名称匹配）
• 建议在导入前备份场景
• 大量物体操作时会显示进度条
• 权重文件使用 pickle 格式，不同 Python 版本间可能存在兼容性问题

🐛 故障排除

导入失败

• 检查物体名称是否匹配
• 检查顶点数量是否一致
• 确认权重文件路径正确
• 查看 Maya 脚本编辑器的详细错误信息

关节缺失

• 启用 addNewToHierarchy 参数
• 确保导出时使用了 saveJointInfo=True
• 手动创建缺失的关节

PyMEL 相关问题

• 模块会自动降级到 cmds，无需担心
• 如果需要强制使用 cmds，可以在导入前设置环境变量