Nexus/2023/scripts/animation_tools/SHELF_BUTTONS.md

# Maya 工具架按钮命令

所有工具的标准启动命令，**不需要使用绝对路径**。

## 📋 前提条件

确保 `animation_tools` 在 Maya 的 Python 路径中。通常通过以下方式之一：

1. **userSetup.py** (推荐)
   ```python
   import sys
   import os
   scripts_path = r'h:\Workspace\Raw\Tools\Plugins\Maya\2023\scripts'
   if scripts_path not in sys.path:
       sys.path.insert(0, scripts_path)
   ```

2. **Maya.env**
   ```
   PYTHONPATH=h:\Workspace\Raw\Tools\Plugins\Maya\2023\scripts
   ```

## 🔧 工具架按钮命令

### 1. Studio Library

**Python 命令：**
```python
import animation_tools.studiolibrary as studiolib
studiolib.show()
```

**MEL 命令：**
```mel
python("import animation_tools.studiolibrary as studiolib; studiolib.show()");
```

---

### 2. DreamWall Picker

**Python 命令：**
```python
import animation_tools.dwpicker as dwpicker
dwpicker.show()
```

**MEL 命令：**
```mel
python("import animation_tools.dwpicker as dwpicker; dwpicker.show()");
```

**切换显示/隐藏：**
```python
import animation_tools.dwpicker as dwpicker
dwpicker.toggle()
```

---

### 3. MG-Picker Studio

**Python 命令（Animator 模式）：**
```python
import animation_tools.mgpicker as mgpicker
mgpicker.start()
```

**Python 命令（Designer 模式）：**
```python
import animation_tools.mgpicker as mgpicker
mgpicker.start(mode=0)
```

**MEL 命令：**
```mel
python("import animation_tools.mgpicker as mgpicker; mgpicker.start()");
```

---

### 4. IK/FK Switcher

**Python 命令：**
```python
import animation_tools.ik_fk_switcher as ikfk
ikfk.show()
```

**MEL 命令：**
```mel
python("import animation_tools.ik_fk_switcher as ikfk; ikfk.show()");
```

---

## 📝 创建工具架按钮步骤

### 方法 1：通过 Maya UI

1. 打开 **Script Editor**（脚本编辑器）
2. 在 **Python** 标签页输入命令
3. 选中代码
4. **鼠标中键拖拽** 到工具架
5. 右键点击按钮 → **Edit** → 设置图标和标签

### 方法 2：通过 MEL 命令

```mel
// Studio Library
shelfButton
    -command "python(\"import animation_tools.studiolibrary as studiolib; studiolib.show()\")"
    -annotation "Studio Library"
    -label "StudioLib"
    -image "commandButton.png"
    -imageOverlayLabel "SL";

// DreamWall Picker
shelfButton
    -command "python(\"import animation_tools.dwpicker as dwpicker; dwpicker.show()\")"
    -annotation "DreamWall Picker"
    -label "DWPicker"
    -image "commandButton.png"
    -imageOverlayLabel "DW";

// MG-Picker
shelfButton
    -command "python(\"import animation_tools.mgpicker as mgpicker; mgpicker.start()\")"
    -annotation "MG-Picker Studio"
    -label "MGPicker"
    -image "commandButton.png"
    -imageOverlayLabel "MG";

// IK/FK Switcher
shelfButton
    -command "python(\"import animation_tools.ik_fk_switcher as ikfk; ikfk.show()\")"
    -annotation "IK/FK Switcher"
    -label "IK/FK"
    -image "commandButton.png"
    -imageOverlayLabel "IK";
```

---

## 🎨 推荐的按钮图标

### Studio Library
- **图标**: `UVEditorSnapshot.png` 或 `folder-open.png`
- **标签**: `SL` 或 `Studio`

### DreamWall Picker
- **图标**: `pickHandlesComp.png` 或 `pickOtherComp.png`
- **标签**: `DW` 或 `Picker`

### MG-Picker
- **图标**: `pickWalkUp.png` 或 `selectByHierarchy.png`
- **标签**: `MG` 或 `MGPick`

