# 2.5.1 动画生成和播放功能设计说明

## 2.5.1.1. 模块描述

动画生成和播放模块是碰撞检测功能的核心模块，负责指定物流组件（待载转运车），选择路径，生成动画仿真物流组件的运动过程。支持设置动画时长，支持动画的播放、停止和步进播放。该模块通过TimeLiner集成和动态变换实现沿路径的动画效果，为碰撞检测提供动态测试环境。

该模块与PathAnimationManager、TimeLinerIntegrationManager和PathCurveEngine紧密集成，实现流畅的路径动画仿真。

## 2.5.1.2. 功能

### 核心功能
1. **动画生成**：根据路径生成物流组件的运动动画
2. **动画播放**：播放生成的动画
3. **动画控制**：支持播放、暂停、停止、步进控制
4. **时长设置**：支持设置动画总时长
5. **速度控制**：支持调整播放速度
6. **双向播放**：支持正向和反向播放

### 子功能
| 功能编号 | 功能名称 | 功能描述 |
|---------|---------|---------|
| 2.5.1.F1 | 动画对象选择 | 选择要动画的物流组件 |
| 2.5.1.F2 | 路径选择 | 选择动画路径 |
| 2.5.1.F3 | 动画生成 | 生成沿路径的动画 |
| 2.5.1.F4 | 播放控制 | 播放、暂停、停止动画 |
| 2.5.1.F5 | 步进控制 | 单步前进/后退 |
| 2.5.1.F6 | 时长设置 | 设置动画总时长 |
| 2.5.1.F7 | 速度调节 | 调节播放速度倍率 |
| 2.5.1.F8 | 进度跳转 | 跳转到指定进度 |
| 2.5.1.F9 | 循环播放 | 设置循环播放模式 |
| 2.5.1.F10 | TimeLiner集成 | 与TimeLiner任务同步 |

## 2.5.1.3. 性能

### 性能指标
| 指标名称 | 目标值 | 说明 |
|---------|-------|------|
| 动画生成时间 | < 2秒 | 生成动画的响应时间 |
| 播放帧率 | > 30FPS | 动画播放的帧率 |
| 内存占用 | < 200MB | 动画过程的内存占用 |
| 支持路径长度 | 无限制 | 支持的最长路径 |

### 性能优化策略
1. 预计算动画帧数据
2. 使用空间索引优化碰撞检测
3. 帧数据缓存和复用

## 2.5.1.4. 输入输出项

### 1. 字段输入输出

#### 输入字段
| 字段名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| AnimatedObject | ModelItem | 是 | 动画对象 |
| Route | PathRoute | 是 | 动画路径 |
| Duration | double | 否 | 动画时长（秒），默认10秒 |
| FrameRate | int | 否 | 帧率，默认30FPS |

#### 输出字段
| 字段名 | 类型 | 说明 |
|-------|------|------|
| AnimationFrames | List<AnimationFrame> | 动画帧数据 |
| TotalFrames | int | 总帧数 |
| CurrentFrame | int | 当前帧索引 |
| AnimationState | AnimationState | 动画状态 |

### 2. 界面交互输入输出

#### 界面输入
- 对象选择操作
- 路径选择
- 播放控制按钮
- 进度条拖动
- 速度调节滑块

#### 界面输出
- 动画状态显示
- 进度条更新
- 当前帧信息显示
- 播放时间显示

## 2.5.1.5. 算法

### 动画生成算法
```
算法：生成路径动画
输入：动画对象，路径，时长，帧率
输出：动画帧数据

1. 计算总帧数：duration * frameRate
2. 对于每帧：
   3. 计算进度：frameIndex / totalFrames
   4. 根据进度计算路径上的位置
   5. 计算朝向（根据路径方向）
   6. 创建动画帧数据
7. 返回所有帧数据
```

### 路径位置计算算法
```
算法：计算路径上的位置
输入：路径点列表，进度（0-1）
输出：位置和朝向

1. 计算目标距离：总长度 * 进度
2. 遍历路径段：
   3. 如果目标距离在当前段内：
      4. 计算段内插值比例
      5. 插值计算位置
      6. 计算朝向向量
      7. 返回结果
   8. 减去当前段长度，继续
```

### 动画帧插值算法
```
算法：平滑插值动画帧
输入：当前帧索引，总帧数，路径数据
输出：插值后的位置和旋转

1. 计算精确的进度值
2. 找到前后关键帧
3. 计算插值权重
4. 对位置进行Lerp插值
5. 对旋转进行Slerp插值
6. 返回插值结果
```

## 2.5.1.6. 流程逻辑

