pythagodzilla/likeRunner

Fork 0

pythagodzilla 07cb1304d2 init

2026-03-19 17:57:03 +08:00

5.0 KiB

Raw Permalink Blame History

快速开始指南

项目已准备好！

新项目位置：/Users/pythagodzilla/Projects/Kotlin/refactored-likeRunner/

文件清单

📌 必读文档（3份）

README.md - 项目完整说明
DATA_FLOW_GUIDE.md - 数据流快速参考（最重要）
BEFORE_AFTER.md - 改进前后对比

📌 项目代码（9个文件）

数据模型层

model/Coordinate.kt - 4种坐标类型
model/MotionState.kt - 2种状态类型

核心模拟层

core/TrajectorySimulator.kt - 主协调器（从这里开始理解）
core/physics/RunnerPhysics.kt - 物理计算
core/trajectory/PathInterpolator.kt - 路径插值（Haversine完全保留）

噪声处理层

noise/NoiseProcessor.kt - 噪声协调器
noise/GpsNoiseEngine.kt - GPS噪声 + 预留其他引擎

程序入口

Main.kt - 使用示例

数据资源

resources/data/SampleRoute.kt - 样本轨迹

5分钟快速理解

问题1：程序是干什么的？

✅ 模拟真实的跑步轨迹，包含：

物理计算（距离、速度、加速度）
路径插值（根据距离找坐标）
GPS噪声模拟（白噪声 + 漂移）

问题2：怎么用？

✅ 看 Main.kt 就行：

val simulator = TrajectorySimulator(sampleRoute)
for (time in 0.0..duration step 0.1) {
    val motionState = simulator.simulate(time)
    println(motionState)
}

问题3：数据流是什么？

✅ 4步简单流程：

时间 → [物理] → 距离 → [路径] → 坐标 → [噪声] → 最终坐标 → [组装] → 输出

详见 DATA_FLOW_GUIDE.md

问题4：我想加新功能怎么办？

✅ 取决于是什么功能：

改物理：改 RunnerPhysics.kt
加噪声：改 GpsNoiseEngine.kt
改坐标：改 Coordinate.kt
改路径：改 PathInterpolator.kt（只改命名，算法完全保留）

详见 DATA_FLOW_GUIDE.md 的"在哪里插入新功能"

问题5：原有代码呢？

✅ 完全保留在 /Users/pythagodzilla/Projects/Kotlin/likeRunner/

新项目不会影响原项目。

文件阅读顺序

第一次接触项目（推荐）

1. 本文件（QUICK_START.md）      ← 你在这里
2. README.md                     ← 了解项目概况
3. Main.kt                       ← 看代码怎么用
4. DATA_FLOW_GUIDE.md           ← 深入理解数据流
5. core/TrajectorySimulator.kt  ← 看主协调器

要修改代码时

1. DATA_FLOW_GUIDE.md            ← 找到目标步骤
2. 对应的代码文件                ← 修改代码
3. BEFORE_AFTER.md              ← 参考改进示例

要添加新功能时

1. DATA_FLOW_GUIDE.md            ← "在哪里插入新功能"部分
2. GpsNoiseEngine.kt             ← 参考预留位置的代码
3. 创建新文件或修改现有文件

核心概念速查

4步数据流

步骤1 [物理]    : time → PhysicsState
步骤2 [路径]    : distance → RawCoordinate
步骤3 [噪声]    : RawCoordinate → NoisyCoordinate
步骤4 [组装]    : 所有 → MotionState

关键类

TrajectorySimulator  ← 主协调器，管理4步
RunnerPhysics        ← 步骤1
PathInterpolator     ← 步骤2
NoiseProcessor       ← 步骤3
GpsNoiseEngine       ← 步骤3的实现

关键方法

TrajectorySimulator.simulate(time)     ← 主入口
RunnerPhysics.calculate(time)          ← 物理计算
PathInterpolator.interpolate(distance) ← 路径查询
NoiseProcessor.applyNoise(...)         ← 添加噪声

代码规范

✅ 保留原样

Haversine算法逻辑
GPS噪声模型逻辑
所有数学计算

✅ 改进

方法命名（haversine → calculateHaversineDistance）
类名规范（PathLinearize → PathInterpolator）
数据类型清晰（每步都有明确的输出类型）
充分注释（伪代码、说明、预留标记）

✅ 新增

NoiseProcessor 协调器
中间数据类型（RawCoordinate, PhysicsState等）
详细注释和文档

常见问题

Q: Haversine算法被改了吗？ A: 没有。只改了方法名（haversine → calculateHaversineDistance），逻辑完全一样。

Q: GPS噪声算法被改了吗？ A: 没有。白噪声和漂移的计算逻辑完全保留，返回值改为Triple以包含噪声大小。

Q: 我能直接跑这个代码吗？ A: 大部分可以（Main.kt展示了完整流程），但物理计算部分还需要实现（已标记TODO）。

Q: 怎么才能在项目中看到数据流？ A: 打开 core/TrajectorySimulator.kt，simulate() 方法就是完整的4步流程。

Q: 预留位置在哪里？ A: 在 GpsNoiseEngine.kt 和 NoiseProcessor.kt 中，都用注释清晰标记了。

Q: 能同时运行原项目和新项目吗？ A: 可以，它们完全独立。新项目在 refactored-likeRunner/ 文件夹里。

下一步

阅读 README.md 了解完整项目
在 Main.kt 中看程序怎么用
阅读 DATA_FLOW_GUIDE.md 深入理解数据流
根据需要修改或添加功能

祝你使用愉快！有问题随时查看相关文档。

5.0 KiB Raw Permalink Blame History Unescape Escape