GPXを到着時間推定に合わせて走らせるようにし、同梱のGPXを作り直した

[TinyKitten]

概要

GPX 生成スクリプトで、駅間の長さに線路の長さを使うようにしました。--line-group では、StationAPI の到着時間推定の見込みに合わせて走らせます。あわせて、同梱の GPX を作り直しました。

これまでの GPX は、駅間を直線距離で測り、固定の最高速度と 60 秒の停車で走っていました。そのため所要時間が実際より短くなっていました。京王線の特急（新宿→京王八王子）は、実際のダイヤでは約 45 分かかりますが、GPX は約 35 分でした。今回作り直した GPX では 41.4 分です。

GPX が使う見込みは trainRoute の Estimated で、線路の長さと、その距離で求め直した較正を使います（TrainLCD/StationAPI#1712、#1714）。アプリの ETA（estimateArrivalTimes）と経路検索は元の計算のままなので、GPX の所要時間は ETA の見込みと一致しません。同梱の GPX を ETA 補助ありとなしで流すテスト（location.gpxEtaAssist.test.ts）では、どの GPX も両者の走行結果が一致し、ETA 補助による棄却は起きませんでした。

変更の種類

• バグ修正
• 新機能
• リファクタリング
• ドキュメント
• CI/CD
• その他

変更内容

• 生成スクリプト（scripts/generate-location-gpx.mjs）
  • 駅間の長さは trackDistanceFromPrevious（線路の長さ）を使います。値が返らない区間だけ直線距離にします。逆向きに走らせるときは、値を走る向きの直前の駅に付け替えます。
  • --line-group では、trainRoute に model: Estimated（trainRouteに到着時間推定のモデルで区間の値を返すEstimatedモードを追加 StationAPI#1710）を渡し、到着・出発の見込みを取ります。
    • 停車駅間の走行時間は「次の停車駅の到着 − この駅の出発」です。この時間で走り切る巡航速度を台形の式から求め、線路の長さの上を走らせます。
    • 途中駅の停車時間は、推定の値（出発 − 到着）です。
    • 推定では停まるが GPX では通過する駅（平日運転の駅を休日に走るときや --skip）は、その停車時間を走行時間から引きます。GPX で停まる駅を推定が通過しているときは、--dwell の指定を求めて止まります。
    • 区間ごとの 1 秒未満の端数は、次の区間で計画した到着時刻へ戻すので、終点までに積み上がりません。京王線特急では、12 の停車駅すべてで、見込みとの差が 1.5 秒以内でした。
  • --max-speed と --dwell は、明示したときだけ見込みの代わりに使います。--line は、これまでどおり --max-speed（既定 320）で走ります。
• 同梱の GPX（assets/gpx/）
  • SampleJY.gpx（実走行の記録）以外の 5 本を作り直しました。
  • SampleTohokuShinkansen.gpx は --line で作っているので、線路の長さだけが反映されています。
• テスト
  • location.gpxLag.test.ts と location.ts は変更していません（dev のまま）。作り直した GPX でも、EMAスムージングのαを測位の配信間隔で正規化して到着判定が駅の直前までずれ込む不具合を修正 #6917 の配信間隔の見張りを含めてすべて通ります。
  • location.gpxEtaAssist.test.ts は、精度の悪い条件では終着駅を検知できない前提で、検知駅数を完全一致で見ていました。作り直した GPX では終着駅も検知できた（片町線・京王線）ので、下限と上限の範囲で見るようにしました。途中の駅の取りこぼしは、これまでどおり検出します。
  • location.subwayGpx.test.ts の FLinerSeibu.gpx の形（90 秒を超える欠測の数と最長の欠測）を、作り直した GPX の実測値（5 件、326 秒）に合わせました。
• ドキュメント
  • docs/location-simulation.md と replay-gpx スキルから、「最高 120km/h」のように、作り直した GPX には当てはまらない記述を削りました。見込みに合わせる仕組みと、その結果として現実とずれる点を書き足しました。

現実との差として残る点

• 巡航速度は、路線の最高速度より低くなります。見込みには運転余裕のぶんの時間が入っているためで、たとえば京王線特急は 78km/h、総武快速線は 84km/h です。このため、駅間の中ほどでは実際の列車より遅く走ります。到着圏に入るときの速度は減速度で決まり、巡航速度にはほとんど依存しません。
• 較正テーブルに無い路線・種別では、見込みと実際のダイヤの差が残ります。京王線特急は 41.4 分で、実際（約 45 分）より短いままです。
• 点は駅座標を結んだ直線の上に置いています。カーブの区間では、実際の線路から横にずれます。

テスト

• npm run lint が通ること
• npm test が通ること
• npm run typecheck が通ること

npm run lint、npm run typecheck、npm test（321 スイート・3573 件）はすべて成功しました。生成スクリプトのテスト（node --test scripts/generate-location-gpx.test.mjs）は 31 件すべて成功しました。

