AMADEUS
日本語マニュアル

1. 起動

推奨環境

AMADEUSは、Windows/LinuxのNVIDIA GPU、macOSのApple Silicon、および一部のAMD GPU（ROCm）に対応しています。

NVIDIAおよびAMD GPUについては、動画の解像度や個体数にも依存しますが、8 GB以上のVRAMを推奨しています。ただし、4 GB VRAMのNVIDIA GPUを備えたノートパソコンでも実行可能であることを確認しています。

お使いのOSのボタンからファイルをダウンロードし、実行してください。

v1.0.4までをインストールした方は、以下に案内する手順に従って一度アンインストールしてから、最新版をインストールしてください。

エラーが発生した場合は、納富（jpmyrmecol [at] gmail.com）まで、OS、インストール方法、表示されたエラーメッセージを添えてご連絡ください。特にAMD GPU（ROCm）は実機での検証がまだ十分ではないため、動作結果や問題についてもご報告いただけると助かります。

初回セットアップにはインターネット接続が必要です。

chmod +x ~/AMADEUS/AMADEUS-Setup.command

bash ~/Downloads/AMADEUS-Setup.sh

git clone https://github.com/jpmyrmecol/AMADEUS.git && cd AMADEUS && AMADEUS.bat

amadeus

git clone https://github.com/jpmyrmecol/AMADEUS.git && cd AMADEUS && bash AMADEUS.sh

git clone https://github.com/jpmyrmecol/AMADEUS.git && cd AMADEUS && bash AMADEUS.sh

rm -f ~/.local/bin/amadeus ~/.local/bin/amade

rm -f ~/.local/bin/amadeus ~/.local/bin/amade

2. ホーム画面

3. 基本の流れ

1. Easy Tracking を開き、画面の案内に従って動画を入力した後、Launch Segmentation を押します。
2. Segmentation で動物が背景から適切に抽出されるように設定し、Analysis ボタンを押します。
3. 単独個体が青、接触個体・断片・その他の外れ値が橙になるように、IQRの閾値（またはAbsoluteの範囲）を調整して、Processing を実行します。終了後、自動的に Easy Tracking に戻ります。
4. Easy Trackingで3つの質問項目に回答し、Processing を押して、休憩します。
5. 結果動画とCSVを確認し、必要なら Refinement で修正します。

細かい条件を指定する場合は、Switch Advanced Mode でパラメータを調整します。
なお、必要に応じて、開始前に Cropping & Trimming で動画を整えます。

4. Cropping & Trimming（任意）

解析したい領域をcroppingし、解析したいframeをtrimmingして、動画を整えます。

1. Input Video で動画を選びます。
2. Set In と Set Out で使用区間を決めます。
3. Full を使うか、Add Crop で領域を追加します。
4. 領域をドラッグ・リサイズし、出力する領域を選びます。
5. 領域ごとに明るさ、コントラスト、カラー／グレースケールを設定します。
6. 出力先、名前、FPSを確認して Export します。

5. Segmentation（前景抽出）

動画から動物の領域を抽出し、単独個体と接触個体を区別します。

1. 動画と解析フレーム範囲を確認します。
2. 前景の抽出方法を選びます。背景差分を使う場合は、Median・Maximum・Minimumから選択します。
3. Threshold と Minimum Blob Area を調整し、動物が背景からきれいに抽出されるようにします。
4. 最初の前景抽出の閾値調整が終わったら、Analyze を押します。AMADEUSが複数フレームをサンプリングし、Outlier Extractionに使用する面積分布を計算します。
5. Analyzeが完了すると、Outlier Extraction の設定が表示されます。単独個体が青、接触個体・断片・その他の外れ値が橙になるように、IQRの閾値（またはAbsoluteの範囲）を調整します。
6. Processing を押して保存します。

前景の抽出方法

結果は <Session>/segmentation/ に保存されます。

追加設定は初期状態では非表示です。サイドバー上部の Show optional settings にチェックを入れると、以下のOptional項目が表示されます。

6. Easy Tracking

個体数と2つの質問から設定を作り、学習から結果出力までをまとめて実行します。

