# MIGAN 인페인팅 모듈 설정 안내

## 개요
MIGAN ONNX 파이프라인을 사용한 전체 이미지 인페인팅 모듈이 추가되었습니다. 기존 ROI 기반 인페인팅과 함께 사용할 수 있으며, `toggle_states`를 통해 선택할 수 있습니다.

## 모델 파일 설정

### 1. 모델 디렉토리 생성
```bash
mkdir -p worker/models
```

### 2. MIGAN 모델 파일 배치
`migan_pipeline_v2.onnx` 파일을 다음 경로에 배치하세요:
```
worker/models/migan_pipeline_v2.onnx
```

### 3. TensorRT 캐시 디렉토리 (선택사항)
TensorRT 엔진 캐시를 위한 디렉토리:
```bash
mkdir -p /app/temp_files/trt_cache
```

## 사용 방법

### 인페인팅 방법 선택
`toggle_states`에서 `inpaint_method` 키를 통해 인페인팅 방법을 선택할 수 있습니다:

```python
# ROI 기반 인페인팅 (기본값)
toggle_states = {
    "inpaint_method": "roi"
}

# MIGAN 전체 이미지 인페인팅
toggle_states = {
    "inpaint_method": "migan"
}
```

### MIGAN 설정 옵션

#### 기본 설정
```python
toggle_states = {
    "inpaint_method": "migan",
    "migan_onnx_path": "/app/worker/models/migan_pipeline_v2.onnx",
    "migan_use_cuda": True,
    "migan_use_tensorrt": True,
    "migan_trt_fp16_enable": True,
    "migan_trt_engine_cache_enable": True,
    "migan_max_image_size": 1600,
    "migan_output_max_width": 800,
    "migan_enable_output_resize": True
}
```

#### 설정 옵션 설명

**ONNX 모델 설정:**
- `migan_onnx_path`: ONNX 모델 파일 경로
- `migan_use_cuda`: CUDA 사용 여부 (기본: True)
- `migan_intra_threads`: ONNX Runtime 스레드 수 (기본: 0 = 자동)
- `migan_inter_threads`: ONNX Runtime 스레드 수 (기본: 0 = 자동)

**TensorRT 최적화:**
- `migan_use_tensorrt`: TensorRT 사용 여부 (기본: True)
- `migan_trt_fp16_enable`: FP16 최적화 활성화 (기본: True)
- `migan_trt_engine_cache_enable`: 엔진 캐시 활성화 (기본: True)

**이미지 처리:**
- `migan_max_image_size`: 최대 이미지 크기 제한 (긴 변 기준, 기본: 1600px)
- `migan_output_max_width`: 출력 최대 가로 크기 (기본: 800px)
- `migan_enable_output_resize`: 출력 크기 조정 활성화 (기본: True)

#### 직접 모듈 사용 (개발/테스트용)
```python
from worker.migan_inpainting_module import MIGANInpaintingModule

# ⚠️ 프로덕션에서는 celery_worker의 전역 인스턴스 사용 권장
inpainter = MIGANInpaintingModule(config={
    'use_cuda': True,
    'max_image_size': 1600
})

# 인페인팅 실행
result = inpainter.inpaint_with_migan(image, mask)
# cleanup_memory() 호출하지 말 것 - 전역 인스턴스는 계속 유지
```

#### 전역 인스턴스 사용 (권장)
```python
# celery_worker.py에서 자동으로 처리됨
# toggle_states만 설정하면 됨

toggle_states = {
    "inpaint_method": "migan",
    "migan_use_tensorrt": True,
    "migan_trt_fp16_enable": True,
    "migan_max_image_size": 2048
}

# worker가 자동으로 전역 인스턴스를 사용하고 설정을 동적 업데이트
```

## 주요 특징





































































































### MIGAN vs ROI 인페인팅 비교

| 항목 | MIGAN | ROI |
|------|-------|-----|
| 처리 방식 | 전체 이미지 | 영역별 분할 |
| 전처리 | 모델 내장 | 외부 처리 |
| ROI 분석 | 불필요 | 필수 |
| 메모리 사용 | 고정적 | 적응적 |
| 속도 | 일정 | 영역 수에 따라 변동 |
| 품질 | 일관적 | 영역별 최적화 |

