gpt-edit/TOOL_USAGE_GUIDE.md

# 📋 GPT-Edit 도구 사용 가이드

gpt-edit 프로젝트는 OpenAI의 GPT-Image-1 모델을 사용한 AI 이미지 편집 도구 **총 5개**를 제공합니다.

## 🎯 도구 우선순위 및 사용 권장사항

### ⭐⭐⭐ **최우선 도구** (일반 사용자 추천)

#### 1. `gpt_edit_image`
**가장 간단하고 직관적인 이미지 편집**
- **사용법**: 이미지 파일을 `input_images/` 폴더에 업로드 → 파일명과 편집 지시사항 입력
- **특징**: 자동 최적화, 크기 관리, 완전 자동화
- **권장 대상**: 모든 사용자 (초보자부터 전문가까지)

```json
{
  "input_image_name": "my_photo.jpg",
  "prompt": "make the sky more dramatic with sunset colors",
  "background": "transparent"
}
```

#### 2. `gpt_edit_image_with_mask`
**정밀한 선택적 영역 편집**
- **사용법**: 이미지 + 마스크 파일을 `input_images/`에 업로드 → 편집 지시
- **특징**: 마스크의 흰색 영역만 편집, 정교한 제어 가능
- **권장 대상**: 정밀한 편집이 필요한 사용자

```json
{
  "input_image_name": "portrait.jpg",
  "mask_image_name": "background_mask.png", 
  "prompt": "change background to mountain landscape"
}
```

### ⭐⭐ **중요 유틸리티 도구**

#### 3. `validate_image`
**이미지 파일 검증 및 정보 확인**
- **용도**: 편집 전 이미지 상태 확인, 최적 크기 제안
- **권장 시점**: 편집 전 사전 검사

#### 4. `create_mask_from_alpha`
**PNG 투명도로 마스크 생성**
- **용도**: PNG 이미지의 알파 채널을 마스크로 변환
- **권장 시점**: 투명 배경 이미지를 마스크로 활용할 때

### ⭐ **고급/자동화 도구** (특수 목적)

#### 5. `gpt_batch_edit`
**대량 이미지 일괄 편집 (Claude Code 전용 권장)**

## 🚀 `gpt_batch_edit` 상세 사용 가이드

### ✅ **이런 경우에 사용하세요:**

#### 📸 **전자상거래 대량 처리**
```python
# Claude Code에서 사용 예시
batch_config = {
    "edits": [
        {
            "input_image_name": "product_001.jpg",
            "prompt": "remove background, make it pure white",
            "background": "opaque"
        },
        {
            "input_image_name": "product_002.jpg", 
            "prompt": "remove background, make it pure white",
            "background": "opaque"
        }
        # ... 최대 16개까지
    ]
}
```

#### 🎨 **소셜미디어 템플릿 자동 생성**
```python
# 같은 편집을 여러 이미지에 적용
social_templates = [
    {"file": "template_mon.jpg", "text": "Monday Motivation"},
    {"file": "template_tue.jpg", "text": "Tuesday Tips"},
    {"file": "template_wed.jpg", "text": "Wednesday Wisdom"}
]

batch_edits = [
    {
        "input_image_name": template["file"],
        "prompt": f"add bold text '{template['text']}' at center top"
    }
    for template in social_templates
]
```

#### 🏭 **마케팅 자료 대량 생성**
- 브랜드 로고 일괄 추가
- 워터마크 적용
- 크기/비율 표준화

### ❌ **이런 경우에는 개별 도구를 사용하세요:**

#### 🎭 **Claude Desktop 대화형 편집**
- 각 이미지마다 다른 편집이 필요한 경우
- 실험적이거나 창작적인 편집
- 단일 이미지 정밀 작업

#### 🔬 **정밀하거나 실험적 편집**
- 여러 번 시행착오가 필요한 작업
- 결과를 보고 다음 편집 방향을 정해야 하는 경우

### 🚧 **gpt_batch_edit 제약사항**

1. **최대 16개 제한**: 한 번에 최대 16개 이미지만 처리 가능
2. **순차 처리**: 병렬 처리 없음, 총 시간 = 개별 시간 × 이미지 수
3. **파일 사전 준비**: 모든 이미지를 `input_images/` 폴더에 미리 업로드 필요
4. **실패 시 영향**: 중간에 실패하면 전체 배치에 영향

### 💡 **Claude Code 활용 패턴**

#### 파일 준비 자동화
```python
import os
import shutil

# 원본 폴더에서 input_images로 자동 복사
def prepare_batch_files(source_dir, target_dir="input_images"):
    os.makedirs(target_dir, exist_ok=True)
    
    image_files = []
    for filename in os.listdir(source_dir):
        if filename.lower().endswith(('.jpg', '.jpeg', '.png', '.webp')):
            shutil.copy2(
                os.path.join(source_dir, filename),
                os.path.join(target_dir, filename)
            )
            image_files.append(filename)
    
    return image_files
```

#### 대량 처리 분할
```python
def create_batch_chunks(file_list, prompt, chunk_size=16):
    \"\"\"파일 리스트를 16개씩 나누어 배치 생성\"\"\"
    batches = []
    
    for i in range(0, len(file_list), chunk_size):
        chunk = file_list[i:i+chunk_size]
        batch = {
            "edits": [
                {
                    "input_image_name": filename,
                    "prompt": prompt,
                    "background": "transparent"
                }
                for filename in chunk
            ]
        }
        batches.append(batch)
    
    return batches
```

## 📊 **도구 선택 플로우차트**

```
이미지 편집이 필요한가요?
    ↓
단일 이미지인가요? → YES → 마스크가 필요한가요?
    ↓                        ↓ YES → gpt_edit_image_with_mask
    NO                       ↓ NO  → gpt_edit_image
    ↓
여러 이미지 (2개 이상)인가요?
    ↓ YES
Claude Code를 사용하나요? & 같은 편집인가요?
    ↓ YES → gpt_batch_edit
    ↓ NO  → gpt_edit_image (개별적으로 여러 번 사용)
```

## 🎯 **최적 사용 전략**

### 🥇 **초보자 권장**
1. `gpt_edit_image` 위주 사용
2. 필요시 `validate_image`로 사전 검사

### 🥈 **중급자 권장** 
1. `gpt_edit_image` + `gpt_edit_image_with_mask` 조합
2. `create_mask_from_alpha`로 마스크 생성 활용

### 🥉 **고급 사용자 (Claude Code)**
1. 모든 도구 활용
2. `gpt_batch_edit`로 자동화 워크플로우 구성
3. 스크립트 기반 대량 처리

## 💾 **파일 저장 규칙**

모든 편집 결과는 다음 형식으로 저장됩니다:
```
generated_images/
├── gptimage1_123456_20250826_143022_000.png  # 입력 파일 (추적용)
├── gptimage1_123456_20250826_143022_001.png  # 편집 결과
└── gptimage1_123456_20250826_143022_001.json # 편집 파라미터
```

**Base Name 형식**: `gptimage1_{6자리시드}_{날짜}_{시간}`
- 시드는 세션별로 동일하게 유지
- 모든 관련 파일이 같은 base name 사용
- JSON 파일에 편집 과정 전체가 기록됨

---

이 가이드를 통해 상황에 맞는 최적의 도구를 선택하여 효율적인 AI 이미지 편집을 경험해보세요! 🎨✨