gandol2-ocr 0.0.4
이미지를 시각적 경계 기준으로 안전하게 섹션 분리 & OCR (Korean, Chinese)
License: MIT
Requires Python: <3.13,>=3.9
Keywords: image, section, split, opencv, computer-vision

# gandol2-ocr

이미지 섹션 분리와 OCR을 통합한 Python 유틸리티입니다. 세로로 긴 상세페이지 이미지를 시각적 경계 기준으로 안전하게 섹션 분리하고, 각 섹션에 대해 OCR을 수행할 수 있습니다.

## ✨ 주요 기능

### 🖼️ 이미지 섹션 분리 (Splitter)

-   세로로 긴 상세페이지 이미지를 시각적 경계 기준으로 자동 분리
-   OpenCV 기반의 고급 이미지 처리 알고리즘
-   시각적 경계 감지 및 안전한 섹션 분할
-   분리된 섹션 정보를 구조화된 데이터로 제공

### 🔍 OCR (Optical Character Recognition)

-   PaddleOCR 기반의 고성능 OCR 엔진
-   한국어(`korean`) 포함 다국어 지원
-   GPU/CPU 선택 가능
-   바운딩박스와 텍스트 결과를 JSON으로 저장

## 📦 설치

### **중요**

```bash
# paddlepaddle-gpu==3.2.0 버전이 필수 입니다.
# pyproject.toml 설정 이후 패키지를 설치해주세요

dependencies = [
    ...
    "paddlepaddle-gpu==3.2.0",
    ...
]

[tool.uv.sources]
paddlepaddle-gpu = { index = "paddle" }


[[tool.uv.index]]
name = "paddle"
url = "https://www.paddlepaddle.org.cn/packages/stable/cu126/"
explicit = true

> uv sync

```

```bash
# uv 사용 (권장)
uv add gandol2-ocr

# pip 사용
pip install gandol2-ocr
```

또는 소스에서 설치:

```bash
# uv 사용
uv add git+https://github.com/gandol2/gandol2-ocr.git

# pip 사용
pip install git+https://github.com/gandol2/gandol2-ocr.git
```

## 🖥️ 요구 사항

-   Python **3.9-3.12** (pyproject.toml에 명시됨)
-   (선택) NVIDIA GPU + CUDA 12.6 환경 (PaddlePaddle GPU 지원)

## 🚀 사용법

### 1) 이미지 섹션 분리

```python
from gandol2_ocr.splitter import split_image_sections

# 이미지를 섹션으로 분리
sections = split_image_sections(
    image_path="./input/image.png",
    output_dir="./output"
)

print(f"총 {len(sections)}개 섹션 생성:")
for section in sections:
    print(f"  {section.order}. {section.top}-{section.bottom} ({section.height}px)")
```

### 2) OCR 실행

```python
from gandol2_ocr.ocr import run_ocr

# OCR 실행
results = run_ocr(
    input_image="./input/image.png",
    output_dir="./output",
    lang="korean",
    device="gpu"
)

# 결과 출력
for result in results:
    print(result["rec_texts"])
```

### 3) 통합 워크플로우

```python
from gandol2_ocr.splitter import split_image_sections
from gandol2_ocr.ocr import run_ocr

# 1단계: 이미지 섹션 분리
sections = split_image_sections(
    image_path="./input/long_image.png",
    output_dir="./sections"
)

# 2단계: 각 섹션에 대해 OCR 수행
for section in sections:
    ocr_results = run_ocr(
        input_image=section.path,
        output_dir=f"./ocr_results/section_{section.order}",
        lang="korean",
        device="gpu"
    )
    print(f"섹션 {section.order}: {len(ocr_results)}개 텍스트 감지")
```

### 4) 다양한 Import 방법

```python
# 방법 1: 최상위 모듈 (권장)
from gandol2_ocr.ocr import run_ocr
from gandol2_ocr.splitter import split_image_sections

# 방법 2: 패키지 레벨
from gandol2_ocr import run_ocr, split_image_sections

# 방법 3: 서브모듈 직접 접근
from gandol2_ocr.image_ocr.ocr import run_ocr
from gandol2_ocr.splitter.splitter import split_image_sections

# 방법 4: 클래스 import
from gandol2_ocr.splitter import ImageSectionSplitter, SectionInfo
```

## 🧱 프로젝트 구조

