========================================================================
システム構成仕様 (System Architecture Specification)
========================================================================


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

    1-0. 目的

    ライントレース自律走行を実現するために，Raspberry Pi と PC が
    それぞれ担う処理と，両者間の通信の流れを定義する．


    1-1. 全体構成

    Raspberry Pi はカメラ画像の取得とモーター制御を担当し，
    PC は画像処理・操舵量計算・GUI 表示を担当する．

        Raspberry Pi                    PC
        ────────────                    ──
        カメラ撮影                      画像受信
            │                               │
            └──── 画像送信 ──────>           │
                                        画像処理・線検出
                                            │
                                        操舵量計算（PD 制御）
                                            │
            ┌──── 操舵量受信 <──────    操舵量送信
            │
        モーター制御


2. Raspberry Pi 側の処理 (Raspberry Pi Processing)
------------------------------------------------------------------------

    2-1. カメラ画像の取得

    ・Picamera2 を使用してグレースケール（Y8 フォーマット）でフレームを取得する．
    ・取得した画像を JPEG 圧縮して PC に送信する．
        ※ グレースケールで取得することで，転送データ量を BGR 比で 1/3 に削減する．

    2-2. 操舵量の受信

    ・PC から送信された操舵量（throttle，steer）を受信する．

    2-3. モーター制御

    ・受信した throttle，steer を既存の `MotorDriver.set_drive()` に渡し，
        左右モーターを制御する．
    ・差動2輪駆動の計算は既存コードを流用する．
        - left  = throttle + steer
        - right = throttle - steer
    ・極性補正・PWM 出力も既存コードに従う．

    2-4. フェイルセーフ

    ・一定時間（例: 0.5秒）操舵量を受信しなかった場合，
        モーターを自動停止する．
    ・通信切断時の暴走を防止する．


3. PC 側の処理 (PC Processing)
------------------------------------------------------------------------

    3-1. 画像の受信

    ・Raspberry Pi から送信されたカメラ画像を受信する．

    3-2. 画像処理・線検出

    ・受信した画像から黒線の位置を検出する．
    ・処理手順:
        1. CLAHE によるコントラスト強調
        2. ガウシアンブラー（ノイズ除去）
        3. 固定閾値で二値化
        4. オープニングで孤立ノイズ除去
        5. 横方向クロージングで途切れ補間
        6. 白ピクセルに2次多項式フィッティング
        ※ グレースケール変換は Pi 側（撮影時）で完了しているため不要
    ・位置偏差・傾き・曲率を算出する．
    ・詳細は `TECH_01_操舵量計算仕様.txt` を参照する．

    3-3. 操舵量計算

    ・多項式フィッティングから得た位置偏差と傾きで
        PD 制御により操舵量を計算する．
    ・速度は曲率に応じて動的に調整する．
    ・レートリミッターで急激な操舵変化を抑制する．
    ・詳細は `TECH_01_操舵量計算仕様.txt` を参照する．

    3-4. 操舵量の送信

    ・計算した throttle，steer を Raspberry Pi に送信する．

    3-5. GUI 表示

    ■ カメラ映像表示
    ・受信した画像をリアルタイムで表示する．
    ・デバッグオーバーレイを重ねて表示できる．
    ・詳細は `TECH_03_デバッグオーバーレイ仕様.txt` を参照する．

    ■ 自動操縦の切り替え
    ・自動操縦の ON / OFF を切り替えるボタンを設ける．
    ・ON: 画像処理の結果に基づいて操舵量を自動計算・送信する．
    ・OFF: 手動操作モードに切り替わる．

    ■ パラメータ調整
    ・PD 制御パラメータ（Kp，Kh，Kd 等）をリアルタイムに変更できる
        UI を設ける．
    ・画像処理パラメータ（二値化閾値，CLAHE 強度等）も
        リアルタイムに変更できる．
    ・変更したパラメータは即座に処理に反映される．

    ■ パラメータ保存・読み込み
    ・調整したパラメータをタイトル・メモ付きで JSON に保存できる．
    ・保存済みパラメータをコンボボックスから選択・読み込みできる．
    ・確認ダイアログ付きの削除機能を備える．

    ■ 手動操作
    ・自動操縦 OFF 時に，ユーザーが手動で車体を操作できる．
    ・操作方式は操作性を重視して設計する．


4. 設計方針 (Design Policy)
------------------------------------------------------------------------

    4-1. 操舵量計算の独立性

    操舵量の計算ロジックは，タイム短縮やコースアウト防止のために
    試行錯誤で改善していくことを前提とする．
    そのため，操舵量計算を他の処理から独立させ，計算式やアルゴリズムの
    変更が通信・モーター制御・GUI のコードに影響しない構成とする．

    ・入力: グレースケールのカメラ画像（NumPy 配列）
    ・出力: throttle（float: -1.0 ~ +1.0），steer（float: -1.0 ~ +1.0）

    この入出力を維持する限り，計算の中身（偏差の取り方，制御式，
    速度調整の方法等）を自由に変更できる．


5. 通信の流れ (Communication Flow)
------------------------------------------------------------------------

    5-1. 全体のループ

    以下のサイクルを毎フレーム繰り返す．

        1. Pi: カメラでフレームを取得する．
        2. Pi → PC: 画像を送信する．
        3. PC: 画像処理・線検出を行う．
        4. PC: 操舵量を計算する（自動時）またはユーザー入力を取得する（手動時）．
        5. PC → Pi: 操舵量（throttle，steer）を送信する．
        6. Pi: 受信した操舵量でモーターを制御する．

    5-2. 通信要件

    ・双方向通信: Pi → PC（画像），PC → Pi（操舵量）．
    ・低遅延: 画像取得からモーター反映までの遅延を最小限にする．
        ※ 遅延が大きいとコースアウトのリスクが増加する．
    ・信頼性: パケットロス時の振る舞いを定義する．
        - 画像が届かない場合: 前フレームの操舵量を維持する．
        - 操舵量が届かない場合: フェイルセーフでモーター停止する．