README.md

---
title: ROEM-AI
emoji: 📸
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
short_description: AI fashion model cut generator
---

# AI ModelCut Studio

## Hugging Face Dataset Save

Generated images are saved to a Hugging Face Dataset when these Space secrets are set:

```text
HF_DATASET_REPO=sunyoung00/ROEM_TEST
HF_TOKEN=hf_...
```

`HF_TOKEN` must have write permission for the dataset repo. If `HF_DATASET_REPO` is not set, the app defaults to `sunyoung00/ROEM_TEST`. Upload failures are logged but do not block image generation.

Saved files are uploaded under:

```text
generated/YYYYMMDDTHHMMSSZ_requestid/
  01_label.png
  metadata.json
```

제품 이미지, AI 모델 얼굴, 체형 레퍼런스, 제품 기장, 샷별 포즈 레퍼런스를 조합해 쇼핑몰용 AI 모델컷을 생성하는 Hugging Face Spaces용 앱 구조입니다. (얼굴/체형/포즈 레퍼런스 배치는 `assets/README.md` 참고)

## Hugging Face Spaces 실행 구조

이 저장소는 Docker Space로 바로 실행할 수 있습니다.

필수 파일:

- `Dockerfile`: Hugging Face Spaces Docker SDK가 빌드하는 컨테이너 정의
- `app.py`: FastAPI 기반 웹 서버와 생성 API
- `requirements.txt`: Python 런타임 의존성
- `index.html`, `styles.css`, `script.js`: 별도 프론트엔드 시안

Hugging Face에서 새 Space를 만들 때 SDK는 `Docker`로 선택하면 됩니다.

```text
Space SDK: Docker
Port: 7860
Start command: Dockerfile CMD 사용
```

현재 `app.py`는 OpenAI/Gemini 이미지 생성 API를 우선 호출합니다. API 키가 없거나 `DEMO_FALLBACK=true`로 설정한 경우에는 업로드한 제품 이미지를 합성하는 데모 worker를 사용할 수 있습니다.

## 실제 이미지 생성 API

현재 앱은 Docker 컨테이너에서 OpenAI 또는 Gemini 이미지 생성 API를 호출할 수 있습니다.

환경변수:

```text
OPENAI_API_KEY=...
GEMINI_API_KEY=...
OPENAI_IMAGE_MODEL=gpt-image-2
GEMINI_IMAGE_MODEL=gemini-3.1-flash-image-preview
DEMO_FALLBACK=false

# 데이터셋 저장
HF_DATASET_REPO=sunyoung00/ROEM_TEST
HF_TOKEN=hf_...

# 생성 동작 튜닝 (선택)
GEN_MAX_WORKERS=4            # 일괄 샷 / Gemini 후보 동시 생성 수
API_INPUT_MAX_SIDE=2048      # 레퍼런스 이미지 전송 시 긴 변 상한
MATCH_REFERENCE_FRAMING=true # 샷 레퍼런스 프레이밍에 맞춰 자동 크롭
SUBJECT_BG_TOLERANCE=32      # 배경 대비 피사체 검출 민감도(크롭용)
IDEALIZE_PROPORTIONS=false   # 체형 레퍼런스 없을 때 8.2~8.5등신 강제 여부
FRAMING_TOP_MARGIN=          # (선택) 수동 크롭 상단 여백 비율, 예: 0.10
FRAMING_BOTTOM_MARGIN=       # (선택) 수동 크롭 하단 여백 비율, 예: 0.08
```

화면의 `이미지 생성 모델`에서 아래 provider를 선택합니다.

- `openai:gpt-image-2`
- `openai:gpt-image-1.5`
- `openai:gpt-image-1`
- `gemini:gemini-3.1-flash-image-preview`
- `gemini:gemini-3-pro-image-preview`
- `gemini:gemini-2.5-flash-image`

`1K`는 1024px급 세로 결과, `2K`는 2048px급 세로 결과를 요청합니다. GPT Image 2와 Gemini 3.1/3 Pro 이미지 모델처럼 2K 요청을 지원하는 모델은 API 요청 단계에서 2K를 지정하고, 반환 이미지 크기가 다르면 최종 캔버스에 맞춰 정규화합니다.

API 키가 없거나 모델명이 해당 계정에서 지원되지 않으면 화면에 오류가 표시됩니다. `DEMO_FALLBACK=true`를 설정한 경우에만 기존 데모 렌더러로 대체됩니다.

## 모델 얼굴 프리셋

첨부한 모델 얼굴 이미지는 아래 경로에 저장해서 함께 업로드하면 기본 프리셋으로 사용됩니다.

```text
assets/model_face_preset.png
```

앱에서는 `모델 얼굴 소스` 기본값이 `첨부 얼굴 프리셋`으로 설정되어 있습니다. 별도 얼굴 이미지를 테스트하고 싶을 때만 `업로드 얼굴`을 선택하면 됩니다.

