========================================================================
技術スタック選定 (Technology Stack Selection)
========================================================================


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

    1-0. 目的

    ライントレース自律走行システムで使用する技術スタックと，
    その選定理由を定義する．


    1-1. 全体方針

    ・言語: Python で統一する（Pi 側・PC 側ともに）．
    ・既存資産: モーター制御コード（`src/pi/motor/driver.py`）を参考にする．
    ・選定基準: 低遅延・軽量・Python との親和性を重視する．


2. 技術スタック一覧 (Technology Stack)
------------------------------------------------------------------------

    2-1. 通信: ZMQ（ZeroMQ）

    ・ライブラリ: pyzmq
    ・通信パターン: PUB/SUB
    ・オプション: ZMQ_CONFLATE=1（受信側で最新メッセージのみ保持）
    ・用途:
        - Pi → PC: テレメトリ（カメラ画像・検出結果・操舵量）の送信
        - PC → Pi: コマンド（モード切替・パラメータ更新・手動操作）の送信

    ■ 選定理由
    ・ブローカー不要で軽量，低遅延に適している．
    ・PUB/SUB + CONFLATE により，送受信が互いをブロックせず，
        常に最新データのみを扱える．
    ・バイナリデータ（画像）の送受信が容易である．

    ■ 不採用とした候補
    ・WebSocket: バイナリ送信のオーバーヘッドが大きい．
    ・gRPC: 構造化 API 向きで，リアルタイム制御には過剰．
    ・生 UDP: 最も低遅延だが，フレーミングやシリアライズを
        自前で実装する必要がある．

    2-2. GUI フレームワーク: PySide6

    ・用途: PC 側のアプリケーション全般
        - カメラ映像のリアルタイム表示
        - 自動操縦 ON/OFF ボタン
        - パラメータ調整スライダー
        - 手動操作のキー入力ハンドリング

    ■ 選定理由
    ・ボタン・スライダー等のウィジェットが豊富である．
    ・QTimer による映像のリアルタイム更新が容易である．
    ・キーボード入力のハンドリングが柔軟で，手動操作に適している．
    ・ライセンスが LGPL で利用しやすい．

    ■ 不採用とした候補
    ・OpenCV highgui（imshow）: ボタンやスライダーの自由度が低い．
    ・tkinter: リアルタイム映像表示のパフォーマンスに不安がある．

    2-3. 画像処理: OpenCV（cv2）

    ・用途: Pi 側・PC 側での画像処理・線検出
        - グレースケール変換・ガウシアンブラー・二値化（固定・適応的閾値）
        - CLAHE（コントラスト制限付き適応ヒストグラム均等化）
        - モルフォロジー処理（Opening・Closing・Black-hat・距離変換）
        - 画像リサイズ・JPEG 圧縮

    ■ 選定理由
    ・ライントレースに必要な処理がすべて揃っている．
    ・NumPy ベースで PySide6 への画像受け渡しが容易である．
    ・既存コードでの使用実績がある．

    2-4. 数値計算: NumPy

    ・用途: Pi 側・PC 側での数値計算・配列操作
        - 多項式フィッティング（numpy.polyfit）
        - Theil-Sen 直線近似・RANSAC 外れ値除去
        - 画像の配列操作・統計処理

    ■ 選定理由
    ・OpenCV と同一のデータ形式（ndarray）で連携が容易である．
    ・多項式フィッティングや統計処理の関数が揃っている．

    2-5. カメラ制御: Picamera2

    ・用途: Pi 側でのカメラフレーム取得

    ■ 選定理由
    ・Raspberry Pi カメラの標準ライブラリである．
    ・既存コードでの使用実績がある．

    2-6. モーター制御: RPi.GPIO

    ・用途: Pi 側での TB6612FNG モータードライバ制御

    ■ 選定理由
    ・既存コード（`src/pi/motor/driver.py`）をそのまま流用できる．
    ・PWM 制御・GPIO 出力に必要な機能が揃っている．


    2-7. 機械学習: scikit-learn

    ・ライブラリ: scikit-learn, joblib
    ・用途: 十字路分類モデルの学習（PC 側）・推論（Pi 側・PC 側）
        - 複数モデルの交差検証による比較評価
        - 最良モデルの保存・読み込み

    ■ 選定理由
    ・40×30 二値画像の 2 クラス分類であり，軽量なモデルで十分である．
    ・SVM，ロジスティック回帰，MLP 等を統一的な API で比較できる．
    ・NumPy ベースで既存コードとの統合が容易である．

    ■ 不採用とした候補
    ・PyTorch/TensorFlow: 入力が 1200 特徴量と小さく，
        深層学習フレームワークは過剰である．

    2-8. 環境変数管理: python-dotenv

    ・用途: .env ファイルから環境変数を読み込む
        - PC の IP アドレス
        - 通信ポート番号

    ■ 選定理由
    ・ネットワーク設定など環境固有の値をコードから分離できる．
    ・.env ファイルを .gitignore に含めることで，
        Git に環境固有情報をコミットしない運用が可能．


3. 構成まとめ (Summary)
------------------------------------------------------------------------

    ■ Raspberry Pi 側

    ・Picamera2: カメラフレーム取得
    ・RPi.GPIO: モーター制御
    ・OpenCV: 画像処理・線検出
    ・NumPy: 多項式フィッティング・Theil-Sen 近似・配列操作
    ・scikit-learn: 十字路分類モデルの推論
    ・joblib: モデルとスケーラの読み込み
    ・pyzmq: PC との通信
    ・python-dotenv: 環境変数管理

    ■ PC 側

    ・PySide6: GUI アプリケーション
    ・OpenCV: 画像処理・線検出
    ・NumPy: 多項式フィッティング・Theil-Sen 近似・配列操作
    ・scikit-learn: 十字路分類モデルの学習・推論
    ・joblib: モデルとスケーラの保存・読み込み
    ・pyzmq: Pi との通信
    ・python-dotenv: 環境変数管理