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

Skin API

高性能的 Maya 蒙皮权重管理工具，使用 Maya API 进行快速的权重导出、导入和操作。

功能特性

1. 权重导出 (WeightExport)

• 导出选中物体的蒙皮权重到文件
• 保存骨骼层级信息
• 支持多物体批量导出
• 使用 pickle 格式高效存储

2. 权重导入 (WeightImport)

• 从文件导入蒙皮权重
• 自动匹配场景中的物体
• 支持选择导入或全场景导入
• 自动重建骨骼层级
• 支持命名空间处理

3. 解绑蒙皮 (UnbindSkin)

• 移除选中物体的蒙皮集群
• 保留模型几何体
• 支持批量操作
• 安全确认对话框

使用方法

从工具架使用

在 Rigging 工具架上点击对应按钮：

• Export - 导出权重
• Import - 导入权重
• Unbind - 解绑蒙皮

从 Python 使用

from rigging_tools.skin_api import ui

# 导出权重
ui.WeightExport()

# 导入权重
ui.WeightImport()

# 解绑蒙皮
ui.UnbindSkin()

高级用法

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 使用

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 字典：

{
    "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