156 lines
3.8 KiB
Markdown
156 lines
3.8 KiB
Markdown
# Skin API
|
||
|
||
高性能的 Maya 蒙皮权重管理工具，使用 Maya API 进行快速的权重导出、导入和操作。
|
||
|
||
## 功能特性
|
||
|
||
### 1. 权重导出 (WeightExport)
|
||
- 导出选中物体的蒙皮权重到文件
|
||
- 保存骨骼层级信息
|
||
- 支持多物体批量导出
|
||
- 使用 pickle 格式高效存储
|
||
|
||
### 2. 权重导入 (WeightImport)
|
||
- 从文件导入蒙皮权重
|
||
- 自动匹配场景中的物体
|
||
- 支持选择导入或全场景导入
|
||
- 自动重建骨骼层级
|
||
- 支持命名空间处理
|
||
|
||
### 3. 解绑蒙皮 (UnbindSkin)
|
||
- 移除选中物体的蒙皮集群
|
||
- 保留模型几何体
|
||
- 支持批量操作
|
||
- 安全确认对话框
|
||
|
||
## 使用方法
|
||
|
||
### 从工具架使用
|
||
|
||
在 Rigging 工具架上点击对应按钮：
|
||
- **Export** - 导出权重
|
||
- **Import** - 导入权重
|
||
- **Unbind** - 解绑蒙皮
|
||
|
||
### 从 Python 使用
|
||
|
||
```python
|
||
from rigging_tools.skin_api import ui
|
||
|
||
# 导出权重
|
||
ui.WeightExport()
|
||
|
||
# 导入权重
|
||
ui.WeightImport()
|
||
|
||
# 解绑蒙皮
|
||
ui.UnbindSkin()
|
||
```
|
||
|
||
### 高级用法
|
||
|
||
```python
|
||
from rigging_tools.skin_api import apiVtxAttribs
|
||
|
||
# 创建 API 实例
|
||
api = apiVtxAttribs.ApiVtxAttribs()
|
||
|
||
# 导出选中物体的权重
|
||
msg = api.exportSkinWeights(selected=True, saveJointInfo=True)
|
||
print(msg)
|
||
|
||
# 导入权重到选中物体
|
||
msg = api.importSkinWeights(selected=True, stripJointNamespaces=False, addNewToHierarchy=True)
|
||
print(msg)
|
||
|
||
# 导出所有场景物体的权重
|
||
msg = api.exportSkinWeights(filePath="D:/weights.skinWeights", selected=False)
|
||
|
||
# 导入权重到所有匹配的场景物体
|
||
msg = api.importSkinWeights(filePath="D:/weights.skinWeights", selected=False)
|
||
```
|
||
|
||
### 底层 API 使用
|
||
|
||
```python
|
||
from rigging_tools.skin_api import Skinning, Utils
|
||
|
||
# 获取蒙皮集群信息
|
||
skinInfo = Skinning.getSkinClusterInfo("pSphere1", saveJointInfo=True)
|
||
|
||
# 构建权重字典
|
||
weightDict = Skinning.buildSkinWeightsDict(["pSphere1", "pCube1"])
|
||
|
||
# 保存权重到文件
|
||
Utils.pickleDumpWeightsToFile(weightDict, "D:/weights.skinWeights")
|
||
|
||
# 从文件加载权重
|
||
loadedWeights = Utils.getPickleObject("D:/weights.skinWeights")
|
||
|
||
# 应用权重到物体
|
||
Skinning.skinClusterBuilder("pSphere1", skinInfo, stripJointNamespaces=False)
|
||
```
|
||
|
||
## 模块结构
|
||
|
||
- **Skinning.py** - 核心蒙皮权重操作函数
|
||
- `getSkinClusterInfo()` - 获取蒙皮集群信息
|
||
- `getSkinClusterWeights()` - 获取权重数据
|
||
- `setSkinWeights()` - 设置权重数据
|
||
- `buildSkinWeightsDict()` - 构建权重字典
|
||
- `skinClusterBuilder()` - 重建蒙皮集群
|
||
- `transferSkinWeights()` - 传递权重
|
||
|
||
- **Utils.py** - 工具函数
|
||
- `filePathPrompt()` - 文件对话框
|
||
- `pickleDumpWeightsToFile()` - 保存权重文件
|
||
- `getPickleObject()` - 加载权重文件
|
||
- `matchDictionaryToSceneMeshes()` - 匹配场景物体
|
||
- `getBarycentricWeights()` - 计算重心坐标权重
|
||
|
||
- **ui.py** - 用户界面函数
|
||
- `WeightExport()` - 导出权重 UI
|
||
- `WeightImport()` - 导入权重 UI
|
||
- `UnbindSkin()` - 解绑蒙皮 UI
|
||
|
||
- **apiVtxAttribs.py** - 顶点属性 API 操作
|
||
|
||
## 文件格式
|
||
|
||
权重文件使用 `.skinWeights` 扩展名，内部为 pickle 格式的 Python 字典：
|
||
|
||
```python
|
||
{
|
||
"objectName": {
|
||
"vtxCount": 482,
|
||
"skinCluster": {
|
||
"clusterInfluenceNames": ["joint1", "joint2", ...],
|
||
"clusterMaxInf": 4,
|
||
"clusterWeights": {...},
|
||
"skinJointInformation": {...}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
- 使用 Maya OpenMaya API 进行快速权重读写
|
||
- 批量操作减少 Maya 命令调用
|
||
- 进度条显示长时间操作
|
||
- 支持大规模模型（10万+顶点）
|
||
|
||
## 注意事项
|
||
|
||
1. 导出前确保物体已绑定蒙皮
|
||
2. 导入时会删除物体历史记录
|
||
3. 骨骼名称需要匹配（支持命名空间处理）
|
||
4. 顶点数量需要匹配
|
||
5. 解绑操作不可撤销，建议先保存场景
|
||
|
||
## 依赖
|
||
|
||
- PyMEL
|
||
- Maya OpenMaya API
|
||
- Maya OpenMayaAnim API
|