========================================================================
コースアウト復帰仕様 (Course-Out Recovery Specification)
========================================================================


1. 概要 (Overview)
------------------------------------------------------------------------

    1-0. 目的

    自動操縦中に黒線を見失った場合（コースアウト），
    一定時間経過後に最後に検出した方向へ旋回しながら走行し，
    コースへの復帰を試みる機能を定義する．

    1-1. 基本方針

    ・全制御手法（PD / 2点パシュート / Theil-Sen PD）に共通で適用する
    ・Pi 側のメインループ（pi/main.py）で復帰判定と操舵量の上書きを行う
    ・復帰パラメータは GUI の折りたたみパネルでリアルタイムに調整可能
    ・パラメータは JSON ファイルに自動保存・復元される
    ・PC から復帰パラメータを更新すると Pi に送信され，即座に反映される


2. 復帰判定 (Recovery Trigger)
------------------------------------------------------------------------

    2-1. 判定条件

    以下の条件がすべて満たされたとき，復帰モードに遷移する．

    1. 自動操縦中である
    2. 復帰機能が有効（enabled = True）である
    3. 線検出結果が detected = False である
    4. 最後に線を検出した時刻から timeout_sec 秒以上経過している

    2-2. 復帰モードの解除

    線が再び検出された時点で即座に復帰モードを解除し，
    通常の制御手法による操舵に戻る．


3. 復帰動作 (Recovery Behavior)
------------------------------------------------------------------------

    3-1. 操舵方向の決定

    最後に線を検出したときの位置偏差（position_error）の符号から，
    線がどちら側にあったかを記録する．

    ・position_error > 0（線が画像の左側）: 左へ旋回（steer < 0）
    ・position_error < 0（線が画像の右側）: 右へ旋回（steer > 0）

    復帰操舵量の計算:

        direction = -sign(last_position_error)
        steer = direction × steer_amount

    3-2. 走行速度

    throttle パラメータで復帰時の走行速度を指定する．

    ・負の値: 後退しながら旋回（コースアウト地点に戻る方向）
    ・正の値: 前進しながら旋回（コース先回りで復帰を試みる）
    ・ゼロ: 停止状態で旋回のみ

    用途に応じて GUI で調整する．

    3-3. 処理フロー（Pi 側メインループ）

    1. 各制御手法の compute() を通常通り呼び出す
    2. 検出結果を RecoveryController.update() に渡す
    3. update() が SteeringOutput を返した場合，
       制御手法の出力を復帰用の出力で上書きする
    4. 上書きされた操舵量でモーターを制御する


4. パラメータ一覧 (Parameters)
------------------------------------------------------------------------

    ■ コースアウト復帰パラメータ（GUI で調整可能）

    ・enabled（有効/無効）: True
        - 復帰機能全体のオン/オフ
    ・timeout_sec（判定時間）: 0.5 秒
        - 線を見失ってから復帰動作を開始するまでの時間
        - 短すぎると一時的な検出失敗で誤動作する
        - 長すぎるとコースアウト後の復帰が遅れる
    ・steer_amount（操舵量）: 0.5
        - 復帰時の旋回の強さ（0.0 ~ 1.0）
        - 大きいほど急旋回する
    ・throttle（速度）: -0.3
        - 復帰時の走行速度（-1.0 ~ +1.0）
        - 負の値で後退，正の値で前進


5. GUI 仕様 (GUI Specification)
------------------------------------------------------------------------

    5-1. パネル配置

    「コースアウト復帰」という名前の折りたたみパネルを，
    制御パラメータパネルとデバッグ表示パネルの間に配置する．

    5-2. UI 構成

    ・チェックボックス: 「復帰機能を有効にする」
    ・判定時間: QDoubleSpinBox（0.1 ~ 10.0 秒，0.1 刻み）
    ・操舵量: QDoubleSpinBox（0.0 ~ 1.0，0.05 刻み）
    ・速度: QDoubleSpinBox（-1.0 ~ +1.0，0.05 刻み）

    5-3. 自動保存

    パラメータの変更は即座に params/recovery.json に保存され，
    次回起動時に復元される．


6. 実装ファイル (Implementation Files)
------------------------------------------------------------------------

    ・src/common/steering/recovery.py: RecoveryParams，RecoveryController
    ・src/pi/main.py: Pi 側メインループでの復帰ロジック統合
    ・src/pc/gui/panels/recovery_panel.py: RecoveryPanel
    ・src/pc/gui/main_window.py: 復帰パラメータ管理・Pi への送信
    ・src/pc/steering/auto_params.py: save_recovery / load_recovery