Update

2025-11-24 21:05:22 +08:00
parent e76152945e
commit e4c713035b
12 changed files with 585 additions and 414 deletions
--- a/2023/scripts/rigging_tools/skin_api/README.md
+++ b/2023/scripts/rigging_tools/skin_api/README.md
@@ -1,155 +1,139 @@
-# Skin API
+# Skin API Module

-高性能的 Maya 蒙皮权重管理工具，使用 Maya API 进行快速的权重导出、导入和操作。
+强大的 Maya 蒙皮权重管理工具，支持权重的导出、导入和蒙皮解绑功能。

-## 功能特性
+## 📁 文件结构

-### 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()
+```
+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 apiVtxAttribs
+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.ApiVtxAttribs()
+api = ApiVtxAttribs()

-# 导出选中物体的权重
-msg = api.exportSkinWeights(selected=True, saveJointInfo=True)
-print(msg)
+# 导出权重
+api.exportSkinWeights(selected=True, saveJointInfo=True)

-# 导入权重到选中物体
-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.importSkinWeights(selected=False, stripJointNamespaces=False, addNewToHierarchy=True)
 ```

-### 底层 API 使用
+## ✨ 主要功能

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

-# 获取蒙皮集群信息
-skinInfo = Skinning.getSkinClusterInfo("pSphere1", saveJointInfo=True)
+## 🔧 版本兼容性

-# 构建权重字典
-weightDict = Skinning.buildSkinWeightsDict(["pSphere1", "pCube1"])
+### 支持的 Maya 版本
+- **所有 Maya 版本** - 从 Maya 2016 到最新版本

-# 保存权重到文件
-Utils.pickleDumpWeightsToFile(weightDict, "D:/weights.skinWeights")
+### API 兼容性
+模块采用双重 API 支持策略：
+- **PyMEL** - 优先使用 PyMEL（如果可用）
+- **Maya Commands** - 自动降级到 `maya.cmds`（如果 PyMEL 不可用）
+- **Maya API** - 使用 `maya.OpenMaya` 和 `maya.OpenMayaAnim` 进行高性能操作

-# 从文件加载权重
-loadedWeights = Utils.getPickleObject("D:/weights.skinWeights")
+### 兼容性特性
+1. **自动 API 检测** - 运行时检测可用的 API
+2. **优雅降级** - PyMEL 不可用时自动使用 cmds
+3. **相对导入** - 支持作为包导入或独立模块使用
+4. **异常处理** - 完善的错误处理和用户提示

-# 应用权重到物体
-Skinning.skinClusterBuilder("pSphere1", skinInfo, stripJointNamespaces=False)
-```
+## 📝 文件格式

-## 模块结构
+权重文件使用 `.skinWeights` 格式（基于 Python pickle）：
+- 包含顶点权重数据
+- 包含影响对象（关节）信息
+- 可选包含关节变换信息
+- 支持多物体批量导出

- **Skinning.py** - 核心蒙皮权重操作函数
-  - `getSkinClusterInfo()` - 获取蒙皮集群信息
-  - `getSkinClusterWeights()` - 获取权重数据
-  - `setSkinWeights()` - 设置权重数据
-  - `buildSkinWeightsDict()` - 构建权重字典
-  - `skinClusterBuilder()` - 重建蒙皮集群
-  - `transferSkinWeights()` - 传递权重
+## 💡 使用技巧

- **Utils.py** - 工具函数
-  - `filePathPrompt()` - 文件对话框
-  - `pickleDumpWeightsToFile()` - 保存权重文件
-  - `getPickleObject()` - 加载权重文件
-  - `matchDictionaryToSceneMeshes()` - 匹配场景物体
-  - `getBarycentricWeights()` - 计算重心坐标权重
+### 导出权重
+1. 选择需要导出的蒙皮物体
+2. 运行 `WeightExport()`
+3. 选择保存位置和文件名
+4. 建议启用 `saveJointInfo` 以保存完整的关节信息

- **ui.py** - 用户界面函数
-  - `WeightExport()` - 导出权重 UI
-  - `WeightImport()` - 导入权重 UI
-  - `UnbindSkin()` - 解绑蒙皮 UI
+### 导入权重
+1. **选中物体导入** - 选择目标物体后导入（仅导入到选中物体）
+2. **自动匹配导入** - 不选择物体导入（自动匹配场景中的所有物体）
+3. 确保物体名称和顶点数量匹配
+4. 如果关节缺失，可启用 `addNewToHierarchy` 自动创建

- **apiVtxAttribs.py** - 顶点属性 API 操作
+### 解绑蒙皮
+1. 选择需要解绑的物体
+2. 运行 `UnbindSkin()`
+3. 确认对话框后执行解绑
+4. 支持批量解绑多个物体

-## 文件格式
+## ⚠️ 注意事项

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

-```python
-{
-    "objectName": {
-        "vtxCount": 482,
-        "skinCluster": {
-            "clusterInfluenceNames": ["joint1", "joint2", ...],
-            "clusterMaxInf": 4,
-            "clusterWeights": {...},
-            "skinJointInformation": {...}
-        }
-    }
-}
-```
+## 🐛 故障排除

-## 性能优化
+### 导入失败
+- 检查物体名称是否匹配
+- 检查顶点数量是否一致
+- 确认权重文件路径正确
+- 查看 Maya 脚本编辑器的详细错误信息

- 使用 Maya OpenMaya API 进行快速权重读写
- 批量操作减少 Maya 命令调用
- 进度条显示长时间操作
- 支持大规模模型（10万+顶点）
+### 关节缺失
+- 启用 `addNewToHierarchy` 参数
+- 确保导出时使用了 `saveJointInfo=True`
+- 手动创建缺失的关节

-## 注意事项
-
-1. 导出前确保物体已绑定蒙皮
-2. 导入时会删除物体历史记录
-3. 骨骼名称需要匹配（支持命名空间处理）
-4. 顶点数量需要匹配
-5. 解绑操作不可撤销，建议先保存场景
-
-## 依赖
-
- PyMEL
- Maya OpenMaya API
- Maya OpenMayaAnim API
+### PyMEL 相关问题
+- 模块会自动降级到 cmds，无需担心
+- 如果需要强制使用 cmds，可以在导入前设置环境变量