# **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.
* 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`.
* Vẽ bounding box.
* Sau khi vẽ bounding box, chọn nhãn và thuộc tính (nếu có) tương ứng.
* 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`.
* 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 ] 
[ Sát ] 
* ==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/```
Sign in with Wallet
Connect another wallet