# PaddleOCR 기반 문서 분석 웹 애플리케이션

이 프로젝트는 [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)의 강력한 PP-StructureV3 모델을 사용하여 이미지 속 문서의 구조를 분석하고, 그 결과를 시각적으로 보여주는 Streamlit 웹 애플리케이션입니다.

사용자는 이미지 파일을 업로드하여 문서의 레이아웃, 텍스트, 표 등을 자동으로 분석하고 구조화된 결과를 확인할 수 있습니다.

## ✨ 주요 기능

- **간편한 이미지 업로드**: 웹 인터페이스를 통해 손쉽게 이미지 파일(JPG, PNG, BMP 등)을 업로드할 수 있습니다.
- **지능형 문서 분석**: PP-StructureV3 모델을 사용하여 다음과 같은 복합적인 분석을 수행합니다.
  - **레이아웃 분석 (Layout Analysis)**: 문서 내의 제목, 문단, 표, 그림 등의 영역을 자동으로 식별합니다.
  - **광학 문자 인식 (OCR)**: 이미지 속 모든 텍스트를 정확하게 추출합니다.
  - **표 인식 (Table Recognition)**: 표의 구조를 인식하고 셀 단위로 데이터를 추출하여 HTML로 변환합니다.
  - **자동 보정**: 기울어진 문서를 바로잡는 등 OCR 정확도를 높이기 위한 전처리 작업을 수행합니다.
- **시각적인 결과 확인**: 분석 과정에서 생성되는 다양한 결과물(영역 감지, OCR 결과 등)을 단계별 이미지와 상세한 설명으로 확인할 수 있습니다.
- **구조화된 데이터 제공**: 분석된 텍스트와 표 데이터를 화면에 체계적으로 표시하며, 원본 JSON 데이터도 확인할 수 있습니다.

## 🛠️ 사용 기술

- **애플리케이션 프레임워크**: Streamlit
- **OCR 및 문서 분석**: PaddleOCR (PP-StructureV3)
- **패키지 및 환경 관리**: uv
- **컨테이너화**: Docker, Docker Compose

## 🚀 실행 방법

이 프로젝트를 실행하는 가장 권장되는 방법은 Docker를 사용하는 것입니다. Docker는 시스템 의존성 문제를 해결하여 어떤 환경에서든 안정적인 실행을 보장합니다.

### 1. Docker를 이용한 실행 (권장)

**요구사항**: Docker, Docker Compose가 설치되어 있어야 합니다.

터미널에서 다음 명령어를 실행하세요.

```bash
docker-compose up --build
```

빌드가 완료되면, 웹 브라우저에서 `http://localhost:8502` 주소로 접속하여 애플리케이션을 사용할 수 있습니다.

### 2. 로컬 환경에서 직접 실행

**요구사항**: Python 3.12+, `uv`

**주의**: 이 방법은 시스템에 `opencv-python`이 필요로 하는 라이브러리(예: `libGL.so.1`)가 설치되어 있지 않으면 오류가 발생할 수 있습니다.

1.  **가상 환경 생성 및 활성화**:
    ```bash
    # 가상 환경 생성
    uv venv

    # (Linux/macOS)
    source .venv/bin/activate
    ```

2.  **의존성 패키지 설치**:
    ```bash
    uv pip install -r pyproject.toml
    ```

3.  **Streamlit 앱 실행**:
    ```bash
    streamlit run app.py --server.port=8502
    ```

    이제 웹 브라우저에서 `http://localhost:8502` 주소로 접속할 수 있습니다.

## 📂 프로젝트 구조

```
.
├── 📄 app.py                # Streamlit 웹 애플리케이션 메인 코드
├── 🐳 docker-compose.yml     # Docker Compose 설정 파일
├── 🐳 dockerfile              # Docker 이미지 빌드를 위한 설정 파일
├── 📝 pyproject.toml         # Python 프로젝트 설정 및 의존성 목록
├── 🔒 uv.lock                # 의존성 버전 고정 파일
└── 📖 README.md             # 프로젝트 설명서
```