### MIGAN 모듈 장점
1. **내장 전처리**: 리사이즈, 정규화 등이 ONNX 모델에 포함
2. **TensorRT 최적화**: FP16, 엔진 캐시를 통한 성능 향상
3. **세션 재사용**: 메모리 효율성 및 초기화 시간 단축
4. **자동 폴백**: MIGAN 실패 시 ROI 방식으로 자동 전환
5. **크기 제한**: 메모리 사용량 제어를 위한 이미지 크기 제한
6. **🔥 전역 인스턴스**: 모델은 한 번만 로딩되어 메모리에 상주
7. **🔥 동적 설정**: 실행 중 설정 변경 가능 (필요시 세션 재생성)

## 환경 변수

```bash
# TensorRT 엔진 캐시 디렉토리 (선택사항)
export TRT_ENGINE_CACHE_DIR="/app/temp_files/trt_cache"

# 디버그 아티팩트 저장 디렉토리
export DEBUG_DUMP_DIR="/app/temp_files/debug"
```

## 로그 분석

### 정상 처리 로그 예시
```
[MIGAN] ONNX Runtime 세션 생성 완료: ['TensorrtExecutionProvider', 'CUDAExecutionProvider', 'CPUExecutionProvider']
[INPAINT] MIGAN 처리 통계: 마스크 커버리지 15.3%, 최대 크기 제한: 1600px
이미지 스케일링: 2000x1500 → 1600x1200 (factor=0.800)
MIGAN 인페인팅 완료: 총 1.234s (추론: 0.987s)
```

### 에러 및 폴백 로그 예시
```
[MIGAN] ONNX 파일을 찾을 수 없습니다: /app/worker/models/migan_pipeline_v2.onnx
[INPAINT] MIGAN 인페인팅 실패, ROI로 폴백: FileNotFoundError
```

## 메모리 관리 및 성능

### 전역 인스턴스 방식
- **모델 로딩**: 워커 프로세스 시작 시 한 번만 로딩
- **메모리 상주**: 모델이 메모리에 계속 유지되어 초기화 오버헤드 없음
- **세션 재사용**: ONNX Runtime 세션이 캐시되어 반복 사용
- **동적 설정**: 필요시에만 세션 재생성 (경로 변경 등)

### 주의사항
- `cleanup_memory()` 메소드를 전역 인스턴스에서 호출하지 마세요
- 프로덕션 환경에서는 celery_worker의 전역 인스턴스를 사용하세요
- 개발/테스트에서만 직접 인스턴스 생성을 사용하세요

## 성능 최적화 팁

1. **TensorRT 활용**: GPU가 있는 환경에서는 TensorRT를 활성화하여 성능 향상
2. **엔진 캐시**: 첫 실행 후 생성되는 TensorRT 엔진을 캐시하여 재시작 시 빠른 로딩
3. **크기 제한**: 메모리 부족 시 `migan_max_image_size`를 조정하여 처리 가능한 크기로 제한
4. **출력 크기**: 클라이언트 요구사항에 맞춰 `migan_output_max_width` 조정

## 문제 해결

### 일반적인 문제들

1. **모델 파일 없음**
   - 에러: `FileNotFoundError: ONNX 파일을 찾을 수 없습니다`
   - 해결: `worker/models/migan_pipeline_v2.onnx` 파일 확인

2. **CUDA 메모리 부족**
   - 에러: GPU 메모리 관련 오류
   - 해결: `migan_max_image_size` 값을 줄이거나 `migan_use_cuda: False`로 설정

3. **TensorRT 초기화 실패**
   - 에러: TensorRT Provider 초기화 실패
   - 해결: `migan_use_tensorrt: False`로 설정하여 CUDA Provider만 사용

4. **세션 생성 실패**
   - 에러: ONNX Runtime 세션 생성 실패
   - 해결: CPU 모드로 폴백 (`migan_use_cuda: False`)

### 디버깅

1. **로그 레벨 조정**: 디버그 로그를 활성화하여 상세 정보 확인
2. **아티팩트 저장**: 디버그 이미지를 저장하여 각 단계별 결과 확인
3. **성능 모니터링**: GPU 메모리 사용량 및 처리 시간 모니터링

## 업데이트 및 확장

새로운 MIGAN 모델 버전을 사용하려면:
1. 새 ONNX 파일을 `worker/models/` 디렉토리에 배치
2. `toggle_states`에서 `migan_onnx_path` 업데이트
3. 필요시 입출력 형태에 맞춰 모듈 코드 수정