NavisworksTransport/doc/working/2017/timeliner_integration_plan.md

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 不支持）

技术实现

核心架构

// 主要集成类
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 vehicle);
    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 任务创建

public TimelinerTask CreateTransportTask(string taskName, List<Point3D> pathPoints, 
    TimeSpan duration, ModelItem vehicle)
{
    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(vehicle);
    task.Selection.CopyFrom(selection);
    
    // 添加到文档
    _documentTimeliner.Tasks.Add(task);
    
    return task;
}

2. 动画状态同步

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 集成增强

public class TimeLinerIntegratedAnimationManager : PathAnimationManager
{
    private TimeLinerIntegrationManager _timeLinerManager;
    
    public override void StartAnimation(ModelItem vehicle, List<Point3D> pathPoints, TimeSpan duration)
    {
        // 创建 TimeLiner 任务
        var task = _timeLinerManager.CreateTransportTask(
            $"运输路径_{DateTime.Now:HHmmss}", 
            pathPoints, 
            duration, 
            vehicle);
        
        // 启动自制动画系统
        base.StartAnimation(vehicle, 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 引用

<Reference Include="Autodesk.Navisworks.Api.Timeliner">
  <HintPath>$(NAVISWORKS_INSTALL_PATH)\Autodesk.Navisworks.Api.Timeliner.dll</HintPath>
</Reference>

新增的命名空间

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 不可用时自动切换到现有实现
• 充分测试：每个功能都要在实际环境中测试

成功标准

基础成功标准

• 能够在 TimeLiner 中创建运输任务
• 任务信息正确显示（名称、时间、关联对象）
• 动画状态正确同步到 TimeLiner
• 不影响现有动画功能

进阶成功标准

• TimeLiner 播放控制能够控制动画
• 时间轴进度与动画进度同步
• 支持多个并发运输任务
• 任务层次结构管理功能

后续扩展

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

---

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