# IKFK Switch Tool

## 概述
IKFK Switch Tool 是一个用于在Maya中实现IK和FK动画之间无缝切换的工具。该工具从原始MEL脚本转换为Python版本，提供更好的跨版本兼容性。

## 版本信息
- **版本**: V1.0
- **兼容性**: Maya 2018+
- **语言**: Python
- **原始版本**: MEL (ikfk_switch.mel)

## 功能特性

### 主要功能
1. **无缝切换**: 在IK和FK动画之间进行无缝切换，保持动画连续性
2. **自动匹配**: 切换时自动匹配控制器位置和旋转
3. **关键帧设置**: 自动在切换点设置关键帧
4. **预设支持**: 内置ADV绑定预设，支持快速设置

### UI功能
- **FK控制器加载**: 加载FK骨骼和控制器
  - FK Joint Root/Mid/End
  - FK Ctrl Root/Mid/End
  
- **IK控制器加载**: 加载IK骨骼和控制器
  - IK Joint Root/Mid/End
  - IK Ctrl Root (IK手柄)
  - IK Ctrl Pole (极向量控制器)
  
- **切换控制器**: 设置切换属性
  - Switch Ctrl (切换控制器)
  - Switch Attr (切换属性名称)

### 辅助功能
- **ADV Build**: 快速为ADV绑定设置IKFK切换
- **Empty**: 清空所有输入字段
- **BiliBili**: 打开教程链接

## 使用方法

### 基本使用流程

1. **加载FK控制器**
   - 选择FK骨骼根节点，点击"< FK Joint Root"
   - 选择FK骨骼中间节点，点击"< FK Joint Mid"
   - 选择FK骨骼末端节点，点击"< FK Joint End"
   - 重复以上步骤加载FK控制器

2. **加载IK控制器**
   - 选择IK骨骼节点，点击相应按钮
   - 选择IK控制器和极向量控制器

3. **设置切换控制器**
   - 选择用于切换的控制器，点击"< Switch Ctrl"
   - 在通道盒中选择切换属性，点击"< Switch Attr"

4. **构建切换系统**
   - 点击"<<< Build Seamless Switching >>>"按钮
   - 系统会自动创建必要的属性和脚本节点

5. **使用切换功能**
   - 在切换控制器上找到"IKFK_Seamless"属性
   - 切换该属性值（IK=0, FK=1）即可实现无缝切换

### ADV绑定快速设置

如果使用ADV绑定系统，可以使用预设功能：
1. 展开"Edit"面板
2. 点击"<<< ADV Build >>>"
3. 系统会自动为左右手臂和腿部设置IKFK切换

## 技术实现

### 核心组件

1. **IKFKSwitchUI类**: UI界面管理
   - 创建和管理UI窗口
   - 处理用户输入
   - 调用切换逻辑

2. **seamless_switching函数**: 核心切换逻辑
   - 创建数据存储locator
   - 添加必要属性
   - 建立属性连接
   - 创建脚本节点

3. **create_switching_script函数**: 创建全局切换脚本
   - 使用MEL脚本实现切换逻辑
   - 处理约束和关键帧

4. **create_script_job函数**: 创建脚本任务
   - 监听属性变化
   - 自动触发切换

### 兼容性设计

- 使用`maya.cmds`和`maya.mel`模块，确保跨版本兼容
- 避免使用版本特定的API
- 使用f-string格式化（Python 3.6+）
- 异常处理确保稳定性

## 工具架集成

该工具已集成到Nexus Animation工具架：
- **图标**: ikfk_switch.png
- **位置**: 动画工具架末尾
- **调用**: `import animation_tools.ikfx_switch; animation_tools.ikfx_switch.show()`

## 文件位置

### Maya 2023
- 脚本: `scripts/animation_tools/ikfx_switch.py`
- 图标: `icons/ikfk_switch.png`
- 工具架: `shelves/shelf_Nexus_Animation.mel`

### Maya 2025
- 脚本: `scripts/animation_tools/ikfx_switch.py`
- 图标: `icons/ikfk_switch.png`
- 工具架: `shelves/shelf_Nexus_Animation.mel`

## 注意事项

1. **属性要求**: 切换属性必须有最小值和最大值设置
2. **命名规范**: 建议使用清晰的命名规范以便识别
3. **关键帧**: 切换会在当前帧和前一帧设置关键帧
4. **选择保持**: 切换后会恢复原始选择

## 故障排除

### 常见问题

1. **切换不工作**
   - 检查所有必需的对象是否存在
   - 确认切换属性已正确设置
   - 查看脚本编辑器的错误信息

2. **位置不匹配**
   - 确保FK和IK骨骼层级正确
   - 检查约束设置
   - 验证控制器方向

3. **属性加载失败**
   - 确保在通道盒中选择了属性
   - 检查属性是否可关键帧化