윈도우 CVAT 설치부터 Auto Labeling까지!

 

이번에는 대표적인 라벨링 툴인 CVAT의 설치와 사용 방법, 그리고 모델을 배포하여 Object Detection, Pose Estimation을 오토 라벨링하는 부분까지 다뤄보고자 한다

직접 PC에 다시 설치해보면서 글을 작성해보았다

 

물론 공식 문서에는 설치 방법, 라벨링 가이드, 모델 배포하고 오토 라벨링까지 사용하는 방법들이 다 나와있지만... 가이드에서 표류하지 않고 글 하나만 보고 빠르게 셋업해서 라벨링 시작할 수 있게끔 가이드를 작성해보자는 목적으로 해당 글을 정리해본다

 

그래도 설치 가이드 먼저 올려봅니다. 

https://docs.cvat.ai/docs/administration/basics/installation/#windows-10

Installation Guide

 

 

 

---

 

 

 

1. CVAT 설치 (WSL 기반)

 

1-1. 라이브러리 사전 설치

CVAT을 설치하기 전에, WSL과 도커가 먼저 필요하다

 

WSL 설치

WSL 설치하는 부분은 이전 Xavier NX 셋업 내용을 가져왔다

윈도우 환경에서 디바이스 셋팅을 진행했기에 WSL2를 사용하였다
이전에는 많은 명령어를 실행하고 설정에 들어가서 체크하는 등 복잡하던 WSL 셋팅이 굉장히 간단하고 편리해졌다. 

명령 프롬프트에서 wsl --list --online 을 실행하고 wsl.exe --install Ubuntu-22.04 이렇게 실행하면 윈도우에서 우분투 환경을 간단하게 셋팅할 수 있다

 

 

도커 설치

가이드대로 exe파일로 윈도우에 설치하는 도커 데스크톱을 설치해도 좋다.

하지만 개인적으로 명령어 입력으로 설치가 더 익숙해서 필요한 명령어들만 정리해보았다

 

최신 버젼으로 도커 설치

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

 

sudo 없이 도커 명령어 사용하도록 사용자 권한 부여. 아래 명령어 실행하고 WSL을 껐다 다시 켜면 잘 적용된다

sudo groupadd docker

sudo usermod -aG docker $USER

 

 

---

1-2. CVAT 설치

 

 

CVAT 깃허브 소스를 가져온다

git clone https://github.com/cvat-ai/cvat
cd cvat

 

 

CVAT에 필요한 이미지들을 빌드한다

docker compose up -d

 

 

빌드 전 IP를 지정하지 않으면 localhost로 CVAT IP가 설정된다. localhost:8080.로 접속가능하다

 

 

PC의 IP를 지정하고 서버를 내렸다가 다시 올리면 localhost가 아닌 지정한 IP:8080 으로 CVAT 웹 페이지 접속이 된다

export CVAT_HOST=<your computer ip>

docker compose down
docker compose up -d

 

 

 

웹에 접속해서 계정을 만들 수 있지만 명령어로 계정 생성 가능하다

sudo docker exec -it cvat_server bash -ic 'python3 ~/manage.py createsuperuser'

 

아래 사진처럼 만들 수 있는데 비밀번호를 1234로 설정했더니 너무 짧다고 경고가 뜨지만 그래도 생성할 수는 있다 

 

 

로그인하면 다음과 같은 화면이 뜬다. 

 

 

 

 

---

 

 

2. CVAT 모델 배포

 

CVAT에 모델을 배포하여 오토라벨링을 사용하는 튜툐리얼은 아래의 공식 문서 가이드를 참고한다

 

https://docs.cvat.ai/docs/administration/advanced/installation_automatic_annotation/

Semi-automatic and Automatic Annotation

 

 

https://docs.cvat.ai/docs/manual/advanced/serverless-tutorial/

Serverless tutorial

 

 

2-1. nuclio 설치

CVAT에 학습된 모델을 배포하여 오토 라벨링을 사용하는데 nuclio라는 라이브러리를 사용한다

아무 버전이나 설치하는 것이 아닌, 깃 클론을 통해 가져온 CVAT 소스에 맞는 버젼을 설치해야 한다

