# TrajectoryRunner - 轨迹生成器

## 概述

这是一个模拟真实跑步轨迹的 Kotlin 程序，用于生成带有物理特性和GPS噪声的运动轨迹数据。

## 核心架构

整个程序遵循清晰的 4 步数据流：

```
时间 t
  ↓
[步骤1: 物理计算] → 距离、速度、加速度
  ↓
[步骤2: 路径插值] → 原始坐标(lon, lat)
  ↓
[步骤3: 噪声处理] → 添加GPS/速度/加速度噪声
  ↓
[步骤4: 结果组装] → MotionState(完整运动状态)
  ↓
输出: 模拟的轨迹点
```

## 目录结构

```
src/main/kotlin/
├── Main.kt                              # 程序入口
├── model/                               # 数据模型
│   ├── Coordinate.kt                   # 坐标类型定义
│   └── MotionState.kt                  # 运动状态定义
├── core/                                # 核心模拟逻辑
│   ├── TrajectorySimulator.kt          # 主协调器
│   ├── physics/                         # 物理引擎
│   │   └── RunnerPhysics.kt            # 物理计算
│   └── trajectory/                      # 轨迹处理
│       └── PathInterpolator.kt         # 路径插值（含Haversine算法）
├── noise/                               # 噪声引擎
│   ├── NoiseProcessor.kt               # 噪声协调器
│   ├── GpsNoiseEngine.kt               # GPS噪声（已实现）
│   │                                   # + VelocityNoiseEngine（预留）
│   │                                   # + AccelerationNoiseEngine（预留）
└── resources/data/                      # 样本数据
    └── SampleRoute.kt                  # 样本轨迹数据

```

## 关键类说明

### TrajectorySimulator（轨迹模拟器）
- **职责**：管理整个数据流，协调各个引擎
- **初始化**：创建 PathInterpolator, RunnerPhysics, NoiseProcessor
- **核心方法**：`simulate(time)` - 执行完整的4步处理

### PathInterpolator（路径插值器）
- **职责**：根据距离在轨迹上查找坐标
- **算法**：Haversine（计算球面距离）
- **核心方法**：`interpolate(distance)` - 线性插值

### RunnerPhysics（物理引擎）
- **职责**：计算物理参数（距离、速度、加速度）
- **输入**：时间
- **输出**：PhysicsState

### NoiseProcessor（噪声处理器）
- **职责**：管理并应用各种噪声
- **已实现**：GpsNoiseEngine（GPS信号误差 + 漂移）
- **预留**：VelocityNoiseEngine, AccelerationNoiseEngine

## 数据模型

### MetaCoordinate（原始坐标）
```kotlin
data class MetaCoordinate(val lon: Double, val lat: Double)
```
轨迹的基础路径点。

### PhysicsState（物理状态）
```kotlin
data class PhysicsState(
    val time: Double,
    val distance: Double,
    val velocity: Double,
    val acceleration: Double
)
```
某一时刻的物理参数。

### MotionState（运动状态）
```kotlin
data class MotionState(
    val time: Double,
    val distance: Double,
    val velocity: Double,
    val acceleration: Double,
    val latitude: Double,           // 带GPS噪声
    val longitude: Double,          // 带GPS噪声
    val gpsError: Double,
    val velocityNoise: Double,      // 预留
    val accelNoise: Double          // 预留
)
```
最终的综合运动状态。

## 添加新功能的方法

### 例1：添加速度噪声
在 `GpsNoiseEngine.kt` 中，有预留的 `VelocityNoiseEngine` 类框架，只需在 `NoiseProcessor.applyNoise()` 中调用：
```kotlin
val velocityNoise = velocityNoiseEngine.applyNoise(physicsState.velocity)
```

### 例2：添加高程信息
在 `PathInterpolator.interpolate()` 返回后，创建 `ElevationInterpolator`，在步骤2和步骤3之间插入：
```kotlin
// 步骤2.5：插值高程
val elevation = elevationInterpolator.interpolate(physicsState.distance)
```

### 例3：支持不同运动模式
在 `RunnerPhysics.calculate()` 中增加运动模式判断，不同模式使用不同的速度曲线。

## 代码设计原则

1. **单一职责**：每个类只做一件事
2. **清晰的数据流**：4步处理，输入输出明确
3. **易于扩展**：预留位置和接口，支持未来添加新功能
4. **逻辑完整**：核心算法逻辑保持原有
5. **充分注释**：伪代码和数据流说明帮助理解

## 使用示例

```kotlin
fun main() {
    // 创建模拟器
    val simulator = TrajectorySimulator(sampleRoute)
    
    // 配置参数
    simulator.setPhysicsParams(5000.0, 1800.0, 4.0)
    simulator.setNoiseParams(0.00002, 0.3)
    
    // 模拟运动
    for (time in 0.0..1800.0 step 0.1) {
        val motionState = simulator.simulate(time)
        println(motionState)
    }
}
```

## 预留扩展点

- [ ] 完整的 RunnerPhysics 物理模型实现
- [ ] VelocityNoiseEngine 速度噪声引擎
- [ ] AccelerationNoiseEngine 加速度噪声引擎
- [ ] 高程插值 (ElevationInterpolator)
- [ ] GPX/KML 导出功能
- [ ] 不同运动模式支持