```
开始
  │
  ▼
┌─────────────────┐
│  选择动画对象    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  选择动画路径    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  设置动画参数    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  生成动画数据    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  开始播放动画    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  更新对象位置    │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐  ┌────────┐
│继续播放│  │用户控制│
└───┬────┘  └───┬────┘
    │    暂停   │
    │  ┌────────┘
    │  ▼
    │ ┌──────────┐
    │ │ 暂停状态 │
    │ └───┬──────┘
    │     │ 继续
    └─────┤
          │
          ▼
┌─────────────────┐
│  动画结束/停止   │
└────────┬────────┘
         │
         ▼
        结束
```

## 2.5.1.7. 接口

### 公共接口
```csharp
/// <summary>
/// 路径动画管理器
/// </summary>
public class PathAnimationManager
{
    /// <summary>
    /// 创建动画
    /// </summary>
    /// <param name="animatedObject">动画对象</param>
    /// <param name="route">动画路径</param>
    /// <param name="config">动画配置</param>
    public void CreateAnimation(ModelItem animatedObject, PathRoute route, AnimationConfig config);
    
    /// <summary>
    /// 播放动画
    /// </summary>
    public void Play();
    
    /// <summary>
    /// 暂停动画
    /// </summary>
    public void Pause();
    
    /// <summary>
    /// 停止动画
    /// </summary>
    public void Stop();
    
    /// <summary>
    /// 步进播放
    /// </summary>
    /// <param name="direction">方向：1=前进，-1=后退</param>
    public void Step(int direction);
    
    /// <summary>
    /// 跳转到指定进度
    /// </summary>
    /// <param name="progress">进度（0-1）</param>
    public void Seek(double progress);
    
    /// <summary>
    /// 设置播放速度
    /// </summary>
    /// <param name="speed">速度倍率</param>
    public void SetPlaybackSpeed(double speed);
}

/// <summary>
/// 动画配置
/// </summary>
public class AnimationConfig
{
    public double Duration { get; set; }
    public int FrameRate { get; set; }
    public double DetectionTolerance { get; set; }
    public bool EnableCollisionDetection { get; set; }
}
```

### 事件接口
```csharp
/// <summary>
/// 动画状态变更事件
/// </summary>
public event EventHandler<AnimationState> StateChanged;

/// <summary>
/// 动画进度更新事件
/// </summary>
public event EventHandler<double> ProgressUpdated;

/// <summary>
/// 动画帧更新事件
/// </summary>
public event EventHandler<AnimationFrame> FrameUpdated;
```

## 2.5.1.8. 注释设计

### 代码注释规范
```csharp
/// <summary>
/// 动画状态
/// </summary>
public enum AnimationState
{
    /// <summary>
    /// 空闲，未生成动画
    /// </summary>
    Idle,
    
    /// <summary>
    /// 已就绪，动画已生成但未播放
    /// </summary>
    Ready,
    
    /// <summary>
    /// 播放中
    /// </summary>
    Playing,
    
    /// <summary>
    /// 暂停
    /// </summary>
    Paused,
    
    /// <summary>
    /// 已停止
    /// </summary>
    Stopped,
    
    /// <summary>
    /// 已完成
    /// </summary>
    Finished
}

/// <summary>
/// 动画帧数据
/// </summary>
public class AnimationFrame
{
    /// <summary>
    /// 帧索引
    /// </summary>
    public int Index { get; set; }
    
    /// <summary>
    /// 进度（0-1）
    /// </summary>
    public double Progress { get; set; }
    
    /// <summary>
    /// 该帧的位置
    /// </summary>
    public Point3D Position { get; set; }
    
    /// <summary>
    /// 绕Z轴的偏航角（弧度）
    /// </summary>
    public double YawRadians { get; set; }
}
```

## 2.5.1.9. 数据结构

### AnimationState 枚举
| 值 | 说明 |
|---|------|
| Idle | 空闲状态 |
| Ready | 已就绪 |
| Playing | 播放中 |
| Paused | 暂停 |
| Stopped | 已停止 |
| Finished | 已完成 |

### AnimationConfig 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| Duration | double | 动画时长（秒） |
| FrameRate | int | 帧率（FPS） |
| DetectionTolerance | double | 检测容差（米） |
| EnableCollisionDetection | bool | 启用碰撞检测 |
| LoopPlayback | bool | 循环播放 |

### AnimationFrame 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| Index | int | 帧索引 |
| Progress | double | 进度（0-1） |
| Position | Point3D | 位置 |
| YawRadians | double | 偏航角（弧度） |
| Collisions | List<CollisionResult> | 碰撞结果 |
| HasCollision | bool | 是否有碰撞 |

### PlaybackState 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| State | AnimationState | 当前状态 |
| CurrentFrame | int | 当前帧索引 |
| CurrentProgress | double | 当前进度 |
| PlaybackSpeed | double | 播放速度倍率 |
| RemainingTime | TimeSpan | 剩余时间 |