Update

2023/scripts/rigging_tools/skin_api/README.md

@@ -0,0 +1,155 @@
+# 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