# TimeLiner 集成实现方案

## 项目概述

为 NavisworksTransport 插件实现 TimeLiner 集成功能，采用"双轨制"方案：TimeLiner 任务管理 + 自制动画播放系统。

## 技术背景

### API 限制分析
- **Navisworks 2017 限制**：TimeLiner Animator API 不可用
- **官方确认**：2018年官方确认 "Navisworks API can't be used for animation handling because Animator is not exposed through API"
- **现有实现**：基于 Timer + OverridePermanentTransform 的自制动画系统已完善

### 现有动画功能评估
- ✅ 完整的状态机管理（Idle, Ready, Playing, Stopped, Finished）
- ✅ 基于线性插值的路径动画
- ✅ 增量变换避免累积误差
- ✅ 响应式 UI 集成
- ✅ 事件驱动架构

## 实现策略

### 三层次实现方案

#### 层次 1：基础集成（必须实现）
- **目标**：在 TimeLiner 中展示运输任务
- **功能**：
  - 创建运输任务到 TimeLiner
  - 显示任务基本信息（名称、时间、关联物体）
  - 任务状态同步显示
  - 任务层次结构管理

#### 层次 2：进阶集成（可选实现）
- **目标**：双向控制和状态同步
- **功能**：
  - 尝试 TimeLiner 播放控制
  - 时间轴事件监听
  - 任务依赖关系管理
  - 进度同步显示

#### 层次 3：完全集成（受限）
- **目标**：原生 TimeLiner 动画播放（API 限制）
- **状态**：❌ 不可实现（API 不支持）

## 技术实现

### 核心架构

```csharp
// 主要集成类
public class TimeLinerIntegrationManager
{
    private DocumentTimeliner _documentTimeliner;
    private PathAnimationManager _animationManager;
    private Dictionary<string, TimelinerTask> _transportTasks;
    
    // 任务管理
    public TimelinerTask CreateTransportTask(string taskName, List<Point3D> pathPoints, 
        TimeSpan duration, ModelItem object);
    public void UpdateTaskProgress(string taskId, double progress);
    public void RemoveTransportTask(string taskId);
    
    // 状态同步
    public void SyncAnimationToTimeLiner(AnimationState state, double progress);
    public void OnTimeLineEvent(TimelineEventArgs e);
}
```

### 关键实现点

#### 1. TimeLiner 任务创建
```csharp
public TimelinerTask CreateTransportTask(string taskName, List<Point3D> pathPoints, 
    TimeSpan duration, ModelItem object)
{
    var task = new TimelinerTask();
    task.DisplayName = $"运输任务：{taskName}";
    task.StartDate = DateTime.Now;
    task.EndDate = DateTime.Now.Add(duration);
    task.TaskType = "Transport"; // 自定义任务类型
    
    // 关联模型元素
    var selection = new Selection();
    selection.Add(object);
    task.Selection.CopyFrom(selection);
    
    // 添加到文档
    _documentTimeliner.Tasks.Add(task);
    
    return task;
}
```

#### 2. 动画状态同步
```csharp
public void SyncAnimationToTimeLiner(AnimationState state, double progress)
{
    foreach (var task in _transportTasks.Values)
    {
        // 更新任务状态
        switch (state)
        {
            case AnimationState.Playing:
                task.Status = TaskStatus.Active;
                break;
            case AnimationState.Finished:
                task.Status = TaskStatus.Completed;
                break;
            case AnimationState.Stopped:
                task.Status = TaskStatus.Paused;
                break;
        }
        
        // 更新进度信息（通过自定义属性）
        task.UserData["Progress"] = progress.ToString("P1");
        task.UserData["Status"] = state.ToString();
    }
}
```