```
gandol2-ocr/
├─ pyproject.toml
├─ README.md
├─ src/
│  └─ gandol2_ocr/        # 메인 패키지
│     ├─ __init__.py      # 패키지 진입점
│     ├─ ocr.py           # 최상위 OCR 모듈 (re-export)
│     ├─ splitter.py      # 최상위 Splitter 모듈 (re-export)
│     ├─ image_ocr/       # 내부 OCR 모듈
│     │  ├─ __init__.py
│     │  ├─ cli.py
│     │  └─ ocr.py
│     └─ splitter/         # 내부 Splitter 모듈
│        ├─ __init__.py
│        └─ splitter.py
├─ examples/
│  ├─ demo_splitter.py    # 섹션 분리 예제
│  └─ demo_ocr.py         # OCR 예제
├─ input/                 # 입력 이미지
└─ output/                # 출력 결과
```

## 🔧 API 참조

### Splitter API

#### `split_image_sections(image_path, output_dir, debug_verbose=True, save_diagnostic=True)`

이미지를 섹션으로 분리하는 메인 함수입니다.

**사용법:**

```python
from gandol2_ocr.splitter import split_image_sections
```

**매개변수:**

-   `image_path` (str): 입력 이미지 경로
-   `output_dir` (str): 출력 디렉토리
-   `debug_verbose` (bool): 디버그 출력 여부 (기본: True)
-   `save_diagnostic` (bool): 진단 이미지 저장 여부 (기본: True)

**반환값:**

-   `List[SectionInfo]`: 섹션 정보 리스트

#### `SectionInfo` 클래스

```python
@dataclass
class SectionInfo:
    order: int      # 섹션 순서
    top: int        # 상단 좌표
    bottom: int     # 하단 좌표
    height: int     # 섹션 높이
    path: str       # 저장된 파일 경로
```

### OCR API

#### `run_ocr(input_image, output_dir, lang="korean", device="cpu")`

이미지에서 텍스트를 인식하는 함수입니다.

**사용법:**

```python
from gandol2_ocr.ocr import run_ocr
```

**매개변수:**

-   `input_image` (str): 입력 이미지 경로
-   `output_dir` (str): 출력 디렉토리
-   `lang` (str): OCR 언어 (기본: "korean")
-   `device` (str): "cpu" 또는 "gpu" (기본: "cpu")

**반환값:**

-   `List[dict]`: OCR 결과 리스트

## 🧪 소비측 테스트

패키지 설치 후 다음과 같이 테스트할 수 있습니다:

```python
# test_gandol2_ocr.py
def test_all_import_methods():
    """모든 import 방법 테스트"""
    try:
        # 방법 1: 최상위 모듈 (권장)
        from gandol2_ocr.ocr import run_ocr
        from gandol2_ocr.splitter import split_image_sections
        print("✅ 최상위 모듈 import 성공")

        # 방법 2: 패키지 레벨
        from gandol2_ocr import run_ocr as run_ocr2, split_image_sections as split_sections2
        print("✅ 패키지 레벨 import 성공")

        # 방법 3: 서브모듈
        from gandol2_ocr.image_ocr.ocr import run_ocr as run_ocr3
        from gandol2_ocr.splitter.splitter import split_image_sections as split_sections3
        print("✅ 서브모듈 import 성공")

        # 방법 4: 클래스
        from gandol2_ocr.splitter import ImageSectionSplitter, SectionInfo
        print("✅ 클래스 import 성공")

        print("🎉 모든 import 방법 성공!")
        return True

    except ImportError as e:
        print(f"❌ Import 오류: {e}")
        return False

if __name__ == "__main__":
    test_all_import_methods()
```

## 🛠️ 개발 및 배포

### 로컬 빌드

```bash
uv build
```

### TestPyPI 업로드

### PyPI 업로드

```bash
twine upload dist/*
```

## 🔎 참고사항

-   **의존성**: OpenCV, PaddleOCR, PaddlePaddle, Matplotlib, Pandas, SciPy
-   **GPU 지원**: CUDA 12.6 환경에서 PaddlePaddle GPU 사용 가능
-   **이미지 형식**: PNG, JPG, JPEG 등 OpenCV 지원 형식
-   **언어 지원**: PaddleOCR이 지원하는 모든 언어 (한국어, 영어, 중국어 등)

## 📄 라이선스

MIT License