1. Video File と Session を指定します。
2. Launch Segmentation で前景抽出を設定します。
3. How many animals are in the video? に個体数を入力し、Enterボタンで反映します。
4. 個体の重なり度合いと、後退する個体がいるかを選びます。
5. Processing を押します。

Save Config と Load Config でYAMLを保存・読込できます。Switch Advanced Mode では現在の設定をAdvanced Trackingで開きます。

自動処理

7. Advanced Tracking

各工程とパラメータを詳しく設定します。

1. セッション、学習動画、解析動画、個体数を指定します。
2. Adjust Parameters で動画に合う初期値を測定します。
3. 実行する工程と設定を確認します。
4. Run を押します。

skipチェックボックスをチェックすることで、必要な工程だけを実行できます。

解析する重みは last、best、または保存済みエポック番号で指定できます。

8. Multi Config Batch

複数のTracking設定を順番に実行します。

1. EasyまたはAdvanced Trackingで設定をYAMLに保存します。
2. Add Configs または Add Folder でconfigを追加します。
3. Up / Down で実行順を整えます。
4. Run Queue を押します。

9. Refinement

結果を動画に重ねて確認し、体の向きや個体IDを修正します。

• AMADEUS mode: config.yaml、重み、結果を選択
• Dataset mode: 動画と追跡ファイルを選択

Dataset modeでは、AMADEUS形式のほか、SLEAP、DeepLabCut、idtracker.aiなどのCSV/H5を読み込めます。方向を修正する場合は、前端・後端の座標を持つデータを選びます。

10. Colab（beta）

保存済みのAMADEUS設定をGoogle Colabで実行し、GPUを使って処理できます。

1. Colab（beta） で保存済みの config.yaml とGoogle Driveの保存先を選び、Prepare for Google Colab を押します。
2. 準備後に Open Google Colab を押します。
3. Colabで Run all を実行し、求められたらGoogle Driveを承認します。

GPU runtimeが必要です。最終CSV、結果動画、必要な学習済み重み、summary、logがGoogle Driveへ保存されます。

11. パラメータ調整

今後、主要なパラメータ調整の指針を追加します。基本的には標準設定で問題ありません。

12. 出力

results/ には、後処理後の最終CSVが保存されます。通常は <model>_<dataset>_<run>_<video>.csv、埋め込みID補正工程が実行された場合は <model>_<dataset>_<run>_<video>_id_resolved.csv です。

方向推定ありの通常モードでは、最終CSVは1行が1フレームで、frame と個体別の cx0, cy0, w0, h0, heading0, … を持ちます。個体IDは0から始まります。座標とOBB寸法は入力動画のピクセル単位、原点は左上、xは右向き、yは下向きです。heading は上を0°、時計回りを正とする0°以上360°未満の角度です。欠測は空欄（NaN）で、全個体が全フレームで必ず得られるわけではありません。

学習済み重みは <Session>/main/<model>/training/<動画名>/weights/ に保存されます。

13. 推奨撮影条件

• 比較的細長い体型で体軸が判別可能であり、初心者でも個体の前後を見分けられる動物であること。
  ただし、方向推定なし（Without direction estimation） モードでは、この制約はありません。
• 固定した真上視点のカメラで撮影し、動きが概ね2次元平面内に収まっていること。
• カメラが固定され、照明が安定していること。
• 背景が基本的に静止していること。
• 個体と背景の間に十分なコントラストがあること。
• 初心者でも目視で個体を追跡できる程度の解像度があること。
• 初心者でもフレームごとに目視で個体を追跡できる程度のfpsとシャッタースピードで撮影されていること。
• 学習データ生成のため、個体同士が接触していない単独個体の場面が比較的頻繁に含まれていること。
  ただし、撮影条件が同一であれば、学習用動画と解析用動画を別々に撮影しても構いません。

14. ライセンス

AMADEUSはGNU Affero General Public License v3.0 only（AGPL-3.0-only）で公開しています。同梱する第三者コンポーネントはそれぞれのライセンスに従います。詳細は LICENSE と 第三者ライセンス情報 を参照してください。