필요한 버젼은 CVAT 폴더의 cvat/components/serverless/docker-compose.serverless.yml 에서 확인할 수 있다

 

아래 이미지처럼 확인해보면 1.13.0 버젼이 필요하다

https://github.com/nuclio/nuclio/releases 에서 맞는 버젼의 파일을 다운받을 수 있지만 파일만 확인하고 아래의 wget 명령어로 다운받는 것이 더 편하다

 

릴리즈 노트를 들어가보면 이렇게 버젼, 환경별 파일들이 있다

 

 

 

필요한 버젼이 nuctl-1.13.0-linux-amd64 임을 확인했다면 아래 명령어로 CVAT 폴더에 바로 다운로드 가능하다

wget https://github.com/nuclio/nuclio/releases/download/<version>/nuctl-<version>-linux-amd64

 

 

 

파일을 CVAT 폴더에 다운받았다면 아래 명령어를 실행한다

해당 명령어들은 다운로드한 nuctl 실행 파일에 실행 권한을 부여하고 심볼릭 링크를 생성하여 nuctl을 시스템 경로에서 실행할 수 있도록 설정한다

sudo chmod +x nuctl-<version>-linux-amd64
sudo ln -sf $(pwd)/nuctl-<version>-linux-amd64 /usr/local/bin/nuctl

 

 

정상적으로 동작 시 nuctl --help 명령어를 실행하면 아래와 같은 결과가 출력된다

lee@DESKTOP-UQ5OHLV:~/cvat$ nuctl --help
Nuclio command-line interface

Usage:
  nuctl [command]

Available Commands:
  beta        A beta version of nuctl as a Nuclio api cli client
  build       Build a function
  completion  Generate the autocompletion script for the specified shell
  create      Create resources
  delete      Delete resources
  deploy      Build and deploy a function, or deploy from an existing image
  export      Export functions or projects
  get         Display resource information
  help        Help about any command
  import      Import functions or projects
  invoke      Invoke a function
  parse       Parse report
  update      Update resources
  version     Display the version number of the nuctl CLI

Flags:
      --concurrency int     Max number of parallel patches. The default value is equal to the number of CPUs. (default 12)
  -h, --help                help for nuctl
  -k, --kubeconfig string   Path to a Kubernetes configuration file (admin.conf)
  -n, --namespace string    Namespace
      --platform string     Platform identifier - "kube", "local", or "auto" (default "auto")
  -v, --verbose             Verbose output

Use "nuctl [command] --help" for more information about a command.

 

 

 

 

 

다음으로 아래 명령어를 실행하면 Nuclio 플랫폼을 Docker 컨테이너로 빌드하고 배포하고 CVAT에서 해당 기능을 활성화한다. 

이미지 빌드에 시간이 좀 걸린다.. 

docker compose -f docker-compose.yml -f docker-compose.dev.yml -f components/serverless/docker-compose.serverless.yml up -d --build

 

 

 

CVAT 웹페이지를 새로고침하면 이전에 없던 Models 카테고리가 생성되었다 

 

 

배포한 모델은 nuclio 사이트 주소, localhost:8070 에서도 확인할 수 있다. 아직은 생성한 프로젝트와 배포한 모델이 없어서 default만 존재한다

 

 

 

nuctl get functions 명령어를 실행하면 배포한 모델을 확인할 수 없다. 아직은 없기 때문에 아무 것도 나오지 않는다

nuctl get functions
>> No functions found

 

 

 

---

2-2. YoloV7 배포

CVAT에서는 여러 모델들을 지원하는데 그 중 CVAT이 제공하는 샘플 모델, Yolov7을 배포하여 사용해보겠다

이미 샘플들은 nuclio로 CVAT에 맞게 다 만들어져 있으므로 명령어만 실행하여 이미지 빌드 및  배포 가능하다

해당 샘플은 COCO 데이터셋으로 학습된 기본 모델을 모델로 사용한다

 

아래는 yolov7 CVAT 샘플 소스들이다

https://github.com/cvat-ai/cvat/tree/develop/serverless/onnx/WongKinYiu/yolov7/nuclio

cvat/serverless/onnx/WongKinYiu/yolov7/nuclio at develop · cvat-ai/cvat

 

