Ego-Exo4Dのはじめ方

# はじめに
大学の研究室でEgo-Exo4Dを扱うことになりました。
そこで、Ego-Exo4Dの使い方に関する日本語の解説記事が存在しなかったので、記事を書こうと思いました。
今回はデータセットのダウンロードまでの解説を行います。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3085757/7d253e10-2dbe-78c8-99d5-1ba6c30c92a7.png" width="400" height="400"/>

追記：Ego4Dに関する記事も作成しました。合わせて御覧ください。

https://qiita.com/ryhara/items/7d2f97e73272cf95556f


# Ego-Exo4Dとは
800人を超える参加者が世界13都市の130以上の場所で記録した、合計1400時間以上の1人称視点と３人称視点の映像、さらに映像に同期した音声、センサデータ、点群データを含んだ大規模データセット。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3085757/68383787-7d10-640e-fdaa-ee34f3366b6f.png)
[Ego-Exo4D論文](https://ego-exo4d-data.org/paper/ego-exo4d.pdf) Figure1より引用


以下のような様々なシチュエーションの動画が含まれている。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3085757/cbde1c4d-b4e9-1377-47a3-ef6df2e6cc37.png)

[Ego-Exo4D論文](https://ego-exo4d-data.org/paper/ego-exo4d.pdf) Figure2より引用

詳細は以下のサイトや参考文献をご覧ください

https://ai.meta.com/blog/ego-exo4d-video-learning-perception/

https://ego-exo4d-data.org/


# Ego-Exo4Dの始め方
## Getting Started
大まかな流れは以下のようになります。
1. https://docs.ego-exo4d-data.org/getting-started/ にアクセスする
2. https://ego4ddataset.com/egoexo-license/ にアクセスしてライセンスに同意する
3. https://docs.ego-exo4d-data.org/overview/ にアクセスしてデータセットの概要を確認する。
4. [CLI Downloader](https://docs.ego-exo4d-data.org/download/)を利用してデータセットをダウンロードする 
---

### License Agreement
https://ego4ddataset.com/egoexo-license/ にアクセスしてライセンスに同意します。
以下のような画面が表示されるので、必要事項を入力し提出します。すぐに記入したメールアドレス宛に同意書が送られてくるので、サインを記入して、同意します。
（私はpdfの同意書を翻訳してざっと目を通しましたが、ちゃんとは読んでいません。。。研究などで使用する際はちゃんと目を通したほうが良いと思います。）

通常48時間で承認されるそうです。（私もちょうど２日後にメールが来ていました。）
メールで承認の旨と、アクセスID、アクセスキーが送れられてくるので破棄しないように気を付けましょう。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3085757/33380c94-9317-8d98-15f0-bc18ced8cd31.png)

:::note warn
注意
ライセンスの認証情報は14日で期限が切れます。
期限が切れたら、再度申請を行う必要があります。同じ情報を入力した場合、すぐに承認されるようです。
また、アクセスキーは共有したり、Githubに公開しないように注意しましょう。
:::
---

### Browse The Dataset
- **データセットの確認**
https://docs.ego-exo4d-data.org/overview/ にアクセスしてデータセットを確認できます。
https://docs.ego-exo4d-data.org/annotations/ にそれぞれのデータの詳細が書かれています。
全てに目を通すのは大変なので、ざっくり確認しておけばOKです。実際に使用するとなったら、必要な項目をじっくり見れば良いと思います。
- **サンプルプログラムの確認**
https://github.com/facebookresearch/Ego4d/tree/main/notebooks/egoexo からEgo-Exo4dのサンプルプログラムを確認できます。Jupyter Notebook形式なので[Google Colaboratory](https://colab.research.google.com/?hl=ja)で手軽に確認できます。

- **可視化ツール**
https://visualize.ego4d-data.org/login にアクセスすると可視化ツールが使用できます。
使用には承認後に発行されるアクセスIDが必要です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3085757/340be18c-208a-ed19-09e2-901b0e11563b.png)

承認後ログインすると以下のようにデータセットが一覧で表示されます
選択すると、より詳細にデータセットを確認することができます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3085757/a3e5243b-6f42-70b6-d821-a273857529be.png)


---

