model-yolo-person-classify/README.md

Person Attribute Recognition

COCO80 기반 YOLO26m 객체 탐지 결과를 받아, 탐지된 Person 영역의 상세 속성을 분석하는 ClearML Agent입니다.

개요

1. YOLO26m이 COCO80 클래스로 이미지를 분석하고 Person의 바운딩 박스(xywh)를 전달합니다.
2. 해당 영역을 크롭한 뒤 보행자 속성 인식 모델로 상세 속성을 추론합니다.
3. 결과를 ClearML 아티팩트로 업로드합니다.

프로젝트 구조

파일	역할
main.py	ClearML Task 초기화 및 아티팩트 업로드 (Agent 진입점)
start.py	이미지 로드, 크롭, 모델 추론 로직
inference.py	단일 이미지 로컬 추론 스크립트
train.py / test.py	모델 학습 및 평가

입력

인자	필수	형식	설명
--image_url	O	URL 또는 파일 경로	분석 대상 이미지
--xywh	O	x,y,w,h (정수, 쉼표 구분)	YOLO26m이 탐지한 Person 바운딩 박스

출력

대상	내용
콘솔	속성명·값 목록 (예: gender: female, age: teenager)
ClearML	final_result 아티팩트 — {"output": {...}, "status": "PASS"}

output은 속성명을 키, 속성값을 값으로 하는 딕셔너리입니다.

{
  "output": {
    "gender": "female",
    "age": "teenager"
  },
  "status": "PASS"
}

실행

ClearML Agent (권장)

uv run python main.py \
  --image_url "https://example.com/image.jpg" \
  --xywh "404,290,74,193"

로컬 테스트 (ClearML 없이)

uv run python start.py \
  --image_url "https://example.com/image.jpg" \
  --xywh "404,290,74,193"

요구 사항

• Python 3.11+
• PyTorch, torchvision, ClearML, requests
• 사전 학습 체크포인트: checkpoints/market/resnet50_nfc/net_last.pth
• 속성 라벨 정의: doc/label.json, doc/attribute.json

설치

uv sync

또는

pip install -r requirements.txt

ClearML

항목	값
Project	Person_Attribute_Recognition
Task	model-yolo-person-classify
Artifact	final_result

모델

단계	모델	비고
탐지	YOLO26m (COCO80)	상위 파이프라인에서 수행
속성 인식	ResNet50 + NFC	Market-1501 Attribute (기본값)

start.py의 run() 함수에서 dataset, backbone, use_id 파라미터로 모델 설정을 변경할 수 있습니다.