원문 캡처 · github.com
원문 캡처 · github.com

YOLO CRAFT 저장소는 YOLO 객체 탐지를 위한 스크립트형 능동 학습 워크플로다. 어려운 프레임을 수집하고 OpenCV 인터페이스로 라벨링해 YOLO 데이터셋을 만든 뒤, 모델을 미세 조정하고 웹캠이나 스트림에서 테스트할 수 있다. 증강 미리보기, 배포 형식 내보내기, 마크다운 보고서 생성 기능도 제공한다.

저장소에는 실행 데이터가 포함되지 않는다. 소스 코드와 테스트, 문서, 로고는 추적하지만 수집한 프레임·데이터셋·체크포인트·그래프·벤치마크·내보내기 파일은 Git에서 제외되는 data/와 outputs/에 저장한다.

  • 명령줄 진입점은 python -m yolo_craft 하나다.
  • 웹캠·동영상 파일·RTSP/HTTP 스트림에서 프레임을 수집하고, 여러 클래스를 라벨링해 데이터셋을 분할할 수 있다.
  • 학습에는 기본 증강 설정과 조기 종료 설정을 사용한다. 추론 중 신뢰도·IoU·FPS를 확인하고 선택적으로 동영상을 녹화할 수 있다.
  • ONNX, TFLite, CoreML, TensorRT 형식으로 내보내며, 학습 곡선과 REPORT.md도 생성한다.

설치와 요구 사항

Python 3.10 이상과 pip가 필요하다. 프레임 수집이나 실시간 테스트를 하려면 웹캠, 동영상 파일 또는 네트워크 스트림이 필요하다. 학습 속도를 높이는 데 사용할 수 있는 CUDA 환경의 NVIDIA GPU는 선택 사항이다.

저장소를 복제하고 가상 환경을 만든다.

bash
git clone https://github.com/NovaAixYoussef/yolo-craft.git
cd yolo-craft
python -m venv .venv

가상 환경을 활성화하고 프로젝트 의존성을 설치한다.

bash
# Windows
.venv\Scripts\activate

# Linux or macOS
source .venv/bin/activate
bash
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

테스트 도구까지 설치하려면 다음 명령을 실행한다.

bash
python -m pip install -r requirements-dev.txt

편집 가능한 패키지로 설치하면 yolo-craft 명령을 사용할 수 있다.

bash
python -m pip install -e ".[dev]"
yolo-craft --help

저장소 루트에서 실행하면 패키지를 설치하지 않아도 python -m yolo_craft ... 형식으로 사용할 수 있다.

프레임 수집부터 모델 테스트까지

프레임 수집

기준 모델이 객체를 찾지 못하거나 탐지 신뢰도가 --uncertain-conf보다 낮을 때 프레임을 저장한다. 웹캠은 다음과 같이 지정한다.

bash
python -m yolo_craft capture --source 0

동영상 파일이나 RTSP 스트림도 입력으로 사용할 수 있다.

bash
python -m yolo_craft capture --source data/raw/demo.mp4
python -m yolo_craft capture --source "rtsp://user:password@192.168.1.20:554/stream"

수집 창에서 s를 누르면 현재 프레임을 직접 저장하고, a를 누르면 불확실한 프레임의 자동 수집을 켜거나 끈다. q를 누르면 창을 닫는다. 프레임은 data/raw/에 저장된다.

라벨링과 데이터셋 분할

다음 명령은 라벨링 도구를 연다. 기존 클래스 이름은 data/dataset/data.yaml에서 불러온다. 새 다중 클래스 데이터셋을 만들 때는 클래스를 지정한다.

bash
python -m yolo_craft label
python -m yolo_craft label --classes "leaf,stem"

마우스 왼쪽 버튼을 드래그해 바운딩 박스를 그리고, l을 눌러 클래스를 순환하거나 1부터 9까지 눌러 클래스를 직접 선택한다. s는 이미지와 YOLO 라벨을 저장하고, b는 빈 라벨 파일과 함께 배경 이미지로 저장한다. c는 마지막 박스를 제거하고 n은 프레임을 건너뛴다. q를 눌러 세션을 닫아도 데이터셋 분할은 진행된다.

라벨이 붙은 이미지와 라벨 파일은 data/processed/에 기록된다. 분할 결과는 data/dataset/ 아래에 만들어진다. 학습·검증 데이터 비율과 난수 시드를 바꾸려면 다음처럼 지정한다.

bash
python -m yolo_craft label --train-ratio 0.85 --seed 12

학습

기본 설정으로 학습하려면 다음 명령을 실행한다.

bash
python -m yolo_craft train

기본 체크포인트는 models/yolov8n.pt이며 학습 결과는 outputs/runs/train/에 저장된다. 에포크 수, 이미지 크기, 배치 크기, 장치를 바꿀 수 있다.

bash
python -m yolo_craft train --epochs 150 --imgsz 640 --batch 8 --device 0