배포하기 전에 잠깐!

탐지한 바운딩 박스의 confidence 값을 필터링하는 기준값인 threshold는 main.py에서 수정할 수 있다. 

샘플에서는 0.5가 기본으로 설정되어 있다.

만약 원하는 값을 지정하여 라벨링하고 싶다면 배포 전에 수정해야한다

 

 

CVAT의 serverless 폴더에서 아래 명령어를 실행하여 모델 이미지를 빌드 및 실행한다

./deploy_cpu.sh ./onnx/WongKinYiu/yolov7/nuclio/

 

 

실행 후 아래처럼 출력되고 끝나며 배포된 모델을 확인할 수 있다

nuctl get functions 실행 시에도 동일한 출력이 나온다

 

 

 

CVAT 웹페이지를 보면 이전에 비어있던 Models에 YOLO v7 이 생겼다

 

 

nuclio 사이트에는 cvat 이라는 새로운 프로젝트를 생성하고 모델을 배포하여 running 상태임을 확인할 수 있다

 

 

 

 

---

 

 

그럼 이제 CVAT에 올린 모델로 오토 라벨링을 사용할 수 있는지 확인해보겠다

 

CVAT 페이지에서 아래를 클릭하여 새로운 프로젝트를 만든다

 

 

Person_Labeling이라는 이름의 프로젝트를 생성하려 한다

어떤 클래스를 라벨링할 것인지 직접 정할 수 있지만 모델이 가진 클래스에서 선택할 수 있다

 

 

배포되어 있는 모델을 선택하면 COCO로 학습된 모델의 80개 클래스 중 선택할 수 있다.

여기서 person을 선택 후 Submit & Open을 눌러 새로운 프로젝트를 만든다

 

 

다음은 프로젝트에서 새로운 task를 생성한다

 

 

태스크를 만들면서 라벨링할 이미지를 업로드한다.

여기서 일부 이미지 업로드를 빠뜨리면 중간에 추가 업로드가 불가하므로 새로운 태스크를 만들어야 할 수도 있다

사용한 이미지는 무료 이미지 사이트인 픽사베이에서 가져왔다

 

 

 

Image quality는 기본 70%인데 100%으로 수정하고 생성한다

 

 

이제 프로젝트에 들어가보면 아래처럼 새로운 태스크가 생성되었다. Open을 눌러 들어간다

 

태스크에 들어가면 또 Jobs 가 있는데 Job #1을 누른다

 

 

이제 이렇게 라벨링 작업 환경이 나온다!!

 

왼쪽의 마술봉 마크를 누르고 Detectors를 누르고 Model을 확인해보면 배포한 YOLO v7 모델이 있다. 

모델 설정 후 Annotate를 딱 누르면....!

 

 

아래처럼 야무지게 오토 라벨링을 해준다

 

 

뿐만 아니라 태스크 화면에서 Actions 중 Automatic annotation 기능을 통해 업로드한 전체 이미지를 배포한 모델로 한번에 라벨링하는 것도 가능하다

 

 

 

 

 

 

---

2-3. YoloV8 배포

최근 정말 많이 사용되는 YoloV8 모델을 사용하려면 가이드와 예제를 참고하여 직접 샘플을 만들어야 하는데 이미 만들어져 있는 샘플이 있어서 아래 깃헙을 이용해 배포해보겠다

 

https://github.com/kurkurzz/custom-yolov8-auto-annotation-cvat-blueprint

GitHub - kurkurzz/custom-yolov8-auto-annotation-cvat-blueprint: Integrate custom YOLOv8 model into CVAT for automatic annotation

 

 

깃허브 소스를 다운받는다

git clone https://github.com/kurkurzz/custom-yolov8-auto-annotation-cvat-blueprint.git

 

 

파일 구성은 아래와 같다. 

 

 

해당 샘플은 일부 내용을 수정해야 하므로 바로 사용할 수 없다.

 

 

threshold는 파일 중 main.py에서 수정할 수 있다

https://github.com/kurkurzz/custom-yolov8-auto-annotation-cvat-blueprint/blob/master/main.py

 

 

function.yaml 파일 내용 중 spec 부분에 사용할 모델에 맞는 클래스를 설정해야 한다

 

