アノテーションツールの「VATIC」についていい加減まとめる

# 0. あらまし

近年、研究者たちは、創造的な仕事を奪われ、AIのためにひたすら「アノテーション※」という儀式を繰り返していた・・・。
そして、思考は、簡単にアノテーションできないかと考える日々に流れるのであった。

※アノテーション（英語：annotation）
　あるデータに対して関連する情報（メタデータ）を注釈として付与すること。
　XML等の記述形式を用いてメタデータをタグ付けする場合が多い（Wikipediaより）。

※注意
　本記事にて、対象とする「アノテーション」とは、画像処理の物体検出とトラッキングに使用するアノテーション方法です。
　画像中の物体名（ラベル）と物体の位置（物体を囲む矩形）の情報をアノテーション情報として記録します。

# 1. Vaticとは

物体検出やトラッキングのアノテーションができるアノテーションツールです。
[vatic](http://www.cs.columbia.edu/~vondrick/vatic/)の特徴としては、以下が挙げられます。

+ 物体の検出アノテーションができる
+ 物体のトラッキングアノテーションができる
+ ブラウザで作業するので、サーバーに入れれば、分担作業ができる
+ 遮蔽やフレームアウトまでアノテーションできる
+ フレーム間の補完機能があり、フレームを少し飛ばしてアノテーションできる
+ 欠点：ローカルにインストールするのが大変
  + Dockerで入れることをオススメします

## 1.1. 動作環境
+ Google ChromeかFirefoxがインストールされていること
+ IEでは動作しません

# 2. 前準備

ホームに`data`というディレクトリを作成して、その中に`videos_in`と`labels.txt`を作成します。
`videos_in`の中にアノテーションしたい動画を入れます。複数個入れもいいです。
*事前に動画のフレーム数も確認しておいた方がいいです*

```bash
$ mkdir -p ~/data/videos_in
```

`labels.txt`には、アノテーションしたい対象のラベルを入力します。複数のラベルを入力する場合は、改行して入力します。

```txt:labels.txt
person
car
dog
```

配置は、以下のようになります。

```
~/data
├── labels.txt
└── videos_in
    └── test.mp4
```

# 3. インストール

ローカルにインストールするのは大変なので、簡単なDockerでインストールします。
Dockerのインストール方法は、[公式ホームページ](https://docs.docker.com/install/)で確認してください。

以下のコマンドでイメージのダウンロードが始まり、インストールできます。

```bash

$ sudo docker pull npsvisionlab/vatic-docker
```


# 4. アノテーション実行

以下を実行すると、アノテーションソフトが起動します。あとは、少し設定を変更していきます。
`$PWD`は、コマンド実行した場所のディレクトリパスが挿入されるので、`~/data`があるディレクトリに移動しています。

```bash
$ cd ~
$ sudo docker run -it -p 8111:80 -v $PWD/data:/root/vatic/data npsvisionlab/vatic-docker /bin/bash
```

まず、上記のコマンドを入力直後は、以下の状態になっています。
これは、このソフトを動かしている仮想OS環境(Ubuntu)にログインした状態です。
`ls(ディレクトリ内の一覧表示コマンド)`を入力するとちゃんと表示されると思います。

```bash
root@f10f2d7exxx:/# 
root@f10f2d7exxx:/# ls
bin   dev  home  lib64  mnt  proc  run   srv  tmp  var
boot  etc  lib   media  opt  root  sbin  sys  usr
```

ここからは設定変更を行います。
Vimを使用していますが、ターミナルで使用できるテキストエディタなら
なにを使っても大丈夫です。

```
# vi /root/vatic/example.sh
```
７行目を修正します。`--length [フレーム数以上の数字]`を追加します。
これにより、分担する人のアノテーション枚数が設定できます。
この設定をしないと、1つの動画が数百フレーム程度で分割されてしまうので、
それが嫌いな方は設定してください。

```diff
- TURKOPS="--offline --title HelloTurk!"
+ TURKOPS="--offline --title HelloTurk! --length 10000"
```

変更ができれば、実行します。

```
# bash /root/vatic/example.sh
```


上記を実行すると、下記のようにターミナルにURLが表示されます。
URLの表示数は、動画の長さによって変わります。

```
http://localhost/?id=1&hitId=offline
http://localhost/?id=2&hitId=offline
http://localhost/?id=3&hitId=offline
```

URLをブラウザに貼り付けて場合によっては、`:8111`を`localhost`の後ろに追記します。

```
http://localhost:8111/?id=1&hitId=offline
```

すると、以下の動画の画面が立ち上がります。
この動画を参考にして、アノテーションしてください。

[![IMAGE ALT TEXT HERE](http://img.youtube.com/vi/ljI5pAowACc/0.jpg)](http://www.youtube.com/watch?v=ljI5pAowACc)

## 4.1. Options

ブラウザの下の方に、「Options」のボタンがあります。
使ったほうが楽にアノテーションできるので使用することをオススメします。

+ Disable Resize?　　バウンディングボックスのサイズ変更機能をOFFにする
+ Hide Boxes? 　　　 バウンディングボックスを非表示にする
+ Hide Labels? 　　　ラベルを非表示にする
+ Speed [Slower, Slow, Noumal, Fast]　再生スピードを変更する

### 4.1.1. 遮蔽

物体追跡を行っていると、他の物体に隠れたりして、見えなくなるシーンがあります。
その際には、ラベルのところに表示サれている`Occluded or obstructed`にチェックを入れて、
このシーンでは、物体が見えていないことがタグ付けできます。

### 4.1.2. フレームアウト

物体が画像内から外にでた場合に、`Outside of view frame`にチェックを入れることで、
その物体が以降のフレームに現れないことがタグ付けできます。


### 4.1.3. Save Work

ある程度作業が進めば、`Save work`ボタンでアノテーション情報を保存します。
*このボタンを押さずにブラウザを閉じると悲惨なことになるので、こまめにセーブすることをオススメします。*

## 4.2. 複数人で作業を行う

同じネットワーク内にあるPCでもIPアドレスとポートを指定すればアノテーションが可能になります。
[IP address]の箇所にVaticを動かしているPCののIPを入力すると開くことができます。

```
http://[IP address]:8111/?id=1&hitId=offline
```

# 5. アノテーションの出力

アノテーションが終わった後は、アノテーション情報を様々な形で出力できます。

```
--xml       Use XML
--json      Use JSON
--matlab    Use MATLAB
--pickle    Use Python's Pickle
--labelme   Use LabelMe video's XML format
--pascal    Use PASCAL VOC format, treating each frame as an image
```

出力フォーマットを何も指定しないと、テキスト形式で出力されます。
`currentvideo`の箇所は、`example.sh`の４行目`ID`に入力したIDになります。

```
# cd ~/vatic
# turkic dump currentvideo -o /root/vatic/data/output.txt
Dumping video currentvideo
```

他のフォーマットで出力するなら、以下のオプションを付けて実行します。

```
# turkic dump currentvideo -o /root/vatic/data/output.xml --xml #xml output
# turkic dump currentvideo -o /root/vatic/data/output.json --json #json output
# turkic dump currentvideo -o /root/vatic/data/VOC/ --pascal #pascal VOC output
```

出力フォーマットは以下のようになります。

```xml:output.xml
<annotations count="9">
    <track id="0" label="person">
        <box frame="0" xtl="417" ytl="226" xbr="457" ybr="299" outside="0" occluded="0"/>
        <box frame="1" xtl="418" ytl="226" xbr="458" ybr="299" outside="0" occluded="0"/>
        <box frame="2" xtl="419" ytl="227" xbr="459" ybr="300" outside="0" occluded="0"/>
    <track id="1" label="person">
        <box frame="0" xtl="417" ytl="226" xbr="457" ybr="299" outside="0" occluded="0"/>
```

```json:output.json
{
    "8": {
        "label": "person",
        "boxes": {
            "56": {
                "ybr": 162,
                "occluded": 0,
                "outside": 0,
                "xtl": 130,
                "ytl": 94,
                "xbr": 158,
                "attributes": []
            },
            "2863": {
                "ybr": 404,
                "occluded": 0,
                "outside": 1,
                "xtl": 110,
                "ytl": 318,
                "xbr": 153,
                "attributes": []
            },
}
```

# 注意：PascalVOC出力について

以下のようにPascalVOCのフォーマットで出力できますが。現在（2019/07/20）のDocker用のバージョンでは、以下の問題を抱えています。
1. 画像サイズのwidthとheightの値が入れ替わって入力されるため、そこの値を参照するプログラムを書く場合は、注意が必要
2. `--dimensions`のパラメータが無効になるため、出力画像サイズが`720x405`のような異なったサイズで保存されてしまう。

1.については、githubのmasterではすでにcontribブランチにて修正されているのですが、masterにマージされていないので、
Dockerでは、master側をビルドしてしまいます。
2.については、仕様みたいなので、[Resize-pascal-voc](https://github.com/italojs/resize_dataset_pascalvoc)などを使用して、リサイズする必要があります。


```text:pascal_dir
./VOC
├── Annotations
│   ├── 000001.xml
│   ├── 002941.xml
│   ├── 002971.xml
│   └── 002986.xml
├── ImageSets
│   └── Main
│       ├── person_train.txt
│       ├── person_trainval.txt
│       ├── train.txt
│       └── trainval.txt
└── JPEGImages
    ├── 000001.jpg
    ├── 000016.jpg
    ├── 002971.jpg
    └── 002986.jpg

```

## 5.1. 動画が複数URLにわかれた場合

複数のURLで作業した後に、アノテーション情報を統合する機能があります。
これをしないと、同じ物体にアノテーション作業者ごとに違うIDを振っている可能性があるので、
せっかくのアノテーション情報に矛盾が生じます。
`--merge_threshold`は、物体を囲った矩形の重なり度(IoU)が50％以上の場合に、その矩形を同じIDとしてマージします。

```
# turkic dump currentvideo -o /root/vatic/data/output.xml --xml --merge --merge-threshold 0.5
```

## 5.2 アノテーション情報をリサイズして出力したい

Vaticの仕様で忘れがちなのですが、オプション指定しないと、640x480の画像サイズでアノテーション結果を出力します。
なので、入力画像が`1920x1080`などの異なるサイズの場合は、以下のようにオプションを設定します。

```
# turkic dump identifier -o /root/vatic/data/output.txt --dimensions 1920x1080
```

# 6. 最後に

もう使うことがないだろうと思っていたのですが、最近また使い始めたのでまとめてみました、
出力オプションやアノテーションのプションがかなり多くて、使いこなせると大変便利そうですが、
まとめられているのが、公式のGitHubに英語でしかないです。
※上記のオプション以外にもあるので、お試しあれ。

# 参考サイト

[1] [Vatic](http://www.cs.columbia.edu/~vondrick/vatic/)
[2] [動画アノテーションツール　VATIC(Video Annotation Tool from Irvine, California)を簡単にインストールする方法](http://deep-architecture.hatenablog.com/entry/2017/09/25/012500)
[3] [Vatic github](https://github.com/cvondrick/vatic)