Getting started

1. 환경 설정

---

소스 코드를 준비합니다 (SaigeEdge submodule 포함).

git clone https://github.com/SAIGE-AI/ocr-edge
cd ocr-edge
git submodule update --init --recursive

Python 환경을 생성하고 dependencies를 설치합니다 (Python 3.10+).

conda create -n ocr_edge python=3.10
conda activate ocr_edge

pip install -r requirements/develop.txt

2. 사용

---

import cv2
from ocr import InferenceHandler

# 세 checkpoint 경로는 필수입니다 — 생략/None 이면 에러입니다. 배포 패키지는 기본 경로를 들고
# 있지 않으므로 쓸 모델을 항상 명시합니다.
config = {
    "det_checkpoint_path": "/path/to/det.saigeedge",   # DET .saigeedge
    "ori_checkpoint_path": "/path/to/ori.saigeedge",   # ORI .saigeedge
    "rec_checkpoint_path": "/path/to/rec.saigeedge",   # REC .saigeedge (ONNX + charset)
    "password": None,              # 세 checkpoint 공용 AES password (평문 번들이면 None)
}

err_code, err_msg, handler = InferenceHandler.build(config)

image = cv2.imread("path/to/image.jpg", cv2.IMREAD_COLOR)
with handler:
    err_code, err_msg, result = handler.infer(image)

for box in result.boxes:
    print(box.text, box.confidence, box.polygon)
print(result.stages)  # {"det_ms": .., "crop_ms": .., "ori_ms": .., "rec_ms": .., "total_ms": ..}

ROI 폴리곤을 알고 있는 경우 det/ori 를 생략하고 인식만 수행할 수 있습니다 (수동 모드).

err_code, err_msg, result = handler.infer(image, boxes=[[[x1, y1], [x2, y2], [x3, y3], [x4, y4]]])

runtime option 은 build 후 (model, key, value) 단건 API 로 조정합니다.

err_code, err_msg, _ = handler.set_inference_option("detection", "params.box_thresh", 0.5)

각 기능에 대한 설명은 API Reference를 참고하세요.

3. 데모 실행

---

공식 API 흐름(build → 옵션 조정 → 추론 → 시각화 저장)을 한 번에 보여주는 데모입니다.

python demo/inference.py                     # 기본 test_data 이미지들
python demo/inference.py a.jpg b.png         # 지정 이미지

이미지별로 polygon / text / confidence / rotation 을 출력하고, 시각화 결과를 demo/output/ 에 저장합니다.

4. CLI 실행

---

config 기반으로 이미지 디렉터리를 일괄 추론하고 results.json 을 생성합니다.

python run.py -c config/ocr_cubie.yml -m test_image

5. 라이브러리 빌드

---

배포용으로 cythonize된 라이브러리를 빌드합니다. 예제에서는 deploy/ 폴더를 사용합니다.

python setup.py build_ext --build-lib deploy -j `nproc`

빌드 시 tests, demo, config, requirements 등 개발 전용 디렉토리는 자동으로 제외됩니다.