ai_race

機械学習を学ぶことを目的とした、AIで車両を操作して走行性能を競うゲームです。

1. 準備

ご質問は、FAQに集約します。

1.0. jetson nano準備

記載予定
こちらにjetson nanoの備品を記載
（シミュレータや機械学習は通常のPCでできなくもないが、環境統一のため、以降の環境構築や動作確認はjetson nanoを基準に行う）

1.1. jetson nano起動

以下からイメージファイルを取得する。

推奨バージョンはJetpack 4.4.1

# Jetpack 4.4.1 archive
https://developer.nvidia.com/jetpack-sdk-441-archive

# latest version
https://developer.nvidia.com/embedded/jetpack

取得後、イメージファイルをSDカードに書き込んで、JetsonNanoに挿して起動する。
起動後、ネットワークに接続する。

* お勧め設定 
ユーザ名: jetson
パスワード: (任意)
# お勧め設定は、順次追記予定。ユーザ名を共通化するとフルパス指定が要る時にハマる確率が減る。

• 学習用データ、学習モデル【参考】

こちらにsampleデータを置いています。運営の動作確認用です。

• Docker環境【参考】

こちらにDocker環境の利用手順を置いています。運営の動作確認用です。

2. インストール

結構時間が掛かります。
とりあえず動かしたい方はこちらのDocker環境をお試し頂いてもOKです。
「#」から始まる行はコメントです。

自動インストールスクリプト【推奨】

こちらに、以下 2.0.～2.4. を自動実行するスクリプトを用意しています。
自動インストールスクリプトを使うか、以下の手順を手動で実行してインストールしてください。

2.0 SWAPファイル追加してメモリ増強【必須】

cd ~
git clone https://github.com/JetsonHacksNano/installSwapfile
cd installSwapfile
./installSwapfile.sh
# SWAP領域が増えていることを確認
free -mh

2.1. 基本的なパッケージをインストール

sudo apt-get update
sudo apt-get install -y net-tools git
sudo apt-get install -y python-pip
# install pyqt5 and NumPy
sudo apt-get install -y python3-pip
sudo apt-get install -y python3-pyqt5
pip3 install --upgrade pip
pip3 install numpy
# for judge server
pip3 install flask
pip3 install requests
python -m pip install requests
# pygame
sudo apt-get update -y
sudo apt-get install -y libsdl-dev libsdl-image1.2-dev libsdl-mixer1.2-dev libsdl-ttf2.0-dev
sudo apt-get install -y libsmpeg-dev libportmidi-dev libavformat-dev libswscale-dev
sudo apt-get install -y libfreetype6-dev
sudo apt-get install -y libportmidi-dev
sudo pip3 install pgzero
python -m pip install pygame==1.9.6
# scikit learn
sudo apt install -y gfortran

2.2. ROSのインストール

• ROS(melodic)のインストール

# インストール手順参考:
# https://www.stereolabs.com/blog/ros-and-nvidia-jetson-nano/
# こちらの手順を自動化している、karaage0703さんのjetson-nano-toolsを使わせて頂きます。
# catkin_wsも自動で作成してくれます。
cd ~
git clone https://github.com/karaage0703/jetson-nano-tools
cd jetson-nano-tools
./install-ros-melodic.sh
echo "source /opt/ros/melodic/setup.bash" >> ~/.bashrc
source /opt/ros/melodic/setup.bash

• ROS関連パッケージのインストール

# joint state controller, and ros package
sudo apt install -y ros-melodic-ros-control ros-melodic-ros-controllers  ros-melodic-joint-state-controller ros-melodic-effort-controllers ros-melodic-position-controllers ros-melodic-joint-trajectory-controller
sudo apt install ros-melodic-cob-srvs
# gazebo
sudo apt-get install -y gazebo9
sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list'
wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add -
sudo apt-get update -y
sudo apt-get install -y ros-melodic-gazebo-ros-pkgs ros-melodic-gazebo-ros-control
echo "export GAZEBO_MODEL_PATH=:${HOME}/catkin_ws/src/ai_race/ai_race:${HOME}/catkin_ws/src/ai_race/ai_race/sim_world/models" >> ~/.bashrc
export GAZEBO_MODEL_PATH=:${HOME}/catkin_ws/src/ai_race/ai_race:${HOME}/catkin_ws/src/ai_race/ai_race/sim_world/models
# camera image
sudo apt-get install -y ros-melodic-uvc-camera
sudo apt-get install -y ros-melodic-image-*

