SC-SfMLearner_for_NLab

Unsupervised depth and pose estimationの手法のうちの一つであるSC-SfMLearner(実際にはEndo-SfMLeaner)のpytorch実装です．

使用者のオリジナルデータセットでもトレーニングや推定をコマンドライン上の操作だけですべて済むように調整しました．
参考にした論文は

Unsupervised Scale-consistent Depth and Ego-motion Learning from Monocular Video
Bian, Jia-Wang and Li, Zhichao and Wang, Naiyan and Zhan, Huangying and Shen, Chunhua and Cheng, Ming-Ming and Reid, Ian
SC-SfMLearnerの公式GitHub

EndoSLAM Dataset and An Unsupervised Monocular Visual Odometry and Depth Estimation Approach for Endoscopic Videos: Endo-SfMLearner Kutsev Bengisu Ozyoruk and Guliz Irem Gokceler and Gulfize Coskun and Kagan Incetan and Yasin Almalioglu and Faisal Mahmood and Eva Curto and Luis Perdigoto and Marina Oliveira and Hasan Sahin and Helder Araujo and Henrique Alexandrino and Nicholas J. Durr and Hunter B. Gilbert and Mehmet Turan
EndoSLAMとEndo-SfMLearner公式GitHub

↑gifの容量の関係で画質は粗いですが実際はもっと高精度なdepth推定が期待されます． このコードは色々なコードの複合で成り立っているので非商用利用の用途での利用のみ許可します．

環境構築

1. Anacondaによる仮想環境の構築

pythonのバージョンやパッケージを簡単に管理できるツールAnacodaを利用しますので，公式ホームページでダウンロードします．
インストールが完了すると，PCに Anaconda Prompt というソフトウェアが追加されているので起動します．
起動が完了したらコマンドプロンプト上で以下のように仮想環境を構築します. (当コードはpythonのバージョンが3.6以上を想定している．ここでは3.8を指定)

conda create -n SfMLearnerForNLab python=3.8

その後，作った仮想環境を起動

conda activate SfMLearnerForNLab

2. 必要なパッケージのインストール

まずディープラーニング用のモジュールであるpytorchをインストールします.

pytorchをインストールするためのコマンドはバージョンの変更に伴って適宜変更されるため，公式ホームページでコマンドを確認してください．自分の環境にあったボタンをクリックするだけでpytorchをインストールするためのコマンドが表示されますのでコマンドプロンプトで実行しましょう.pytrochのインストールが完了したら，ダウンロードした「SC-SfMLearner_for_NLab-master」にディレクトリを移動する．

cd PATH_TO_DIR/SC-SfMLearner_for_NLab-master

ディレクトリ内に自動的に必要なモジュールをダウンロードするためのリストである requirements.txt がありますのでそれを利用してモジュールをインストールします．以下のコマンドをコマンドプロンプトで実行します．

pip install -r requirements.txt

もし手動でバージョンを変えたい場合は適宜requirements.txtを参照しながらモジュールをインストールしてください．

データセットの作成

まずはデータセットを作成します．「datasets」ディレクトリに必要な処理が一通りそろってますのでそれを利用します．
「datasets」ディレクトリに移動します．

cd ./datasets

「train_videos」と「val_videos」というディレクトリがありますので，そこにデータセットとして利用したい動画ファイル(現在はmp4ファイルのみに対応)を入れてください．

＊ 学習で利用する動画は全て同じカメラで撮影されていることを確認してください

動画を配置し終わったら，以下のコマンドを実行することで「datasets」内に「data_for_SC_SfMLearner」が生成される．
その際に以下のオプションがあるので利用したいデータセットによって適宜変更してください．

・--save_frequency
動画を何フレーム間隔でデータセットとして利用するか指定するオプション．
フレーム間隔が大きいと省メモリ，Depht推定において遠方の物体の深度推定の高精度化を期待できるが，間隔が大きすぎるとフレーム間の類似性が下がって学習が安定しない．
フレーム間隔が小さいとカメラに近い物体の深度推定の高精度化に寄与し，学習が安定するが，小さすぎるとデータセットの容量増加や遠方の物体の深度推定がされないことがある．

・--save_height, --save_width
データセットとして使う動画のリサイズに関するオプション．
必ず，リサイズ後の高さと幅が32の倍数となるように指定してください．
これはSfM LearnerがDepthを推定する際に画像サイズを半分にするConv処理をした5回した後にDeConv処理を5回するので2の5乗である32の倍数を高さと幅が持つ必要があります．

以下に示すのは実行するコマンド例です．

python make_datasets.py --save_frequency=10 --save_height=512 --save_width=288

プログラムが実行されると以下のようなGUIが起動します．

ここにデータセットとして使うカメラの内部パラメータを入力します．（カメラの内部パラメータ，外部パラメータに関しては

https://jp.mathworks.com/help/vision/ug/camera-calibration.html などを参照してください
通常，画像のリサイズ前後で内部パラメータは変化しますが，リサイズ前の内部パラメータを入力し，「finish」ボタンを押してください．

