# kr_lp_pgnet — 핸드오프 (Claude 전용)

한국 자동차 번호판 검출 + OCR을 위한 PaddleOCR PGNet 학습 프로젝트.

---

## 30초 요약

- **목표**: PGNet 한 모델로 한국 LP 4종 (자가용/영업/전기/화물) 검출+인식 → ONNX export
- **현재 상태 (2026-05-18)**: Step1 학습 중 (run `step1-20260518_1010`, 200 epoch, from-scratch)
- **진단 히스토리**:
  1. 라벨이 판 전체 box → tight box 수정 → **검출 f_score 0.52→0.7 개선**, 그러나 인식 여전히 실패
  2. eval 시각화로 확인: type1 plate가 한글 뒤 공백에서 검출 분리 ("37도1563"→"37도"+"1563"), 한글 전부 □
  3. 코드 검증: CTC는 alignment-free라 char-level polygon 무의미. 진짜 원인은 한글 뒤 36px 공백이 PGNet TCL 연결을 끊는 것 + 한글 클래스 불균형
  4. `gen_type1`의 `col += 60 + 36` → `col += 60` (공백 제거) 후 재학습
- **확인 포인트**: epoch 5~10에서 `eval/hit_str_count` 상승 + 검출 미분리 여부 → 공백 제거 효과 판정
- **남은 이슈**: 한글 클래스 불균형 (plate당 숫자~6 : 한글 1), augmentation 부재 — 공백 효과 확인 후 별도 대응
- **다음 단계**: 학습 완료 후 → eval f_score_e2e 확인 → Step2 fine-tune (실차 데이터)
- **운영 원칙**: 로컬 Mac은 코드 작성·git만, 모든 실행은 외부 GPU 서버에서

---

## 환경

### 1. 로컬 Mac (코드 작성 전용)
- 작업 디렉토리: `/Users/songhyeonsu/Documents/GIT/cuuva_AI/kr_lp_pgnet/`
- **금지**: pip install, 외부 자산 clone, 합성기·학습·평가 실행
- **허용**: 코드/yaml/sh 작성·수정, git commit/push

### 2. 외부 GPU 서버
- **SSH**: `ssh cuuva@192.168.10.189` (사내망 전용)
- **호스트**: Ubuntu 25.10, RTX 5090 32GB, NVIDIA driver 590.48.01, CUDA 13.1
- **레이아웃**:
  ```
  /home/cuuva/workspace/
  ├── PaddleOCR/              # git clone release/2.7
  ├── kr_lp_pgnet/            # 이 repo
  ├── train_data/
  │   ├── kr_lp_synth/        # Step1 학습용 (50k, tight box 라벨)
  │   ├── region_check_y/     # 영업용 region 16종 검증
  │   └── region_check_g/     # 친환경 region 16종 검증
  └── wheels/
      └── paddlepaddle_gpu-3.3.0.dev20251209-cp310-...whl
  ```

### 3. 학습 컨테이너 `kr_lp_pgnet`
- 베이스: `ubuntu:24.04`
- 옵션: `--gpus all --shm-size=8g --restart unless-stopped`
- bind mount: 호스트 `/home/cuuva/workspace` ↔ 컨테이너 `/workspace`
- 재셋업: `bash scripts/recreate_container.sh`

### 4. 파일 서버 컨테이너 `kr_lp_http`
- 합성 결과 시각 확인용: **http://192.168.10.189:8889/**
- 마운트: `/home/cuuva/workspace/train_data` (read-only)

---

## 저장소

- **Git remote**: `http://192.168.10.110/TTA/kr_lp_pgnet.git` (사내 Gitea)
- **브랜치**: `main`만 사용

## wandb

- **Entity**: `hssong_cuuva` / **Project**: `kr_lp_pgnet`
- **현재 run**: `step1-20260518_0216`
- **dashboard**: https://wandb.ai/hssong_cuuva/kr_lp_pgnet

---

## 핵심 이슈 히스토리

### 라벨 박스 문제 (2026-05-18 수정)
기존 학습 데이터(`kr_lp_synth`)의 라벨 박스가 판 전체 영역이었음:
```
수정 전: "points": [[0,0],[520,0],[520,110],[0,110]]  ← 판 전체
수정 후: "points": [[35,13],[467,96],...]             ← 글자 행만
```
결과: 100 epoch 학습해도 f_score_e2e ≈ 0 (hit_str_count 32/2867).
원인: training은 라벨과 직접 비교하므로 loss가 내려갔지만, 추론 시 post-processing이
판 전체 heat map을 받아 박스를 쪼개거나 이상하게 복원 → 인식 실패.
`generate_synthetic.py`의 tight polygon 생성 코드는 이미 수정되어 있었으나
서버 데이터가 구버전으로 생성된 상태였음. 데이터 재생성 후 재학습.

### NVML stale (재발 가능)
컨테이너 장시간 실행 후 `nvidia-smi` 에러. `docker restart kr_lp_pgnet`으로 해결.

### OOM
batch 32 → OOM. **batch 16 확정**.

### cuDNN 9.17 강제
paddle sm_120 wheel은 cuDNN 9.17 빌드. `setup_server.sh`에서 `nvidia-cudnn-cu13>=9.17` 강제 설치.

---

## 자주 쓰는 운영 명령

```bash
# 학습 로그 확인
ssh cuuva@192.168.10.189 'docker exec kr_lp_pgnet sh -c "tail -5 /workspace/PaddleOCR/output/kr_lp_pgnet_*/run.log"'

# GPU 사용량
ssh cuuva@192.168.10.189 'docker exec kr_lp_pgnet nvidia-smi --query-gpu=memory.used,utilization.gpu --format=csv'

# 학습 중단
ssh cuuva@192.168.10.189 'docker exec kr_lp_pgnet pkill -f tools/train.py'

# 컨테이너 재시작 (NVML 풀기)
ssh cuuva@192.168.10.189 'docker restart kr_lp_pgnet'

# 재학습 (처음부터)
ssh cuuva@192.168.10.189 'docker exec -d kr_lp_pgnet bash /workspace/kr_lp_pgnet/scripts/run_step1.sh'
```

---

## 데이터 관련 알려진 이슈

- **자산이 만들 수 없는 글자**: `하`, `호`, `배` — Step2 실차 데이터로 보충
- **REGION_MAP 추정값**: `A='서울'`만 검증, 나머지는 `tools/region_check.py`로 확인 필요
- **세종 누락**: 자산 region 16개, 실제 광역지자체 17개 (세종 미포함)

---

## 진행 상태

### ✅ 완료
1. 환경 셋업 (컨테이너, paddle sm_120, cuDNN 9.17, PaddleOCR release/2.7)
2. dict 67자 + config (pad_num=67, max_text_length=10, valid_set=partvgg)
3. 합성기 4 plate type + tight word-level polygon 라벨
4. wandb 연동
5. make_gt_mat.py (eval GT 생성)
6. run_step1.sh 타임스탬프 기반 output 관리

### 🔄 진행 중
- Step1 학습 (run `step1-20260518_0216`, 200 epoch, 50k tight-box 데이터)

### 📋 다음 단계
1. Step1 완료 후 f_score_e2e 확인 (이전 0.0007 → 대폭 개선 기대)
2. Step2 fine-tune — 실차 한국 LP 사진 수집·라벨링
3. ONNX export