# 🚀 ARM 아키텍처 포팅 가이드

AutoPercenty3를 ARM 아키텍처 (Raspberry Pi, ARM 서버 등)에서 실행하는 방법

## 📋 지원 현황

| 구분 | x86_64 | ARM64 | ARM32 | 상태 |
|------|--------|-------|-------|------|
| **기본 GUI (PySide6)** | ✅ | ✅ | ✅ | 완전 지원 |
| **브라우저 자동화 (Playwright)** | ✅ | ✅ | ⚠️ | 대부분 지원 |
| **이미지 처리 (OpenCV)** | ✅ | ✅ | ✅ | 완전 지원 |
| **OCR - PaddleOCR (기본)** | ✅ | ⚠️ | ❌ | 성능 저하 |
| **OCR - FastDeploy** | ✅ | ✅ | ⚠️ | ARM 최적화 |
| **OCR - ONNX Runtime** | ✅ | ✅ | ✅ | 권장 방식 |

## 🔧 설치 방법

### 1. 시스템 준비 (Ubuntu/Debian 기준)

```bash
# Python 3.11 설치
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

# 빌드 도구 설치
sudo apt install build-essential pkg-config git

# GUI 의존성 (PySide6용)
sudo apt install qt6-base-dev libgl1-mesa-glx

# 브라우저 설치
sudo apt install chromium-browser

# ARM 최적화 라이브러리
sudo apt install libblas3 liblapack3 libopenblas-dev
```

### 2. 프로젝트 클론 및 환경 설정

```bash
# 프로젝트 클론
git clone [your-repo] AutoPercenty3_ARM
cd AutoPercenty3_ARM

# Python 가상환경 생성
python3.11 -m venv venv_arm
source venv_arm/bin/activate

# ARM용 의존성 설치
pip install -r requirements_arm.txt
```

### 3. 자동 빌드 및 실행

```bash
# 아키텍처 자동 감지하여 빌드
python3 build_linux.py

# 빌드 완료 후 실행
cd dist/AutoPercenty3_Linux_ARM/
./start.sh
```

## ⚙️ OCR 백엔드 상세 설정

### A. FastDeploy 사용 (권장 - ARM 최적화)

```bash
# FastDeploy CPU 버전 설치
pip install fastdeploy-cpu==1.0.7

# 모델 그대로 사용 (자동 감지)
# 프로그램 실행시 ARM 감지하여 자동으로 FastDeploy 사용
```

### B. ONNX Runtime 사용 (호환성 최고)

```bash
# 1. 모델 변환 (x86 시스템에서 수행)
python tools/convert_paddle_to_onnx.py \
    --model_dir src/modules/ \
    --output_dir src/modules/onnx_models/ \
    --model_type all

# 2. ONNX 모델을 ARM 시스템으로 복사
# src/modules/PP_Models/ 디렉토리에 model.onnx 파일들 배치

# 3. 자동 실행 (ONNX Runtime 백엔드 자동 선택)
```

### C. 백엔드 우선순위

프로그램이 ARM을 감지하면 다음 순서로 OCR 백엔드를 시도합니다:

1. **FastDeploy** (최고 성능) → 설치된 경우 우선 사용
2. **ONNX Runtime** (최고 호환성) → FastDeploy 실패시 사용  
3. **PaddleOCR** (폴백) → 다른 백엔드 모두 실패시 사용

## 🎯 성능 최적화

### ARM64 (Raspberry Pi 4, Apple M1 등)

```bash
# 환경 변수 최적화 (자동 적용됨)
export OMP_NUM_THREADS=4
export OPENBLAS_NUM_THREADS=4
export MKL_NUM_THREADS=4

# 메모리 최적화
export MALLOC_TRIM_THRESHOLD_=100000
```

### ARM32 (라즈베리 파이 3 등)

```bash
# 메모리 제한 환경
export OMP_NUM_THREADS=2
export OPENBLAS_NUM_THREADS=2

# 스왑 메모리 활성화 권장
sudo swapon /swapfile
```

## 📊 성능 비교

### Raspberry Pi 4 (ARM64, 8GB) 기준

| OCR 백엔드 | 초기화 시간 | 추론 속도 | 메모리 사용량 |
|------------|-------------|-----------|---------------|
| **FastDeploy** | ~3초 | **0.8초/이미지** | **~800MB** |
| **ONNX Runtime** | ~2초 | **1.2초/이미지** | **~600MB** |
| **PaddleOCR** | ~8초 | 3.5초/이미지 | ~1.2GB |

## 🔍 문제 해결

### Q1: "FastDeploy 초기화 실패" 오류

```bash
# 해결책: FastDeploy CPU 버전 재설치
pip uninstall fastdeploy-gpu fastdeploy
pip install fastdeploy-cpu==1.0.7
```

### Q2: "ONNX Runtime 모델 로드 실패"

```bash
# 해결책: 모델 변환 다시 수행
python tools/convert_paddle_to_onnx.py \
    --model_dir src/modules/ \
    --output_dir src/modules/ \
    --model_type all
```

### Q3: 메모리 부족 오류

```bash
# 해결책 1: 스왑 메모리 증가
sudo fallocate -l 2G /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 해결책 2: 브라우저 메모리 제한
export CHROME_FLAGS="--memory-pressure-off --max_old_space_size=512"
```

### Q4: 브라우저 실행 실패

```bash
# 해결책: 시스템 Chromium 설치 확인
sudo apt install chromium-browser

# 또는 권한 문제 해결
sudo chmod +x /usr/bin/chromium-browser
```

## 🚀 개발자용 고급 설정

### 새로운 OCR 백엔드 추가

1. `src/modules/ocr_backends/` 디렉토리에 새 백엔드 클래스 생성
2. PaddleOCR과 동일한 `ocr(img, det=True, rec=True, cls=True)` 인터페이스 구현
3. `src/modules/ocr_module.py`의 `_initialize_arm_ocr()` 메서드에 백엔드 추가

### 커스텀 모델 사용

```python
# src/modules/ocr_backends/custom_ocr.py
class CustomOCR:
    def ocr(self, img, det=True, rec=True, cls=True):
        # 커스텀 OCR 로직 구현
        results = []
        # ...
        return results  # PaddleOCR 형식: [[bbox, (text, confidence)], ...]
```

## 📈 로드맵

- [ ] **OpenVINO 백엔드 추가** (Intel ARM 최적화)
- [ ] **TensorRT 백엔드 추가** (NVIDIA Jetson 지원)
- [ ] **Core ML 백엔드 추가** (Apple Silicon 최적화)
- [ ] **모델 양자화 지원** (INT8 추론으로 속도 향상)

## 🤝 기여하기

ARM 관련 개선사항이나 새로운 백엔드를 추가하고 싶으시면:

1. 이슈 등록 후 논의
2. 포크하여 개발
3. 테스트 결과와 함께 PR 제출

---

**💡 팁**: ARM 환경에서 최적의 성능을 위해서는 **FastDeploy** 사용을 권장합니다!