기준 체크포인트가 없으면 학습 명령이 yolov8n.pt를 models/에 내려받는다. 사용자 지정 체크포인트를 쓰려면 models/에 넣고 경로를 지정한다.

bash
python -m yolo_craft train --model models/custom-base.pt

모델 테스트

웹캠에서 학습 모델을 테스트하는 기본 명령은 다음과 같다.

bash
python -m yolo_craft test --source 0

기본적으로 outputs/runs/train/weights/best.pt를 사용한다. 미세 조정 전 기준 체크포인트를 명시해 실행할 수도 있다.

bash
python -m yolo_craft test --weights models/yolov8n.pt --conf 0.25 --source 0

models/yolov8n.pt가 없으면 해당 위치에 두거나 --weights로 존재하는 체크포인트를 지정해야 한다. 학습 명령은 체크포인트가 없을 때 이를 자동으로 내려받는다.

이미지 한 장을 테스트할 때는 창에서 키를 누를 때까지 결과 창이 열린다.

bash
python -m yolo_craft test --weights models/best.pt --source path/to/image.jpg

시작 시 출력에 체크포인트의 클래스 목록이 표시된다. 모델은 학습한 클래스만 탐지한다. 작은 객체나 약한 탐지를 다룰 때는 추론 이미지 크기를 키우고 테스트 시점 증강을 켤 수 있다.

bash
python -m yolo_craft test --weights models/best.pt --source path/to/image.jpg --conf 0.1 --imgsz 1024 --augment

주석이 붙은 결과를 이미지나 동영상으로 저장하려면 --save에 출력 경로를 전달한다.

bash
python -m yolo_craft test --weights models/best.pt --source path/to/image.jpg --save outputs/annotated.jpg
python -m yolo_craft test --source input.mp4 --save outputs/annotated.mp4

능동 학습과 증강 미리보기

능동 학습 루프는 불확실한 프레임을 data/raw/에 모으고, q를 눌러 수집 창을 닫으면 라벨링 창을 연다. 라벨링이 끝나면 라벨이 붙은 원본 프레임을 제거하고 data/dataset/을 다시 만든다. 클래스 이름은 기존 data/dataset/data.yaml에서 불러오며, 새 클래스 구성을 정의할 때만 --classes를 전달한다.

bash
python -m yolo_craft active

라벨링 도구를 열지 않고 프레임만 수집하려면 다음처럼 실행한다.

bash
python -m yolo_craft active --no-label

증강 미리보기는 기본적으로 data/dataset/images/train/의 이미지를 사용한다.

bash
python -m yolo_craft augment

m은 모자이크, s는 크기 조절과 이동, c는 색상 변화, f는 가로 뒤집기, r은 무작위 모드를 선택한다. space로 일시 정지하고, n으로 다음 이미지로 넘어가며, q로 종료한다. 다른 이미지와 라벨 폴더를 지정할 수도 있다.

bash
python -m yolo_craft augment --images data/processed --labels data/processed

미리보기에는 YOLO 방식의 레터박스, 모자이크, 크기 조절, 색상 변화, 뒤집기가 포함된다.

벤치마크와 보고서

벤치마크 명령은 학습 실행 결과를 그래프로 그리고 두 체크포인트를 비교한다.

bash
python -m yolo_craft benchmark --image path/to/test.jpg

--image를 생략하면 data/dataset/images/val/의 첫 검증 이미지를 사용하고, 검증 이미지가 없으면 첫 학습 이미지를 사용한다. 결과는 outputs/benchmarks/에 before.png, after.png, before_after.png, metrics.json으로 저장되며, curves/ 아래에는 sample_curves.png, summary.csv, 실행별 곡선 파일이 만들어진다.

비교할 체크포인트와 신뢰도·IoU 값을 직접 지정할 수 있다.

bash
python -m yolo_craft benchmark \
 --image path/to/test.jpg \
 --baseline models/yolov8n.pt \
 --finetuned outputs/runs/train/weights/best.pt \
 --conf 0.25 \
 --iou 0.7

학습 실행이 없는 경우 예시용 곡선을 작성하려면 --sample-curves를 사용한다.

bash
python -m yolo_craft benchmark --image path/to/test.jpg --sample-curves

보고서 명령은 outputs/runs/train/results.csv를 읽어 outputs/reports/training_curves.png에 곡선을 저장하고 REPORT.md를 갱신한다.

bash
python -m yolo_craft report

학습 실행이 없는 경우 --sample을 지정해 명시적으로 예시용 보고서를 생성할 수 있다.

bash
python -m yolo_craft report --sample

CSV, 실행 디렉터리, 그래프, 보고서 경로를 사용자 지정할 수도 있다.

bash
python -m yolo_craft report \
 --csv outputs/runs/experiment/results.csv \
 --run-dir outputs/runs/experiment \
 --curves outputs/reports/experiment_curves.png \
 --report outputs/reports/experiment.md

