OpenUpScaler

Real-ESRGAN 기반 로컬 AI 이미지 업스케일러.
클라우드 없이 내 PC에서 직접 실행하며, 설치 후 브라우저에서 바로 사용할 수 있습니다.

• AI 모델: Real-ESRGAN (일반 사진 / 애니메이션 / 문서·텍스트)
• 배율: 2× / 4×
• 배치 처리: 한 번에 최대 20장, 순차 처리 후 ZIP으로 일괄 다운로드
• GPU 가속: NVIDIA CUDA 자동 감지 (없으면 CPU로 자동 전환)
• 지원 포맷: PNG · JPG · WEBP · BMP (장당 최대 50MB)

---

요구 사항

• Python 3.10 이상
• (선택) NVIDIA GPU + CUDA 드라이버

---

설치

Step 1. 가상환경 생성

conda를 사용하는 경우

conda create -n openupscaler python=3.11 -y
conda activate openupscaler

venv를 사용하는 경우

python -m venv .venv

# Linux / macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

---

Step 2. PyTorch 설치 (GPU/CPU 환경에 맞게 선택)

nvidia-smi 명령어로 CUDA 버전을 확인한 뒤 아래에서 해당하는 명령어를 실행하세요.

CPU만 사용 (GPU 없음)

pip install torch torchvision

NVIDIA GPU — CUDA 11.8 (RTX 20xx / 30xx 일부)

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

NVIDIA GPU — CUDA 12.4 (RTX 30xx / 40xx)

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

NVIDIA GPU — CUDA 12.8 (RTX 50xx / Blackwell, 드라이버 570+)

RTX 5070 등 Blackwell 아키텍처는 PyTorch stable 미지원으로 nightly 빌드가 필요합니다.

pip install --pre torch torchvision --index-url https://download.pytorch.org/whl/nightly/cu128

설치 후 GPU 인식 확인:

python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU mode')"

---

Step 3. 백엔드 의존성 설치

pip install -r backend/requirements.txt

---

실행

# 가상환경 활성화 후
cd backend
uvicorn main:app --port 8000

브라우저에서 http://localhost:8000 접속

종료

터미널에서 Ctrl+C를 누르면 서버가 종료됩니다.

---

사용법

1. 이미지 업로드

방법	설명
드래그&드롭	파일을 업로드 영역에 끌어다 놓기 (여러 장 동시 가능)
클릭해서 선택	업로드 영역 클릭 → 파일 탐색기에서 선택 (Ctrl/Cmd로 다중 선택)
클립보드 붙여넣기	Ctrl+V — 여러 번 반복하면 누적 추가됩니다 (1회에 1장)

• 최대 20장까지 업로드할 수 있습니다.
• 잘못 추가한 파일은 목록의 × 버튼으로 개별 삭제할 수 있습니다.

2. 옵션 선택

• 배율: 2× 또는 4× (기본값 4×)

• 모델: 이미지 종류에 맞게 선택

  모델	적합한 이미지
  일반 사진	실사 사진, 풍경, 인물 등
  애니메이션	만화, 애니, 일러스트 등
  문서 / 텍스트	스캔 문서, 캡처 화면, 인쇄물 등 (4x-UltraSharp 모델)

3. 업스케일 시작

업스케일 시작 버튼을 클릭하면 AI 처리가 시작됩니다.

• 1장: 처리 완료 후 Before/After 비교 슬라이더로 원본과 결과를 나란히 확인
• 2장 이상: 파일별 진행 상태 실시간 표시 (✓ 완료 / 처리 중 / 대기 중)

4. 다운로드

• 1장: PNG 다운로드 버튼
• 2장 이상: 파일 이름을 입력한 뒤 ZIP 다운로드 버튼으로 전체 결과를 ZIP 하나로 저장
  (기본 파일 이름: upscaled_날짜.zip, 직접 수정 가능)

---

API 엔드포인트

메서드	경로	설명
GET	/api/info	GPU 정보 및 지원 모델 목록
POST	/api/upscale	이미지 업로드(최대 20장) + 처리 시작, job_id 반환
GET	/api/status/{job_id}	처리 상태 및 파일별 진행 현황 (pending / processing / done / error)
GET	/api/result/{job_id}	결과 반환 — 1장: PNG, 2장 이상: ZIP

---

디렉터리 구조

OpenUpScaler/
├── backend/
│   ├── main.py              # FastAPI 엔드포인트
│   ├── upscaler.py          # Real-ESRGAN 래퍼 (GPU/CPU 자동 감지)
│   ├── requirements.txt     # 백엔드 의존성
│   ├── models/              # 모델 파일 자동 다운로드 위치
│   └── outputs/             # 처리 결과 임시 저장
├── frontend/
│   ├── app/
│   │   ├── page.tsx         # 메인 페이지
│   │   └── layout.tsx
│   ├── components/
│   │   ├── UploadZone.tsx   # 드래그&드롭 + 클립보드 업로드
│   │   └── CompareSlider.tsx # Before/After 슬라이더 + 다운로드
│   └── store/
│       └── upscaler.ts      # Zustand 전역 상태
└── README.md

---

프론트엔드 코드 수정 시

Node.js 18 이상이 필요합니다.

UI 코드를 수정한 뒤 아래 명령어로 다시 빌드하면 변경사항이 반영됩니다.

cd frontend
npm run build

빌드 후 브라우저에서 http://localhost:8000 새로고침
(백엔드 서버는 재시작 없이 새 파일을 자동으로 서빙합니다)

---

트러블슈팅

GPU가 인식되지 않는 경우

CUDA 드라이버가 설치되어 있는지 확인하고, Step 2에서 GPU에 맞는 PyTorch를 설치했는지 재확인하세요.
GPU 없이도 CPU 모드로 동작하지만 처리 속도가 느릴 수 있습니다.

처음 업스케일 시 시간이 오래 걸리는 경우

backend/models/에 모델 파일이 없으면 첫 요청 시 자동 다운로드합니다.
일반 모델 약 67MB, 애니메이션 모델 약 18MB, 문서 모델(4x-UltraSharp) 약 64MB이며 인터넷 연결이 필요합니다.