もし先ほどオプションで指定したリサイズ後の内部パラメータが既知の場合はその内部パラメータを入力し，GUI上の「Is resized image's intrinsic」にチェックを入れて「finish」ボタンを押してください． 一定時間後にデータセット作成が完了し，デフォルトのオプションであれば「datasets」ディレクトリに「data_for_SC_SfMLearner」が作成されます．

モデルのトレーニング

1. トレーニングのクイックスタート

トレーニングのために，「SC-SfMLearner_for_NLab-master」ディレクトリに戻ります．「datasets」ディレクトリにいる場合は以下のコマンドによって親ディレクトリに戻ります．

cd ..

トレーニングのためにもいくつかオプションがあり，各自の環境にあった設定ができます以下に示すのは代表的なオプションです．GPUの指定などはpytorchのモジュールによって自動的に行われます．

・--epochs(デフォルトは200)
エポック数の指定

・--batch_size(デフォルトは4)
バッチサイズの指定

・--print_freq(デフォルトは1000)
1バッチサイズの処理を1イテレーションとしたときに，何イテレーション毎にフィードバックするかを指定できます．
具体的にはコマンドプロンプト上へのloss値の表示，「checkpoints」ディレクトリにtensorboard用のeventファイルの保存，モデルの重みファイル(pthファイル)の保存を行います．

これらのオプションを利用して，コマンドプロンプトで「train.py」を実行します．以下に示すのは実行の例です．

python train.py --epochs=100 --batch_size=8

他にも様々なオプションがありますが利用したい場合は「train.py」のコードを見てください．

2. トレーニングの経過を見る

ディープラーニングの学習経過を見るためには 「tensorboard」 を利用すると学習途中のdepthマップやloss値の推移をビジュアル的にブラウザ(Microsft EdgeやGoogle Chroomなど)上で観察できます．
以下にtensorboardの使い方を示します．　　

「train.py」を実行すると「checkpoints」ディレクトリが作成され，その中に実行した日付のディレクトリが子ディレクトリとしてあり，その中にeventファイルと重みファイル(pthファイル)があります．それらのファイルが作成されていることを確認した後に以下の例ようなコマンドを仮想環境で実行してください．

tensorboard --logdir=PATH_TO_YOUR_DIR/checkpoints/12-05-19-47 --port=8888

「--logdir」にはeventファイルや重みファイルが入っているディレクトリを指定します．「--port」には使用するポート番号を指定します．

実行に成功するとコマンドプロンプト上にtensorboardを実行するためのURLが表示されますのでブラウザ上で実行してください．

すると以下のような画面が表示され，トレーニングの経過が観察できます．

学習済みデータを用いた深度・ポーズ推定

学習が終了したら，そのモデルの重みを使って深度推定やポーズ推定を行うことが出来ます．
一通りの機能は「prediction」ディレクトリ内に揃っています．以下に利用する例を示します．
まずコマンドプロンプト上で「prediction」ディレクトリに移動します．

cd --logdir=PATH_TO_YOUR_DIR/SC-SfMLearner_for_NLab-master/prediction

その後，推定したい要素によって実行するpythonファイルは異なりますが，実行時のオプションは共通なのでここで示します．

・--weight_pth
pthファイルの指定．

・--path_to_yaml(デフォルトは"../datasets/data_for_SC_SfMLearner/environment.yaml")
学習環境を記録したyamlファイルへのパスを指定．学習に利用したデータセットをデフォルトのディレクトリに保存している場合はこのオプションを変更する必要が無い．

・--use_camera(デフォルトは-9999)
usbカメラをPCに接続し，そのusbカメラから深度・ポーズを推定したい場合はこのオプションにカメラポート番号を指定する．このオプションを指定した場合は「input」ディレクトリに入っている動画，画像ファイルに対する深度・ポーズ推定は行われない．

1. 深度推定

「input」ディレクトリに画像・動画を入れた後に「pred_disp.py」を実行します．以下に実行例を示します．

python pred_disp.py --weight_pth=PATH_TO_YOUR_DIR/checkpoints/12-05-19-47/dispnet_10000.pth

推定された結果は「output」ディレクトリに自動的に保存されます．

もしusbカメラをPCに接続して使用したい場合は「--use_camera」オプションにカメラポート番号を指定します．

python pred_disp.py --weight_pth=PATH_TO_YOUR_DIR/checkpoints/12-05-19-47/dispnet_10000.pth --use_camera=0

この場合推定結果は保存されず，リアルタイムで表示されます．

2. ポーズ推定

「input」ディレクトリに動画を入れた後に「pred_disp.py」を実行します．以下に実行例を示します．(画像を推定対象として指定することは出来ません)

python pred_pose.py --weight_pth=PATH_TO_YOUR_DIR/checkpoints/12-05-19-47/posenet_10000.pth

推定された結果は「output」ディレクトリにcsvファイルとして自動的に保存されます．

もしusbカメラをPCに接続して使用したい場合は「--use_camera」オプションにカメラポート番号を指定します．

python pred_pose.py --weight_pth=PATH_TO_YOUR_DIR/checkpoints/12-05-19-47/posenet_10000.pth --use_camera=0

こちらは実行結果が「output」ディレクトリに自動的に保存されます．