================================================================================
  main.py 실행에 필요한 모듈 및 환경 정리
  프로젝트: ANT 리플렉터 비전 검사 시스템
  분석 기준: E:\ANT 폴더 소스 코드 및 .venv 설치 목록
  작성일: 2026-06-10
================================================================================

■ 1. 실행 방법
--------------------------------------------------------------------------------
  1) 프로젝트 루트(E:\ANT)에서 실행
     python main.py

  2) 가상환경 사용 권장 (.venv)
     .venv\Scripts\activate
     python main.py

  ※ Python 3.12 기준으로 .venv가 구성되어 있음 (pyvenv.cfg: 3.12.10)


■ 2. pip 설치 패키지 (서드파티 — 필수)
--------------------------------------------------------------------------------
  패키지명              pip 명령              용도                          사용 위치
  ─────────────────────────────────────────────────────────────────────────────
  PyQt5                 pip install PyQt5     GUI 프레임워크                main.py, gui/*
  opencv-python         pip install opencv-python  이미지 처리, ORB/NCC     inspect_page, register_page,
                                                      retrain_page, pattern_matcher, inspector
  numpy                 pip install numpy     배열/이미지 데이터            detector, basler, inspect_page 등
  ultralytics           pip install ultralytics  YOLOv8 추론/재학습       ai/detector.py, ai/trainer.py
  pypylon               pip install pypylon   Basler 카메라 SDK             camera/basler.py
  pyodbc                pip install pyodbc    MS SQL Server 연결            db/sql_client.py
  pymelsec              pip install pymelsec  Mitsubishi PLC (MC 3E)        plc/plc_client.py
  pyyaml                pip install pyyaml    학습 데이터셋 YAML 생성       ai/trainer.py

  ※ ultralytics 설치 시 torch, torchvision 등 AI 관련 의존성이 함께 설치됨
  ※ 현재 .venv 기준: torch 2.5.1+cu121, torchvision 0.20.1+cu121, ultralytics 8.4.41


■ 3. pip 설치 패키지 (간접/자동 의존성)
--------------------------------------------------------------------------------
  ultralytics → torch, torchvision, scipy, matplotlib, pillow, polars, psutil 등
  opencv-python → numpy
  PyQt5 → PyQt5-Qt5, PyQt5-sip

  현재 .venv에 함께 설치된 주요 간접 패키지:
    - scipy 1.17.1
    - matplotlib 3.10.9
    - pillow 12.1.1
    - requests 2.33.1
    - lap 0.5.13 (ultralytics 추적용)


■ 4. pip 설치 패키지 (선택 / 레거시)
--------------------------------------------------------------------------------
  pymysql               pip install pymysql   MySQL 클라이언트 (레거시)     db/mysql_client.py
                                              ※ main.py 실행 경로에서는 미사용
                                              ※ db/sql_client.py (pyodbc)가 실제 사용됨

  pyinstaller           pip install pyinstaller  EXE 빌드용              reflector_inspector.spec
                                              ※ 앱 실행 자체에는 불필요


■ 5. 시스템 / 외부 소프트웨어 의존성
--------------------------------------------------------------------------------
  [필수 — Windows]
  - Windows 10/11 (main.py에서 작업표시줄 아이콘 설정 시 ctypes 사용)

  [DB 사용 시]
  - Microsoft ODBC Driver 18 for SQL Server
    ※ pyodbc 연결 문자열: DRIVER={ODBC Driver 18 for SQL Server}
    ※ config.json → db.server / database / username / password

  [Basler 카메라 사용 시]
  - Basler pylon Camera Software Suite (별도 설치 필수)
    다운로드: https://www.baslerweb.com/en/downloads/software-downloads/
    ※ pypylon은 pylon SDK가 먼저 설치되어 있어야 동작함

  [Cognex In-Sight 카메라 사용 시]
  - 네트워크 연결 (Telnet 포트 23, FTP)
  ※ config.json → cognex.ip / cognex.port

  [PLC 사용 시]
  - Mitsubishi PLC (MC Protocol 3E, 기본 포트 5010)
  ※ config.json → plc.ip / plc.port

  [AI 추론/재학습 GPU 가속 (선택)]
  - NVIDIA GPU + CUDA 12.1 드라이버
  ※ CPU만으로도 실행 가능 (속도는 느림)


■ 6. 프로젝트 내부 모듈 (로컬 Python 패키지)
--------------------------------------------------------------------------------
  main.py가 직접/간접으로 import하는 프로젝트 모듈:

  [루트]
    logger.py              — 로그 설정/해제, 검사·타이밍·학습 로그
    paths.py               — PROJECT_ROOT / BUNDLE_ROOT 경로 해석

  [utils/]
    utils/path_helper.py   — get_path(), BASE_PATH (PyInstaller 호환)

  [gui/]
    gui/main_window.py     — 메인 윈도우 (4탭 네비게이션)
    gui/splash_screen.py   — 스플래시 화면 + InitWorker (백그라운드 초기화)
    gui/pages/settings_page.py   — 환경설정 탭
    gui/pages/register_page.py   — 제품 등록 탭
    gui/pages/inspect_page.py    — 검사 탭
    gui/pages/retrain_page.py    — 재학습 탭
    gui/dialogs/image_settings_dialog.py — 이미지 설정 다이얼로그

  [camera/]
    camera/insight.py      — Cognex In-Sight (Telnet + FTP)
    camera/basler.py       — Basler USB 카메라 (pypylon)

  [ai/]
    ai/detector.py         — YOLOv8 불량 검출 (ultralytics 지연 로딩)
    ai/trainer.py          — YOLOv8 재학습 + TrainWorker (subprocess 격리)

  [db/]
    db/sql_client.py       — MS SQL Server (pyodbc)

  [plc/]
    plc/plc_client.py      — Mitsubishi PLC (pymelsec Type3E)

  [logic/]
    logic/inspector.py         — PatMax 결과 판독 + Pass/Fail
    logic/group_manager.py     — A/B 그룹 전환
    logic/pattern_matcher.py     — ORB + NCC 패턴 매칭


■ 7. Python 표준 라이브러리 (별도 pip 설치 불필요)
--------------------------------------------------------------------------------
  multiprocessing, sys, json, os, socket, ftplib, io, time,
  threading, itertools, pickle, shutil, random, csv, builtins,
  pathlib, datetime, typing, ctypes (Windows 작업표시줄 아이콘)


■ 8. 실행 시 필요한 파일 / 리소스
--------------------------------------------------------------------------------
  [필수]
    config.json                    — 카메라/DB/AI/PLC 설정 (프로젝트 루트)

  [권장 / 기능별]
    ai/models/best.pt              — YOLO AI 모델 (config.json → ai.model_path)
    assets/images/ant_logo.png     — 앱 아이콘 (main.py ICON_PATH)
    assets/patterns.pkl            — PatternMatcher 등록 패턴 (없으면 신규 생성 가능)

  [자동 생성]
    logs/app/                      — 앱 로그
    logs/inspect/                  — 검사 결과 CSV
    logs/timing/                   — 카메라 타이밍 CSV
    logs/train/                    — 재학습 로그


■ 9. main.py 실행 흐름 (모듈 로딩 순서)
--------------------------------------------------------------------------------
  main.py
    → logger.setup_logging()
    → PyQt5 QApplication 생성
    → gui/splash_screen.SplashScreen 표시
    → gui/splash_screen.InitWorker (QThread) 백그라운드 초기화:
         1) config.json 로드
         2) camera/insight.InSightCamera 연결
         3) camera/basler.BaslerCamera 연결
         4) ai/detector.Detector 모델 로드 (ultralytics)
         5) db/sql_client.SQLClient DB 연결 (pyodbc)
         6) plc/plc_client.PLCClient 연결 (pymelsec)
    → gui/main_window.MainWindow 표시
    → PyQt5 이벤트 루프 (app.exec_())
    → logger.teardown_logging()


■ 10. 한 번에 설치하는 pip 명령 (권장)
--------------------------------------------------------------------------------
  pip install PyQt5 opencv-python numpy ultralytics pypylon pyodbc pymelsec pyyaml

  ※ GPU(CUDA 12.1) torch가 필요한 경우 ultralytics 설치 전/후에
     PyTorch 공식 사이트 기준 cu121 wheel을 별도 설치할 수 있음.


■ 11. 현재 .venv 설치 버전 참고 (2026-06-10 기준)
--------------------------------------------------------------------------------
  PyQt5==5.15.11
  opencv-python==4.13.0.92
  numpy==2.4.3
  ultralytics==8.4.41
  torch==2.5.1+cu121
  torchvision==0.20.1+cu121
  pypylon==26.3.1
  pyodbc==5.3.0
  pymelsec==0.2.5
  pyyaml==6.0.3
  pymysql==1.1.3          (레거시, main 실행 경로 미사용)
  pyinstaller==6.20.0     (빌드 전용)

================================================================================