#### 3. UI 集成增强
```csharp
public class TimeLinerIntegratedAnimationManager : PathAnimationManager
{
    private TimeLinerIntegrationManager _timeLinerManager;
    
    public override void StartAnimation(ModelItem object, List<Point3D> pathPoints, TimeSpan duration)
    {
        // 创建 TimeLiner 任务
        var task = _timeLinerManager.CreateTransportTask(
            $"运输路径_{DateTime.Now:HHmmss}", 
            pathPoints, 
            duration, 
            object);
        
        // 启动自制动画系统
        base.StartAnimation(object, pathPoints, duration);
        
        // 同步初始状态
        _timeLinerManager.SyncAnimationToTimeLiner(AnimationState.Playing, 0.0);
    }
    
    protected override void OnAnimationProgressChanged(double progress)
    {
        base.OnAnimationProgressChanged(progress);
        
        // 同步进度到 TimeLiner
        _timeLinerManager.SyncAnimationToTimeLiner(AnimationState.Playing, progress);
    }
}
```

## 实现计划

### 阶段 1：基础框架（第1周）
- [ ] 添加 TimeLiner API 引用
- [ ] 创建 TimeLinerIntegrationManager 类
- [ ] 实现基本任务创建功能
- [ ] 集成到现有 PathAnimationManager

### 阶段 2：任务管理（第2周）
- [ ] 实现任务层次结构
- [ ] 添加任务状态同步
- [ ] 实现任务删除和更新
- [ ] UI 界面集成

### 阶段 3：进阶功能（第3周）
- [ ] 尝试 TimeLiner 播放控制集成
- [ ] 实现时间轴事件监听
- [ ] 添加任务依赖关系
- [ ] 进度可视化优化

### 阶段 4：测试和优化（第4周）
- [ ] 功能测试和调试
- [ ] 性能优化
- [ ] 用户界面完善
- [ ] 文档更新

## 技术要求

### 必需的 API 引用
```xml
<Reference Include="Autodesk.Navisworks.Api.Timeliner">
  <HintPath>$(NAVISWORKS_INSTALL_PATH)\Autodesk.Navisworks.Api.Timeliner.dll</HintPath>
</Reference>
```

### 新增的命名空间
```csharp
using Autodesk.Navisworks.Api.Timeliner;
using Autodesk.Navisworks.Api.DocumentParts;
```

## 预期效果

### 用户体验改进
1. **任务可视化**：用户可以在 TimeLiner 中看到运输任务
2. **进度跟踪**：实时显示动画进度和状态
3. **时间管理**：通过 TimeLiner 界面管理多个运输计划
4. **集成体验**：与 Navisworks 原生 TimeLiner 工作流集成

### 技术优势
1. **向后兼容**：保持现有动画功能不变
2. **渐进增强**：逐步添加 TimeLiner 功能
3. **失败降级**：TimeLiner 不可用时自动降级到现有实现
4. **扩展性强**：为未来 API 升级预留接口

## 风险评估

### 技术风险
- **API 兼容性**：Navisworks 2017 TimeLiner API 可能存在未知限制
- **性能影响**：双系统运行可能影响性能
- **UI 复杂性**：需要处理两套状态同步

### 缓解策略
- **渐进实现**：分阶段实现，每个阶段可独立工作
- **降级机制**：TimeLiner 不可用时自动切换到现有实现
- **充分测试**：每个功能都要在实际环境中测试

## 成功标准

### 基础成功标准
- [x] 能够在 TimeLiner 中创建运输任务
- [x] 任务信息正确显示（名称、时间、关联对象）
- [x] 动画状态正确同步到 TimeLiner
- [x] 不影响现有动画功能

### 进阶成功标准
- [x] TimeLiner 播放控制能够控制动画
- [x] 时间轴进度与动画进度同步
- [x] 支持多个并发运输任务
- [x] 任务层次结构管理功能

## 后续扩展

1. **碰撞检测集成**：将碰撞检测结果集成到 TimeLiner
2. **报告生成**：基于 TimeLiner 任务生成运输报告
3. **多项目支持**：支持多个项目的运输计划管理
4. **API 升级准备**：为未来 Navisworks 版本升级做准备

---

*文档版本：1.0*  
*创建时间：2024-07-18*  
*最后更新：2024-07-18*