2.3. 機械学習ライブラリのインストール

# インストール手順参考:
# https://forums.developer.nvidia.com/t/pytorch-for-jetson-version-1-7-0-now-available/72048
# https://github.com/NVIDIA-AI-IOT/torch2trt
# https://github.com/mdegans/nano_build_opencv
# 上記のサイト等を参考にした上で、必要なコマンドを下記に記載しています。


### pytorch from pip image (v1.4)
wget https://nvidia.box.com/shared/static/yhlmaie35hu8jv2xzvtxsh0rrpcu97yj.whl -O torch-1.4.0-cp27-cp27mu-linux_aarch64.whl
sudo apt-get install -y python-pip libopenblas-base libopenmpi-dev
pip install torch-1.4.0-cp27-cp27mu-linux_aarch64.whl
wget https://nvidia.box.com/shared/static/c3d7vm4gcs9m728j6o5vjay2jdedqb55.whl -O torch-1.4.0-cp36-cp36m-linux_aarch64.whl
sudo apt-get install -y python3-pip libopenblas-base libopenmpi-dev
pip3 install torch-1.4.0-cp36-cp36m-linux_aarch64.whl

### torch vision (v0.2.2)
# https://forums.developer.nvidia.com/t/pytorch-for-jetson-version-1-7-0-now-available/72048
pip install future
pip3 install future
sudo apt-get install libjpeg-dev zlib1g-dev libpython3-dev libavcodec-dev libavformat-dev libswscale-dev
cd ~
git clone --branch v0.5.0 https://github.com/pytorch/vision torchvision
cd torchvision
export BUILD_VERSION=0.2.2
sudo python setup.py install
sudo python3 setup.py install
cd ../
pip install 'pillow<7'

### torch2trt
cd ~
git clone https://github.com/NVIDIA-AI-IOT/torch2trt
cd torch2trt
git checkout d1fa6f9f20c6c4c57a9486680ab38c45d0d94ec3   # 動作確認済みのバージョン（Wed Nov 4時点）に戻す
sudo python setup.py install
sudo python3 setup.py install

### sklearn python3
pip3 install scikit-learn
#pip3 install matplotlib
#sudo apt-get -y install python3-tk

### pandas python2,3 (defaultを使えばよい)
#pip3 install cython
#pip3 install numpy
#pip3 install -U pandas

### opencv python
### opencv python はソースからビルドする必要がある. 8～10時間ほど掛かる.
cd ~
git clone https://github.com/mdegans/nano_build_opencv
cd nano_build_opencv
./build_opencv.sh 3.4.10

• ライブラリバージョン
  

推奨環境

ライブラリ	バージョン(python3)	バージョン(python)	備考
pytorch	1.6.0 1.4.0	1.4.0	-
torchvision	0.2.2	0.2.2	-
torch2trt	-	-	動作確認済みのバージョン git checkout d1fa6f9f20c6c4c57a9486680ab38c45d0d94ec3
sklearn	0.23.2	Not_Installed	-
pandas	0.22.0 (1.1.3必須かも)	Not_Installed	-
cv2	3.4.10	3.4.10	-
pygame	1.9.6	1.9.6	-

参考
pytorchとtensoflowのバージョンをコマンドラインから調べる

2.4. ai_raceリポジトリの取得とビルド

（例）https://github.com/seigot/ai_race リポジトリの場合

mkdir -p ~/Images_from_rosbag
cd ~/catkin_ws/src
git clone http://github.com/seigot/ai_race         # 自分のリポジトリを取得する場合は、ここのURLを変えて下さい。
cd ~/catkin_ws
catkin build
source devel/setup.bash
echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc

