---
# System prepended metadata

title: '**Vatic Annotation Tool**'

---

# **Vatic Annotation Tool**

```
Data
 |——————images
 |        └——————train
 |        |         └——————frames
 |        |         └——————gt
 |        |         └——————seqinfo.ini
 |        └——————test (optional)
 └——————labels_with_ids
            └——————train
```
---
## 1. Yêu cầu
* Ubuntu
* Docker
---
## 2. Cài đặt

#### Tạo folder lưu trữ dữ liệu cho docker

>DATA_DIR = /home/your_username/data/
>mkdir -p $DATA_DIR

* Tất cả dữ liệu đã làm trên container sẽ được lưu vào máy local ở folder đã tạo```/home/your_username/data/```.
* Ngược lại dữ liệu copy từ máy local vào folder này sẽ tự động được nhận diện bên trong container
* ==Nên kiểm tra folder này trước khi xóa container.==

#### Khởi tạo Vatic container
> docker run -it -p 8080:80 -v $DATA_DIR:/home/vagrant/data jldowns/vatic-docker-contrib:0.1

* Câu lệnh trên chạy thành công khi thấy màn hình 1 shell mới trong container.
* Kiểm tra directory trong container bằng câu lệnh```pwd``` (output chuẩn là ```/home/vagrant```)
* Câu lệnh trên map port ```8080``` của container với port ```80``` của máy local. Nếu muốn map port khác, thay đổi `8080`.

#### Khởi tạo MySQL server và Apache server
Bên trong container chạy script ```start_services.sh``` để khởi tạo MySQL server và Apache server.

> ./start_services.sh
>hoặc sh /home/vagrant/start_services.sh
---
## 3. Sử dụng
* Câu lệnh chính để sử dụng tool là ```turkic```
* ==Chú ý câu lệnh này chỉ hoạt động trong folder ```/home/vagrant/vatic/```==

#### Trích xuất frame từ video
> turkic extract /home/vagrant/path_to_your_video.mp4 /home/vagrant/path_to_output_video_frames/ --no-resize

* Nên tạo 1 folder riêng dành riêng cho việc trích xuất frame xong container, ví dụ như ```/home/vagrant/data/video_frames```. 
* Câu lệnh ví dụ: ```turkic extract /home/vagrant/data/test.mp4 /home/vagrant/data/video_frames/ --no-resize```.
* ==Mỗi lần chỉ extract được 1 video. Khi trích xuất video mới, tool sẽ tự động xóa các frame cũ.== 
* Chú ý sử dụng flag ==```--no-resize```== ở cuối.

#### Load frame và labels vào Vatic
> turkic load job_id /home/vagrant/path_to_your_video_frames/ Label1 Label2 ~Attr1 ~Attr2 Label3 --offline

```
job_id: Id cho video đang đánh nhãn.
Label1 ... LabelN: Tên nhãn muốn đánh.
Attr1 ... AttrN: Thuộc tính của mỗi nhãn.
```

* Sử dụng dấu `~` đằng trước các thuộc tính để phân biệt với `Label`. Thuộc tính của nhãn nào viết ngay đằng sau nhãn đó.
* Chú ý sử dụng flag ==```--offline```== ở cuối.
* Câu lệnh ví dụ: ``` turkic load vid_10 /home/vagrant/data/video_frames/vid_10/ Car ~Kia ~Ford Truck ~Heavy ~Container Motorbike ~SH ~Wave --offline```.

#### Sử dụng Vatic
> turkic publish --offline