https://github.com/cvat-ai/cvat/blob/develop/serverless/onnx/WongKinYiu/yolov7/nuclio/function.yaml

cvat/serverless/onnx/WongKinYiu/yolov7/nuclio/function.yaml at develop · cvat-ai/cvat

 

yolov7에 있는 클래스 부분을 가져와서 붙여넣었다

COCO로 학습된 기본 모델이 아닌 커스텀 모델이라면 아래의 형식에 맞게 클래스를 작성해주면 된다

 

 

CVAT 폴더에서 아래 명령어를 실행한다. 빌드에 시간이 꽤 걸린다... 

./serverless/deploy_cpu.sh ./custom-yolov8-auto-annotation-cvat-blueprint/

 

빌드 후 배포된 것을 확인할 수 있다. 그럼 이제 CVAT에서 제대로 동작하는지 확인해보자

 

 

 

Nuclio 사이트에 추가 완료! 정상적으로 Running 중!

 

 

모델에 custom-model-yolov8 추가 완료!

 

 

라벨링 페이지에서도 추가 완료! 그럼 라벨링 결과는...?

 

 

 

 

역시 라벨링을 잘 하는 것을 볼 수 있다!! 

 

 

 

 

 

 

---

2-4. MMPose 배포

마지막은 Pose Estimation 모델을 배포하려 한다

Yolov8-Pose 모델은 샘플을 찾지 못했기 때문에 직접 샘플을 만들어야 하는데 다행히 CVAT에서는 MMPose 모델을 지원한다

이미 샘플들이 만들어져 있기 때문에 사용법도 간단하다. Yolov7과 동일하다

 

아래는 MMPose CVAT 샘플이다

https://github.com/cvat-ai/cvat/tree/develop/serverless/pytorch/mmpose/hrnet32/nuclio

cvat/serverless/pytorch/mmpose/hrnet32/nuclio at develop · cvat-ai/cvat

 

 

 

아래 명령어를 실행하여 모델 이미지 빌드 및 실행한다. 마찬가지로 시간이 좀 걸린다..

./serverless/deploy_cpu.sh ./serverless/pytorch/mmpose/hrnet32/nuclio/

 

정상적으로 빌드 완료!

 

 

---

 

이번에는 Pose Estimation이므로 이전에 만든 프로젝트에 스켈레톤 라벨을 추가해보겠다

 

Person_Labeling 프로젝트에 From model을 다시 눌러보면..

 

아래처럼 Human pose estimation이 새롭게 추가되어 있다. 

 

 

모델을 선택하면 4개 스켈레톤을 선택할 수 있다. 사람을 스켈레톤 라벨링하고 싶으므로 body를 선택하고 Done 누른다

 

라벨링 작업, Job으로 넘어가보면 이렇게 오토 라벨링 기능이 활성화된다

Annotate를 누르면...!

 

 

 

 

아래와 같은 결과물을 얻을 수 있다. 라벨링을 잘 하는 것을 확인할 수 있다

 

 

 

 

 

 

---

 

 

 

 

 

 

지금까지 CVAT을 윈도우 환경에서 설치하고 모델을 배포하여 오토 라벨링을 하는 과정을 살펴보았다

오토 라벨링으로 사람을 대상으로 Object Detection과 Pose Estimation만 해봤으나 CVAT은 SAM 모델을 배포하여 Segmentation도 하는 샘플을 지원한다

 

CVAT에서 SAM을 통해 Segmentation 라벨링하는 내용은 아래 블로그글에 잘 설명되어 있다

https://developnote-blog.tistory.com/198

[Vision] Click 한 번에 Segmentation?! - CVAT에 SAM 적용

 

 

셋팅이 다소 복잡할 수도 있는 CVAT이지만 익숙해지면 여러 사용자들이 CVAT에 접속하여 각각의 태스크를 분담하고 작업할 수 있는 좋은 툴이다. 

뿐만 아니라 모델 배포를 통한 오토 라벨링 기능까지 있으므로 컴퓨터 비전쪽에서 일하다보면 한번 쯤은 하게 되는 라벨링.. 이런 툴을 잘 활용하는 것이 큰 도움이 될 것이라 생각한다