화면의 `페르소나 얼굴 업로드`에 얼굴 이미지를 올리면 해당 파일이 `/api/generate`의 `model_face`로 전달됩니다. 실제 API 생성에서는 이 얼굴 레퍼런스를 첫 번째 참조 이미지로 넣고, 후보 3장과 후속 샷 모두 동일 인물로 유지하도록 프롬프트에 identity lock 지시를 포함합니다.

## 화면 구성

- 로그인 / 프로젝트 저장
- QR 또는 로컬 제품 이미지 업로드: 제품 1~4 각각 앞면, 뒷면 옵션
- 카테고리, 핏, 제품 기장, 스타일 선택
- 프롬프트 입력
- 카테고리(상의/하의 등)에 따라 달라지는 샷 버튼 선택
- 전신(앞면) 후보 3장 우선 생성
- 선택한 후보 컷 기준 샷 구도 변경 생성 (각 샷은 assets/poses의 명명 레퍼런스를 따라감)
- 1K / 2K 해상도 선택
- 선택 컷 재생성
- AI 표기 삽입
- 일괄 다운로드
- 생성 시간 안내

## 권장 생성 파이프라인

1. 입력 검증
   - 제품 원본 해상도, 배경 투명도, 블러, 로고 영역, 메타데이터 확인
   - 긴 변 기준 최소 1500px 이상 권장

2. 제품 전처리
   - 제품 1~4의 앞면/뒷면 레퍼런스 제품 영역 세그멘테이션
   - 실루엣, 로고, 패턴, 버튼, 소재 텍스처 보존용 마스크 생성
   - 카테고리와 기장 값을 프롬프트 조건으로 변환

3. 모델 조건 생성
   - 선택한 AI 모델 얼굴 임베딩 또는 레퍼런스 이미지 연결
   - 포즈 레퍼런스에서 OpenPose / DensePose / depth 조건 추출
   - 전신 3컷을 먼저 생성하고 이후 스타일 변형 컷 생성

4. 1차 이미지 생성
   - 전신(정면) 후보 3장을 먼저 생성
   - 사용자가 선택한 기준 컷의 얼굴/의상 정보를 후속 샷 생성의 기준으로 사용
   - 제품 마스크를 강하게 고정
   - 얼굴, 손, 다리, 옷 경계부를 별도 검수 대상으로 저장
   - 컷별 seed, prompt, negative prompt, model version 기록

5. 샷 구도 확장
   - 선택 기준 컷에서 얼굴, 의상, 색상, 소재, 로고를 유지
   - 각 샷은 `assets/poses/`의 동일 이름 레퍼런스(예: `전신_앞면_.*`)에서 포즈·각도·크롭만 가져옴
   - 카테고리에 따라 노출 샷이 달라짐
     - 상의(원피스·아우터 포함): 전신(앞면), 전신(측면), 전신(후면), 상반신(앞면), 상반신(측면), 상반신(후면), 상반신(클로즈업), 디테일(후면)
     - 하의(스커트 포함): 전신(앞면), 전신(측면), 전신(후면), 상반신(앞면), 상반신(측면), 하반신, 하반신(클로즈업)
   - 전신·상반신(앞/측/후)·하반신은 레퍼런스 프레이밍에 맞춰 자동 크롭, 클로즈업·디테일은 크롭 생략

6. 품질 검수
   - 제품 형태 변형률
   - 로고 왜곡
   - 손가락, 얼굴, 다리 비율
   - 배경 누끼 품질
   - AI 표기 누락 여부

7. 고해상도 후처리
   - 1K 생성 후 2K 업스케일
   - 얼굴/제품 디테일 영역 선택 샤픈
   - 색상 편차 보정
   - JPG/PNG/WebP 및 ZIP 일괄 다운로드

## 추천 백엔드 구조

```text
client
  upload panel
  option builder
  result gallery

api
  POST /projects
  POST /assets/product
  POST /assets/model-face
  POST /jobs/generate
  POST /jobs/:id/regenerate
  GET  /jobs/:id
  GET  /projects/:id/results.zip

worker
  preprocess product
  extract pose
  generate first-pass images
  run quality checks
  upscale and sharpen
  export final assets

storage
  original assets
  masks
  intermediate renders
  final images
  job metadata
```

## 로컬 실행

Docker 앱:

```bash
docker build -t modelcut-studio .
docker run --rm -p 7860:7860 -e OPENAI_API_KEY=... -e GEMINI_API_KEY=... modelcut-studio
```

Python 직접 실행:

```bash
pip install -r requirements.txt
python app.py
```

정적 UI 시안:

`index.html`을 브라우저로 열면 바로 확인할 수 있습니다.