別リポジトリのビルドや、パッケージ追加時の再ビルド手順は、FAQ #catkin_wsを再buildするにはどうすればよい？をご参考下さい。

3. サンプルコード

3.1. サンプルコードの実行

別々のターミナルで実行して下さい。

サンプルデータのダウンロード

cd $HOME
git clone http://github.com/seigot/ai_race_data_sample

シミュレータ起動

cd ~/catkin_ws/src/ai_race/scripts
bash prepare.sh

学習モデルを利用した推論、車両操作

サンプルデータのダウンロードして使う場合の例。
以下の通り実行する。

# 分割しているsampleデータを結合する
cd $HOME/ai_race_data_sample/model/plane
cat sample_plane_trt_p* > sample_plane_trt.pth
# 推論
cd ~/catkin_ws/src/ai_race/ai_race/learning/scripts
python inference_from_image.py --trt_module --trt_model $HOME/ai_race_data_sample/model/plane/sample_plane_trt.pth

学習モデルを作成

サンプルデータを使って学習モデルを作成する場合の例。
動作確認用に--n_epoch 3を指定して約30分程で終わるようにしています。

cd ~/catkin_ws/src/ai_race/ai_race/learning/scripts
python3 train.py --data_csv $HOME/ai_race_data_sample/dataset/plane/_2020-11-17-01-34-45/_2020-11-17-01-34-45.csv --model_name sample_model --n_epoch 3

train.pyの実行ログを参照し、学習モデル(*.pth)ファイルが作成できていることを確認下さい。
train.pyの引数に与えられるパラメータは以下で確認できます。--n_epoch NN等のパラメータは適宜調整して下さい。

python3 train.py -h

学習モデルの軽量化

JetsonNanoに合わせて学習モデルを軽量化する。(trtあり版と呼ばれるもの)
作成した学習モデルのパスが、$HOME/ai_race_data_sample/model/plane/sample_plane.pth である場合の例。一度実行すると約10分程掛かります。

python3 trt_conversion.py --pretrained_model $HOME/ai_race_data_sample/model/plane/sample_plane.pth --trt_model sample_model_trt.pth

trt_conversion.pyの実行ログを参照し、--trt_modelに指定したファイルが作成できていることを確認下さい。
その後は前述同様、軽量化した学習モデルを利用して推論、車両操作を行って下さい。

学習用データの取得 (Optional)

rqt, joystick, 各種コントローラーで車両操作し、学習用のデータ（画像、コマンド操作ログ）を取得する。
サンプルデータでは期待する性能を出ない等、課題を感じた場合は、学習データを独自に取得することをお勧めします。
以下を実行することで、keyboardから車両操作ができます。

cd ~/catkin_ws/src/ai_race/ai_race/utility/scripts
python keyboard_con_pygame_videosave.py

### `ESC`キー押下で終了
### 終了後、学習データ（画像とコマンド）を格納したディレクトリがあることをコマンドから確認する
ls ${HOME}/Images_from_rosbag/

上記実行後、左下の「？」のうちkeyboard_con....pyが表示されてるものを押して、
その状態で以下キーを押すと車両が動く。

キー　車両の動き
l 進む
a 左にまがる
d 右にまがる

keyboard_con_pygame_videosave.pyの停止はESCキーを押下して下さい。
その後、${HOME}/Images_from_rosbag/以下に学習データ（画像とコマンド）が格納されます。

以上で作成したデータを、学習モデル作成に使用下さい。

3.2. 各種コマンドの説明

学習用データの取得、学習モデルを作成、学習モデルを利用した推論用コマンド

• Step1.学習用データの取得

bash prepare.shを実行した状態で、別ターミナルから以下を実行

## 学習用データ取得
## rosbag取得
roslaunch sim_environment rosbag.launch output_path:=<出力ファイルのディレクトリ 絶対パス指定>
rqt # rqtを使う場合。robot steering -> 車両制御パラメータ（v,rad）指定

