diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..cc57693 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Rinto Hasegawa + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..a779d61 --- /dev/null +++ b/README.md @@ -0,0 +1,164 @@ +# 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)