140 lines
4.0 KiB
Markdown
140 lines
4.0 KiB
Markdown
# 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 调用
|
||
|
||
#### 导出权重
|
||
```python
|
||
from rigging_tools.skin_api import WeightExport
|
||
WeightExport()
|
||
```
|
||
|
||
#### 导入权重
|
||
```python
|
||
from rigging_tools.skin_api import WeightImport
|
||
WeightImport()
|
||
```
|
||
|
||
#### 解绑蒙皮
|
||
```python
|
||
from rigging_tools.skin_api import UnbindSkin
|
||
UnbindSkin()
|
||
```
|
||
|
||
#### 使用核心 API
|
||
```python
|
||
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，可以在导入前设置环境变量
|