* Kết quả trả về sẽ là các url.
```
http://localhost/?id=1&hitId=offline
http://localhost/?id=2&hitId=offline
http://localhost/?id=3&hitId=offline
```
* Copy các url này vào web browser (firefox, chrome...) và tool Vatic sẽ được load.
![](https://i.imgur.com/5o0aurY.jpg)
* Chú ý thêm port ```8080``` ở phía sau ```localhost```:
```http://localhost:8080/?id=1&hitId=offline```
* Trong trường hợp sử dụng `ssh`, thay ```localhost``` bằng địa chỉ ip của máy đang được connect tới.

#### Thực hiện gán nhãn
* Bắt đầu đánh nhãn bằng cách click vào nút `New Object`.
![](https://i.imgur.com/SJlw855.png)
* Vẽ bounding box.
![](https://i.imgur.com/CCMV9bJ.png)
* Sau khi vẽ bounding box, chọn nhãn và thuộc tính (nếu có) tương ứng.
![](https://i.imgur.com/R13kdQW.png)
* Có thể kéo thả bounding box trực tiếp nên không cần vẽ cho từng frame.
* Nếu vật thể bị che khuất, chọn `Occluded or obstructed`. Nếu vật thể biến mất, chọn `Outside of view frame`.
![](https://i.imgur.com/39NBSUX.png)
* Chú ý sử dụng nút `Save work` để lưu các nhãn đã được gán vào database trong trường hợp bị disconnect giữa chừng.
* Chú ý vẽ bounding box sát với vật thể nhất có thể.
    [ Không sát ] ![](https://i.imgur.com/kDU9i4b.png)

    [ Sát ]    ![](https://i.imgur.com/wCiHcMm.png)

* ==Hướng dẫn gán nhãn:== https://www.youtube.com/watch?v=ljI5pAowACc.

#### Xuất file annotation
> turkic dump *job_id* -o output.txt --merge --merge-threshold=1 

* Nhãn đã đánh của video `job_id` sẽ được viết ra file `output.txt`
* Format của dữ liệu là các dòng, mỗi dòng gồm 10+ cột, cách nhau bởi dấu cách.
```
1   Track ID. Id của vật thế.
2   xmin. Tọa độ x của điểm trái trên.
3   ymin. Tọa độ y của điểm trái trên.
4   xmax. Tọa độ x của điểm phải dưới.
5   ymax. Tọa độ y của điểm phải dưới.
6   frame. Frame mà dữ liệu này biểu diễn.
7   lost. Vật thể biến mất nếu giá trị này bằng 1.
8   occluded. Vật thể bị che khuất nếu giá trị này bằng 1.
9   generated. Vật thể được nội suy tự động nếu giá trị này bằng 1.
10  label. Nhãn của vật thể.
11+ attributes. Mỗi cột đằng sau thể hiện thuộc tính của vật thể.
```

* Chú ý sử dụng flag ==--merge== và ==--merge-threshold=1==.
* Có thể sử dụng các format ngoài file text bằng cách thêm các flag ở cuối.
```
--xml       Định dạng XML
--json      Định dạng JSON
--matlab    Định dạng MATLAB
--pickle    Định dạng Python's Pickle
--labelme   Định dạng LabelMe (MIT) video's XML format
--pascal    Định dạng PASCAL VOC format
```

#### Kiểm tra kết quả đánh nhãn
> turkic visualize *job_id* */path_to_folder* --merge --merge-threshold=1 --no-augment --renumber

* Kết quả trả về là các frame cùng với vật thể đã được đánh nhãn.
* Nên tạo 1 folder riêng cho việc visualize kết quả. Ví dụ: `/home/vagrant/data/visualize`.
* Chú ý sử dụng các flag ==--merge==, ==--merge-threshold== và ==--renumber==.
* Các frame này có thể sử dụng để tạo video cho việc visualization (ví dụ như `ffmpeg`).
* Nếu muốn hiển thị cả nhãn của từng vật thể, sử dụng thêm flag `--labels` ở cuối.

---
## 4. Các câu lệnh phụ
#### Liệt kê các video gán nhãn
> turkic list
#### Xóa video gãn nhán
> turkic delete *your_video*

* Nếu video đã được đánh nhãn, câu lệnh trên sẽ cảnh báo. 
* Nếu vẫn muốn xóa video, sử dụng flag `--force` ở cuối.
#### Liệt kê các container
> docker ps -a
#### Chạy container
> docker start *name_of_container*
#### Truy cập vào container
> docker attach *name_of_container*

---
## 5. Các lỗi thường gặp
#### Không thể sử dụng lệnh turkic
> No handlers could be found for logger "turkic.geolocation"
* Kiểm tra lại directory đang làm việc. 
* Lệnh `turkic` chỉ hoạt động trong directory `/home/vagrant/vatic`.

#### Không hiển thị nhãn của vật thể khi gán
* Dùng nút `Options` trên giao diện.
* Tick chọn ẩn hoặc hiện nhãn.

#### Video mới hiện lên những box cũ
* Do sử dụng các url cũ.
* Hoặc url load các frame đã được trích xuất từ video cũ.
* Không làm nhiều video cùng lúc. 
* Sau khi xuất file annotate của video cũ nên xóa `job_id`, tránh việc `publish` ra nhiều url.

#### Không truy cập được vào folder chứa frame
* Cấu trúc file chứa frame của Vatic
```
Vatic Folder -> (0, 1, 2, ...) -> (0, 1, 2, ...) -> 100 images
```
* Mỗi folder có thể chứa tối đa 100 ảnh đến khi folder tiếp theo được tạo.
* Ví dụ: Truy cập 1 frame được trích xuất qua directory `home/vagrant/data/video_frames/0/0/96.jpg` hoặc `home/vagrant/data/video_frames/0/9/6.jpg`.

#### Lỗi khi visualize
> ValueError: cannot determine region size; use 4-item box
* Lỗi nằm ở file `/home/vagrant/vatic/cli.py`.
* Sửa lỗi bằng cách comment dòng 504 `aug.paste("black")`.

#### Kết quả visualize không đúng
* Do frame được trích xuất và dữ liệu gán nhãn khác nhau.
* Kiểm tra các frame được trích xuất từ trước và `job_id` đang gán nhãn phải giống nhau.
* Có lỗi ở frame 321 và frame 1199 (Có thể bỏ qua 2 frame này).

---
## Nguồn
* Paper: ```Carl Vondrick, Donald Patterson, Deva Ramanan. "Efficiently Scaling Up Crowdsourced Video Annotation" International Journal of Computer Vision (IJCV). June 2012. ```
* Github: ```https://github.com/cvondrick/vatic```
* Docker hub: ```https://hub.docker.com/r/jldowns/vatic-docker-contrib/```