## rosbag --> image/command 変換
cd ~/catkin_ws/src/ai_race/ai_race/utility/scripts
mkdir -p /Images_from_rosbag
sudo chmod 777 /Images_from_rosbag
python rosbag_to_images_and_commands.py **.bag   # bagファイルから学習用データ（画像と車両制御パラメータ）を取得
python listup_all_rosbag_timestamp.py *.bag               # 時刻表示できる

• Step2.学習用データから、学習モデルを作成

## 学習 
cd learning/scripts (学習用フォルダへ移動) 
python3 train.py --data_csv <csvのパス フルパス指定> --model_name <保存するモデル名>  
#### 実行ログ記載のディレクトリにモデルが保存されます

• Step3.学習モデルを使って推論、車両操作

bash prepare.shを実行した状態で、別ターミナルから以下を実行

## 学習モデルを利用した推論、車両操作
## 推論(trtなし trt=比較的軽量なモデル) 
cd ~/catkin_ws/src/ai_race/ai_race/learning/scripts
python inference_from_image.py --pretrained_model <学習させたモデル フルパス指定> 

• Step3+.学習モデルを軽量化して推論、車両操作

## 推論(trtあり）
#### 準備（準備は最初の一回でOK） 
cd ~/catkin_ws/src/ai_race/ai_race/learning/scripts
python3 trt_conversion.py --pretrained_model <学習させたモデル フルパス指定> --trt_model <保存するtrtモデル名>   
#### 指定したディレクトリにモデルが保存されます
#### 実行 
python inference_from_image.py --trt_module --trt_model <保存したtrtモデル名 フルパス指定> 

3.3 ディレクトリ構成

ディレクトリ	内容	備考
./ai_race/learning	機械学習スクリプト	-
./ai_race/utility	学習データ取得ツール	-
./ai_race/your_environment	各参加者の作成コードを格納するためのディレクトリ（ここにコードを置くと運営側のアップデートとconflictしない）	主に参加者向け
./scripts	起動、終了スクリプト	-
./ai_race/sim_world	シミュレータ用モデルデータ	主に運営向け
./ai_race/sim_environment	シミュレータ用ROSノード等	主に運営向け
./judge	審判サーバ	主に運営向け
./document	公開資料	主に運営向け
./docker	docker環境	主に運営向け
./ai_race/example	シミュレータ用モデルデータのサンプル	ROS/シミュレータ等、学びたい人向けチュートリアル

(主要なファイルを抜粋)
├── README.md                           # 本Readme
├── ai_race
│   ├── learning
│   │   └── scripts                     # 機械学習スクリプト
│   │       ├── MyDataSet.py            # 学習モデル作成用スクリプト
│   │       ├── train.py                # 学習モデル作成用スクリプト
│   │       ├── inference_from_image.py # 推論による車両操作用スクリプト
│   │       └── trt_conversion.py       # 学習モデル軽量化用スクリプト（TRT版に変換する用）
│   ├── utility
│   │   └── scripts                              # 学習データ取得ツール
│   │       ├── joycon.py                        # 車両操作用
│   │       ├── keyboard_con_pygame2.py          # 車両操作用
│   │       ├── listup_all_rosbag_timestamp.py   # rosbag timestamp表示用
│   │       └── rosbag_to_images_and_commands.py # rosbag-->image,comand変換用
│   │  
│   ├── your_environment       # 各参加者の作成コードを格納するためのディレクトリ
│   │   │                      # （ここにコードを置くと運営側のアップデートとconflictしない）
│   │   ├── launch
│   │   │   └── sim_environment.launch  # 参加者独自で学習データ取得する場合の、シミュレータモデル追加用ひな形ファイル
│   │   └── scripts
│   │       └── your_train.py           # 参加者独自でtrain.pyを作成する場合のひな形ファイル
│   │   
│   ├── example                   # シミュレータ用モデルデータのサンプル	
│   │   └── tutorial1-7 
│   ├── sim_environment           # シミュレータ用ROSノード等	
│   └── sim_world                 # シミュレータ用モデルデータ
│   
├── FAQ.md            # FAQ
├── docker            # docker環境
├── document          # 公開資料
├── judge             # 審判サーバ
└── scripts           # 起動用スクリプト
    ├── prepare.sh    # シミュレータ環境起動用(level1-3対応)
    ├── start.sh      # [大会用] 開始スクリプト
    └── stop.sh       # [大会用] 停止スクリプト

