217 lines
5.8 KiB
Markdown
217 lines
5.8 KiB
Markdown
# 数据流快速参考指南
|
||
|
||
## 一句话理解：4步处理流程
|
||
|
||
```
|
||
时间 → 物理 → 路径 → 噪声 → 结果
|
||
```
|
||
|
||
## 详细数据流
|
||
|
||
### 第1步：物理计算 (Physics)
|
||
|
||
```
|
||
输入：double time（秒）
|
||
|
||
过程：
|
||
RunnerPhysics.calculate(time)
|
||
↓
|
||
计算距离、速度、加速度
|
||
|
||
输出：PhysicsState
|
||
{
|
||
time: Double, // 时间
|
||
distance: Double, // 行进距离（米）
|
||
velocity: Double, // 速度（m/s）
|
||
acceleration: Double // 加速度（m/s²）
|
||
}
|
||
|
||
文件位置：src/main/kotlin/core/physics/RunnerPhysics.kt
|
||
```
|
||
|
||
### 第2步：路径插值 (Trajectory)
|
||
|
||
```
|
||
输入：double distance（米）来自第1步
|
||
|
||
过程：
|
||
PathInterpolator.interpolate(distance)
|
||
↓
|
||
在轨迹上查找对应坐标
|
||
（使用Haversine算法计算路段距离）
|
||
（线性插值得到准确坐标）
|
||
|
||
输出：RawCoordinate（无噪声）
|
||
{
|
||
lon: Double, // 经度
|
||
lat: Double // 纬度
|
||
}
|
||
|
||
文件位置：src/main/kotlin/core/trajectory/PathInterpolator.kt
|
||
```
|
||
|
||
### 第3步：噪声处理 (Noise)
|
||
|
||
```
|
||
输入：
|
||
- RawCoordinate（第2步的输出）
|
||
- PhysicsState（第1步的输出）
|
||
|
||
过程：
|
||
NoiseProcessor.applyNoise()
|
||
↓
|
||
├─ GpsNoiseEngine.applyNoise(lon, lat)
|
||
│ - 白噪声：每个时刻的随机偏差
|
||
│ - 漂移：GPS偏向某侧的持续特性
|
||
│ - 返回：(lon±noise, lat±noise, error_magnitude)
|
||
│
|
||
├─ [预留] VelocityNoiseEngine.applyNoise(velocity)
|
||
│ - 速度波动噪声
|
||
│
|
||
└─ [预留] AccelerationNoiseEngine.applyNoise(acceleration)
|
||
- 加速度波动噪声
|
||
|
||
输出：NoisyCoordinate
|
||
{
|
||
lon: Double, // 经度（带噪声）
|
||
lat: Double, // 纬度（带噪声）
|
||
gpsError: Double // 噪声大小（米）
|
||
}
|
||
|
||
文件位置：
|
||
- 协调器：src/main/kotlin/noise/NoiseProcessor.kt
|
||
- GPS噪声：src/main/kotlin/noise/GpsNoiseEngine.kt
|
||
```
|
||
|
||
### 第4步：结果组装 (Assembly)
|
||
|
||
```
|
||
输入：
|
||
- PhysicsState（第1步）
|
||
- NoisyCoordinate（第3步）
|
||
|
||
过程：
|
||
组装所有数据到单一对象
|
||
|
||
输出：MotionState（最终结果）
|
||
{
|
||
time: Double, // 时间（秒）
|
||
distance: Double, // 距离（米）
|
||
velocity: Double, // 速度（m/s）
|
||
acceleration: Double, // 加速度（m/s²）
|
||
latitude: Double, // 纬度（带噪声）
|
||
longitude: Double, // 经度（带噪声）
|
||
gpsError: Double, // GPS噪声（米）
|
||
velocityNoise: Double, // 速度噪声（预留）
|
||
accelNoise: Double // 加速度噪声（预留）
|
||
}
|
||
|
||
文件位置：src/main/kotlin/model/MotionState.kt
|
||
```
|
||
|
||
## 在哪里插入新功能？
|
||
|
||
### 想添加速度噪声？
|
||
```
|
||
位置：第3步 - NoiseProcessor.applyNoise()
|
||
方法：
|
||
1. 在 GpsNoiseEngine.kt 中实现 VelocityNoiseEngine
|
||
2. 在 NoiseProcessor 中调用：
|
||
val velNoise = velocityNoiseEngine.applyNoise(physicsState.velocity)
|
||
3. 在 MotionState 中记录结果：velocityNoise = velNoise
|
||
```
|
||
|
||
### 想添加高程信息？
|
||
```
|
||
位置：第2步和第3步之间
|
||
方法：
|
||
1. 创建 src/main/kotlin/core/trajectory/ElevationInterpolator.kt
|
||
2. 在 TrajectorySimulator.simulate() 中：
|
||
步骤2.5: val elevation = elevationInterpolator.interpolate(distance)
|
||
3. 扩展 MotionState 添加 elevation 字段
|
||
```
|
||
|
||
### 想改变运动模式（跑步/散步）？
|
||
```
|
||
位置：第1步 - RunnerPhysics.calculate()
|
||
方法：
|
||
1. 在 RunnerPhysics 中添加运动模式参数
|
||
2. 根据速度判断当前模式
|
||
3. 不同模式使用不同的速度曲线
|
||
```
|
||
|
||
### 想添加传感器噪声（加速度计）？
|
||
```
|
||
位置：第3步 - NoiseProcessor.applyNoise()
|
||
方法：
|
||
1. 在 GpsNoiseEngine.kt 中实现 AccelerationNoiseEngine
|
||
2. 在 NoiseProcessor 中调用
|
||
3. 在 MotionState 中记录结果
|
||
```
|
||
|
||
## 重要的类和文件
|
||
|
||
| 类名 | 文件位置 | 职责 |
|
||
|------|---------|------|
|
||
| TrajectorySimulator | core/TrajectorySimulator.kt | 主协调器，管理4步流程 |
|
||
| RunnerPhysics | core/physics/RunnerPhysics.kt | 第1步：物理计算 |
|
||
| PathInterpolator | core/trajectory/PathInterpolator.kt | 第2步：路径插值 |
|
||
| NoiseProcessor | noise/NoiseProcessor.kt | 第3步：噪声处理 |
|
||
| GpsNoiseEngine | noise/GpsNoiseEngine.kt | GPS噪声实现 |
|
||
| MotionState | model/MotionState.kt | 最终输出数据结构 |
|
||
|
||
## 调用顺序（不要改）
|
||
|
||
```
|
||
main()
|
||
↓
|
||
TrajectorySimulator(route) // 初始化
|
||
↓
|
||
for (time in 0..duration)
|
||
↓
|
||
simulator.simulate(time)
|
||
↓
|
||
[第1步] physicsEngine.calculate(time) → PhysicsState
|
||
↓
|
||
[第2步] pathInterpolator.interpolate(distance) → RawCoordinate
|
||
↓
|
||
[第3步] noiseProcessor.applyNoise(rawCoord, physicsState) → NoisyCoordinate
|
||
↓
|
||
[第4步] 组装 MotionState
|
||
↓
|
||
return MotionState
|
||
```
|
||
|
||
## 核心算法（逻辑保持原样）
|
||
|
||
### Haversine 公式（计算球面距离）
|
||
位置：PathInterpolator.calculateHaversineDistance()
|
||
- 输入：两个坐标点
|
||
- 输出：球面距离（米）
|
||
- **逻辑完全保留**
|
||
|
||
### GPS 噪声模型
|
||
位置：GpsNoiseEngine.applyNoise()
|
||
- 白噪声：高斯分布
|
||
- 漂移：0.8 衰减 + 随机累积
|
||
- **逻辑完全保留**
|
||
|
||
## 常见问题
|
||
|
||
**Q: 我该改哪个文件？**
|
||
A: 看你要做什么：
|
||
- 改物理计算 → RunnerPhysics.kt
|
||
- 改路径算法 → PathInterpolator.kt（但不要改Haversine）
|
||
- 加新噪声 → GpsNoiseEngine.kt 或新建文件
|
||
- 改输出格式 → MotionState.kt
|
||
|
||
**Q: 怎么知道在哪一步插入新功能？**
|
||
A: 问自己"我的新功能需要什么输入"：
|
||
- 需要时间 → 第1步前
|
||
- 需要距离 → 第2步前
|
||
- 需要坐标 → 第3步前
|
||
- 需要物理参数 → 第3步中
|
||
|
||
**Q: 原有代码会不会被破坏？**
|
||
A: 不会。原始项目（likeRunner）完全保留，新项目（refactored-likeRunner）独立放置。
|