### IK/FK Switcher
- **图标**: `ikSCsolver.png` 或 `kinHandle.png`
- **标签**: `IK` 或 `Switch`

---

## ⚠️ 常见问题

### 问题 1: ModuleNotFoundError: No module named 'animation_tools'

**原因**: `animation_tools` 不在 Python 路径中

**解决方案**:
1. 检查 `userSetup.py` 是否正确设置
2. 或在按钮命令前添加路径：
   ```python
   import sys
   scripts_path = r'h:\Workspace\Raw\Tools\Plugins\Maya\2023\scripts'
   if scripts_path not in sys.path:
       sys.path.insert(0, scripts_path)
   
   import animation_tools.studiolibrary as studiolib
   studiolib.show()
   ```

### 问题 2: 工具重复打开

**原因**: 没有使用正确的启动命令

**解决方案**: 使用本文档中的标准命令，所有工具都有窗口管理机制

### 问题 3: 版本不兼容

**原因**: 使用了错误的 Maya 版本目录

**解决方案**: 
- Maya 2023 使用: `Maya\2023\scripts`
- Maya 2024 使用: `Maya\2024\scripts`
- Maya 2025 使用: `Maya\2025\scripts`

---

## 📦 完整的 userSetup.py 示例

创建或编辑: `Documents/maya/scripts/userSetup.py`

```python
#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
Maya User Setup
自动加载动画工具路径
"""

import sys
import os
import maya.cmds as cmds

def setup_animation_tools():
    """设置动画工具路径"""
    # 获取 Maya 版本
    maya_version = cmds.about(version=True).split('.')[0]
    
    # 构建路径
    base_path = r'h:\Workspace\Raw\Tools\Plugins\Maya'
    scripts_path = os.path.join(base_path, maya_version, 'scripts')
    
    # 添加到 Python 路径
    if os.path.exists(scripts_path):
        if scripts_path not in sys.path:
            sys.path.insert(0, scripts_path)
        print("Animation tools loaded from: " + scripts_path)
    else:
        print("Warning: Animation tools path not found: " + scripts_path)

# 在 Maya 启动时执行
if __name__ == '__main__':
    cmds.evalDeferred(setup_animation_tools)
```

---

## ✅ 验证安装

在 Maya Script Editor 中运行：

```python
import sys
print("Python paths:")
for path in sys.path[:5]:
    print("  -", path)

print("\nTesting imports:")
try:
    import animation_tools.studiolibrary
    print("  ✓ Studio Library")
except ImportError as e:
    print("  ✗ Studio Library:", e)

try:
    import animation_tools.dwpicker
    print("  ✓ DreamWall Picker")
except ImportError as e:
    print("  ✗ DreamWall Picker:", e)

try:
    import animation_tools.mgpicker
    print("  ✓ MG-Picker")
except ImportError as e:
    print("  ✗ MG-Picker:", e)

try:
    import animation_tools.ik_fk_switcher
    print("  ✓ IK/FK Switcher")
except ImportError as e:
    print("  ✗ IK/FK Switcher:", e)
```

预期输出：
```
Python paths:
  - h:\Workspace\Raw\Tools\Plugins\Maya\2023\scripts
  - ...

Testing imports:
  ✓ Studio Library
  ✓ DreamWall Picker
  ✓ MG-Picker
  ✓ IK/FK Switcher
```

---

## 🚀 快速启动所有工具

```python
# 一键启动所有动画工具
import animation_tools.studiolibrary as studiolib
import animation_tools.dwpicker as dwpicker
import animation_tools.mgpicker as mgpicker
import animation_tools.ik_fk_switcher as ikfk

studiolib.show()
dwpicker.show()
mgpicker.start()
ikfk.show()
```

---

## 📞 支持

如果遇到问题：

1. 检查 Python 路径是否正确
2. 检查 Maya 版本是否匹配
3. 查看 Script Editor 的完整错误信息
4. 确认所有文件都在正确的位置

---

**所有工具现在都支持无绝对路径启动！** ✨