보고서에는 최고·최종 mAP, 최종 박스·클래스 손실, 데이터셋의 이미지·박스 수, 클래스별 인스턴스 수, args.yaml의 학습 설정이 포함된다. outputs/benchmarks/metrics.json이 있으면 전후 벤치마크 값도 포함하며, 재현 명령과 다음 단계도 기록한다.

배포 형식 내보내기와 데이터 보관

지원되는 모든 형식을 내보내려면 다음과 같이 실행한다.

bash
python -m yolo_craft export --format all

형식을 하나씩 지정할 수도 있다.

bash
python -m yolo_craft export --format onnx --imgsz 640 --simplify
python -m yolo_craft export --format tflite
python -m yolo_craft export --format coreml
python -m yolo_craft export --format engine --device 0

내보낸 파일은 outputs/exports/에 복사된다. ONNX는 데스크톱·서버·브라우저를 대상으로 하며 Ultralytics가 가져오는 ONNX 의존성이 필요하다. TFLite는 Android·엣지 기기용으로 TensorFlow와 플랫폼별 설정이 필요하다. CoreML은 iOS·macOS용이며 CoreML 도구와 macOS가 필요하다. TensorRT 엔진은 NVIDIA GPU용으로 TensorRT와 맞는 CUDA 환경이 필요하다. 형식별 선택 의존성은 서로 다르다. 한 형식의 내보내기에 실패해도 다른 형식은 계속 진행하며, 명령은 실패한 형식을 보고한다.

데이터셋은 기본적으로 outputs/dataset.zip에 압축한다. 원본과 출력 경로를 바꿀 수 있다.

bash
python -m yolo_craft archive
python -m yolo_craft archive --source data/dataset --output outputs/dataset.zip

데이터 형식과 프로젝트 구성

YOLO 라벨 파일은 한 줄에 박스 하나를 기록한다. 좌표는 모두 [0, 1] 범위로 정규화한다. 라벨 도구가 이 형식으로 파일을 작성한다. 모든 이미지에는 대응하는 .txt 파일이 있어야 하며, 배경 이미지는 내용이 빈 라벨 파일을 사용한다.

text
class_id center_x center_y width height

생성되는 data/dataset/data.yaml의 구조는 다음과 같다.

yaml
path: /absolute/path/to/data/dataset
train: images/train
val: images/val
names:
 0: leaf
 1: stem

저장소에는 .github/workflows/ci.yml, assets/logo.jpg, tests/, yolo_craft/의 모듈과 LICENSE, README.md, REPORT.md, pyproject.toml, requirements.txt, requirements-dev.txt가 있다. yolo_craft/에는 수집, 라벨링, 학습, 추론, 증강, 벤치마킹, 내보내기, 보고서, 보관, CLI 관련 모듈이 포함된다.

data/에는 원본 프레임, 처리된 이미지와 라벨, 생성된 YOLO 데이터셋을 둔다. models/에는 기준 및 미세 조정 체크포인트를 둔다. outputs/는 학습 실행, 내보낸 파일, 벤치마크, 보고서를 보관한다. 이 세 디렉터리에는 .gitkeep 파일만 추적하며 생성된 내용은 Git에서 제외한다. 가중치는 models/ 또는 outputs/runs/.../weights/에 두고, 학습 프로젝트는 outputs/runs/, 내보내기 결과는 outputs/exports/, 벤치마크는 outputs/benchmarks/, 그래프와 보고서는 outputs/reports/에 저장한다.

테스트와 문제 해결

전체 테스트와 구문 검사는 각각 다음 명령으로 실행한다.

bash
python -m pytest
python -m compileall -q yolo_craft tests

테스트 스위트는 소스 파싱, 수집 파일 이름, 라벨 분할, 데이터셋 YAML 생성, 증강 기하, CSV 파싱, 보고서 생성, 압축 보관, CLI 연결, 내보낸 파일 복사를 다룬다. GitHub Actions CI도 제공한다. Python 소스와 CLI 출력, 문서는 영어로 작성하며 Python 파일에는 주석이나 독스트링이 없다.

웹캠이 열리지 않으면 다른 인덱스를 시도한다.

bash
python -m yolo_craft test --source 1

CUDA를 사용할 수 없으면 CPU를 명시한다.

bash
python -m yolo_craft train --device cpu

학습에서 데이터셋을 찾지 못하면 data/dataset/data.yaml이 있고 경로가 올바른지 확인한 뒤 라벨 명령을 다시 실행한다.

bash
python -m yolo_craft label

벤치마크에 검증 이미지가 없으면 이미지 경로를 직접 전달한다.

bash
python -m yolo_craft benchmark --image path/to/test.jpg

프로젝트는 GNU Affero General Public License v3.0에 따라 배포된다. 자세한 내용은 저장소의 LICENSE 파일에 있다.