custom_nodes/dolphin_nodes/dataset_builder/README.md

# Wan 2.2 LoRA Dataset Builder

임의의 이미지/영상 폴더를 넣으면 피사체 중심으로 크롭하고 로컬 VLM으로 캡션을 달아,
LoRA 학습 스크립트(musubi-tuner 등)에 바로 넣을 수 있는 `images/`, `videos/`,
`.txt` 캡션, `dataset.toml` 초안을 생성하는 독립 CLI 도구.

ComfyUI 노드가 아님 — `__init__.py`에서 import하지 않으므로 ComfyUI 노드 로딩에
관여하지 않고, `python_embeded\python.exe`로 직접 실행한다.

**사용 전제: 학습 대상 인물/캐릭터가 명백히 성인이어야 함.** 나이가 불명확하거나
앳돼 보이는 인물의 성적 콘텐츠 데이터셋 구축에는 이 도구를 쓰지 말 것.

## 사용법

```
D:\SD\ComfyUI_windows_portable\python_embeded\python.exe ^
  dataset_builder\build.py ^
  --input "D:\raw_media" ^
  --output "D:\wan_lora_dataset" ^
  --trigger "ohwx man" ^
  --captioner joycaption
```

`--input` 폴더를 재귀적으로 스캔해 이미지(jpg/png/webp/bmp)와 영상(mp4/mov/mkv/avi/webm)을
자동 분류하여 처리한다.

## 파이프라인

1. **피사체 감지**: mediapipe 얼굴 검출 → (실패 시) OpenCV Haar cascade 얼굴 검출 →
   (그래도 실패 시) ultralytics YOLOv8n 사람 검출 → (그래도 없으면) 전체 프레임
   그대로 사용. 사람이 아닌 사물/장면 LoRA는 자연스럽게 "전체 프레임" 경로로 빠진다.
2. **버킷 매칭 + 크롭**: 감지된 bbox를 얼굴 2.2배 / 사람 1.3배로 패딩한 뒤, Wan
   480p/720p/1080p × (가로/세로/정사각) 버킷 중 종횡비가 가장 가까운 것을 골라
   그 해상도로 크롭+리사이즈(16 배수 정렬). 원본 해상도보다 커지는(업스케일) 버킷은
   자동으로 건너뛴다 — `--max-tier`로 상한만 지정.
3. **영상 씬 분할**: OpenCV 히스토그램 차분으로 컷 지점을 찾고, `--clip-min-sec`
   ~ `--clip-max-sec` 범위로 클립을 나눈다. 클립마다 대표 프레임 몇 장의 bbox
   중앙값으로 크롭을 고정하고(프레임 흔들림 방지), `--video-fps`로 리샘플, 4n+1
   프레임 수로 트리밍, optical flow 평균 크기로 "static/subtle/moderate/fast
   motion" 태그를 캡션에 덧붙인다.
4. **캡셔닝** (`--captioner`):
   - `joycaption` (기본) — `fancyfeast/llama-joycaption-beta-one-hf-llava`.
     **주의**: HuggingFace 모델 카드에 "학습용 캡션" 전용 프롬프트 문자열이 공식
     문서화되어 있지 않아, 여기 쓰인 지시문(`caption.py`의 `DEFAULT_PROMPT`)은
     자체 작성한 기본값이다. 원하는 스타일이 있으면 `--caption-prompt`로 바꿔라.
   - `florence2` — `microsoft/Florence-2-large`, 가볍고 빠름(~0.77B).
   - `wd14` — `SmilingWolf/wd-vit-tagger-v3` (onnx), booru 태그 스타일.
   - 공통: `--trigger`로 넘긴 트리거 워드를 캡션 맨 앞에 자동 삽입.

## 출력

```
output_dir/
  images/0001.jpg, 0001.txt, ...
  videos/0001.mp4, 0001.txt, ...
  dataset.toml   # musubi-tuner 스타일 초안 — 실제 트레이너 버전 문서와 대조 후 사용
```

## 모델 다운로드 / VRAM 참고

- 최초 실행 시 HuggingFace에서 캡셔너 가중치(JoyCaption ~16GB, Florence-2-large
  ~1.5GB, WD14 ~수백MB)와 ultralytics `yolov8n.pt`(~6MB)를 자동 다운로드한다.
  네트워크/디스크 용량 확인 후 실행할 것.
- RTX 5090 32GB 기준, ComfyUI가 이미 VRAM을 점유 중이면 JoyCaption(8B, bf16 기준
  ~16GB)이 부족할 수 있다. 이 경우 `--load-in-4bit`(bitsandbytes)로 줄이거나,
  ComfyUI 서버를 잠시 내려두고 실행할 것.

## 알려진 환경 특이사항

- 이 embedded Python 환경은 `import torch`만 해도 인터프리터 종료 시 비정상
  종료 코드(예: `-1073740791`)를 낸다. `dataset_builder`와 무관한 기존 환경
  이슈이며, 실제 작업(파일 저장)은 그 전에 이미 끝난 뒤 발생하는 종료 시점
  크래시라 결과물에는 영향 없음. 배치 스크립트에서 종료 코드로 성공/실패를
  판단하지 말고 콘솔 로그의 `Done.` 줄로 확인할 것.

## 검증된 것 / 안 된 것

- `crop_resize.py`(버킷 매칭 수학), `detect.py`(다단계 폴백), `scene_split.py`
  (씬 컷 + 클립 추출 + 4n+1 트리밍 + 모션 태그)는 실제 샘플 이미지/영상으로
  스모크 테스트 완료.
- `caption.py`(JoyCaption/Florence-2/WD14 실제 추론 호출)는 모델 가중치 다운로드가
  커서 이번 세션에서 end-to-end로 돌려보지 않았다. 클래스/전처리는 각 모델의
  공식 문서(HF 모델 카드, wd-tagger Space 소스)를 대조해 작성했지만, 처음
  실행할 때 캡셔너 쪽 에러가 나면 그 부분부터 확인할 것.