関連Issue

Refs TrainLCD/StationAPI#1710, TrainLCD/StationAPI#1712, TrainLCD/StationAPI#1714

スクリーンショット（任意）

UI 変更なし: assets/gpx/ は開発者向けの GPX で、アプリのコードからは読み込みません。

🤖 Generated with Claude Code

Summary by CodeRabbit

• 機能改善
  • GPX生成時に、駅間の線路距離と到着・出発時刻の推定を反映できるようになりました。最高速度を指定した場合は、その速度に基づいて経路を生成します。
  • 到着時刻に間に合わない区間や、推定時刻を取得できない場合の動作が明確になりました。
• ドキュメント
  • GPX生成の設定、所要時間、サンプル経路の説明を更新しました。
• テスト
  • 距離計算や時刻推定に関する検証を追加・更新しました。

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Essentials

Run ID: e1df04f8-d087-4171-8ac6-355597186f19

📥 Commits

Reviewing files that changed from the base of the PR and between ed11ecd and 529073c.

📒 Files selected for processing (13)

• .claude/skills/replay-gpx/SKILL.md
• assets/gpx/FLinerSeibu.gpx
• assets/gpx/KatamachiRapid.gpx
• assets/gpx/KeioSpecialExpress.gpx
• assets/gpx/SampleTohokuShinkansen.gpx
• assets/gpx/SobuRapid.gpx
• docs/location-simulation.md
• scripts/generate-location-gpx.mjs
• scripts/generate-location-gpx.test.mjs
• src/store/atoms/location.gpxEtaAssist.test.ts
• src/store/atoms/location.gpxLag.test.ts
• src/store/atoms/location.subwayGpx.test.ts
• src/store/atoms/location.ts

Included review availability: This review used your included allowance. 1 included review remains after this review. Your included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

---

📝 Walkthrough

Walkthrough

GPX生成器は、StationAPI の線路距離と Estimated 到着・出発見込みを使って waypoint を生成します。到着判定のテストは、猶予時間と複数の測位条件を扱うよう更新されました。

Changes

GPX生成

Layer / File(s)	Summary
線路距離と走行方向の対応 scripts/generate-location-gpx.mjs, scripts/generate-location-gpx.test.mjs, docs/location-simulation.md	StationAPI の線路距離を累積距離に使います。値がない区間では直線距離を使い、逆方向の経路では線路距離を走行順に対応させます。テストは距離の選択、座標補間、距離の向きを確認します。
推定時刻に基づく区間計画 scripts/generate-location-gpx.mjs, scripts/generate-location-gpx.test.mjs, docs/location-simulation.md, .claude/skills/replay-gpx/SKILL.md, src/store/atoms/location.subwayGpx.test.ts	--line-group で Estimated の到着・出発見込みを取得し、区間時間と停車時間から速度を計画します。見込みが不足する場合の処理、警告、出力ログを追加しました。関連テスト、生成例、同梱GPXの説明と欠測時間の期待値も更新しました。

到着判定テスト

Layer / File(s)	Summary
猶予時間と複数条件での到着判定 src/store/atoms/location.gpxLag.test.ts, src/store/atoms/location.gpxEtaAssist.test.ts, src/store/atoms/location.ts, docs/location-simulation.md	テスト用測位列に開始時刻のオフセットとノイズシードを追加しました。最後の到着圏内測位から猶予時間内は、圏外測位でも到着状態とする判定を検証します。測位条件ごとの到着位置・ばたつき判定、到着駅数の期待値、説明を更新しました。

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Generator as generate-location-gpx.mjs
  participant StationAPI
  participant WaypointBuilder as buildWaypoints
  participant GPX as GPX出力
  Generator->>StationAPI: 駅情報と Estimated の trainRoute を要求
  StationAPI-->>Generator: 駅間距離、到着・出発見込み、運動条件を返す
  Generator->>WaypointBuilder: 経路、区間距離、区間時間を渡す
  WaypointBuilder-->>Generator: 時刻に合わせた waypoint を返す
  Generator->>GPX: waypoint を出力

Loading

Merge Risk: ⚪ Minimal · up to 52907

This change regenerates sample GPX files and updates the generator script, tests and docs. It does not affect production app behavior, and no merge-blocking issues were identified.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 6…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	タイトルは、GPXを到着時間推定に合わせて生成し、同梱GPXを更新したという主要な変更を明確に示しています。
Description check	✅ Passed	概要、変更内容、テスト結果、関連Issue、UI変更なしの説明を含み、テンプレートの必須項目を十分に満たしています。

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{うさぎが線路の距離をたどる
到着時刻に合わせて跳ねる
駅では停まり、また走り
測位の揺れにも耳を澄ます
新しいGPXを月まで運ぶ}

_{Comment @coderabbitai help to get the list of available commands.}