AMADEUS

AMADEUS

複数個体の方向付き境界ボックス（OBB）検出とID追跡を行います。解析対象の動画そのものから自己教師的にモデルを学習するため、学習画像への手動アノテーションは必要ありません。

AMADEUS 1.0.0

AMADEUSでできること

手動アノテーション不要

学習画像とラベルは入力された動画から生成されます。手動のラベル付け作業は必要ありません。

バッチ処理

最初のセグメンテーションの後、3つの質問に答えるだけでその後のすべての工程が自動で実行されます。

グラフィカルユーザーインターフェース

ユーザーフレンドリーなGUIを備えています。

位置と方向を推定

各個体は、個体を囲う方向付き境界ボックスで出力されます。

相互作用に頑健

相互作用を再現した画像を大量に合成して学習することで、交差時や密集した状況でも安定して追跡することができます。

多様な動画での実行

動物種を問わず、様々な実験室動画での解析が可能です。

基本の流れ

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

細かい条件を指定する場合はEasy Trackingの代わりに Advanced Tracking を、複数の設定を順番に実行する場合は Multi Config Batch を使います。

マニュアルを読む

インストールと起動

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

Windows10 / 11 macOSApple Silicon LinuxUbuntu / WSL2

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

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

ダウンロードしたファイルの開き方

Windows：AMADEUS-Setup.bat をダブルクリックします。次回からはデスクトップの AMADEUS ショートカットでも起動できます。

macOS：AMADEUS-Setup.command を開きます。ブラウザーからのダウンロードでは実行権限が付かない場合があります。その場合はターミナルで chmod +x と入力し、末尾にファイルをドラッグしてEnterを押してから、再度開いてください。macOSが開く操作をブロックした場合は「システム設定 → プライバシーとセキュリティ」で表示を確認してください。

Linux：ファイルのプロパティで「プログラムとして実行」を許可し、AMADEUS-Setup.sh を「端末で実行」します。名称や操作はデスクトップ環境で異なります。デスクトップまたはWSLgのGUI表示環境が必要です。

macOSはPython 3.10–3.12とTcl/Tk 8.6が必要です。既存の対応環境は AMADEUS_VENV、Pythonは AMADEUS_PYTHON で指定できます。設定・修復手順をご覧ください。macOS用パッケージはMPS／CPUに対応します。

macOS・Linuxでは、次回も同じ起動用ファイルを実行できます。保存されたAMADEUS本体を使用します。

Gitを使ってインストールする場合（Windows・macOS・Linux）

Windows

Gitを導入済みなら、保存先のフォルダーでコマンドプロンプト（cmd）を開き、次の1行を実行します（Windows 10 / 11）。保存先に同名の AMADEUS フォルダーがない状態で実行してください。

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

uv・Python・必要なパッケージを自動で準備し、セットアップ完了後にホーム画面を開きます。初回セットアップにはインターネット接続が必要です。

次回からは、新しいコマンドプロンプトで次を実行します。作成された AMADEUS フォルダーは移動・削除せずに残してください。

amadeus

macOS (Apple Silicon)

Gitを導入後、保存先のターミナルで次の1行を実行します。

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

Apple Siliconを対象としています。Intel Macは同梱のPyTorch 2.7.1構成の対象外です。Rosettaを使わず起動してください。

AMADEUS.command を開きます。実行権限のエラーが出る場合は、AMADEUSフォルダーのターミナルで chmod +x AMADEUS.command AMADEUS.sh を実行してください。

利用可能な場合はMPS、利用できない場合はCPUを選択します。MPSおよびmacOS実機での全工程は未検証です。

ターミナルから amadeus / amade を使うには ~/.local/bin をPATHに追加します。設定方法は起動時の案内を参照してください。エラーはターミナルで確認できます。

Linux (Ubuntu / WSL2)

Gitを導入後、保存先のターミナルで次の1行を実行します。

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

AMADEUSフォルダーで bash AMADEUS.sh を実行します。デスクトップ環境またはWSLgなどのGUI表示環境が必要です。

Tk・OpenCVや共有ライブラリのエラーが出た場合は、ターミナルに表示された不足項目を確認してください。対応するNVIDIA GPUではCUDA、その他ではCPUを利用します。

amadeus / amade を使うには ~/.local/bin をPATHに追加します。Linux x86_64のCPU環境構築は確認済みですが、実動画による全工程とLinux ARM実機は未検証です。

ZIPをダウンロードしてインストールする場合

GitHubの「Code → Download ZIP」からダウンロードし、展開後にOSに合ったランチャーを起動します。

OSランチャー
Windows 10 / 11AMADEUS.bat をダブルクリック
macOS（Apple Silicon）AMADEUS.command を開く
Ubuntu / WSL2bash AMADEUS.sh を実行

推奨撮影条件

AMADEUSは与えられた動画から学習するため、撮影条件が結果を左右します。次のような録画を想定しています。

  • 体が比較的細長く体軸が判別でき、初心者でも前後を区別できる動物。
  • 固定した真上からのカメラで、動きが概ね二次元平面に収まっていること。
  • 照明が安定し、背景がほぼ静止していること。
  • 初心者が1フレームずつ個体を目で追える程度のコントラスト・解像度・フレームレート。
  • 個体が接触せず単独でいる場面が比較的多く含まれること。ここから学習データが作られます。

撮影条件が同じであれば、学習用動画と解析用動画は別に撮影しても構いません。

引用

プレプリントのDOIと推奨引用形式は、Publicationページに掲載します。

あわせて本サイトのアドレスもご記載ください：https://amadeus.jpmyrmecol.com/

ライセンス

AMADEUSはGNU Affero General Public License v3.0 only（AGPL-3.0-only）で公開しています。同梱する第三者コンポーネントはそれぞれのライセンスに従い、内容はソフトウェアに同梱の第三者ライセンス表記に記載しています。