3.4 学習モデル自作のはじめかた

本リポジトリのfork

まず、Githubアカウントを取得して本リポジトリを自リポジトリにforkして下さい。

リポジトリのフォークの例

0. GitHubアカウントを作成/ログインする。
   
1. GitHub で、https://github.com/seigot/ai_raceリポジトリに移動します
   
2. ページの右上にある [Fork] をクリックします。
   参考：リポジトリをフォークする
   

学習用データの取得、チューニング、学習モデル作成

forkしたリポジトリで各々の学習データ取得、チューニング、学習モデル作成をしてください。
変更ファイルは、運営とのconflictを避けるためにyour_environmentディレクトリ以下に登録することをお勧めします。

• 学習データの取得を工夫する

サンプルの学習用データの取得を参考に、車両を自ら操作して学習データを取得することが可能です。
走行経路や入力画像のバリエーションなど、各々工夫をしてみてください。

※ 学習データ自体はサイズが大きいため、ファイルの受渡しはgithub以外でやりとりすることをお勧めします。
　（Githubは1ファイル最大が50MBまで、1GB 以下を推奨という制約があり、大きなファイルを扱うのに適しているとはいえない）

• チューニング、学習モデルの作成を工夫する

train.pyや周辺ファイルを参考に、各種パラメータを調整することが可能です。
機械学習アルゴリズム選定など含め、各々工夫をしてみてください。

自リポジトリの学習モデルを公式リリースする

学習モデルを公式リリースする場合は、Githubリリースの機能を使うと簡単なのでお勧めです。

学習モデルを提出（バイナリリリース）する場合の手順参考
リポジトリのリリースを管理する
7.オプションで、コンパイルされたプログラムなどのバイナリファイルをリリースに含めるには、ドラッグアンドドロップするかバイナリボックスで手動で選択します。

本リポジトリの最新バージョン取り込み

今後、本リポジトリもバージョンアップしていく予定です。
本リポジトリのバージョンアップを取り込む場合は、forkしたリポジトリにて以下を実行して下さい。

git checkout main                                          # ローカルのmainブランチに移動
git remote add upstream https://github.com/seigot/ai_race  # fork元のリポジトリをupstream という名前でリモートリポジトリに登録（名前はなんでもいい。登録済みならスキップ）
git fetch upstream                                         # upstream から最新のコードをfetch
git merge upstream/main                                    # upstream/main を ローカルのmaster にmerge
git push                                                   # 変更を反映

参考：github で fork したリポジトリで本家に追従する

Pull Requestを送る（Optional）

本リポジトリへ修正リクエストを送ることが可能です。詳しくは参考をご参照下さい。

※追記　Pull Request練習用リポジトリを作成しました。
test_pull_request

参考：
GitHub-プルリクエストの作成方法
[実践] はじめてのPull Requestをやってみよう
【GitHub】Pull Requestの手順

3.5 SimpleNetを使う

デフォルトでは、ニューラルネットワークとしてResNet-18を使うようになっていますが、自分でニューラルネットワークを作成する場合のサンプルとして、シンプルなニューラルネットワーク(SimpleNet)を用意しています。
ResNet-18ではなくSimpleNetを使う場合は、train.py, trt_conversion.py, inference_from_image.pyの実行時に、--model simplenetオプションを付けてください。

cd ~/catkin_ws/src/ai_race/ai_race/learning/scripts
python3 train.py --model simplenet　 --data_csv $HOME/ai_race_data_sample/dataset/plane/_2020-11-17-01-34-45/_2020-11-17-01-34-45.csv --model_name sample_model
python3 trt_conversion.py --model simplenet --pretrained_model <学習させたモデル フルパス指定> --trt_model <保存するtrtモデル名>
python inference_from_image.py --model simplenet --trt_module --trt_model <保存したtrtモデル名 フルパス指定> 

