# RobotCar — カメラ搭載ライントレース自律走行システム

カメラ画像のみを用いて黒線コースを自律走行するロボットカーの制御システム．
Raspberry Pi がリアルタイム制御を担当し，PC が GUI モニタリング・パラメータ調整を担当する．

## システム概要

```
Raspberry Pi                         PC
────────────                         ──
カメラ撮影                           テレメトリ受信
    │                                │
画像処理・線検出                     映像・状態表示
    │                                │
操舵量計算（3手法切替）              パラメータ調整
    │                                │
モーター制御                         コマンド送信
    │                            (モード切替・手動操作)
    └──── テレメトリ(ZMQ) ──────>     │
    ┌──── コマンド受信   <──────      │
```

- **制御ループ**（カメラ取得 → 画像処理 → 操舵計算 → モーター制御）は Pi 内で完結し，通信遅延の影響を受けない
- **PC** はモニタリング GUI・パラメータ調整・手動操作のみを担当

## 主な機能

| 機能 | 概要 |
|------|------|
| 線検出 | 5 種類の検出手法を GUI から切替可能（CLAHE，Black-hat，二重正規化，ロバスト，谷検出） |
| 操舵制御 | PD 制御・2点パシュート制御・Theil-Sen PD 制御の 3 手法を切替可能 |
| 速度制御 | カーブの度合いに応じて動的に減速・加速 |
| 十字路判定 | SVM 分類器で十字路を検出し直進に切替 |
| コースアウト復帰 | 線を見失った場合に自動で復帰動作を実行 |
| パラメータ調整 | GUI スライダーでリアルタイムに変更・プリセット保存 |
| 手動操作 | キーボード入力による手動走行モード |

## ハードウェア構成

- **メインコンピュータ**: Raspberry Pi
- **カメラ**: Raspberry Pi カメラモジュール（車体前方，真下向き）
- **モータードライバ**: TB6612FNG
- **駆動方式**: 差動 2 輪駆動（左右モーターの回転速度差で旋回）

## 技術スタック

| 用途 | ライブラリ |
|------|-----------|
| 通信 | ZeroMQ (pyzmq) — PUB/SUB + CONFLATE |
| GUI | PySide6 |
| 画像処理 | OpenCV |
| 数値計算 | NumPy |
| カメラ制御 | Picamera2 |
| モーター制御 | RPi.GPIO |
| 十字路分類 | scikit-learn |
| 環境変数 | python-dotenv |

## ディレクトリ構成

```
RobotCar/
├── src/
│   ├── common/          共通設定・画像処理・操舵量計算
│   │   ├── vision/      線検出パイプライン・検出手法・十字路分類
│   │   └── steering/    PD制御・パシュート制御・Theil-Sen PD制御・復帰制御
│   ├── pc/              PC側（GUI・テレメトリ受信・コマンド送信）
│   └── pi/              Pi側（カメラ・モーター・自律制御ループ）
├── docs/                ドキュメント
├── tests/               ユニットテスト
├── params/              パラメータ・モデル
├── data/                学習データ（十字路分類用）
├── deploy.sh            Pi への転送スクリプト
├── requirements_pc.txt  PC 用依存パッケージ
└── requirements_pi.txt  Pi 用依存パッケージ
```

## セットアップ

### PC

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements_pc.txt
cp .env.example .env   # IP アドレス・ポート番号を設定
```

### Raspberry Pi

```bash
# PC から Pi へファイルを転送
./deploy.sh

# Pi 上で仮想環境を構築
python -m venv .venv
source .venv/bin/activate
pip install -r requirements_pi.txt
```

詳細は [docs/04_ENV/](docs/04_ENV/) を参照．

## 実行方法

```bash
# Pi 側（自律制御ループ）
python -m src.pi.main

# PC 側（GUI）
python -m src.pc.main
```

## ドキュメント

詳細な仕様は `docs/` 以下を参照．

### ガイドライン（01_GUIDE）

| ファイル | 内容 |
|---------|------|
| [GUIDE_01_ドキュメント作成ガイド](docs/01_GUIDE/GUIDE_01_ドキュメント作成ガイド.txt) | 句読点は「，」「．」，見出し書式等 |
| [GUIDE_02_ドキュメント命名規則](docs/01_GUIDE/GUIDE_02_ドキュメント命名規則.txt) | `[カテゴリ]_[連番]_[ファイル名].txt` |
| [GUIDE_03_Git運用ルール](docs/01_GUIDE/GUIDE_03_Git運用ルール.txt) | ブランチ命名，コミットメッセージ規約 |
| [GUIDE_04_コーディング規則](docs/01_GUIDE/GUIDE_04_コーディング規則.txt) | PEP 8 ベース，snake_case，型ヒント必須 |
| [GUIDE_05_コードコメント規則](docs/01_GUIDE/GUIDE_05_コードコメント規則.txt) | docstring は日本語，Google スタイル |

### プロジェクト計画（02_PLAN）

| ファイル | 内容 |
|---------|------|
| [PLAN_01_プロジェクト概要](docs/02_PLAN/PLAN_01_プロジェクト概要.txt) | 目的・最終目標・ハードウェア構成・システム概要 |

### 技術仕様（03_TECH）

| ファイル | 内容 |
|---------|------|
| [TECH_01_操舵量計算仕様](docs/03_TECH/TECH_01_操舵量計算仕様.txt) | PD 制御・パシュート制御・Theil-Sen PD 制御，速度制御，レートリミッター |
| [TECH_02_システム構成仕様](docs/03_TECH/TECH_02_システム構成仕様.txt) | Pi/PC の役割分担，通信フロー，ZMQ プロトコル詳細 |
| [TECH_03_デバッグオーバーレイ仕様](docs/03_TECH/TECH_03_デバッグオーバーレイ仕様.txt) | オーバーレイ表示項目，描画色，GUI 操作 |
| [TECH_04_線検出精度向上方針](docs/03_TECH/TECH_04_線検出精度向上方針.txt) | 線検出の課題（照明・影），5 種類の検出手法の方針 |
| [TECH_05_コースアウト復帰仕様](docs/03_TECH/TECH_05_コースアウト復帰仕様.txt) | 復帰判定ロジック，復帰動作，パラメータ一覧 |
| [TECH_06_十字路分類モデル評価](docs/03_TECH/TECH_06_十字路分類モデル評価.txt) | モデル比較結果，採用モデル，F1 スコア（学習時に自動生成） |

### 環境構築（04_ENV）

| ファイル | 内容 |
|---------|------|
| [ENV_01_技術スタック選定](docs/04_ENV/ENV_01_技術スタック選定.txt) | ZMQ，PySide6，OpenCV，Picamera2 等の選定理由 |
| [ENV_02_PC環境構築手順](docs/04_ENV/ENV_02_PC環境構築手順.txt) | venv 作成，ライブラリインストール |
| [ENV_03_RaspPi環境構築手順](docs/04_ENV/ENV_03_RaspPi環境構築手順.txt) | SSH 接続，deploy.sh による転送，venv 構築 |
| [ENV_04_ディレクトリ構成](docs/04_ENV/ENV_04_ディレクトリ構成.txt) | src/ の詳細構成と各ファイルの役割 |

### テスト（05_TEST）

| ファイル | 内容 |
|---------|------|
| [TEST_01_テスト方針](docs/05_TEST/TEST_01_テスト方針.txt) | テスト方針，実行方法，構成，追加ルール |

## 作成者

Rinto Hasegawa

## ライセンス

[MIT License](LICENSE)