AMADEUS
日本語マニュアル

1. 起動

お使いのOSのボタンからファイルをダウンロードし、実行してください。Gitの事前導入は不要です。macOSでは、以下に示す対応したPython環境が必要です。

macOSおよびLinuxでは、まだ十分な動作検証を行えていません。 エラーが発生した場合は、Yusuke Notomi（jpmyrmecol [at] gmail.com）まで、OS、インストール方法、表示されたエラーメッセージを添えてご連絡ください。

本体・uv・必要なパッケージを準備し、完了するとホーム画面が開きます。Windows・LinuxではPythonも自動で準備します。インターネット接続が必要です。

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

2. ホーム画面

3. 基本の流れ

1. 必要に応じて Cropping & Trimming で動画を整えます。
2. Segmentation で動物が正しく抽出される設定を作ります。
3. Easy Tracking で学習と追跡を実行します。
4. 結果動画とCSVを確認し、必要なら Refinement で修正します。

細かい条件を指定する場合は、Easy Trackingの代わりに Advanced Tracking を使います。

4. Cropping & 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 を実行します。
5. 単独個体が青、接触個体などが橙になるように外れ値範囲を調整します。
6. （任意）前景として抽出されずに残った動物や動物の一部がある場合は、Additional Outlier で追加の閾値を設定し、それらが橙色でカバーされるように調整して除外します。
7. Processing を押して保存します。

前景の抽出方法

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

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

個体数が変わる場合は、MainのBasic SettingsでVariable populationを有効にしてください。

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

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/ には、tracked（後処理なし）、filled（通常後処理済み）、もしくはid_resolved（埋め込みID補正 + 後処理済み）の最終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. 推奨撮影条件

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

14. ライセンス

GNU Affero General Public License v3.0 only（AGPL-3.0-only）です。LICENSE と 第三者ライセンス情報 を参照してください。