========================================================================
PC 環境構築手順 (PC Environment Setup)
========================================================================


1. 前提条件 (Prerequisites)
------------------------------------------------------------------------

    1-1. OS

    ・Windows 11 Home

    1-2. Python

    ・バージョン: 3.12.10
    ・インストール元: Microsoft Store 版
    ・確認コマンド:

        $ python --version

    1-3. pip

    ・Python に同梱されているものを使用する．


2. venv の作成 (Create Virtual Environment)
------------------------------------------------------------------------

    2-1. 作成

    プロジェクトルートで以下を実行する．

        $ cd c:\Users\rinto\source\RobotCar
        $ python -m venv .venv

    ・`.venv/` ディレクトリが作成される．
    ・`.venv/` は Git 管理外とする（`.gitignore` に追加）．

    2-2. 有効化

    ■ PowerShell の場合

        $ .venv\Scripts\Activate.ps1

    ■ コマンドプロンプトの場合

        $ .venv\Scripts\activate.bat

    ■ Git Bash の場合

        $ source .venv/Scripts/activate

    ・有効化するとプロンプトの先頭に `(.venv)` が表示される．

    2-3. pip のアップグレード

        $ python -m pip install --upgrade pip


3. ライブラリのインストール (Install Libraries)
------------------------------------------------------------------------

    3-1. 一括インストール

    `requirements_pc.txt` を使用して一括インストールする．

        $ pip install -r requirements_pc.txt

    3-2. インストールされるライブラリ

    ・PySide6 (6.10.2): GUI フレームワーク
    ・opencv-python (4.13.0.92): 画像処理
    ・pyzmq (27.1.0): ZMQ 通信
    ・numpy (2.4.3): 数値計算（OpenCV の依存ライブラリ）
    ・python-dotenv (1.2.2): .env ファイルからの環境変数読み込み
    ・scikit-learn (1.6.1): 十字路分類モデルの学習・推論
    ・joblib (1.4.2): モデルのシリアライズ
    ・pytest (9.0.2): ユニットテスト

    3-3. インストール確認

        $ pip freeze

    上記コマンドで `requirements_pc.txt` に記載されたライブラリと
    バージョンが表示されることを確認する．


4. 環境変数の設定 (Environment Variables)
------------------------------------------------------------------------

    4-1. .env ファイルの作成

    プロジェクトルートにある `.env.example` をコピーして `.env` を作成する．

        $ cp .env.example .env

    ・`.env` は Git 管理外のため，環境ごとに作成する必要がある．
    ・`.env.example` は設定項目のテンプレートとして Git 管理されている．

    4-2. 設定項目

    `.env` に以下の値を記入する．

        PC_IP=<PC の IP アドレス>   # Raspberry Pi からの接続先
        IMAGE_PORT=<ポート番号>      # 画像受信ポート（Pi → PC）
        CONTROL_PORT=<ポート番号>    # 操舵量送信ポート（PC → Pi）

    ・PC_IP は `ipconfig`（Windows）または `ip a`（Linux/Mac）で確認する．
    ・ポート番号は Pi 側の `.env` と一致させること．
    ・Pi 側の `.env` は `deploy.sh` で転送される
      （詳細は `ENV_03_RaspPi環境構築手順.txt` を参照）．

    4-3. 設定例

        PC_IP=192.168.1.10
        IMAGE_PORT=5555
        CONTROL_PORT=5556


5. アプリの起動 (Run Application)
------------------------------------------------------------------------

    5-1. 起動コマンド

    venv を有効化した状態で `src/` ディレクトリ内から以下を実行する．

        $ cd src
        $ python -m pc.main

    または，プロジェクトルートから `PYTHONPATH` を指定して実行する．

        $ PYTHONPATH=src python -m pc.main

    ・`src/pc/main.py` がエントリーポイントとなる．
    ・プロジェクトルートから `python -m src.pc.main` とすると
      モジュール解決に失敗するため，上記いずれかの方法で起動すること．
    ・Raspberry Pi との通信を行う場合は，先に Pi 側を起動しておくこと
      （Pi 側の起動手順は `ENV_03_RaspPi環境構築手順.txt` を参照）．

    5-2. 終了

    GUI ウィンドウを閉じる，またはターミナルで Ctrl+C を押す．


6. 動作確認 (Verification)
------------------------------------------------------------------------

    6-1. ライブラリの import 確認

    以下を Python で実行し，エラーが出ないことを確認する．

        $ python -c "import PySide6; import cv2; import zmq; import dotenv; print('OK')"