159 lines
4.9 KiB
Markdown
159 lines
4.9 KiB
Markdown
# 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 导出功能
|
||
- [ ] 不同运动模式支持
|