### Download The Dataset
[CLI Downloader](https://docs.ego-exo4d-data.org/download/)を利用してデータセットをダウンロードします。

- Ego4DのリポジトリのREADMEにある[Setup](https://github.com/facebookresearch/Ego4d?tab=readme-ov-file#setup)の項目を見て、設定を行う
    - anacondaを使用した設定方法のみが記載されています。 pyenvやvenvを使用した設定も可能。以下参考記事
    - [pyenv によるPythonインストールと落とし穴 (Mac, Ubuntu, CentOS) | Qiita](https://qiita.com/hoppiece_/items/b498b5b38570b4a1ed97)
    - [venv: Python 仮想環境管理 | Qiita](https://qiita.com/fiftystorm36/items/b2fd47cf32c7694adc2e)
- [ドキュメント](https://docs.ego-exo4d-data.org/download/)を参考に必要なデータセットをダウンロード

### 公式ドキュメント、リポジトリを読んだだけではわかりにくい点
1. [Ego4Dリポジトリ](https://github.com/facebookresearch/Ego4d)をclone
2. Setupの[Option2](https://github.com/facebookresearch/Ego4d?tab=readme-ov-file#option-2-clonedownload-the-code)をcloneしたリポジトリのルートで実行
3. **AWS CLI**の設定
awsにデータセットが置かれているようで、コマンドラインからそのデータセットを取得するのに**AWS CLI**の設定が必要なようです。
[AWS CLIの設定](https://github.com/facebookresearch/Ego4d/blob/main/ego4d/cli/README.md#prerequisites)はこのEgo4DのREADME.mdには前提条件として書かれているのですが、Ego-Exo4Dの方には明記されていない気がします。
- https://aws.amazon.com/jp/cli/ にアクセスしてAWS CLIをインストール
- インストールの完了後、`aws configure`とターミナルに打ち込む
- `Access Key ID` , `Secret Access Key` に承認時に送られてきた情報を入力する。
- `Default region name`, `Default output format`は空のままEnterでOK
  - aws cliを他にも使いたい場合は、始めに`aws configure --profile ego4d` とすることでego4d用の設定とデフォルトの設定を分けることが出来る。

4\. ルートで**egoexo**コマンド使用してデータセットをダウンロード

:::note warn
注意
デフォルトでは、約**14TiB**(= 約14 × 1024GB)のデータセットがダウンロードされます。使うデータに絞ってダウンロードすることをおすすめします。
:::

---

### ダウンロード例
実際に自分が行った例です

```shell:例1
egoexo -o ./outdir  --uids 〇〇
```
**uid**の基準が私もあまりわかっていないのですが、`〇〇_uid`という英数字の羅列の値を持つ変数が、可視化ツールの詳細情報の中に沢山あります。
この中の`〇〇_uid`を選択するとその情報のみを取得出来ます。

指定して実行できても、`0バイトダウンロードされました`となるidが多くあります。動画だと思われるものは一回もダウンロード出来ませんでした。（原因不明）

---

```shell:例2
egoexo -o ./outdir --parts 〇〇
```
容量が大きすぎるものは実際にダウンロードしていません。これからダウンロードするもののサイズが表示され、`y/n`で次に進むかを決めることが出来ます。

errorとなっているものはドキュメントの文言のまま記述してもエラーが出ました。（原因不明）

| parts | ファイル形式 | およその容量 |
|:------------:|:------------:|:------------:|
metadata | json |　35.1M　|
annotations　| json |　1.03G　|
takes | - | 7969.379GiB | 
captures　| - | 42.5GiB |  
take_trajectory | - | 376GiB |  
take_eye_gaze | error | error |
take_vrs_noimagestream | - |745.3GiB |
take_point_cloud | - | 2286.5 GiB |
take_vrs | - | 9148.0 GiB | 
capture_trajectory | - | 734.9 GiB |
capture_eye_gaze |- | 2.0GiB |
capture_point_cloud | - |  4089.6 GiB | 
downscaled_takes/448 | - | 364.3 GiB | 
features/omnivore_video | - | 37.3 GiB | 

使用予定のegposeについてのデータセットも試してみました
| benchmarks | およその容量 |
|:------------:|:------------:|
| egopose | 549.9 GiB | 

---

```shell:例3
egoexo -o . --benchmarks egopose --view ego -u fair  --num_workers 1
```
benchmarkがegopose, 視点はego、fair 大学、　num_workersに関しては1にしても、4にしても変わらなかったので、何に作用しているかよくわかりませんでした。
このoptionで**2.0 GiB**でした。`.json`ファイルと`mp4`の動画ファイルが取得できました。


このようにかなり情報を絞るとダウンロード可能な容量になってくることが分かりました。
可視化ツールで目当てのデータセットを見つけて、条件を絞ってダウンロードするのが良さそうです。

## その他
データセットの形状などの詳細は以下のページを参考にしてください

- **Data :**　https://docs.ego-exo4d-data.org/data/
- **Annotations :**　https://docs.ego-exo4d-data.org/annotations/　
- **Benchmarks :** https://docs.ego-exo4d-data.org/benchmarks/

また、[Ego4D Workshop @ CVPR 2023](https://ego4d-data.org/workshops/cvpr23/)が2023年の3月〜6月にかけて開催されていました。
今年も開催が予想されるため、興味がある方は情報を追っておくと良いと思います。

# 最後に
ここまででダウンロードは完了です。ここからはサンプルコードなどを参考に実装していきましょう。
日本語での情報がほとんど無いので、基本は公式ドキュメントを訳しながら、自分で試したことを書いています。
実装はまだなので、これからEgo-Exo4Dを触っていき、気付いたことがあればまた記事を書こうと思います。

最後まで読んでいただきありがとうございました。これからEgo-Exo4Dを触る人の参考になれば嬉しいです。

# 参考文献

https://ai.meta.com/blog/ego-exo4d-video-learning-perception/

https://ego-exo4d-data.org/

https://www.iis.u-tokyo.ac.jp/ja/news/4379/