4. ルール

4.1. 概要

学習モデルにより推論し、車両を操作して走行性能を競います。
今回は以下のルールを採用予定です。

• 制限時間4分以内に、コースを何週回れるかを競う。
  
• 後述するコースのうち、最もシンプルなlevel1を使う。
  
• コースアウトは、自力復帰困難な場合はスタート地点に復帰して走行を継続する。
  

こちら に詳細を記載予定

4.2. 経過時間と周回回数の計測方法

前述のprepare.sh実行時に起動するタイマーと、周回カウンターを使い自動計測します。

4.3 コース

以下のコースを用意しました。

-	level1	level1 with透明壁	level1 advance
名称	Plane	Plane(with透明壁)	Plane(advance)
外観
特徴	地面：一様な模様です	地面：一様な模様です	地面：一様な模様+周辺に草が生えています。 草エリア走行時は速度が落ちます。
障害物	なし	赤い点線部分に透明の壁があります	赤い点線部分に透明の壁があります
起動コマンド	bash prepare.sh -l 1	bash prepare.sh -l 1t	bash prepare.sh -l 1a
学習データのサンプル	あり（１週分）url	なし	なし
備考	今回のルールで採用	初回起動前に、FAQを参考に再度catkin buildして下さい	初回起動前に、FAQを参考に再度catkin buildして下さい

-	level1春	level1夏	level1秋	level1冬
名称	cherry	summer	fall	winter
外観	こちら	こちら	こちら	こちら
特徴	フィールド一面に桜が広がっています	フィールド一面、夏模様です	フィールド一面に落ち葉が広がっています	フィールド一面、、冬模様です
障害物	-	-	-	-
起動コマンド	bash prepare.sh -l 1c	bash prepare.sh -l 1s	bash prepare.sh -l 1f	bash prepare.sh -l 1w
学習データのサンプル	なし	なし	なし	なし
備考	-	-	-	-

-	level1 large
名称	level1 large track
外観	こちら
特徴	level1を大きくしたフィールドに障害物が置かれています
障害物	コース上に三角コーンが複数置かれます（置き方はランダムになる予定です）
起動コマンド	bash prepare.sh -l l
学習データのサンプル	なし
備考	-

-	level2	level3
名称	Medium Track	Hard track
外観
特徴	地面：濃淡付きの模様です	地面：サーキット型の模様です。カーブが急で、速度を調整しないと曲がれない
障害物	なし	三角コーンを置くかも
起動コマンド	bash prepare.sh -l 2	bash prepare.sh -l 3
学習データのサンプル	あり（１週分）url	なし
備考	optional	optional（準備中）

4.4 提出して頂くもの

• 競技コースで動作する学習モデル、コマンド実行方法を提出して下さい。（学習モデルは、trtあり版/trtなし版どちらでもOKです）
  
• 提出方法は、Githubリリースの機能を使うと簡単なのでお勧めです。この場合はGithubリポジトリ名/リリースURLを教えて下さい。
  

学習モデルを提出（バイナリリリース）する場合の手順参考
リポジトリのリリースを管理する
7.オプションで、コンパイルされたプログラムなどのバイナリファイルをリリースに含めるには、ドラッグアンドドロップするかバイナリボックスで手動で選択します。

• 途中経過含めて、上位の結果はどこかに載せたいと考えています。
  

FAQ

こちらに記載

参考

Jetson NanoにROSをインストールする方法
Jetson Nano関係のTIPSまとめ Swapファイルの設定
NVIDIA Jetson Nanoで OpenCV 3をビルドしてインストールする方法、NVCaffe等の OpenCV 4未対応を動かす
https://github.com/mdegans/nano_build_opencv
PyTorch for Jetson
https://github.com/NVIDIA-AI-IOT/torch2trt
RESPECT OneNightRobocon
リポジトリをフォークする
github で fork したリポジトリで本家に追従する
リポジトリのリリースを管理する

Finally

~~ HAVE FUN ! ~~