Upload 10 files

nu/0.ingest_daily_LLS.py

@@ -0,0 +1,262 @@
+# ingest_daily_lls_simple.py
+import os
+import sys
+import warnings
+import numpy as np
+import pandas as pd
+import urllib3
+from datetime import datetime, timedelta
+import trino
+from trino.auth import BasicAuthentication
+
+warnings.filterwarnings("ignore")
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+# 출력 디렉터리 생성
+os.makedirs("./daily", exist_ok=True)
+sys.path.append(os.getcwd())
+
+
+# ============================================================
+# 1. 설정 정보
+# ============================================================
+conn_info = {
+    'host': "aidp-trino-analysis.sksiltron.co.kr",
+    'port': 31085,
+    'catalog': "iceberg",
+    'schema': "ibg_lake"
+}
+
+login_info = {
+    'user': '257285',
+    'pw': 'tjrdlA1!',
+}
+
+# 데이터 추출 설정
+data_info = {
+    'wafer_type': 'EPI',
+}
+
+
+# 기간 설정: 20240101 \~ 오늘
+START_DATE = "20240101"
+END_DATE = datetime.now().strftime("%Y%m%d")
+
+
+# ============================================================
+# 2. Trino 연결
+# ============================================================
+def get_trino_connection():
+    return trino.dbapi.connect(
+        host=conn_info['host'],
+        port=conn_info['port'],
+        user=login_info['user'],
+        catalog=conn_info['catalog'],
+        schema=conn_info["schema"],
+        http_scheme="https",
+        auth=BasicAuthentication(login_info['user'], login_info['pw']),
+        verify=False
+    )
+
+# ============================================================
+# 3. 쿼리 실행
+# ============================================================
+def make_df(conn, query):
+    cursor = conn.cursor()
+    cursor.execute(query)
+    columns = [col[0] for col in cursor.description]
+    results = cursor.fetchall()
+    cursor.close()
+    return pd.DataFrame(results, columns=columns)
+
+# ============================================================
+# 4. roughbin_no 매핑 함수 (전처리용)
+# ============================================================
+def map_roughbin_no(roughbin):
+    roughbin_mapping = {
+        0: 'LPD', 100: 'LPD-N', 110: 'Micro-Scratch', 111: 'Void', 115: 'PID',
+        120: 'LPD-E', 130: 'LPD-S', 140: 'LLPD', 141: 'Air Pocket', 150: 'DIC-Unique',
+        160: 'Stain', 170: 'COP', 200: 'Cluster Area', 205: 'Extended Defects',
+        210: 'Scratch', 220: 'Slipline', 230: 'Line', 231: 'Area', 233: 'Radial',
+        234: 'Ring', 512: 'Residue', 520: 'Boat Mark', 902: 'Streak', 999: 'Nuisance',
+        990: 'LPD Nuisance', 991: 'PPD Nuisance', 501: 'Haze Slipline', 502: 'Hazeline',
+        600: 'Grid', 700: 'ROI', 800: 'X Section'
+    }
+    if pd.isna(roughbin):
+        return None
+    try:
+        roughbin = int(roughbin)
+    except:
+        return None
+    if roughbin in roughbin_mapping:
+        return roughbin_mapping[roughbin]
+    if 541 <= roughbin <= 548:
+        return 'Haze Slipline'
+    if 531 <= roughbin <= 538:
+        return 'Hazeline'
+    if 601 <= roughbin <= 609:
+        return 'Grid'
+    if 701 <= roughbin <= 709:
+        return 'ROI'
+    if 801 <= roughbin <= 809:
+        return 'X Section'
+    return 'Unknown'
+
+
+# ============================================================
+# 5. 일자별 쿼리 템플릿 (운영 기준 07:00 반영)
+# ============================================================
+LLS_DAILY_QUERY = """
+SELECT 
+    B.SUBLOT_ID, B.CAR_ID, B.SCAN_TIME, B.EQP_ID AS EQP_ID_8210, B.EQP_ID_8030, 
+    B.ROUTE_ID, B.PROD_ID, B.HIS_REGIST_DTTM AS HIS_REGIST_DTTM_8030, 
+    HIS_REGIST_DTTM_Pcounter, B.WAF_ID, B.DEFECT_CNT, B.OPE_ID, 
+    A.coor_x, A.coor_y, A.d_size, A.test_no, A.roughbin_no 
+FROM 
+    iceberg.ibg_lake.DAS_DEFECT A,
+    (
+        SELECT 
+            B.HIS_REGIST_DTTM AS HIS_REGIST_DTTM_Pcounter, 
+            C.SUBLOT_ID, B.WAF_ID, B.SCANINDEX, B.EQP_ID, C.EQP_ID AS EQP_ID_8030, 
+            B.PT_D, C.BASE_DT, C.CAR_ID, C.SLOT_NO, B.RECIP_ID, B.DEFECT_CNT, 
+            B.PROD_ID, B.ROUTE_ID, C.HIS_REGIST_DTTM, B.SCAN_TIME, B.OPE_ID 
+        FROM 
+            iceberg.ibg_lake.das_inspection B,
+            (
+                SELECT 
+                    SUBLOT_ID, WAF_ID, EQP_ID, HIS_REGIST_DTTM, CAR_ID, SLOT_NO, BASE_DT 
+                FROM 
+                    iceberg.ibg_lake.odb_dwaf_ope_his 
+                WHERE 1=1
+                  AND BASE_DT BETWEEN '{search_min_date}' AND '{search_max_date}'
+                  AND OPE_ID = '8030'
+                  AND SUBLOT_ID NOT LIKE '7V%'
+                  AND SUBLOT_ID NOT LIKE '7G%'
+                  AND HIS_CAT = 'OC'
+            ) C
+        WHERE 1=1
+          AND C.WAF_ID = B.WAF_ID
+          AND B.OPE_ID = '8210'
+          AND (
+            B.ROUTE_ID LIKE 'WF7EP%' OR 
+            B.ROUTE_ID LIKE '%RW%' OR 
+            B.ROUTE_ID = 'SUB-LLS-10EA' OR 
+            B.ROUTE_ID = 'SUB-LLS-T-OV' OR 
+            B.ROUTE_ID = 'SUB-SLIP-LLS'
+          )
+        ORDER BY B.SCAN_TIME DESC
+    ) B
+WHERE 1=1
+  AND A.SCANINDEX = B.SCANINDEX 
+  AND A.TEST_NO IN (1, 6)
+  AND B.HIS_REGIST_DTTM >= '{start_timestamp}'
+  AND B.HIS_REGIST_DTTM < '{end_timestamp}'
+"""
+
+
+# ============================================================
+# 6. 일자별 수집 함수
+# ============================================================
+def ingest_single_day(target_date: str):
+    output_path = f"./daily/{target_date}.parquet"
+    if os.path.exists(output_path):
+        print(f"[SKIP] 이미 존재함: {output_path}")
+        return True
+
+    # 운영 기준 시간 계산 (07:00 기준)
+    start_dt = datetime.strptime(target_date, "%Y%m%d") + timedelta(hours=7)  # YYYYMMDD 07:00:00
+    end_dt = start_dt + timedelta(days=1)  # YYYYMMDD+1 07:00:00
+
+    search_min_date = (start_dt - timedelta(days=1)).strftime("%Y%m%d")  # BASE_DT 검색 범위 확장
+    search_max_date = end_dt.strftime("%Y%m%d")
+    start_timestamp = start_dt.strftime("%Y%m%d%H%M%S")  # YYYYMMDD070000
+    end_timestamp = end_dt.strftime("%Y%m%d%H%M%S")      # YYYYMMDD+1 070000
+
+    query = LLS_DAILY_QUERY.format(
+        search_min_date=search_min_date,
+        search_max_date=search_max_date,
+        start_timestamp=start_timestamp,
+        end_timestamp=end_timestamp
+    )
+
+    conn = None
+    try:
+        conn = get_trino_connection()
+        print(f"[{target_date}] 쿼리 실행...")
+        df = make_df(conn, query)
+        print(f"[{target_date}] 조회 완료: {len(df):,}건")
+
+        if len(df) == 0:
+            print(f"[{target_date}] 데이터 없음 → 빈 파일 저장")
+            df = pd.DataFrame()
+
+        # 전처리
+        df['HIS_REGIST_DTTM_8030'] = df['HIS_REGIST_DTTM_8030'].astype(str).str[:14]
+        df['HIS_REGIST_DTTM_Pcounter'] = df['HIS_REGIST_DTTM_Pcounter'].astype(str).str[:14]
+        df['d_size'] = pd.to_numeric(df['d_size'], errors='coerce')
+        df = df[~(df['DEFECT_CNT'] >= 9999)].copy()
+        df['coor_x'] = df['coor_x'] / 1000 - 150
+        df['coor_y'] = df['coor_y'] / 1000 - 150
+        df['coor_x'] = df['coor_x'].astype(float)
+        df['coor_y'] = df['coor_y'].astype(float)
+        df['ANGLE'] = (np.arctan2(df['coor_y'], df['coor_x']) / np.pi * 180 + 360) % 360
+        df['DISTANCE'] = np.sqrt(df['coor_x'] ** 2 + df['coor_y'] ** 2)
+        df['LLS 구분'] = df['roughbin_no'].apply(map_roughbin_no)
+        df['Particle 분포'] = np.select(
+            condlist=[df['DISTANCE'] <= 105, df['DISTANCE'] > 105],
+            choicelist=["면내", "Edge"],
+            default="기타"
+        )
+
+        # d_size 필터
+        D_SIZE_MIN = 0.037
+        df = df[df['d_size'] >= D_SIZE_MIN].reset_index(drop=True)
+        print(f"[{target_date}] 전처리 완료: {len(df):,}건")
+
+        # 저장
+        df.to_parquet(output_path, index=False)
+        print(f"[{target_date}] 저장 완료: {output_path}")
+        return True
+
+    except Exception as e:
+        print(f"[ERROR] {target_date} 실패: {str(e)}")
+        error_df = pd.DataFrame([{"date": target_date, "error": str(e)}])
+        error_df.to_parquet(f"../data/daily/daily/error_{target_date}.parquet", index=False)
+        return False
+    finally:
+        if conn:
+            conn.close()
+
+
+# ============================================================
+# 7. 전체 기간 실행
+# ============================================================
+def ingest_historical_range():
+    start_dt = datetime.strptime(START_DATE, "%Y%m%d")
+    end_dt = datetime.strptime(END_DATE, "%Y%m%d")
+    total_days = (end_dt - start_dt).days + 1
+
+    print(f"=== LLS 일자별 데이터 수집 시작 ===")
+    print(f"기간: {START_DATE} ~ {END_DATE} ({total_days}일)")
+    print(f"운영 기준: 07:00 기준 (ex. 20240101 = 2024-01-01 07:00:00 \~ 2024-01-02 06:59:59)")
+    print(f"저장 위치: ./daily/")
+
+    success_count = 0
+    fail_count = 0
+
+    for i in range(total_days):
+        target_date = (start_dt + timedelta(days=i)).strftime("%Y%m%d")
+        if ingest_single_day(target_date):
+            success_count += 1
+        else:
+            fail_count += 1
+
+    print(f"=== 수집 완료 ===")
+    print(f"성공: {success_count}, 실패: {fail_count}, 총: {total_days}")
+
+
+# ============================================================
+# 8. 실행
+# ============================================================
+# if __name__ == "__main__":
+ingest_historical_range()

nu/README.md

@@ -0,0 +1,623 @@
+# LLS 결함 패턴 자동 분석 시스템
+
+> 반도체 웨이퍼 LLS(Laser Light Scattering) 검사 데이터에서
+> **환형 / 선형 / 군집** 결함 패턴을 자동 검출하고,
+> 공정 설비 접촉 각도와 매칭해 **원인 후보 부위**를 추적하는 분석 파이프라인.
+
+---
+
+## 목차
+1. [개요 및 목적](#1-개요-및-목적)
+2. [전체 아키텍처](#2-전체-아키텍처)
+3. [데이터 흐름](#3-데이터-흐름)
+4. [모듈별 상세](#4-모듈별-상세)
+5. [설정 파일](#5-설정-파일-lls_configjson)
+6. [사용법](#6-사용법)
+7. [출력 구조](#7-출력-구조)
+8. [패턴 분류 알고리즘](#8-패턴-분류-알고리즘)
+9. [Contact 매핑 로직](#9-contact-매핑-로직)
+10. [검증 및 테스트](#10-검증-및-테스트)
+11. [확장/튜닝 가이드](#11-확장튜닝-가이드)
+
+---
+
+## 1. 개요 및 목적
+
+### 문제 정의
+반도체 웨이퍼는 다수의 공정 단계를 거치는 동안 다양한 설비 부위와 접촉하며, 일부 접촉은 결함(particle, scratch 등)을 유발합니다. LLS 검사기는 웨이퍼 표면 결함의 좌표/크기/타입을 측정하지만, **어느 설비의 어느 부위가 원인인지**는 자동으로 알려주지 않습니다.
+
+### 본 시스템의 역할
+1. 일자별 LLS 결함 데이터를 자동 수집·전처리
+2. 동일 캐리어(CAR_ID) 또는 동일 일자의 결함을 통합하여 **공통 패턴**을 검출
+3. 검출된 패턴의 위치(centroid)를 사전 정의된 **설비 접촉 각도 테이블**과 매칭하여 원인 후보 부위 산출
+4. 결과를 CSV + 웨이퍼 맵 이미지로 시각화하여 운영자가 빠르게 검토 가능하도록 출력
+
+### 핵심 가정
+- **공통 위치에 반복되는 결함 = 의미 있는 패턴**: 단발성 결함은 노이즈로 간주.
+- **결함 발생 위치는 설비 접촉 위치와 강한 상관관계**: edge 영역 접촉부와 결함 centroid의 기하학적 근접도로 후보 추정.
+
+---
+
+## 2. 전체 아키텍처
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    Trino DB (iceberg.ibg_lake)               │
+│         das_inspection / das_defect / odb_dwaf_ope_his       │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼ ① 데이터 수집 (일자별)
+                ┌───────────────────────────┐
+                │   0.ingest_daily_LLS.py   │
+                │     (Trino → parquet)     │
+                └───────────────────────────┘
+                              │
+                              ▼
+                   ./daily/YYYYMMDD.parquet
+                              │
+                              ▼ ② 패턴 분석 + Contact 매핑
+                ┌───────────────────────────┐
+                │   pattern_analyzer.py     │
+                │   LLSPatternAnalyzer      │
+                │                           │
+                │   ┌─────────────────────┐ │
+                │   │ utils.WaferUtils    │ │  ← 전처리/시각화
+                │   │ pattern_detection.  │ │  ← 패턴 분류
+                │   │   PatternDetector   │ │
+                │   │ contact_mapper.     │ │  ← 설비 부위 매핑
+                │   │   ContactMapper     │ │
+                │   └─────────────────────┘ │
+                └───────────────────────────┘
+                              │
+                              ▼ ③ 결과 출력
+                ./result_daily/
+                  ├── by_cst/*.csv           (Mode 2: CST × 시각)
+                  ├── daily_agg/*.csv        (Mode 1: 일자 통합)
+                  ├── figures_by_cst/        (CST별 wafer map)
+                  ├── figures_daily/         (일자별 wafer map)
+                  └── LLS_*_full_analysis.csv (통합 결과)
+```
+
+### 모듈 의존성 그래프
+
+```
+                       ┌──────────────────┐
+                       │  lls_config.json │
+                       └────────┬─────────┘
+                                │
+   ┌────────────────────────────┼────────────────────────────┐
+   │                            ▼                            │
+   │              ┌──────────────────────────┐               │
+   │              │   pattern_analyzer.py    │               │
+   │              │   LLSPatternAnalyzer     │               │
+   │              └──────────┬───────────────┘               │
+   │                         │                               │
+   │    ┌────────────────────┼────────────────────┐          │
+   │    ▼                    ▼                    ▼          │
+   │ ┌────────┐     ┌────────────────┐    ┌────────────────┐ │
+   │ │utils.py│     │pattern_         │    │contact_mapper. │ │
+   │ │Wafer   │     │ detection.py    │    │py              │ │
+   │ │Utils   │     │PatternDetector  │    │ContactMapper   │ │
+   │ └────────┘     └────────────────┘    └────────────────┘ │
+   │                                                          │
+   └──────────────────────────┬───────────────────────────────┘
+                              ▼
+                  ┌──────────────────────┐
+                  │  contact_angle.csv   │
+                  └──────────────────────┘
+```
+
+---
+
+## 3. 데이터 흐름
+
+### Stage 1: 데이터 수집 (`0.ingest_daily_LLS.py`)
+
+| 단계 | 처리 |
+|------|------|
+| 1. Trino 연결 | BasicAuth + HTTPS, verify=False |
+| 2. 운영일 정의 | 07:00 기준 (`YYYYMMDD 07:00:00` ~ `YYYYMMDD+1 06:59:59`) |
+| 3. 쿼리 실행 | OPE_ID 8030(공정) ↔ 8210(LLS 검사) JOIN, ROUTE_ID 필터링 |
+| 4. 전처리 | 좌표 변환(`/1000 - 150`), d_size 필터(`>=0.037`), ANGLE/DISTANCE 계산, roughbin 매핑, LLS 구분, Particle 분포 라벨링 |
+| 5. 저장 | `./daily/YYYYMMDD.parquet` |
+
+### Stage 2: 패턴 분석 (`pattern_analyzer.py`)
+
+```
+parquet 로드
+    │
+    ▼
+[for each date]
+    │
+    ▼
+모드 분기
+    │
+    ├── Mode 2 (by_cst)                  ├── Mode 1 (daily aggregated)
+    │   [for each CAR_ID]                │   하루 전체 결함 통합
+    │     [for each HIS_REGIST_DTTM]     │
+    │                                    │
+    ▼                                    ▼
+fine-grid 할당 (cell_size_mm)        ←┘
+    │
+    ▼
+n1 필터 (cell당 unique wafer ≥ n1_min_wafers)
+    │
+    ▼
+n2 필터 (cell당 결함 수 ≥ n2_min_cell_defects)
+    │
+    ▼
+PatternDetector.classify()
+   • HDBSCAN → DBSCAN fallback (1차 클러스터링)
+   • LOF outlier 제거 (2차)
+   • 패턴 판정: 환형 → 선형 → 군집(서브분류)
+    │
+    ▼
+ContactMapper.map_pattern()
+   • 환형 → Line 제외 전체 (각도 무관)
+   • 선형 → Line 마킹, |P.x - centroid_x|
+   • 군집 → Line 제외, dist(P, centroid)
+    │
+    ▼
+record 생성 + CSV 저장 + wafer map 이미지 생성
+```
+
+---
+
+## 4. 모듈별 상세
+
+### 4.1 `utils.py` — `WaferUtils`
+
+웨이퍼 결함 처리 공용 유틸리티 (모든 메서드 static).
+
+| 메서드 | 역할 |
+|--------|------|
+| `setup_korean_font()` | matplotlib에 한글 폰트 등록 (Malgun Gothic 우선) |
+| `load_config(path)` | JSON 설정 로드 |
+| `map_roughbin_no(rb)` | 검사기 raw 코드 → 운영 결함 분류명 |
+| `add_zone_labels(df, inner_radius)` | `{Inner\|Outer}_{시계위치}` 라벨 부여 |
+| `assign_fine_grid(df, cell_size_mm)` | 결함을 격자 cell에 할당 |
+| `get_cell_wafer_counts(df)` | cell별 unique wafer/결함 수 집계 |
+| `filter_by_cell_wafer_count(df, n1_min_wafer)` | n1 필터 적용 |
+| `summarize_filtering_result(orig, filt)` | 필터 전후 요약 통계 |
+| `plot_wafer_map(...)` | 웨이퍼 맵 시각화 (산점도 + 동심원 + 시계 그리드 + centroid 마킹) |
+
+**상수**:
+- `ROUGHBIN_MAPPING`: roughbin_no → 결함명 dict
+- `CLOCK_LABELS`: `["12", "01", ..., "11"]`
+- `PATTERN_COLORS`: 패턴별 시각화 색상
+
+### 4.2 `pattern_detection.py` — `PatternDetector`
+
+LLS 결함 패턴 자동 분류기. config를 주입받아 사용.
+
+**핵심 API**: `classify(df) → (result_df, dominant_zone, pattern_list, centroid)`
+
+**분류 파이프라인**:
+1. **1차 클러스터링** (`_cluster_hdbscan`) — HDBSCAN으로 outlier(-1) 제거
+   - 모두 outlier면 DBSCAN fallback (`_cluster_dbscan_fallback`)
+2. **2차 outlier 제거** (`_apply_lof`) — LOF로 지역 밀도 기반 추가 제거
+3. **패턴 판정** (우���순위 순):
+   - **환형** (`_is_ring`): PCA 선형성 거부 → main r-band 추출 → 각도/sector 커버리지 → 원 피팅 RMSE → 중심 원점 근접
+   - **선형** (`_is_linear_set`): PCA eigenvalue ratio → 직선 편차 → gap ratio
+   - **군집** (`_classify_cluster_or_sub_linear`): DBSCAN 서브클러스터 → compactness/PCA로 재판정
+4. **dominant_zone** (`_dominant_zone`) — inlier 중 가장 빈번한 zone_label
+5. **centroid** (`_zone_centroid`) — dominant zone 점들의 평균
+
+### 4.3 `contact_mapper.py` — `ContactMapper`
+
+패턴 centroid를 contact_angle.csv와 매칭.
+
+**핵심 API**: `map_pattern(pattern, centroid_x, centroid_y) → DataFrame`
+
+**좌표계**: 모든 각도는 **수학(atan2) 반시계**, 0°=3시 방향.
+
+`Contact_Angle θ` → edge 좌표 변환: `P = (150·cos θ, 150·sin θ)`
+
+| 패턴 | 후보 행 | 거리 정의 |
+|------|---------|-----------|
+| 선형 | `Defect_Direction == "Line"` | `\|P.x - centroid_x\|` |
+| 군집 | `Defect_Direction != "Line"` | `√((P.x-cx)² + (P.y-cy)²)` |
+| 환형 | `Defect_Direction != "Line"` | 거리 계산 안 함 (전체 반환) |
+
+`tolerance_mm` 이하 통과 후보만 가까운 순 정렬 반환.
+
+### 4.4 `pattern_analyzer.py` — `LLSPatternAnalyzer`
+
+위 3개 클래스를 조합하는 일자별 일괄 처리 오케스트레이터.
+
+**핵심 API**: `run(mode) → DataFrame`
+
+**두 가지 모드**:
+- `"by_cst"`: CAR_ID × HIS_REGIST_DTTM 그룹별 (세밀)
+- `"daily"`: 하루 전체 통합 (트렌드)
+
+**Mode 1만의 특징**:
+- `is_significant` 플래그로 유의/비유의 구분
+- 분류 실패해도 필터링된 결함은 `filtered_defects/*.parquet`에 항상 저장
+- 시각화는 `significant/` vs `others/` 폴더 분리
+
+---
+
+## 5. 설정 파일 (`lls_config.json`)
+
+```jsonc
+{
+  "preprocessing": {
+    "d_size_min": 0.037,             // d_size 필터 최소값 (mm)
+    "inner_radius_mm": 105.0,        // Inner/Outer zone 경계
+    "cell_size_mm": 3.0,             // fine-grid cell 크기
+    "n1_min_wafers": 2,              // cell당 최소 unique wafer 수
+    "n2_min_zone_defects": 3         // cell당 최소 결함 수
+                                     //   (구버전 호환: n2_min_cell_defects도 인식)
+  },
+  "clustering": {
+    "min_cluster_size": 3,           // HDBSCAN 최소 클러스터 크기
+    "min_samples": 2,
+    "cluster_selection_method": "leaf",
+    "dbscan_eps": 20.0,              // 1차 fallback DBSCAN eps
+    "cluster_dbscan_eps": 15.0       // 서브클러스터 DBSCAN eps
+  },
+  "lof": {
+    "lof_min_points": 5,             // LOF 적용 최소 inlier 수
+    "lof_n_neighbors": 13,
+    "lof_contamination": 0.07
+  },
+  "cluster": {
+    "cluster_compactness_radius": 25.0  // 군집 compactness 한계
+  },
+  "linear": {
+    "linear_pca_ratio_min": 2.5,     // 선형 판정 PCA √eig_ratio 최소
+    "linear_max_deviation": 30.0,    // 직선 평균 편차 한계 (mm)
+    "linear_min_length": 5.0,        // 선형 최소 길이 (mm)
+    "linear_max_gap_ratio": 0.5,
+    "centroid_linear_min_length": 20.0,
+    "centroid_linear_pca_min": 2.0,
+    "centroid_linear_dev_max": 25.0
+  },
+  "ring": {
+    "ring_min_points": 10,
+    "ring_band_width": 3.0,          // r-히스토그램 bin 폭 (mm)
+    "ring_r_absolute_tolerance": 10.0,
+    "ring_min_angular_coverage": 200.0,
+    "ring_min_sectors": 7,           // 12 sector 중 최소 몇 개
+    "ring_fit_rmse_max": 10
+    // (선택) "ring_pca_ratio_max": 2.5  // 환형 선형성 거부 임계
+  },
+  "misc": {
+    "min_points_for_clustering": 3
+  },
+  // (선택) Mode 1 유의 패턴 판정
+  "mode_daily": {
+    "min_defect_count": 30,
+    "min_wafer_count": 3,
+    "excluded_patterns": ["Others", "정상/미달", "데이터 없음", "None"]
+  },
+  // (선택) Contact 매핑
+  "contact_mapping": {
+    "tolerance_mm": 30.0,
+    "top_n": 5
+  }
+}
+```
+
+---
+
+## 6. 사용법
+
+### CLI 실행
+
+```bash
+# 데이터 수집
+python 0.ingest_daily_LLS.py
+
+# 패턴 분석 (Mode 2: 기본)
+python pattern_analyzer.py
+python pattern_analyzer.py by_cst
+
+# 패턴 분석 (Mode 1: daily 통합)
+python pattern_analyzer.py daily
+```
+
+### Python API
+
+```python
+from pattern_analyzer import LLSPatternAnalyzer
+
+analyzer = LLSPatternAnalyzer(
+    config_path="./lls_config.json",
+    daily_input_dir="./daily",
+    output_dir="./result_daily",
+    contact_csv="./contact_angle.csv",
+)
+df_daily = analyzer.run(mode="daily")     # 일자별 통합
+df_by_cst = analyzer.run(mode="by_cst")   # CST × 스캔시각
+```
+
+### 단독 클래스 사용
+
+```python
+# 패턴 분류만
+from pattern_detection import PatternDetector
+from utils import WaferUtils
+
+config = WaferUtils.load_config("./lls_config.json")
+detector = PatternDetector(config)
+result_df, dominant_zone, pattern_list, centroid = detector.classify(df_sample)
+
+# Contact 매핑만
+from contact_mapper import ContactMapper
+
+cm = ContactMapper("./contact_angle.csv", tolerance_mm=30.0)
+candidates = cm.map_pattern("군집", centroid_x=130, centroid_y=0)
+
+# 전처리만
+df_grid = WaferUtils.assign_fine_grid(df_raw, cell_size_mm=3.0)
+df_zone = WaferUtils.add_zone_labels(df_grid, inner_radius=105.0)
+df_filt = WaferUtils.filter_by_cell_wafer_count(df_zone, n1_min_wafer=2)
+```
+
+자세한 예제는 `demo_LLS_pattern_analysis.ipynb` 참조.
+
+---
+
+## 7. 출력 구조
+
+```
+./result_daily/
+├── by_cst/                              # Mode 2 일자별 CST 결과
+│   └── YYYYMMDD_LLS_CST_analysis.csv
+│
+├── daily_agg/                           # Mode 1 일자별 통합 결과
+│   ├── YYYYMMDD_LLS_daily_analysis.csv
+│   └── filtered_defects/
+│       └── YYYYMMDD_filtered.parquet    # 필터 통과 결함 (분류 무관)
+│
+├── figures_by_cst/                      # Mode 2 시각화
+│   └── YYYYMMDD/
+│       └── {CST_ID}_{HIS_REGIST_DTTM}.jpg
+│
+├── figures_daily/                       # Mode 1 시각화
+│   ├── significant/DAILY_YYYYMMDD.jpg   # 유의 패턴
+│   └── others/DAILY_YYYYMMDD.jpg        # 비유의
+│
+├── config_used/                         # 재현성용 config 백업
+│   └── YYYYMMDD_HHMMSS_config.json
+│
+├── LLS_by_cst_full_analysis.csv         # 전체 기간 통합 결과 (Mode 2)
+└── LLS_daily_agg_full_analysis.csv      # 전체 기간 통합 결과 (Mode 1)
+```
+
+### CSV 컬럼 (record 단위)
+
+| 컬럼 | 의미 |
+|------|------|
+| `status` | 처리 상태 ("Success") |
+| `mode` | "by_cst" / "daily" |
+| `is_significant` | (Mode 1만) 유의 패턴 여부 |
+| `CST_ID` | 캐리어 ID (Mode 1은 "ALL") |
+| `HIS_REGIST_DTTM` | 8030 공정 시각 (Mode 1은 일자) |
+| `EQP_NM_8030` | 8030 공정 설비명 (mode 값) |
+| `analysis_date` | 분석 일자 |
+| `wafer_count` | 그룹 내 unique wafer 수 |
+| `defect_count` | 분류 대상 결함 수 |
+| `overall_pattern` | 검출된 패턴 ("환형"/"선형"/"군집"/"Others") |
+| `overall_dominant_zone` | 주요 zone 라벨 |
+| `main_centroid_x`, `_y` | 패턴 중심 좌표 (mm) |
+| `main_centroid_Angle` | 중심 각도 (math 반시계, 0~360°) |
+| `main_centroid_Distance` | 원점에서 중심까지 거리 |
+| `contact_candidate_count` | 매칭된 후보 총 개수 |
+| `contact_candidates` | "EQP_TYPE:Part \| ..." top-N 요약 |
+
+---
+
+## 8. 패턴 분류 알고리즘
+
+### 8.1 전처리 (n1, n2 필터)
+
+```
+[원본 결함]
+    │
+    ▼
+fine-grid 할당: 좌표 → cell_id ("cx_cy" 형식)
+    │
+    ▼
+n1 필터: 같은 cell에서 결함이 발생한 wafer 수 ≥ n1_min_wafers
+   ↳ 의도: "여러 wafer에 공통 발생한 위치만 의미 있다"
+    │
+    ▼
+n2 필터: cell당 결함 수 ≥ n2_min_cell_defects
+   ↳ 의도: "충분한 결함이 응집된 cell만 분류 대상"
+```
+
+### 8.2 패턴 판정 우선순위
+
+```
+                  ┌─ HDBSCAN inlier 추출
+                  │
+                  ▼
+                LOF로 2차 outlier 제거
+                  │
+                  ▼
+           ┌──────┴───────┐
+           │ 환형 검사    │  (PCA 선형성 거부 → main band → 원 피팅)
+           └──────┬───────┘
+                  │ ─yes─→ ["환형"], centroid=inlier 평균
+                  │
+                  │ no
+                  ▼
+           ┌──────┴───────┐
+           │ 선형 검사    │  (전체 inlier PCA + 편차 + gap)
+           └──────┬───────┘
+                  │ ─yes─→ ["선형"], centroid=dominant zone 평균
+                  │
+                  │ no
+                  ▼
+           ┌──────┴───────┐
+           │ 군집 분석    │  (DBSCAN 서브 → 중심점 일직선? / 각자 분류)
+           └──────┬───────┘
+                  ▼
+                ["군집"] 또는 sub-clusters 다수결
+```
+
+### 8.3 환형 검출 — 5단계 게이트
+
+1. **포인트 수**: `n >= ring_min_points`
+2. **PCA 선형성 거부**: `√(eig_ratio) < ring_pca_ratio_max` (원점 통과 선형 false-positive 방지)
+3. **r-band 응집**: top r-bin 점들의 `r.max - r.min ≤ ring_r_absolute_tolerance`
+4. **각도 커버리지**: `circular_range >= ring_min_angular_coverage` AND `sector >= ring_min_sectors`
+5. **원 피팅**: `RMSE <= ring_fit_rmse_max` AND `중심점 원점 거리 <= 10mm`
+
+### 8.4 선형 검출
+
+- PCA 1차 eigenvalue / 2차 eigenvalue 비율의 sqrt ≥ `linear_pca_ratio_min`
+- 주축 직각방향 평균 편차 ≤ `linear_max_deviation`
+- 주축 투영 후 최대 gap / 전체 길이 ≤ `linear_max_gap_ratio`
+- 전체 길이 ≥ `linear_min_length`
+
+### 8.5 군집 검출
+
+- 환형/선형 모두 아닌 경우 default
+- 서브 DBSCAN으로 분할
+  - 서브클러스터 ≥2 + 중심점들이 일직선 → 선형 재분류
+  - 그 외: 각 ���브를 군집/선형으로 라벨링 후 다수결
+
+---
+
+## 9. Contact 매핑 로직
+
+### 9.1 좌표 변환
+
+```
+Contact_Angle θ (math 반시계 기준)
+    │
+    ▼
+edge 좌표: P = (150·cos θ, 150·sin θ)
+```
+
+예시:
+- θ=0° → P=(150, 0)  (3시)
+- θ=90° → P=(0, 150)  (12시)
+- θ=180° → P=(-150, 0) (9시)
+- θ=270° → P=(0, -150) (6시)
+
+### 9.2 패턴별 거리
+
+| 패턴 | 거리 | 의미 |
+|------|------|------|
+| **선형** | `\|P.x - centroid_x\|` | Y축 평행선과 contact point의 수평 거리 |
+| **군집** | `√((P.x-cx)² + (P.y-cy)²)` | centroid와 contact point의 2D 거리 |
+| **환형** | 계산 안 함 | 각도 무관, 전체 후보 반환 |
+
+### 9.3 후보 필터링/정렬
+
+1. tolerance 통과: `distance_mm <= tolerance_mm`
+2. 가까운 순 정렬
+3. top-N 요약: `"EQP_TYPE:Part | EQP_TYPE:Part | ..."`
+
+### 9.4 `contact_angle.csv` 형식
+
+| 컬럼 | 내용 | 비고 |
+|------|------|------|
+| `EQP_TYPE` | 설비 타입 | EPI_REACTOR, EBIS, AVIS, SP3, Wafersight, Wafersight2 |
+| `Part` | 설비 내 부위 | FI Robot, Aligner, Chuck, Edge Stage 등 |
+| `Contact_Angle` | 각도 (0~360°) | math 반시계 기준 |
+| `Defect_Direction` | "Line" 또는 공란 | Line=선형 매칭용, 공란=군집/환형용 |
+
+원본 CSV 4번째 컬럼 헤더가 인코딩 깨지는 경우 위치 기반으로 강제 rename.
+
+---
+
+## 10. 검증 및 테스트
+
+### 10.1 합성 데이터 검증 (`test_synthetic_7days.py`)
+
+7일치 의도적 패턴을 가진 합성 데이터로 분석기 동작 확인.
+
+| 일자 | 의도 패턴 | 기대 contact 매칭 |
+|------|----------|-------------------|
+| 20260101 | 환형 r=85 | Line 제외 전체 |
+| 20260102 | 선형 x=38 | EPI:FI Robot 75°, T/C Blade 75° 등 (cos≈0.26) |
+| 20260103 | 군집 (135, 0) | EPI:FI FOUP 0°, EBIS:Edge Stage 0° |
+| 20260104 | 군집 (0, 140) | EBIS:Edge Stage 90°, Back Stage 90° |
+| 20260105 | 군집 (-135, 0) | EPI:FI FOUP 180°, EBIS:Edge Stage 180° |
+| 20260106 | 선형 x=-141 | AVIS:Flipper 158°/197° |
+| 20260107 | 군집 (50, 50) | **매칭 없음** (negative test) |
+
+실행:
+```bash
+python test_synthetic_7days.py
+```
+
+### 10.2 실습 노트북 (`demo_LLS_pattern_analysis.ipynb`)
+
+각 클래스 단독 사용법 + 전체 파이프라인 시연.
+
+```bash
+jupyter notebook demo_LLS_pattern_analysis.ipynb
+```
+
+---
+
+## 11. 확장/튜닝 가이드
+
+### 11.1 임계치 튜닝 절차
+
+1. **합성 데이터로 baseline 확보** — `test_synthetic_7days.py` 결과가 의도와 일치하는지 확인
+2. **실제 데이터 sample 분석** — `LLS_by_cst_full_analysis.csv`의 패턴 분포 검토
+3. **오분류 케이스 검토** — `figures_by_cst/`에서 의심 사례 시각 확인
+4. **config 조정 후 재분석** — 한 번에 하나의 파라미터만 변경 권장
+
+### 11.2 자주 조정하는 파라미터
+
+| 증상 | 조정 |
+|------|------|
+| 너무 많은 noise가 inlier로 잡힘 | `lof_contamination` ↑, `n1_min_wafers` ↑ |
+| 환형 false positive (선형이 환형으로) | `ring_pca_ratio_max` ↓ |
+| 선형 underdetect | `linear_pca_ratio_min` ↓, `linear_max_deviation` ↑ |
+| 군집이 너무 잘게 쪼개짐 | `cluster_dbscan_eps` ↑ |
+| Contact 후보가 너무 많음 | `contact_mapping.tolerance_mm` ↓ |
+| Contact 후보가 안 잡힘 | `contact_mapping.tolerance_mm` ↑ |
+
+### 11.3 새 패턴 타입 추가
+
+1. `pattern_detection.PatternDetector`에 `_is_my_pattern()` 메서드 추가
+2. `classify()`의 판정 우선순위에 끼워 넣기
+3. `utils.PATTERN_COLORS`에 색상 추가
+4. `contact_mapper`의 매칭 규칙 확장 (필요 시)
+5. `mode_daily.excluded_patterns`에 추가 (필요 시)
+
+### 11.4 새 설비 부위 추가
+
+1. `contact_angle.csv`에 행 추가 (EQP_TYPE, Part, Contact_Angle, Defect_Direction)
+2. 별도 코드 수정 없이 자동 반영됨
+
+---
+
+## 부록 A. 파일 목록
+
+| 파일 | 종류 | 설명 |
+|------|------|------|
+| `lls_config.json` | 설정 | 분석 파라미터 |
+| `contact_angle.csv` | 데이터 | 설비 접촉 각도 테이블 |
+| `utils.py` | 코드 | `WaferUtils` 클래스 |
+| `pattern_detection.py` | 코드 | `PatternDetector` 클래스 |
+| `contact_mapper.py` | 코드 | `ContactMapper` 클래스 |
+| `pattern_analyzer.py` | 코드 | `LLSPatternAnalyzer` 클래스 (메인) |
+| `0.ingest_daily_LLS.py` | 코드 | Trino → parquet 수집 |
+| `test_synthetic_7days.py` | 테스트 | 합성 데이터 검증 |
+| `demo_LLS_pattern_analysis.ipynb` | 문서 | 실습 노트북 |
+| `README.md` | 문서 | 본 문서 |
+
+## 부록 B. 좌표·각도 규약 정리
+
+- **좌표 단위**: mm
+- **웨이퍼 반지름**: 150 mm (0.0 ~ 150.0)
+- **원점**: 웨이퍼 중심
+- **각도 (analyzer 내부)**: math 반시계, 0°=3시(+x), 90°=12시(+y)
+- **각도 (시각화 라벨)**: 시계방향, 12시=0°, 1시=30°, ..., 11시=330°
+- **각도 (contact_angle.csv)**: math 반시계 (analyzer와 동일)
+- **Zone 라벨 형식**: `{Inner|Outer}_{시계위치}` (예: `Inner_03` = 3시 방향 내측)
+
+---
+
+*Last updated: 2026-05-12*

nu/contact_angle.csv

@@ -0,0 +1,103 @@
+EQP_TYPE,Part,Contact_Angle,Defect ���� ����
+EPI_REACTOR,FI FOUP,180,
+EPI_REACTOR,FI FOUP,0,
+EPI_REACTOR,FI Robot,255,Line
+EPI_REACTOR,FI Robot,130,Line
+EPI_REACTOR,FI Robot,50,Line
+EPI_REACTOR,FI Robot,285,Line
+EPI_REACTOR,LDLK Indexer Pin,205,Line
+EPI_REACTOR,LDLK Indexer Pin,155,Line
+EPI_REACTOR,LDLK Indexer Pin,25,Line
+EPI_REACTOR,LDLK Indexer Pin,335,Line
+EPI_REACTOR,T/C Blade,255,Line
+EPI_REACTOR,T/C Blade,285,Line
+EPI_REACTOR,T/C Blade,105,Line
+EPI_REACTOR,T/C Blade,75,Line
+Wafersight,Robot,125,Line
+Wafersight,Robot,55,Line
+Wafersight,Robot,270,Line
+Wafersight,Robot,250,Line
+Wafersight,Robot,290,Line
+Wafersight,Aligner,194,
+Wafersight,Aligner,167,
+Wafersight,Aligner,13,
+Wafersight,Aligner,346,
+Wafersight,Buffer,195,Line
+Wafersight,Buffer,90,Line
+Wafersight,Buffer,345,Line
+Wafersight,Pallet,225,Line
+Wafersight,Pallet,135,Line
+Wafersight,Pallet,0,Line
+Wafersight2,Robot,119,Line
+Wafersight2,Robot,64,Line
+Wafersight2,Robot,270,Line
+Wafersight2,Robot,250,Line
+Wafersight2,Robot,290,Line
+Wafersight2,Aligner,194,
+Wafersight2,Aligner,167,
+Wafersight2,Aligner,13,
+Wafersight2,Aligner,346,
+Wafersight2,Buffer,195,Line
+Wafersight2,Buffer,90,Line
+Wafersight2,Buffer,345,Line
+Wafersight2,Pallet,225,Line
+Wafersight2,Pallet,135,Line
+Wafersight2,Pallet,0,Line
+AVIS,Robot,105,Line
+AVIS,Robot,75,Line
+AVIS,Robot,270,Line
+AVIS,Robot,255,Line
+AVIS,Robot,285,Line
+AVIS,Flipper,197,Line
+AVIS,Flipper,158,Line
+AVIS,Flipper,19,Line
+AVIS,Flipper,339,Line
+AVIS,Inspection,234,Line
+AVIS,Inspection,226,Line
+AVIS,Inspection,131,Line
+AVIS,Inspection,124,Line
+AVIS,Inspection,54,Line
+AVIS,Inspection,45,Line
+AVIS,Inspection,319,Line
+AVIS,Inspection,313,Line
+EBIS,Robot,261,Line
+EBIS,Robot,248,Line
+EBIS,Robot,235,Line
+EBIS,Robot,131,Line
+EBIS,Robot,41,Line
+EBIS,Robot,305,Line
+EBIS,Robot,292,Line
+EBIS,Robot,278,Line
+EBIS,Edge Stage,240,
+EBIS,Edge Stage,210,
+EBIS,Edge Stage,180,
+EBIS,Edge Stage,120,
+EBIS,Edge Stage,90,
+EBIS,Edge Stage,60,
+EBIS,Edge Stage,0,
+EBIS,Edge Stage,330,
+EBIS,Edge Stage,240,
+EBIS,Back Stage,209,
+EBIS,Back Stage,90,
+EBIS,Back Stage,329,
+SP3,Robot,270,Line
+SP3,Robot,251,Line
+SP3,Robot,119,Line
+SP3,Robot,64,Line
+SP3,Robot,291,Line
+SP3,Aligner,227,Line
+SP3,Aligner,211,Line
+SP3,Aligner,157,Line
+SP3,Aligner,151,Line
+SP3,Aligner,107,Line
+SP3,Aligner,47,Line
+SP3,Aligner,31,Line
+SP3,Aligner,347,Line
+SP3,Aligner,331,Line
+SP3,Aligner,287,Line
+SP3,Chuck,232,Line
+SP3,Chuck,193,Line
+SP3,Chuck,112,Line
+SP3,Chuck,73,Line
+SP3,Chuck,352,Line
+SP3,Chuck,313,Line

nu/contact_mapper.py

@@ -0,0 +1,254 @@
+# contact_mapper.py
+"""
+LLS 패턴(centroid + 패턴 타입) → 설비 부위 후보 매핑.
+
+검출된 패턴의 발생 위치를 `contact_angle.csv` (각 설비/Part의 접촉 각도 테이블)에
+조회하여, 결함을 유발했을 가능성이 있는 설비 부위 후보 리스트를 반환한다.
+
+좌표계 / 각도 규약
+------------------
+- 모든 각도는 **수학(atan2) 반시계 기준**, 0°=3시 방향(+x).
+- `Contact_Angle θ`를 웨이퍼 edge (r=150mm) 좌표로 변환:
+      P_contact = (150·cos θ, 150·sin θ)
+
+패턴별 매칭 규칙
+----------------
++--------+--------------------+-------------------------------------------+
+| 패턴   | 후보 행 (CSV)      | 거리 정의                                 |
++========+====================+===========================================+
+| 선형   | Defect_Direction   | |P.x - centroid_x|  (Y축 평행선과 P의 수평거리) |
+|        | == "Line" 만       |                                           |
++--------+--------------------+-------------------------------------------+
+| 군집   | Defect_Direction   | √((P.x-cx)² + (P.y-cy)²) (유클리드)        |
+|        | != "Line" 만       |                                           |
++--------+--------------------+-------------------------------------------+
+| 환형   | Defect_Direction   | 거리 계산 안 함 (각도 무관, 전체 반환)     |
+|        | != "Line" 만       |                                           |
++--------+--------------------+-------------------------------------------+
+
+CSV 형식 (`contact_angle.csv`)
+------------------------------
+1열: EQP_TYPE         (예: EPI_REACTOR, EBIS, AVIS, SP3, Wafersight...)
+2열: Part             (예: FI Robot, Aligner, Chuck, Edge Stage...)
+3열: Contact_Angle    (0~360°, math 기준)
+4열: Defect_Direction (Line | 공란)
+
+* 원본 CSV의 4열 헤더가 인코딩 깨짐(예: "Defect ���� ����") 가능하므로
+  ``_load_contact_table()``에서 컬럼 위치 기반으로 강제 rename한다.
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+
+# ----------------------------------------------------------------------
+# 상수
+# ----------------------------------------------------------------------
+# 웨이퍼 반지름 (mm). edge contact point 좌표 산출 시 사용.
+WAFER_RADIUS_MM = 150.0
+
+# CSV 4번째 컬럼 (원본 헤더가 깨질 수 있어 내부에서 강제 사용할 별칭).
+CONTACT_COL_DIRECTION = "Defect_Direction"
+
+
+# ----------------------------------------------------------------------
+# 내부 헬퍼
+# ----------------------------------------------------------------------
+def _load_contact_table(csv_path: str) -> pd.DataFrame:
+    """
+    contact_angle.csv 로드 및 정규화.
+
+    - 컬럼명은 **위치 기반**으로 강제 rename → EQP_TYPE / Part / Contact_Angle /
+      Defect_Direction (원본 헤더 깨짐 대응).
+    - Contact_Angle을 numeric으로 변환, 결측 행 제거.
+    - Defect_Direction은 NaN → "" 변환 + 양끝 공백 strip.
+    """
+    df = pd.read_csv(csv_path, encoding="utf-8", header=0)
+    cols = list(df.columns)
+    rename_map = {
+        cols[0]: "EQP_TYPE",
+        cols[1]: "Part",
+        cols[2]: "Contact_Angle",
+        cols[3]: CONTACT_COL_DIRECTION,
+    }
+    df = df.rename(columns=rename_map)
+    df["Contact_Angle"] = pd.to_numeric(df["Contact_Angle"], errors="coerce")
+    df = df.dropna(subset=["Contact_Angle"]).reset_index(drop=True)
+    df[CONTACT_COL_DIRECTION] = (
+        df[CONTACT_COL_DIRECTION].fillna("").astype(str).str.strip()
+    )
+    return df
+
+
+# ======================================================================
+# ContactMapper
+# ======================================================================
+class ContactMapper:
+    """
+    설비 접촉 각도 테이블을 활용한 패턴-설비 매핑기.
+
+    Parameters
+    ----------
+    csv_path : str
+        ``contact_angle.csv`` 경로.
+    tolerance_mm : float
+        Edge contact point로부터의 매칭 허용 거리 (mm 단위 grid).
+        선형: x축 거리, 군집: 2D 유클리드 거리에 적용.
+
+    Attributes
+    ----------
+    df : pd.DataFrame
+        정규화된 contact 테이블 (`contact_x`, `contact_y` 컬럼 포함).
+
+    Examples
+    --------
+    >>> cm = ContactMapper("./contact_angle.csv", tolerance_mm=30.0)
+    >>> cm.map_pattern("선형", centroid_x=38.0, centroid_y=0.0)
+    >>> cm.map_pattern("군집", centroid_x=130, centroid_y=0)
+    >>> cm.map_pattern("환형")
+    """
+
+    def __init__(self, csv_path: str, tolerance_mm: float = 30.0):
+        if not os.path.exists(csv_path):
+            raise FileNotFoundError(f"contact CSV 없음: {csv_path}")
+        self.tolerance_mm = tolerance_mm
+        self.df = _load_contact_table(csv_path)
+
+        # edge contact point 좌표 사전 계산 (math 반시계 기준)
+        theta_rad = np.deg2rad(self.df["Contact_Angle"].values)
+        self.df["contact_x"] = WAFER_RADIUS_MM * np.cos(theta_rad)
+        self.df["contact_y"] = WAFER_RADIUS_MM * np.sin(theta_rad)
+
+    # ------------------------------------------------------------------
+    # 내부 행 필터
+    # ------------------------------------------------------------------
+    def _line_rows(self) -> pd.DataFrame:
+        """Defect_Direction == 'Line' 행만."""
+        return self.df[self.df[CONTACT_COL_DIRECTION].str.lower() == "line"].copy()
+
+    def _non_line_rows(self) -> pd.DataFrame:
+        """Defect_Direction != 'Line' 행만 (공란 등)."""
+        return self.df[self.df[CONTACT_COL_DIRECTION].str.lower() != "line"].copy()
+
+    def _all_rows(self) -> pd.DataFrame:
+        """전체 행 (현재 미사용, 확장용)."""
+        return self.df.copy()
+
+    # ------------------------------------------------------------------
+    # 패턴별 매칭 메서드
+    # ------------------------------------------------------------------
+    def match_linear(self, centroid_x: float) -> pd.DataFrame:
+        """
+        선형 패턴 매칭.
+
+        해석: 결함이 (centroid_x, *)를 지나는 **Y축 평행선** 형태.
+        거리: ``|P.x - centroid_x|`` (= |150·cos θ - centroid_x|)
+
+        Parameters
+        ----------
+        centroid_x : float
+            패턴 centroid의 x좌표.
+
+        Returns
+        -------
+        pd.DataFrame
+            tolerance 통과 행만, distance_mm 오름차순.
+        """
+        rows = self._line_rows()
+        if rows.empty:
+            return rows
+        rows = rows.assign(distance_mm=np.abs(rows["contact_x"] - centroid_x))
+        return rows[rows["distance_mm"] <= self.tolerance_mm].sort_values("distance_mm")
+
+    def match_cluster(self, centroid_x: float, centroid_y: float) -> pd.DataFrame:
+        """
+        군집 패턴 매칭.
+
+        해석: 결함이 (cx, cy) 한 점에 응집.
+        거리: ``√((P.x-cx)² + (P.y-cy)²)`` (2D 유클리드)
+
+        Note: 군집은 Line이 아닌 행만 (선형 전용 접촉부 제외).
+        """
+        rows = self._non_line_rows()
+        rows = rows.assign(
+            distance_mm=np.sqrt(
+                (rows["contact_x"] - centroid_x) ** 2
+                + (rows["contact_y"] - centroid_y) ** 2
+            )
+        )
+        return rows[rows["distance_mm"] <= self.tolerance_mm].sort_values("distance_mm")
+
+    def match_ring(self) -> pd.DataFrame:
+        """
+        환형 패턴 매칭.
+
+        해석: 결함이 전 각도에 분포 → 특정 위치 매칭 불가.
+        반환: Line 표시 없는 전체 행 (각도 무관). distance_mm는 NaN.
+        """
+        return self._non_line_rows().assign(distance_mm=np.nan)
+
+    # ------------------------------------------------------------------
+    # 통합 디스패처
+    # ------------------------------------------------------------------
+    def map_pattern(
+        self,
+        pattern: str,
+        centroid_x: Optional[float] = None,
+        centroid_y: Optional[float] = None,
+    ) -> pd.DataFrame:
+        """
+        패턴명에 따라 적절한 매칭 메서드 호출.
+
+        Parameters
+        ----------
+        pattern : str
+            "환형" / "선형" / "군집" (쉼표 결합 문자열도 허용 — 첫 토큰만 사용).
+        centroid_x, centroid_y : float, optional
+            환형이 아닌 경우 필수.
+
+        Returns
+        -------
+        pd.DataFrame
+            컬럼: EQP_TYPE, Part, Contact_Angle, Defect_Direction,
+                  contact_x, contact_y, distance_mm.
+            매칭 없으면 빈 DF.
+        """
+        if pattern is None:
+            return pd.DataFrame()
+        pat = (pattern.split(",")[0].strip()
+               if isinstance(pattern, str) else str(pattern))
+
+        if pat == "환형":
+            return self.match_ring()
+        if centroid_x is None or centroid_y is None:
+            return pd.DataFrame()
+        if pat == "선형":
+            return self.match_linear(centroid_x)
+        if pat == "군집":
+            return self.match_cluster(centroid_x, centroid_y)
+        return pd.DataFrame()
+
+    # ------------------------------------------------------------------
+    # 요약 헬퍼
+    # ------------------------------------------------------------------
+    def summarize_candidates(
+        self, candidates: pd.DataFrame, top_n: int = 5
+    ) -> str:
+        """
+        후보 DF를 "EQP_TYPE:Part | ..." 형식의 요약 문자열로 변환.
+
+        Parameters
+        ----------
+        candidates : pd.DataFrame
+            ``map_pattern()`` 반환 DF (이미 distance_mm 오름차순).
+        top_n : int
+            상위 몇 개를 포함할지.
+        """
+        if candidates.empty:
+            return ""
+        head = candidates.head(top_n)
+        return " | ".join(f"{r['EQP_TYPE']}:{r['Part']}" for _, r in head.iterrows())

nu/demo_LLS_pattern_analysis.ipynb

@@ -0,0 +1,411 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# LLS 결함 패턴 분석 실습 노트북\n",
+    "\n",
+    "이 노트북은 `LLSPatternAnalyzer`, `PatternDetector`, `ContactMapper`, `WaferUtils` 4개 클래스 사용법을 단계별로 보여줍니다.\n",
+    "\n",
+    "## 목차\n",
+    "1. 환경 준비 및 import\n",
+    "2. 합성 결함 데이터 생성 (7일치)\n",
+    "3. `LLSPatternAnalyzer` 초기화\n",
+    "4. Mode 1 (daily aggregated) 실행\n",
+    "5. Mode 2 (by_cst) 실행\n",
+    "6. 결과 CSV 조회\n",
+    "7. 시각화 이미지 표시\n",
+    "8. `PatternDetector` 단독 사용\n",
+    "9. `ContactMapper` 단독 사용\n",
+    "10. `WaferUtils` 유틸 단독 활용"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. 환경 준비 및 import\n",
+    "\n",
+    "현재 작업 디렉터리에 `utils.py`, `pattern_detection.py`, `contact_mapper.py`, `pattern_analyzer.py`, `lls_config.json`, `contact_angle.csv` 가 있어야 합니다."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "import sys\n",
+    "import shutil\n",
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "import matplotlib.pyplot as plt\n",
+    "from IPython.display import Image, display\n",
+    "\n",
+    "# 작업 디렉터리: 이 노트북이 위치한 폴더(scr)로 이동\n",
+    "if not os.path.exists('./lls_config.json'):\n",
+    "    os.chdir(os.path.dirname(os.path.abspath('demo_LLS_pattern_analysis.ipynb')))\n",
+    "sys.path.append(os.getcwd())\n",
+    "\n",
+    "from utils import WaferUtils\n",
+    "from pattern_detection import PatternDetector, classify_wafer_patterns\n",
+    "from contact_mapper import ContactMapper\n",
+    "from pattern_analyzer import LLSPatternAnalyzer\n",
+    "\n",
+    "print('✅ 모듈 import 완료')\n",
+    "print('  cwd =', os.getcwd())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. 합성 결함 데이터 생성 (7일치)\n",
+    "\n",
+    "실제 Trino DB 연결 없이도 분석기를 시연하기 위해 의도적 패턴을 가진 7일치 parquet을 생성합니다.\n",
+    "각 일자마다 다른 contact angle과 매칭되도록 좌표를 배치합니다."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 작업 디렉터리 준비\n",
+    "WORK_ROOT = './_demo_run'\n",
+    "DAILY_DIR = os.path.join(WORK_ROOT, 'daily')\n",
+    "OUTPUT_DIR = os.path.join(WORK_ROOT, 'result')\n",
+    "if os.path.exists(WORK_ROOT):\n",
+    "    shutil.rmtree(WORK_ROOT)\n",
+    "os.makedirs(DAILY_DIR, exist_ok=True)\n",
+    "\n",
+    "\n",
+    "def base_record(car_id, waf_id, dttm, eqp='EQP_A'):\n",
+    "    return {\n",
+    "        'SUBLOT_ID': f'S{car_id}', 'CAR_ID': car_id, 'SCAN_TIME': dttm,\n",
+    "        'EQP_ID_8210': 'L01', 'EQP_ID_8030': eqp,\n",
+    "        'ROUTE_ID': 'WF7EP01', 'PROD_ID': 'P001',\n",
+    "        'HIS_REGIST_DTTM_8030': dttm, 'HIS_REGIST_DTTM_Pcounter': dttm,\n",
+    "        'WAF_ID': waf_id, 'DEFECT_CNT': 100, 'OPE_ID': '8210',\n",
+    "        'test_no': 1, 'roughbin_no': 0, 'd_size': 0.05,\n",
+    "        'LLS 구분': 'LPD', 'Particle 분포': '면내',\n",
+    "    }\n",
+    "\n",
+    "\n",
+    "def make_ring(n=400, radius=85, noise=3.0):\n",
+    "    th = np.random.uniform(0, 2*np.pi, n)\n",
+    "    r = np.random.normal(radius, noise, n)\n",
+    "    return r*np.cos(th), r*np.sin(th)\n",
+    "\n",
+    "\n",
+    "def make_vertical_line(n=300, x_center=38, y_range=(-60, 60), noise=3.0):\n",
+    "    y = np.random.uniform(*y_range, n)\n",
+    "    x = np.full(n, x_center) + np.random.normal(0, noise, n)\n",
+    "    return x, y\n",
+    "\n",
+    "\n",
+    "def make_cluster(n=300, center=(130, 0), spread=10):\n",
+    "    x = np.random.normal(center[0], spread, n)\n",
+    "    y = np.random.normal(center[1], spread, n)\n",
+    "    return x, y\n",
+    "\n",
+    "\n",
+    "def build_day(day_idx, date_str, pattern_specs, wafers_per_cst=5, n_csts=2):\n",
+    "    rows = []\n",
+    "    for cst_i in range(n_csts):\n",
+    "        car_id = f'C{day_idx:02d}{cst_i}'\n",
+    "        dttm = f'2026010{day_idx}120000'\n",
+    "        px, py = pattern_specs[cst_i % len(pattern_specs)]\n",
+    "        for w in range(wafers_per_cst):\n",
+    "            waf_id = f'{car_id}W{w:02d}'\n",
+    "            jx = px + np.random.normal(0, 1.5, len(px))\n",
+    "            jy = py + np.random.normal(0, 1.5, len(py))\n",
+    "            for x, y in zip(jx, jy):\n",
+    "                rec = base_record(car_id, waf_id, dttm)\n",
+    "                rec['coor_x'] = float(x); rec['coor_y'] = float(y)\n",
+    "                rec['ANGLE'] = (np.arctan2(y, x)/np.pi*180 + 360) % 360\n",
+    "                rec['DISTANCE'] = float(np.sqrt(x**2 + y**2))\n",
+    "                rows.append(rec)\n",
+    "    return pd.DataFrame(rows)\n",
+    "\n",
+    "\n",
+    "np.random.seed(42)\n",
+    "day_configs = {\n",
+    "    '20260101': [make_ring(400, 85), make_ring(400, 85)],                              # 환형\n",
+    "    '20260102': [make_vertical_line(300, 38), make_vertical_line(300, 38)],            # 선형 x=38\n",
+    "    '20260103': [make_cluster(300, (135, 0), 8), make_cluster(300, (135, 0), 8)],      # 군집 @ 3시 edge\n",
+    "    '20260104': [make_cluster(300, (0, 140), 8), make_cluster(300, (0, 140), 8)],      # 군집 @ 12시 edge\n",
+    "    '20260105': [make_cluster(300, (-135, 0), 8), make_cluster(300, (-135, 0), 8)],    # 군집 @ 9시 edge\n",
+    "    '20260106': [make_vertical_line(300, -141), make_vertical_line(300, -141)],        # 선형 x=-141\n",
+    "    '20260107': [make_cluster(300, (50, 50), 10), make_cluster(300, (50, 50), 10)],    # 군집 (매칭 없음)\n",
+    "}\n",
+    "for i, (date, specs) in enumerate(day_configs.items(), start=1):\n",
+    "    df = build_day(i, date, specs, wafers_per_cst=5, n_csts=2)\n",
+    "    df.to_parquet(os.path.join(DAILY_DIR, f'{date}.parquet'), index=False)\n",
+    "    print(f'  생성 {date}: {len(df):>5}건, CST {df[\"CAR_ID\"].nunique()}, WAF {df[\"WAF_ID\"].nunique()}')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. `LLSPatternAnalyzer` 초기화\n",
+    "\n",
+    "- `config_path` : 분석 파라미터가 담긴 JSON\n",
+    "- `daily_input_dir` : 일자별 parquet 폴더\n",
+    "- `output_dir` : 결과 저장 루트\n",
+    "- `contact_csv` : contact 매핑 활성화 (None이면 비활성)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "analyzer = LLSPatternAnalyzer(\n",
+    "    config_path='./lls_config.json',\n",
+    "    daily_input_dir=DAILY_DIR,\n",
+    "    output_dir=OUTPUT_DIR,\n",
+    "    contact_csv='./contact_angle.csv',\n",
+    "    setup_font=True,\n",
+    ")\n",
+    "print('cell_size_mm     =', analyzer.cell_size_mm)\n",
+    "print('n1_min_wafers    =', analyzer.n1_min_wafers)\n",
+    "print('n2_min_cell_def  =', analyzer.n2_min_cell_defects)\n",
+    "print('inner_radius_mm  =', analyzer.inner_radius_mm)\n",
+    "print('contact_tol_mm   =', analyzer.contact_tolerance_mm)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Mode 1 (daily aggregated) 실행\n",
+    "\n",
+    "하루 전체 결함을 1회 분류 + contact 매핑."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df_daily = analyzer.run(mode='daily')\n",
+    "cols = ['analysis_date', 'overall_pattern', 'is_significant',\n",
+    "        'wafer_count', 'defect_count',\n",
+    "        'main_centroid_x', 'main_centroid_y',\n",
+    "        'contact_candidate_count', 'contact_candidates']\n",
+    "with pd.option_context('display.max_colwidth', 120, 'display.width', 180):\n",
+    "    display(df_daily[cols])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. Mode 2 (by_cst) 실행\n",
+    "\n",
+    "CAR_ID × HIS_REGIST_DTTM 그룹별 세밀 분류."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df_by_cst = analyzer.run(mode='by_cst')\n",
+    "cols = ['analysis_date', 'CST_ID', 'overall_pattern',\n",
+    "        'main_centroid_x', 'main_centroid_y',\n",
+    "        'contact_candidate_count', 'contact_candidates']\n",
+    "with pd.option_context('display.max_colwidth', 120, 'display.width', 180):\n",
+    "    display(df_by_cst[cols])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. 결과 CSV/parquet 파일 확인"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for root, _, files in os.walk(OUTPUT_DIR):\n",
+    "    rel = os.path.relpath(root, OUTPUT_DIR)\n",
+    "    for f in sorted(files):\n",
+    "        print(f'  {rel}/{f}')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 7. 시각화 이미지 표시\n",
+    "\n",
+    "Mode 1 일자별 통합 이미지를 모두 표시."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sig_dir = os.path.join(OUTPUT_DIR, 'figures_daily', 'significant')\n",
+    "imgs = sorted(f for f in os.listdir(sig_dir) if f.endswith('.jpg'))\n",
+    "for f in imgs:\n",
+    "    print(f)\n",
+    "    display(Image(filename=os.path.join(sig_dir, f), width=500))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 8. `PatternDetector` 단독 사용\n",
+    "\n",
+    "분석기 없이 단일 wafer 그룹을 직접 분류해보기."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "config = WaferUtils.load_config('./lls_config.json')\n",
+    "detector = PatternDetector(config)\n",
+    "\n",
+    "# 하루치 데이터 로드 후 한 CAR_ID만 사용\n",
+    "sample_path = os.path.join(DAILY_DIR, '20260103.parquet')\n",
+    "df_sample = pd.read_parquet(sample_path)\n",
+    "df_sample = df_sample[df_sample['CAR_ID'] == df_sample['CAR_ID'].iloc[0]]\n",
+    "\n",
+    "result_df, dominant_zone, pattern_list, centroid = detector.classify(df_sample)\n",
+    "print('패턴       :', pattern_list)\n",
+    "print('Dominant   :', dominant_zone)\n",
+    "print('Centroid   :', centroid)\n",
+    "print('Inlier 수  :', int(result_df['inlier'].sum()))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 9. `ContactMapper` 단독 사용\n",
+    "\n",
+    "임의 centroid 좌표를 입력해서 가능한 설비 부위 후보 조회."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cm = ContactMapper('./contact_angle.csv', tolerance_mm=30.0)\n",
+    "\n",
+    "# 군집 패턴: (130, 0) 에 가까운 비-Line 후보들\n",
+    "print('▶ 군집 매칭 — centroid=(130, 0)')\n",
+    "display(cm.match_cluster(130, 0))\n",
+    "\n",
+    "# 선형 패턴: x=38 vertical line\n",
+    "print('▶ 선형 매칭 — centroid_x=38')\n",
+    "display(cm.match_linear(38).head(10))\n",
+    "\n",
+    "# 환형 패턴: 각도 무관 전체\n",
+    "print('▶ 환형 매칭 (각도 무관)')\n",
+    "display(cm.match_ring().head(10))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 10. `WaferUtils` 유틸 단독 활용\n",
+    "\n",
+    "패턴 분류 없이 전처리/시각화만 수행."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df_raw = pd.read_parquet(os.path.join(DAILY_DIR, '20260101.parquet'))\n",
+    "\n",
+    "# Fine-grid 할당 + Zone 라벨링\n",
+    "df_grid = WaferUtils.assign_fine_grid(df_raw, cell_size_mm=3.0)\n",
+    "df_zone = WaferUtils.add_zone_labels(df_grid, inner_radius=105.0)\n",
+    "\n",
+    "print('총 결함        :', len(df_zone))\n",
+    "print('Unique cells   :', df_zone['cell_id'].nunique())\n",
+    "print('Zone 분포      :')\n",
+    "display(df_zone['zone_label'].value_counts().head())\n",
+    "\n",
+    "# n1 필터\n",
+    "df_filtered = WaferUtils.filter_by_cell_wafer_count(df_zone, n1_min_wafer=2, cell_size_mm=3.0)\n",
+    "summary = WaferUtils.summarize_filtering_result(df_zone, df_filtered)\n",
+    "print('\\n필터링 요약:', summary)\n",
+    "\n",
+    "# 시각화 (직접 호출)\n",
+    "save_path = os.path.join(WORK_ROOT, 'manual_plot.jpg')\n",
+    "WaferUtils.plot_wafer_map(\n",
+    "    result_df=df_filtered.assign(inlier=True),\n",
+    "    key='manual_demo',\n",
+    "    pattern_list=['환형'],\n",
+    "    dominant_zone='Inner_03',\n",
+    "    meta={'wafer_count': df_filtered['WAF_ID'].nunique(),\n",
+    "          'EQP_NM_8030': 'EQP_A',\n",
+    "          'main_centroid_x': 0, 'main_centroid_y': 0},\n",
+    "    save_path=save_path,\n",
+    ")\n",
+    "display(Image(filename=save_path, width=500))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 요약\n",
+    "\n",
+    "| 클래스 | 역할 |\n",
+    "|--------|------|\n",
+    "| `WaferUtils` | 한글 폰트, config 로드, fine-grid/zone 라벨링, n1 필터, 시각화 |\n",
+    "| `PatternDetector` | HDBSCAN + LOF 기반 환형/선형/군집 분류 |\n",
+    "| `ContactMapper` | centroid 좌표 → contact_angle.csv의 설비 부위 매핑 |\n",
+    "| `LLSPatternAnalyzer` | 위 3개 클래스를 조합한 일자별 일괄 처리 (Mode 1/2) |\n",
+    "\n",
+    "프로덕션 운영 시:\n",
+    "1. `0.ingest_daily_LLS.py` 로 Trino → `./daily/*.parquet` 수집 \n",
+    "2. `python pattern_analyzer.py daily` 또는 `by_cst` 로 분석 \n",
+    "3. 결과 CSV/이미지 검토"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

nu/lls_config.json

@@ -0,0 +1,49 @@
+{
+  "experiment": {
+    "name": "LLS_CST_Pattern_Analysis",
+    "version": "2026.04.09",
+    "description": "CST 단위 LLS 결함 맵 자동 분류 (환형/선형/군집)"
+  },
+  "preprocessing": {
+    "d_size_min": 0.037,
+    "inner_radius_mm": 105.0,
+    "cell_size_mm": 3.0,
+    "n1_min_wafers": 2,
+    "n2_min_zone_defects": 3
+  },
+  "clustering": {
+    "min_cluster_size": 3,
+    "min_samples": 2,
+    "cluster_selection_method": "leaf",
+    "dbscan_eps": 20.0,
+    "cluster_dbscan_eps": 15.0
+  },
+  "lof": {
+    "lof_min_points": 5,
+    "lof_n_neighbors": 13,
+    "lof_contamination": 0.07
+  },
+  "cluster": {
+    "cluster_compactness_radius": 25.0
+  },
+  "linear": {
+    "linear_pca_ratio_min": 2.5,
+    "linear_max_deviation": 30.0,
+    "linear_min_length": 5.0,
+    "linear_max_gap_ratio": 0.5,
+    "centroid_linear_min_length": 20.0,
+    "centroid_linear_pca_min": 2.0,
+    "centroid_linear_dev_max": 25.0
+  },
+  "ring": {
+    "ring_min_points": 10,
+    "ring_band_width": 3.0,
+    "ring_r_absolute_tolerance": 10.0,
+    "ring_min_angular_coverage": 200.0,
+    "ring_min_sectors": 7,
+    "ring_fit_rmse_max": 10
+  },
+  "misc": {
+    "min_points_for_clustering": 3
+  }
+}

nu/pattern_analyzer.py

@@ -0,0 +1,561 @@
+# pattern_analyzer.py
+"""
+LLS 일자별 데이터 분석 오케스트레이터.
+
+`./daily/YYYYMMDD.parquet` 형태의 일자별 결함 데이터를 일괄 처리하여
+패턴 분류 + Contact 매핑 + 시각화까지 한 번에 수행한다.
+
+두 가지 실행 모드 지원
+----------------------
+- ``"by_cst"`` : CAR_ID(캐리어) × HIS_REGIST_DTTM(스캔시각) 단위로 분류.
+                동일 캐리어 내 동일 시각 그룹별 패턴 발생 추적에 사용.
+- ``"daily"``  : 하루 전체 결함을 한 그룹으로 합쳐 1회 분류.
+                일자별 공정 트렌드/장비 이상 추적에 사용. 유의 패턴 여부와
+                무관하게 필터링된 결함은 항상 보존.
+
+내부 의존성
+-----------
+- :class:`utils.WaferUtils`        : 전처리·시각화 유틸
+- :func:`pattern_detection.classify_wafer_patterns` : 패턴 분류
+- :class:`contact_mapper.ContactMapper`             : 설비 부위 매핑
+
+출력 구조
+---------
+    output_dir/
+    ├── by_cst/{date}_LLS_CST_analysis.csv          # Mode 2
+    ├── daily_agg/{date}_LLS_daily_analysis.csv     # Mode 1
+    ├── daily_agg/filtered_defects/{date}_filtered.parquet
+    ├── figures_by_cst/{date}/{CST_ID}_{dttm}.jpg
+    ├── figures_daily/{significant|others}/DAILY_{date}.jpg
+    ├── config_used/{ts}_config.json
+    └── LLS_{by_cst|daily_agg}_full_analysis.csv
+"""
+from __future__ import annotations
+
+import os
+import sys
+import shutil
+import glob
+import warnings
+from datetime import datetime
+from typing import Optional, Literal, List
+
+import numpy as np
+import pandas as pd
+import urllib3
+from tqdm import tqdm
+
+from utils import (
+    setup_korean_font, load_config, add_zone_labels, plot_wafer_map,
+    assign_fine_grid, filter_by_cell_wafer_count,
+)
+from pattern_detection import classify_wafer_patterns
+from contact_mapper import ContactMapper
+
+warnings.filterwarnings("ignore")
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+# 실행 모드 타입.
+Mode = Literal["by_cst", "daily"]
+
+# Mode 1(daily aggregated)에서 '유의 패턴' 판정시 기본 제외 라벨.
+EXCLUDED_PATTERNS_DEFAULT = {"Others", "정상/미달", "데이터 없음", "None"}
+
+
+class LLSPatternAnalyzer:
+    """
+    LLS 결함 일자별 분석 오케스트레이터.
+
+    Parameters
+    ----------
+    config_path : str
+        ``lls_config.json`` 경로.
+    daily_input_dir : str
+        일자별 parquet 파일 디렉터리. 파일명은 ``YYYYMMDD.parquet`` 형식이어야 함.
+    output_dir : str
+        모든 결과(CSV, parquet, 이미지)가 저장될 루트 디렉터리.
+    contact_csv : str, optional
+        ``contact_angle.csv`` 경로. None 또는 파일 부재 시 contact 매핑 비활성화.
+    setup_font : bool
+        True 면 시작 시 한글 폰트 등록.
+
+    Attributes
+    ----------
+    config : dict
+        ``lls_config.json`` 트리.
+    contact_mapper : ContactMapper | None
+        contact 매핑 활성화 시 인스턴스, 아니면 None.
+
+    Examples
+    --------
+    >>> analyzer = LLSPatternAnalyzer(
+    ...     config_path="./lls_config.json",
+    ...     daily_input_dir="./daily",
+    ...     output_dir="./result_daily",
+    ... )
+    >>> df_daily = analyzer.run(mode="daily")    # Mode 1
+    >>> df_by_cst = analyzer.run(mode="by_cst")  # Mode 2
+    """
+
+    # ------------------------------------------------------------------
+    # 생성자 + 초기화
+    # ------------------------------------------------------------------
+    def __init__(
+        self,
+        config_path: str = "./lls_config.json",
+        daily_input_dir: str = "./daily",
+        output_dir: str = "./result_daily",
+        contact_csv: Optional[str] = "./contact_angle.csv",
+        setup_font: bool = True,
+    ):
+        if setup_font:
+            setup_korean_font()
+
+        self.config_path = config_path
+        self.config = load_config(config_path)
+        self.daily_input_dir = daily_input_dir
+        self.output_dir = output_dir
+
+        # --- Contact mapper (선택) ---
+        cm_cfg = self.config.get("contact_mapping", {})
+        self.contact_tolerance_mm = cm_cfg.get("tolerance_mm", 30.0)
+        self.contact_top_n = cm_cfg.get("top_n", 5)
+        self.contact_mapper: Optional[ContactMapper] = None
+        if contact_csv and os.path.exists(contact_csv):
+            self.contact_mapper = ContactMapper(
+                csv_path=contact_csv,
+                tolerance_mm=self.contact_tolerance_mm,
+            )
+            print(f"✅ Contact mapper 활성화: {contact_csv} (tolerance={self.contact_tolerance_mm}mm)")
+
+        # --- 전처리 파라미터 (lls_config.json::preprocessing) ---
+        pp = self.config["preprocessing"]
+        self.cell_size_mm = pp["cell_size_mm"]
+        self.n1_min_wafers = pp["n1_min_wafers"]
+        # 구버전 config 호환: n2_min_cell_defects 또는 n2_min_zone_defects 모두 인식
+        self.n2_min_cell_defects = pp.get(
+            "n2_min_cell_defects", pp.get("n2_min_zone_defects", 3)
+        )
+        self.inner_radius_mm = pp["inner_radius_mm"]
+
+        # --- Mode 1 유의 패턴 필터링 임계치 (lls_config.json::mode_daily) ---
+        md = self.config.get("mode_daily", {})
+        self.daily_min_defect_count = md.get("min_defect_count", 30)
+        self.daily_min_wafer_count = md.get("min_wafer_count", 3)
+        self.daily_excluded_patterns = set(
+            md.get("excluded_patterns", list(EXCLUDED_PATTERNS_DEFAULT))
+        )
+
+        self._prepare_output_dirs()
+        self._backup_config()
+
+    def _prepare_output_dirs(self) -> None:
+        """출력 디렉터리 일괄 생성."""
+        self.by_cst_dir = os.path.join(self.output_dir, "by_cst")
+        self.daily_agg_dir = os.path.join(self.output_dir, "daily_agg")
+        self.figures_by_cst_dir = os.path.join(self.output_dir, "figures_by_cst")
+        self.figures_daily_dir = os.path.join(self.output_dir, "figures_daily")
+        self.config_used_dir = os.path.join(self.output_dir, "config_used")
+        for d in [
+            self.output_dir, self.by_cst_dir, self.daily_agg_dir,
+            self.figures_by_cst_dir, self.figures_daily_dir, self.config_used_dir,
+        ]:
+            os.makedirs(d, exist_ok=True)
+
+    def _backup_config(self) -> None:
+        """현재 사용된 config를 타임스탬프 파일명으로 백업 (재현성 확보)."""
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup_path = os.path.join(self.config_used_dir, f"{ts}_config.json")
+        shutil.copy(self.config_path, backup_path)
+        print(f"✅ 설정 파일 백업 완료: {backup_path}")
+
+    # ------------------------------------------------------------------
+    # 공용 전처리 헬퍼
+    # ------------------------------------------------------------------
+    def _load_parquet(self, file_path: str) -> Optional[pd.DataFrame]:
+        """
+        Parquet 로드 + HIS_REGIST_DTTM_8030 정규화.
+
+        Returns
+        -------
+        Optional[pd.DataFrame]
+            로드 실패 또는 빈 데이터 시 None.
+        """
+        try:
+            df = pd.read_parquet(file_path)
+        except Exception as e:
+            print(f"❌ 파일 읽기 실패: {file_path}, 오류: {e}")
+            return None
+        if df.empty:
+            return None
+        # 타임스탬프 14자리(YYYYMMDDHHMMSS)로 자르기 — 그룹화 키 일관성 확보
+        if "HIS_REGIST_DTTM_8030" in df.columns:
+            df["HIS_REGIST_DTTM_8030"] = df["HIS_REGIST_DTTM_8030"].astype(str).str[:14]
+        return df
+
+    def _apply_grid_and_n1(self, df: pd.DataFrame) -> pd.DataFrame:
+        """fine-grid 할당 + n1 필터 (cell당 최소 wafer 수)."""
+        df = assign_fine_grid(df, cell_size_mm=self.cell_size_mm)
+        df = filter_by_cell_wafer_count(df, self.n1_min_wafers, cell_size_mm=self.cell_size_mm)
+        return df
+
+    def _apply_n2(self, df: pd.DataFrame) -> pd.DataFrame:
+        """n2 필터: cell당 최소 결함 수 미만인 cell 제거."""
+        if df.empty:
+            return df
+        cell_counts = df["cell_id"].value_counts()
+        valid_cells = cell_counts[cell_counts >= self.n2_min_cell_defects].index
+        return df[df["cell_id"].isin(valid_cells)].copy()
+
+    def _classify(self, df_group: pd.DataFrame) -> Optional[dict]:
+        """
+        한 그룹의 결함을 패턴 분류 + centroid 산출.
+
+        Returns
+        -------
+        Optional[dict]
+            성공 시 result_df / pattern_list / centroid 등을 담은 dict.
+            결함이 0건이면 None.
+        """
+        coords = df_group[["coor_x", "coor_y"]].dropna()
+        if len(coords) == 0:
+            return None
+        df_for_classify = df_group.loc[coords.index].copy()
+        result_df, dominant_zone, pattern_list, centroid = classify_wafer_patterns(
+            df_for_classify, self.config
+        )
+        if centroid:
+            cx, cy = centroid
+            angle = (np.arctan2(cy, cx) / np.pi * 180 + 360) % 360
+            distance = round(float(np.sqrt(cx ** 2 + cy ** 2)), 4)
+        else:
+            angle = distance = None
+        return {
+            "result_df": result_df,
+            "dominant_zone": dominant_zone,
+            "pattern_list": pattern_list,
+            "centroid": centroid,
+            "main_centroid_x": round(centroid[0], 4) if centroid else None,
+            "main_centroid_y": round(centroid[1], 4) if centroid else None,
+            "main_centroid_Angle": angle,
+            "main_centroid_Distance": distance,
+            "defect_count": len(coords),
+        }
+
+    @staticmethod
+    def _pattern_str(pattern_list) -> str:
+        """패턴 리스트를 쉼표 결합 문자열로 정규화."""
+        if isinstance(pattern_list, list):
+            return ", ".join(pattern_list)
+        return str(pattern_list)
+
+    def _attach_contact_candidates(self, record: dict) -> dict:
+        """
+        record에 contact 매핑 결과 컬럼 추가.
+
+        추가되는 컬럼
+            - contact_candidate_count : 매칭 후보 총 개수
+            - contact_candidates      : "EQP:Part | ..." 형식 top-N 요약 문자열
+        """
+        if self.contact_mapper is None:
+            return record
+        pat = record.get("overall_pattern", "")
+        cx = record.get("main_centroid_x")
+        cy = record.get("main_centroid_y")
+        candidates = self.contact_mapper.map_pattern(pat, centroid_x=cx, centroid_y=cy)
+        record["contact_candidate_count"] = int(len(candidates))
+        record["contact_candidates"] = self.contact_mapper.summarize_candidates(
+            candidates, top_n=self.contact_top_n
+        )
+        return record
+
+    def _is_significant(
+        self, pattern_list, defect_count: int, wafer_count: int
+    ) -> bool:
+        """
+        Mode 1 '유의 패턴' 판정.
+
+        세 조건 모두 충족해야 유의:
+            (a) pattern_list가 제외 라벨(Others 등)로만 구성되지 않을 것
+            (b) defect_count >= daily_min_defect_count
+            (c) wafer_count  >= daily_min_wafer_count
+        """
+        patterns = pattern_list if isinstance(pattern_list, list) else [pattern_list]
+        if all(p in self.daily_excluded_patterns for p in patterns):
+            return False
+        if defect_count < self.daily_min_defect_count:
+            return False
+        if wafer_count < self.daily_min_wafer_count:
+            return False
+        return True
+
+    # ------------------------------------------------------------------
+    # Mode 2 : by CST × scan-time
+    # ------------------------------------------------------------------
+    def run_by_cst(self, df: pd.DataFrame, date_str: str) -> List[dict]:
+        """
+        Mode 2 단일 일자 처리: CAR_ID × HIS_REGIST_DTTM 그룹별 분류.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            한 일자 분량의 결함 DF.
+        date_str : str
+            'YYYYMMDD' 일자 문자열 (저장 경로용).
+
+        Returns
+        -------
+        List[dict]
+            각 그룹별 record 리스트. 빈 결과면 [].
+        """
+        daily_results: List[dict] = []
+        daily_result_dfs: dict = {}
+        figures_dir = os.path.join(self.figures_by_cst_dir, date_str)
+        os.makedirs(figures_dir, exist_ok=True)
+
+        for car_id in tqdm(df["CAR_ID"].unique(), desc=f"{date_str} CST", leave=False):
+            df_cst = df[df["CAR_ID"] == car_id].copy()
+            if df_cst.empty:
+                continue
+            df_cst = self._apply_grid_and_n1(df_cst)
+            if df_cst.empty:
+                continue
+            df_cst = add_zone_labels(df_cst, inner_radius=self.inner_radius_mm)
+
+            for dttm, df_group in df_cst.groupby("HIS_REGIST_DTTM_8030"):
+                df_group = self._apply_n2(df_group)
+                if df_group.empty:
+                    continue
+
+                eqp_series = df_group["EQP_ID_8030"].dropna()
+                eqp_nm = eqp_series.mode().iloc[0] if not eqp_series.empty else "Unknown"
+
+                cls = self._classify(df_group)
+                if cls is None:
+                    continue
+
+                key = f"{car_id}_{dttm}"
+                daily_result_dfs[key] = cls["result_df"]
+                rec = {
+                    "status": "Success",
+                    "mode": "by_cst",
+                    "CST_ID": car_id,
+                    "HIS_REGIST_DTTM": dttm,
+                    "EQP_NM_8030": eqp_nm,
+                    "analysis_date": date_str,
+                    "wafer_count": df_group["WAF_ID"].nunique(),
+                    "defect_count": cls["defect_count"],
+                    "overall_pattern": self._pattern_str(cls["pattern_list"]),
+                    "overall_dominant_zone": cls["dominant_zone"],
+                    "main_centroid_x": cls["main_centroid_x"],
+                    "main_centroid_y": cls["main_centroid_y"],
+                    "main_centroid_Angle": cls["main_centroid_Angle"],
+                    "main_centroid_Distance": cls["main_centroid_Distance"],
+                }
+                daily_results.append(self._attach_contact_candidates(rec))
+
+        if daily_results:
+            df_daily = pd.DataFrame(daily_results)
+            df_daily.to_csv(
+                os.path.join(self.by_cst_dir, f"{date_str}_LLS_CST_analysis.csv"),
+                index=False, encoding="utf-8-sig",
+            )
+            for key, result_df in tqdm(daily_result_dfs.items(),
+                                       desc=f"{date_str} 시각화", leave=False):
+                meta = next(
+                    (r for r in daily_results
+                     if f"{r['CST_ID']}_{r['HIS_REGIST_DTTM']}" == key),
+                    None,
+                )
+                if not meta:
+                    continue
+                plot_wafer_map(
+                    result_df=result_df,
+                    key=key,
+                    pattern_list=meta["overall_pattern"],
+                    dominant_zone=meta["overall_dominant_zone"],
+                    meta=meta,
+                    show_mode=False,
+                    save_path=os.path.join(figures_dir, f"{key}.jpg"),
+                )
+        return daily_results
+
+    # ------------------------------------------------------------------
+    # Mode 1 : daily aggregated
+    # ------------------------------------------------------------------
+    def run_daily(self, df: pd.DataFrame, date_str: str) -> List[dict]:
+        """
+        Mode 1 단일 일자 처리: 하루 전체 결함 통합 후 1회 분류.
+
+        패턴 분류 성공 여부와 무관하게 ``filtered_defects/{date}_filtered.parquet``
+        에 필터링된 결함을 항상 보존한다. 시각화는 유의 여부에 따라
+        ``figures_daily/significant/`` 또는 ``others/`` 폴더로 분리 저장.
+
+        Returns
+        -------
+        List[dict]
+            성공 시 1건 record 리스트. 필터 단계에서 모두 제거되면 [].
+        """
+        df_day = df.copy()
+        df_day = self._apply_grid_and_n1(df_day)
+        if df_day.empty:
+            print(f"🟡 {date_str} n1 필터 통과 결함 없음 → 스킵")
+            return []
+        df_day = add_zone_labels(df_day, inner_radius=self.inner_radius_mm)
+        df_day = self._apply_n2(df_day)
+        if df_day.empty:
+            print(f"🟡 {date_str} n2 필터 통과 결함 없음 → 스킵")
+            return []
+
+        wafer_count = df_day["WAF_ID"].nunique()
+        cls = self._classify(df_day)
+
+        # 분류 실패해도 필터링된 결함은 유지 (사용자 요구사항)
+        if cls is None:
+            result_df = df_day.assign(inlier=False)
+            pattern_list = ["None"]
+            dominant_zone = "N/A"
+            defect_count = len(df_day)
+            centroid_fields = {
+                "main_centroid_x": None, "main_centroid_y": None,
+                "main_centroid_Angle": None, "main_centroid_Distance": None,
+            }
+        else:
+            result_df = cls["result_df"]
+            pattern_list = cls["pattern_list"]
+            dominant_zone = cls["dominant_zone"]
+            defect_count = cls["defect_count"]
+            centroid_fields = {
+                "main_centroid_x": cls["main_centroid_x"],
+                "main_centroid_y": cls["main_centroid_y"],
+                "main_centroid_Angle": cls["main_centroid_Angle"],
+                "main_centroid_Distance": cls["main_centroid_Distance"],
+            }
+
+        is_significant = self._is_significant(pattern_list, defect_count, wafer_count)
+
+        eqp_series = (df_day["EQP_ID_8030"].dropna()
+                      if "EQP_ID_8030" in df_day.columns
+                      else pd.Series([], dtype=object))
+        eqp_nm = eqp_series.mode().iloc[0] if not eqp_series.empty else "Unknown"
+
+        key = f"DAILY_{date_str}"
+        record = {
+            "status": "Success",
+            "mode": "daily",
+            "is_significant": is_significant,
+            "CST_ID": "ALL",
+            "HIS_REGIST_DTTM": date_str,
+            "EQP_NM_8030": eqp_nm,
+            "analysis_date": date_str,
+            "wafer_count": wafer_count,
+            "defect_count": defect_count,
+            "overall_pattern": self._pattern_str(pattern_list),
+            "overall_dominant_zone": dominant_zone,
+            **centroid_fields,
+        }
+        record = self._attach_contact_candidates(record)
+
+        # CSV 저장
+        pd.DataFrame([record]).to_csv(
+            os.path.join(self.daily_agg_dir, f"{date_str}_LLS_daily_analysis.csv"),
+            index=False, encoding="utf-8-sig",
+        )
+
+        # 통합 결함 parquet 항상 저장 (분류 무관)
+        defects_dir = os.path.join(self.daily_agg_dir, "filtered_defects")
+        os.makedirs(defects_dir, exist_ok=True)
+        result_df.to_parquet(
+            os.path.join(defects_dir, f"{date_str}_filtered.parquet"),
+            index=False,
+        )
+
+        # 시각화: 유의/비유의 폴더 분리
+        sub_dir = "significant" if is_significant else "others"
+        save_dir = os.path.join(self.figures_daily_dir, sub_dir)
+        os.makedirs(save_dir, exist_ok=True)
+        plot_wafer_map(
+            result_df=result_df,
+            key=key,
+            pattern_list=record["overall_pattern"],
+            dominant_zone=record["overall_dominant_zone"],
+            meta=record,
+            show_mode=False,
+            save_path=os.path.join(save_dir, f"{key}.jpg"),
+        )
+        return [record]
+
+    # ------------------------------------------------------------------
+    # Dispatcher / 진입점
+    # ------------------------------------------------------------------
+    def run(self, mode: Mode = "by_cst") -> pd.DataFrame:
+        """
+        모드별 일자 일괄 처리.
+
+        Parameters
+        ----------
+        mode : {"by_cst", "daily"}
+            "by_cst": CST × 스캔시각 단위 (세밀)
+            "daily" : 일자 통합 단위 (트렌드)
+
+        Returns
+        -------
+        pd.DataFrame
+            모든 일자 record를 합친 통합 DF (`output_dir`에 CSV로도 저장).
+            결과 없으면 빈 DF.
+
+        Raises
+        ------
+        ValueError
+            mode가 허용 값이 아닐 때.
+        FileNotFoundError
+            ``daily_input_dir`` 에 parquet 파일이 없을 때.
+        """
+        if mode not in ("by_cst", "daily"):
+            raise ValueError(f"mode는 'by_cst' 또는 'daily' 여야 합니다. got={mode}")
+
+        parquet_files = sorted(glob.glob(os.path.join(self.daily_input_dir, "*.parquet")))
+        if not parquet_files:
+            raise FileNotFoundError(
+                f"❌ {self.daily_input_dir} 폴더에 parquet 파일이 없습니다."
+            )
+        print(f"✅ 총 {len(parquet_files)}개의 일자별 파일 발견 (mode={mode})")
+
+        all_results: List[dict] = []
+        for file_path in tqdm(parquet_files, desc=f"📅 일자별 처리 ({mode})"):
+            date_str = os.path.basename(file_path).split(".")[0]
+            if not (len(date_str) == 8 and date_str.isdigit()):
+                print(f"🟡 건너뜀 (파일명 형식 오류): {file_path}")
+                continue
+
+            df = self._load_parquet(file_path)
+            if df is None:
+                print(f"🟡 데이터 없음: {file_path}")
+                continue
+
+            if mode == "by_cst":
+                results = self.run_by_cst(df, date_str)
+            else:
+                results = self.run_daily(df, date_str)
+            all_results.extend(results)
+
+        if not all_results:
+            print("❌ 분석된 결과가 없습니다.")
+            return pd.DataFrame()
+
+        final_df = pd.DataFrame(all_results)
+        suffix = "by_cst" if mode == "by_cst" else "daily_agg"
+        final_path = os.path.join(self.output_dir, f"LLS_{suffix}_full_analysis.csv")
+        final_df.to_csv(final_path, index=False, encoding="utf-8-sig")
+        print(f"✅ 전체 분석 완료: {len(all_results)}건 → {final_path}")
+        return final_df
+
+
+# ----------------------------------------------------------------------
+# CLI 진입점: `python pattern_analyzer.py [by_cst|daily]`
+# ----------------------------------------------------------------------
+if __name__ == "__main__":
+    sys.path.append(os.getcwd())
+    mode: Mode = sys.argv[1] if len(sys.argv) > 1 else "by_cst"
+    analyzer = LLSPatternAnalyzer()
+    analyzer.run(mode=mode)

nu/pattern_detection.py

@@ -0,0 +1,460 @@
+# pattern_detection.py
+"""
+LLS 결함 패턴 자동 분류 모듈.
+
+웨이퍼 한 장(또는 한 그룹) 위의 결함 좌표 집합을 입력으로 받아
+환형(Ring) / 선형(Linear) / 군집(Cluster) / Others 중 하나로 분류한다.
+
+분류 파이프라인
+----------------
+    1. HDBSCAN으로 1차 클러스터링 → outlier(-1) 제거
+       └ 실패 시 DBSCAN fallback
+    2. LOF로 2차 outlier 제거 (지역 밀도 기반)
+    3. inlier 집합에 대해 패턴 후보 평가 (우선순위 순)
+        (a) 환형 검출  : 원 피팅 RMSE + 각도 커버리지 + 시계 sector 커버리지
+                       + PCA 선형성 거부(원점 통과 선형 false-positive 방지)
+        (b) 선형 검출  : PCA eigenvalue ratio + 직선 편차 + gap ratio
+        (c) 군집 검출  : DBSCAN sub-cluster → compactness/PCA로 군집/선형 재판정
+    4. dominant_zone 계산 (시각화용)
+    5. centroid 좌표 산출
+        - 환형: inlier 전체 평균
+        - 선형/군집: dominant_zone 점들의 평균 (없으면 inlier 평균)
+
+API
+---
+- `PatternDetector(config).classify(df)` (권장)
+- `classify_wafer_patterns(df, config)` (구버전 호환)
+
+두 API 모두 `(result_df, dominant_zone, pattern_list, centroid)` 튜플 반환.
+"""
+from __future__ import annotations
+
+from collections import Counter
+from typing import Tuple, List, Optional
+
+import numpy as np
+import pandas as pd
+import hdbscan
+from sklearn.decomposition import PCA
+from sklearn.cluster import DBSCAN
+from sklearn.neighbors import LocalOutlierFactor
+
+from utils import WaferUtils
+
+
+# ======================================================================
+# PatternDetector
+# ======================================================================
+class PatternDetector:
+    """
+    config를 주입받아 LLS 결함 패턴을 분류하는 검출기.
+
+    상태로 `self.cfg` 한 가지만 보유하므로 thread-safe하며,
+    동일 인스턴스를 여러 wafer 그룹에 반복 사용해도 무방하다.
+
+    Parameters
+    ----------
+    config : dict
+        `lls_config.json` 구조의 dict.
+        필요한 키 (서브트리):
+            - preprocessing.inner_radius_mm
+            - clustering.{min_cluster_size, min_samples, cluster_selection_method,
+                          dbscan_eps, cluster_dbscan_eps}
+            - lof.{lof_min_points, lof_n_neighbors, lof_contamination}
+            - ring.{ring_min_points, ring_band_width, ring_r_absolute_tolerance,
+                    ring_min_angular_coverage, ring_min_sectors, ring_fit_rmse_max,
+                    (선택) ring_pca_ratio_max}
+            - linear.{linear_pca_ratio_min, linear_max_deviation, linear_min_length,
+                      linear_max_gap_ratio,
+                      centroid_linear_min_length, centroid_linear_pca_min,
+                      centroid_linear_dev_max}
+            - cluster.cluster_compactness_radius
+            - misc.min_points_for_clustering
+    """
+
+    def __init__(self, config: dict):
+        self.cfg = config
+
+    # ==================================================================
+    # 공개 API
+    # ==================================================================
+    def classify(
+        self, df: pd.DataFrame
+    ) -> Tuple[pd.DataFrame, str, List[str], Optional[tuple]]:
+        """
+        결함 DataFrame을 받아 패턴을 분류.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            'coor_x', 'coor_y' 컬럼을 반드시 포함. inner_radius 기반 zone 라벨은
+            내부에서 자동으로 부여한다.
+
+        Returns
+        -------
+        result_df : pd.DataFrame
+            원본 df + 'inlier' (bool) + 'zone_label'/'r'/'theta_deg' 컬럼.
+        dominant_zone : str
+            inlier 중 가장 많이 나타난 zone_label. inlier가 비면 "데이터 없음"/"N/A".
+        pattern_list : list[str]
+            ["환형"] / ["선형"] / ["군집"] / ["Others"] / ["정상/미달"].
+        centroid : tuple[float, float] | None
+            패턴 발생 중심 좌표. 분류 실패 시 None.
+        """
+        cfg = self.cfg
+
+        if df.empty:
+            return df, "데이터 없음", ["None"], None
+
+        # Zone 라벨링 + 좌표 평탄화
+        df = df.copy().reset_index(drop=True)
+        df = WaferUtils.add_zone_labels(df, inner_radius=cfg["preprocessing"]["inner_radius_mm"])
+        coords = df[["coor_x", "coor_y"]].values
+
+        n_total = len(df)
+        if n_total < cfg["misc"]["min_points_for_clustering"]:
+            return (df.assign(inlier=np.zeros(len(df), dtype=bool)),
+                    "데이터 없음", ["정상/미달"], None)
+
+        # --- 1차 클러스터링 (HDBSCAN → DBSCAN fallback) ---
+        labels = self._cluster_hdbscan(coords)
+        if np.all(labels == -1):
+            labels = self._cluster_dbscan_fallback(coords)
+        inlier_mask = labels != -1
+        if not any(inlier_mask):
+            return df.assign(inlier=inlier_mask), "데이터 없음", ["Others"], None
+
+        # --- 2차 outlier 제거 (LOF) ---
+        inlier_mask = self._apply_lof(coords, inlier_mask)
+        inlier_df = df[inlier_mask].copy()
+        inlier_coords = coords[inlier_mask]
+        n_inlier = len(inlier_df)
+
+        if n_inlier < cfg["clustering"]["min_cluster_size"]:
+            return df.assign(inlier=inlier_mask), "데이터 없음", ["Others"], None
+
+        # --- 패턴 판정: 환형 → 선형 → 군집(서브분류) ---
+        if self._is_ring(inlier_df):
+            zone = self._dominant_zone(inlier_df)
+            centroid = tuple(np.mean(inlier_df[["coor_x", "coor_y"]].values, axis=0))
+            return df.assign(inlier=inlier_mask), zone, ["환형"], centroid
+
+        if self._is_linear_set(inlier_coords):
+            zone = self._dominant_zone(inlier_df)
+            centroid = self._zone_centroid(inlier_df, inlier_coords, zone)
+            return df.assign(inlier=inlier_mask), zone, ["선형"], centroid
+
+        # 군집 후보: 서브클러스터 검사
+        zone = self._dominant_zone(inlier_df)
+        centroid = self._zone_centroid(inlier_df, inlier_coords, zone)
+        pattern = self._classify_cluster_or_sub_linear(inlier_coords)
+        return df.assign(inlier=inlier_mask), zone, [pattern], centroid
+
+    # ==================================================================
+    # 1차 클러스터링
+    # ==================================================================
+    def _cluster_hdbscan(self, coords: np.ndarray) -> np.ndarray:
+        """HDBSCAN으로 클러스터 라벨 산출. outlier는 -1."""
+        c = self.cfg["clustering"]
+        clusterer = hdbscan.HDBSCAN(
+            min_cluster_size=c["min_cluster_size"],
+            min_samples=c["min_samples"],
+            cluster_selection_method=c["cluster_selection_method"],
+            metric="euclidean",
+            gen_min_span_tree=True,
+        )
+        return clusterer.fit_predict(coords)
+
+    def _cluster_dbscan_fallback(self, coords: np.ndarray) -> np.ndarray:
+        """HDBSCAN 실패 시 DBSCAN fallback."""
+        c = self.cfg["clustering"]
+        return DBSCAN(eps=c["dbscan_eps"], min_samples=c["min_cluster_size"]).fit(coords).labels_
+
+    # ==================================================================
+    # 2차 outlier 제거 (LOF)
+    # ==================================================================
+    def _apply_lof(self, coords: np.ndarray, inlier_mask: np.ndarray) -> np.ndarray:
+        """LOF로 1차 inlier에서 추가 outlier 제거."""
+        lof_cfg = self.cfg["lof"]
+        inlier_coords = coords[inlier_mask]
+        n_inlier = len(inlier_coords)
+        if n_inlier < lof_cfg["lof_min_points"]:
+            return inlier_mask
+
+        n_neighbors = min(lof_cfg["lof_n_neighbors"], n_inlier - 1)
+        if n_neighbors < 2:
+            return inlier_mask
+
+        lof = LocalOutlierFactor(
+            n_neighbors=n_neighbors,
+            contamination=lof_cfg["lof_contamination"],
+            metric="euclidean",
+        )
+        lof_labels = lof.fit_predict(inlier_coords)
+        # inlier_mask와 동일 길이의 mask로 확장
+        full_mask = np.zeros(len(coords), dtype=bool)
+        full_mask[inlier_mask] = lof_labels == 1
+        return inlier_mask & full_mask
+
+    # ==================================================================
+    # 환형 검출
+    # ==================================================================
+    def _is_ring(self, inlier_df: pd.DataFrame) -> bool:
+        """
+        환형(ring) 판정.
+
+        단계
+        ----
+        1. 최소 포인트 수
+        2. PCA 선형성 거부: 전체 inlier가 강한 선형성을 보이면 ring 아님
+           (원점 통과 선형 false-positive 방지)
+        3. r-히스토그램 top bin만 추출 (main ring band)
+        4. band 내 점 수 / r 폭 / 각도 커버리지 / sector 커버리지
+        5. 원 피팅 RMSE / 중심점 원점 근접도
+        """
+        cfg = self.cfg
+        n_total = len(inlier_df)
+        if n_total < cfg["ring"]["ring_min_points"]:
+            return False
+
+        # 선형성 거부 (Ring pre-check)
+        coords = inlier_df[["coor_x", "coor_y"]].values
+        if len(coords) >= 3:
+            pca_all = PCA(n_components=2).fit(coords)
+            if len(pca_all.explained_variance_) >= 2:
+                eig_ratio = pca_all.explained_variance_[0] / (pca_all.explained_variance_[1] + 1e-9)
+                ring_pca_max = cfg["ring"].get("ring_pca_ratio_max",
+                                                cfg["linear"]["linear_pca_ratio_min"])
+                if np.sqrt(eig_ratio) >= ring_pca_max:
+                    return False
+
+        # Main ring band (top r-bin)
+        main_ring_df = self._filter_main_ring_band(inlier_df,
+                                                   r_bin_width=cfg["ring"]["ring_band_width"],
+                                                   top_n_bins=1)
+        if len(main_ring_df) < cfg["ring"]["ring_min_points"]:
+            return False
+
+        r = main_ring_df["r"].values
+        theta_deg = main_ring_df["theta_deg"].values
+        x = main_ring_df["coor_x"].values
+        y = main_ring_df["coor_y"].values
+
+        if r.max() - r.min() > cfg["ring"]["ring_r_absolute_tolerance"]: return False
+        if self._circular_range_deg(theta_deg) < cfg["ring"]["ring_min_angular_coverage"]: return False
+        if not self._check_sector_coverage(theta_deg, min_sectors=cfg["ring"]["ring_min_sectors"]):
+            return False
+
+        cx, cy, _, rmse = self._fit_circle_least_squares(x, y)
+        if rmse == np.inf or rmse > cfg["ring"]["ring_fit_rmse_max"]: return False
+        # 중심이 원점에서 너무 멀면 wafer ring으로 보지 않음 (10mm 한계)
+        if np.sqrt(cx ** 2 + cy ** 2) > 10.0: return False
+        return True
+
+    @staticmethod
+    def _filter_main_ring_band(
+        df: pd.DataFrame, r_bin_width: float = 5.0, top_n_bins: int = 1
+    ) -> pd.DataFrame:
+        """r-축 히스토그램에서 점이 가장 많은 bin(들)에 속하는 점만 추출."""
+        if len(df) == 0 or "r" not in df.columns:
+            return df.copy()
+        r = df["r"].values
+        r = r[(r >= 0) & (r <= 150)]
+        if len(r) == 0:
+            return pd.DataFrame(columns=df.columns)
+
+        r_bins = np.arange(0, 150 + r_bin_width, r_bin_width)
+        r_hist, r_edges = np.histogram(df["r"].values, bins=r_bins)
+        top_idx = np.argsort(r_hist)[::-1][:top_n_bins]
+
+        mask = np.zeros(len(df), dtype=bool)
+        for bi in top_idx:
+            r_min, r_max = r_edges[bi], r_edges[bi + 1]
+            mask |= ((df["r"] >= r_min) & (df["r"] < r_max)).values
+        return df[mask].copy()
+
+    @staticmethod
+    def _circular_range_deg(angles_deg: np.ndarray) -> float:
+        """원형 각도 분포의 커버리지 (도, 360° 중)."""
+        if len(angles_deg) < 2:
+            return 0.0
+        a = np.sort(np.array(angles_deg) % 360.0)
+        gaps = np.diff(a)
+        circ_gap = 360.0 - a[-1] + a[0]
+        return 360.0 - max(np.max(gaps), circ_gap)
+
+    @staticmethod
+    def _check_sector_coverage(theta_deg: np.ndarray, min_sectors: int = 8) -> bool:
+        """30° 간격 12 sector 중 min_sectors 이상 커버하는지."""
+        if len(theta_deg) == 0:
+            return False
+        sectors = ((theta_deg % 360) // 30).astype(int) % 12
+        return len(np.unique(sectors)) >= min_sectors
+
+    @staticmethod
+    def _fit_circle_least_squares(
+        x: np.ndarray, y: np.ndarray
+    ) -> Tuple[Optional[float], Optional[float], Optional[float], float]:
+        """
+        대수적 최소제곱 원 피팅.
+
+        Returns
+        -------
+        (cx, cy, radius, rmse) — 실패 시 (None, None, None, inf)
+        """
+        if len(x) < 3:
+            return None, None, None, np.inf
+        x = x[:, np.newaxis]
+        y = y[:, np.newaxis]
+        A = np.hstack([x, y, np.ones_like(x)])
+        b = x ** 2 + y ** 2
+        try:
+            sol, *_ = np.linalg.lstsq(A, b, rcond=None)
+            a, bb, c = sol.flatten()
+            cx, cy = a / 2, bb / 2
+            radius = np.sqrt((a ** 2 + bb ** 2) / 4 + c)
+            fitted = np.sqrt((x - cx) ** 2 + (y - cy) ** 2)
+            rmse = np.sqrt(np.mean((fitted - radius) ** 2))
+            return cx, cy, radius, rmse
+        except Exception:
+            return None, None, None, np.inf
+
+    # ==================================================================
+    # 선형 검출
+    # ==================================================================
+    def _is_linear_set(self, coords: np.ndarray) -> bool:
+        """전체 inlier 집합이 직선에 충분히 가까운지."""
+        cfg = self.cfg["linear"]
+        n = len(coords)
+        if n < 3:
+            return False
+
+        centroid = np.mean(coords, axis=0)
+        max_dist = np.max(np.linalg.norm(coords - centroid, axis=1))
+        # 길이 조건 (반지름의 2배 = 최대 길이)
+        if 2 * max_dist < cfg["linear_min_length"]:
+            return False
+
+        pca = PCA(n_components=min(2, n)).fit(coords)
+        if len(pca.explained_variance_) < 2:
+            return False
+        eig_ratio = pca.explained_variance_[0] / (pca.explained_variance_[1] + 1e-9)
+        if np.sqrt(eig_ratio) < cfg["linear_pca_ratio_min"]:
+            return False
+
+        # 주축 직각방향 평균 편차
+        normal = np.array([-pca.components_[0][1], pca.components_[0][0]])
+        if np.mean(np.abs(np.dot(coords - pca.mean_, normal))) > cfg["linear_max_deviation"]:
+            return False
+
+        # 주축 투영 후 gap ratio (선이 끊겨있지 않은지)
+        proj = np.sort(np.dot(coords - pca.mean_, pca.components_[0]))
+        total_len = proj[-1] - proj[0]
+        if total_len > 0 and np.max(np.diff(proj)) / total_len > cfg["linear_max_gap_ratio"]:
+            return False
+        return True
+
+    def _is_centroids_linear(self, sub_coords_list: list) -> bool:
+        """여러 서브클러스터의 중심점들이 일직선 위에 있는지."""
+        cfg = self.cfg["linear"]
+        if len(sub_coords_list) < 3:
+            return False
+        centroids = np.array([np.mean(sc, axis=0) for sc in sub_coords_list])
+        max_span = 2 * np.max(np.linalg.norm(centroids - np.mean(centroids, axis=0), axis=1))
+        if max_span < cfg["centroid_linear_min_length"]:
+            return False
+        pca = PCA(n_components=2).fit(centroids)
+        if len(pca.explained_variance_) < 2:
+            return False
+        if np.sqrt(pca.explained_variance_[0] /
+                   (pca.explained_variance_[1] + 1e-9)) < cfg["centroid_linear_pca_min"]:
+            return False
+        normal = np.array([-pca.components_[0][1], pca.components_[0][0]])
+        if np.mean(np.abs(np.dot(centroids - pca.mean_, normal))) > cfg["centroid_linear_dev_max"]:
+            return False
+        return True
+
+    # ==================================================================
+    # 군집 / 서브 분류
+    # ==================================================================
+    def _classify_cluster_or_sub_linear(self, inlier_coords: np.ndarray) -> str:
+        """
+        ring/linear 둘 다 아닐 때 호출: 서브 DBSCAN으로 분할 후 패턴 재판정.
+
+        - 서브클러스터 ≥2개이고 중심점들이 일직선 → 선형
+        - 그 외: 각 서브를 군집/선형으로 라벨링 후 누적 다수결
+        """
+        cfg = self.cfg
+        if len(inlier_coords) < 2:
+            return "군집"
+
+        sub = DBSCAN(eps=cfg["clustering"]["cluster_dbscan_eps"],
+                     min_samples=cfg["clustering"]["min_cluster_size"]).fit(inlier_coords)
+        sub_labels = sub.labels_
+        n_sub = len(set(sub_labels)) - (1 if -1 in sub_labels else 0)
+
+        if n_sub >= 2:
+            sub_list = [inlier_coords[sub_labels == lbl]
+                        for lbl in set(sub_labels) if lbl != -1]
+            if self._is_centroids_linear(sub_list):
+                return "선형"
+            results = [(self._classify_subcluster(sc), len(sc)) for sc in sub_list]
+            totals = {}
+            for pat, cnt in results:
+                totals[pat] = totals.get(pat, 0) + cnt
+            return max(totals, key=totals.get)
+        return self._classify_subcluster(inlier_coords)
+
+    def _classify_subcluster(self, sub_coords: np.ndarray) -> str:
+        """단일 서브클러스터를 '군집' 또는 '선형'으로 라벨링."""
+        cfg = self.cfg
+        n = len(sub_coords)
+        if n < 3:
+            return "군집"
+        centroid = np.mean(sub_coords, axis=0)
+        max_dist = np.max(np.linalg.norm(sub_coords - centroid, axis=1))
+
+        # compact한 군집
+        if max_dist <= cfg["cluster"]["cluster_compactness_radius"]:
+            return "군집"
+
+        pca = PCA(n_components=min(2, n)).fit(sub_coords)
+        if len(pca.explained_variance_) >= 2:
+            eig_ratio = pca.explained_variance_[0] / (pca.explained_variance_[1] + 1e-9)
+            shape_idx = np.sqrt(eig_ratio)
+            if shape_idx >= cfg["linear"]["linear_pca_ratio_min"]:
+                normal = np.array([-pca.components_[0][1], pca.components_[0][0]])
+                mean_dev = np.mean(np.abs(np.dot(sub_coords - pca.mean_, normal)))
+                if (mean_dev <= cfg["linear"]["linear_max_deviation"]
+                        and 2 * max_dist >= cfg["linear"]["linear_min_length"]):
+                    return "선형"
+        return "군집"
+
+    # ==================================================================
+    # Zone / Centroid 유틸
+    # ==================================================================
+    @staticmethod
+    def _dominant_zone(df: pd.DataFrame) -> str:
+        """가장 빈번한 zone_label."""
+        if len(df) == 0 or "zone_label" not in df.columns:
+            return "N/A"
+        counter = Counter(df["zone_label"])
+        return counter.most_common(1)[0][0]
+
+    @staticmethod
+    def _zone_centroid(
+        inlier_df: pd.DataFrame, inlier_coords: np.ndarray, zone: str
+    ) -> tuple:
+        """dominant zone에 속한 점들의 평균. 없으면 inlier 전체 평균."""
+        dom = inlier_df[inlier_df["zone_label"] == zone] if "zone_label" in inlier_df.columns else inlier_df
+        if not dom.empty:
+            return tuple(np.mean(dom[["coor_x", "coor_y"]].values, axis=0))
+        return tuple(np.mean(inlier_coords, axis=0))
+
+
+# ======================================================================
+# Backward-compat: 기존 함수 API 유지
+# ======================================================================
+def classify_wafer_patterns(df: pd.DataFrame, cfg: dict):
+    """`PatternDetector(cfg).classify(df)`의 함수형 alias."""
+    return PatternDetector(cfg).classify(df)

nu/test_synthetic_7days.py

@@ -0,0 +1,154 @@
+"""
+7일치 합성 LLS 데이터 + Contact 매핑 검증.
+
+각 일자는 contact_angle.csv의 특정 행과 매칭되도록 의도적으로 배치:
+  Day 1 : 환형 (각도 무관, Line 제외 전체 후보)
+  Day 2 : 선형 vertical x=38   → Line 75°/105° 등 (cos*150≈±38.8)
+  Day 3 : 군집 near (130, 0)   → 비-Line, 각도 0° 부근 (EPI FI FOUP)
+  Day 4 : 군집 near (0, 140)   → 비-Line, 각도 90° (EBIS Edge/Back Stage)
+  Day 5 : 군집 near (-130, 0)  → 비-Line, 180° (EPI FI FOUP, EBIS Edge Stage)
+  Day 6 : 선형 vertical x=-141 → Line 158°/197° (AVIS Flipper)
+  Day 7 : 군집 near (50, 50)   → 매칭 없음 (negative test)
+"""
+import os
+import sys
+import shutil
+import numpy as np
+import pandas as pd
+
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+SCR_DIR = os.path.dirname(os.path.abspath(__file__))
+os.chdir(SCR_DIR)
+
+TEST_ROOT = os.path.join(SCR_DIR, "_synthetic_test")
+DAILY_DIR = os.path.join(TEST_ROOT, "daily")
+OUTPUT_DIR = os.path.join(TEST_ROOT, "result")
+if os.path.exists(TEST_ROOT):
+    shutil.rmtree(TEST_ROOT)
+os.makedirs(DAILY_DIR, exist_ok=True)
+
+
+def base_record(car_id, waf_id, dttm, eqp_8030="EQP_A"):
+    return {
+        "SUBLOT_ID": f"S{car_id}",
+        "CAR_ID": car_id,
+        "SCAN_TIME": dttm,
+        "EQP_ID_8210": "L01",
+        "EQP_ID_8030": eqp_8030,
+        "ROUTE_ID": "WF7EP01",
+        "PROD_ID": "P001",
+        "HIS_REGIST_DTTM_8030": dttm,
+        "HIS_REGIST_DTTM_Pcounter": dttm,
+        "WAF_ID": waf_id,
+        "DEFECT_CNT": 100,
+        "OPE_ID": "8210",
+        "test_no": 1,
+        "roughbin_no": 0,
+        "d_size": 0.05,
+        "LLS 구분": "LPD",
+        "Particle 분포": "면내",
+    }
+
+
+def make_ring(n=400, radius=85, noise=3.0):
+    th = np.random.uniform(0, 2 * np.pi, n)
+    r = np.random.normal(radius, noise, n)
+    return r * np.cos(th), r * np.sin(th)
+
+
+def make_vertical_line(n=300, x_center=38, y_range=(-60, 60), noise=3.0):
+    """Y축 평행 선형: 특정 x 좌표에 vertical line."""
+    y = np.random.uniform(*y_range, n)
+    x = np.full(n, x_center) + np.random.normal(0, noise, n)
+    return x, y
+
+
+def make_cluster(n=300, center=(130, 0), spread=10):
+    x = np.random.normal(center[0], spread, n)
+    y = np.random.normal(center[1], spread, n)
+    return x, y
+
+
+def build_day(day_idx, date_str, pattern_specs, wafers_per_cst=5, n_csts=2):
+    rows = []
+    for cst_i in range(n_csts):
+        car_id = f"C{day_idx:02d}{cst_i}"
+        dttm = f"2026010{day_idx}120000"
+        pattern_x, pattern_y = pattern_specs[cst_i % len(pattern_specs)]
+        for w in range(wafers_per_cst):
+            waf_id = f"{car_id}W{w:02d}"
+            jx = pattern_x + np.random.normal(0, 1.5, len(pattern_x))
+            jy = pattern_y + np.random.normal(0, 1.5, len(pattern_y))
+            for x, y in zip(jx, jy):
+                rec = base_record(car_id, waf_id, dttm)
+                rec["coor_x"] = float(x)
+                rec["coor_y"] = float(y)
+                rec["ANGLE"] = (np.arctan2(y, x) / np.pi * 180 + 360) % 360
+                rec["DISTANCE"] = float(np.sqrt(x ** 2 + y ** 2))
+                rows.append(rec)
+    return pd.DataFrame(rows)
+
+
+# ----------------------------------------------------------------------
+# 일자별 패턴 정의 (contact 매칭 의도)
+# ----------------------------------------------------------------------
+np.random.seed(42)
+
+day_configs = {
+    "20260101": [make_ring(n=400, radius=85), make_ring(n=400, radius=85)],
+    "20260102": [make_vertical_line(n=300, x_center=38), make_vertical_line(n=300, x_center=38)],
+    "20260103": [make_cluster(n=300, center=(135, 0), spread=8), make_cluster(n=300, center=(135, 0), spread=8)],
+    "20260104": [make_cluster(n=300, center=(0, 140), spread=8), make_cluster(n=300, center=(0, 140), spread=8)],
+    "20260105": [make_cluster(n=300, center=(-135, 0), spread=8), make_cluster(n=300, center=(-135, 0), spread=8)],
+    "20260106": [make_vertical_line(n=300, x_center=-141), make_vertical_line(n=300, x_center=-141)],
+    "20260107": [make_cluster(n=300, center=(50, 50), spread=10), make_cluster(n=300, center=(50, 50), spread=10)],
+}
+
+for i, (date, specs) in enumerate(day_configs.items(), start=1):
+    df = build_day(i, date, specs, wafers_per_cst=5, n_csts=2)
+    out_path = os.path.join(DAILY_DIR, f"{date}.parquet")
+    df.to_parquet(out_path, index=False)
+    print(f"  생성 {date}: {len(df):>5}건, CST {df['CAR_ID'].nunique()}, WAF {df['WAF_ID'].nunique()}")
+
+print()
+print("=" * 70)
+print("LLSPatternAnalyzer 실행")
+print("=" * 70)
+
+from pattern_analyzer import LLSPatternAnalyzer
+
+analyzer = LLSPatternAnalyzer(
+    config_path="./lls_config.json",
+    daily_input_dir=DAILY_DIR,
+    output_dir=OUTPUT_DIR,
+    contact_csv="./contact_angle.csv",
+    setup_font=True,
+)
+
+print("\n--- Mode 1: daily aggregated ---")
+df_daily = analyzer.run(mode="daily")
+
+print("\n--- Mode 2: by_cst ---")
+df_by_cst = analyzer.run(mode="by_cst")
+
+# ----------------------------------------------------------------------
+# 결과 요약
+# ----------------------------------------------------------------------
+print("\n" + "=" * 70)
+print("Mode 1 (daily) 결과 + Contact 매핑")
+print("=" * 70)
+if not df_daily.empty:
+    cols = ["analysis_date", "overall_pattern", "main_centroid_x", "main_centroid_y",
+            "contact_candidate_count", "contact_candidates"]
+    with pd.option_context("display.max_colwidth", 200, "display.width", 200):
+        print(df_daily[cols].to_string(index=False))
+
+print("\n" + "=" * 70)
+print("Mode 2 (by_cst) 결과 + Contact 매핑")
+print("=" * 70)
+if not df_by_cst.empty:
+    cols = ["analysis_date", "CST_ID", "overall_pattern", "main_centroid_x", "main_centroid_y",
+            "contact_candidate_count", "contact_candidates"]
+    with pd.option_context("display.max_colwidth", 200, "display.width", 200):
+        print(df_by_cst[cols].to_string(index=False))

nu/utils.py

@@ -0,0 +1,545 @@
+# utils.py
+"""
+웨이퍼 결함 데이터 처리 공용 유틸리티.
+
+이 모듈은 LLS(Laser Light Scattering) 결함 분석 파이프라인에서
+패턴 분류 이전·이후 단계에 공통으로 사용되는 함수들을 제공한다.
+
+크게 6가지 범주를 포함:
+    1. 환경 설정         : 한글 폰트, JSON config 로드
+    2. 결함 라벨 매핑    : roughbin_no → 한글 결함 분류명
+    3. Zone 라벨링       : 시계방향 12구역 × Inner/Outer 분류
+    4. Fine-grid 처리    : 결함 좌표를 격자 cell에 할당
+    5. 필터링            : cell 단위 wafer 수 기준 노이즈 제거
+    6. 시각화            : 웨이퍼 맵 (산점도 + zone + centroid 마킹)
+
+클래스 `WaferUtils`로 모든 유틸리티를 묶어 IDE 자동완성/타입힌트 일관성을 높이고,
+하위 호환을 위해 동일 이름의 모듈 레벨 함수도 함께 노출한다.
+"""
+from __future__ import annotations
+
+import os
+import json
+from typing import Optional, Tuple
+
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import matplotlib.font_manager as fm
+from matplotlib.patches import Circle, Wedge
+
+
+# ----------------------------------------------------------------------
+# 모듈 상수
+# ----------------------------------------------------------------------
+
+# roughbin_no(정수) → 결함 분류명(한글/영문) 매핑.
+# 검사기 raw 코드를 운영에서 통용되는 분류명으로 변환할 때 사용.
+ROUGHBIN_MAPPING = {
+    0: 'LPD', 100: 'LPD-N', 110: 'Micro-Scratch', 111: 'Void', 115: 'PID',
+    120: 'LPD-E', 130: 'LPD-S', 140: 'LLPD', 141: 'Air Pocket', 150: 'DIC-Unique',
+    160: 'Stain', 170: 'COP', 200: 'Cluster Area', 205: 'Extended Defects',
+    210: 'Scratch', 220: 'Slipline', 230: 'Line', 231: 'Area', 233: 'Radial',
+    234: 'Ring', 512: 'Residue', 520: 'Boat Mark', 902: 'Streak', 999: 'Nuisance',
+    990: 'LPD Nuisance', 991: 'PPD Nuisance', 501: 'Haze Slipline', 502: 'Hazeline',
+    600: 'Grid', 700: 'ROI', 800: 'X Section',
+}
+
+# 시계방향 12구역 라벨. 12시부터 시작해서 시계방향(1, 2, ... 11시)으로 진행.
+CLOCK_LABELS = ["12", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11"]
+
+# 패턴별 시각화 색상.
+PATTERN_COLORS = {
+    "환형": "darkorange",
+    "선형": "forestgreen",
+    "군집": "mediumpurple",
+    "정상/미달": "gray",
+    "Others": "gray",
+}
+
+
+# ======================================================================
+# WaferUtils
+# ======================================================================
+class WaferUtils:
+    """
+    웨이퍼 결함 데이터 처리 유틸리티 클래스 (facade 형태).
+
+    상태가 필요 없는 순수 함수들이므로 대부분 `@staticmethod`로 구성되며,
+    인스턴스화 없이 `WaferUtils.method(...)` 형태로 사용할 수 있다.
+
+    Examples
+    --------
+    >>> df = WaferUtils.assign_fine_grid(df, cell_size_mm=3.0)
+    >>> df = WaferUtils.add_zone_labels(df, inner_radius=105.0)
+    >>> WaferUtils.plot_wafer_map(result_df, key="...", pattern_list=["환형"], ...)
+    """
+
+    # ------------------------------------------------------------------
+    # 1. 환경 설정
+    # ------------------------------------------------------------------
+    @staticmethod
+    def setup_korean_font() -> Optional[str]:
+        """
+        시스템 한글 폰트를 matplotlib 기본 폰트로 등록.
+
+        선호 순서: Malgun Gothic > Nanum Gothic > NanumBarunGothic > Batang > Gulim > AppleGothic.
+        선호 후보가 없으면 시스템에서 'gothic/mincho/dotum/gulim/malgun/sans/korean'
+        키워드가 포함된 첫 번째 한글 후보를 사용.
+
+        Returns
+        -------
+        Optional[str]
+            적용된 폰트명. 시스템에 한글 폰트가 전혀 없으면 None.
+        """
+        korean_fonts = [
+            f.name for f in fm.fontManager.ttflist
+            if any(k in f.name.lower()
+                   for k in ["gothic", "mincho", "dotum", "gulim", "malgun", "sans", "korean"])
+        ]
+        preferred = ["Malgun Gothic", "Nanum Gothic", "NanumBarunGothic",
+                     "Batang", "Gulim", "AppleGothic"]
+        selected = next((f for f in preferred if f in korean_fonts), None)
+        if selected is None and korean_fonts:
+            selected = korean_fonts[0]
+
+        if selected:
+            plt.rcParams["font.family"] = selected
+            plt.rcParams["font.size"] = 10
+            # 한글 폰트에서 음수 부호(−)가 깨지는 현상 방지
+            plt.rcParams["axes.unicode_minus"] = False
+            print(f"✅ 한글 폰트 설정 완료: {selected}")
+        else:
+            print("⚠️ 경고: 시스템에 한글 폰트가 없습니다. 기본 폰트 사용 (글자 깨짐 발생)")
+        return selected
+
+    @staticmethod
+    def load_config(config_path: str = "./lls_config.json") -> dict:
+        """
+        JSON 형식의 분석 설정 파일 로��.
+
+        Parameters
+        ----------
+        config_path : str
+            설정 파일 경로 (UTF-8 인코딩 가정).
+
+        Returns
+        -------
+        dict
+            설정 트리 (preprocessing / clustering / ring / linear / lof / cluster /
+            misc / contact_mapping 등의 키 포함).
+
+        Raises
+        ------
+        FileNotFoundError
+            지정한 경로에 파일이 없는 경우.
+        """
+        if not os.path.exists(config_path):
+            raise FileNotFoundError(f"설정 파일 없음: {config_path}")
+        with open(config_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+
+    # ------------------------------------------------------------------
+    # 2. 결함 라벨 매핑
+    # ------------------------------------------------------------------
+    @staticmethod
+    def map_roughbin_no(roughbin) -> Optional[str]:
+        """
+        roughbin_no(검사기 raw 코드)를 운영 결함 분류명으로 매핑.
+
+        고정 매핑 테이블(`ROUGHBIN_MAPPING`)을 우선 조회하고,
+        범위형 코드(541~548 등)는 별도 if-조건으로 처리한다.
+
+        Parameters
+        ----------
+        roughbin : Any
+            정수 또는 정수 변환 가능한 값. NaN/None/문자열 등은 None 반환.
+
+        Returns
+        -------
+        Optional[str]
+            분류명("LPD", "Haze Slipline" 등). 매핑 실패 시 "Unknown",
+            입력이 NaN/변환 불가 시 None.
+        """
+        if pd.isna(roughbin):
+            return None
+        try:
+            roughbin = int(roughbin)
+        except (TypeError, ValueError):
+            return None
+
+        if roughbin in ROUGHBIN_MAPPING:
+            return ROUGHBIN_MAPPING[roughbin]
+        # 범위형 코드 처리
+        if 541 <= roughbin <= 548: return "Haze Slipline"
+        if 531 <= roughbin <= 538: return "Hazeline"
+        if 601 <= roughbin <= 609: return "Grid"
+        if 701 <= roughbin <= 709: return "ROI"
+        if 801 <= roughbin <= 809: return "X Section"
+        return "Unknown"
+
+    # ------------------------------------------------------------------
+    # 3. Zone 라벨링
+    # ------------------------------------------------------------------
+    @staticmethod
+    def add_zone_labels(df: pd.DataFrame, inner_radius: float = 105.0) -> pd.DataFrame:
+        """
+        결함 좌표에 zone 라벨을 부여.
+
+        Zone 라벨 형식: `{Inner|Outer}_{시계위치 2자리}`
+            예) "Inner_03"  = 반지름 ≤ inner_radius, 3시 방향
+                "Outer_12"  = 반지름 > inner_radius, 12시 방향
+
+        각도 변환:
+            - 수학 각도(atan2) → 12시 기준 시계방향 각도(`theta_from_12 = (90° - math) mod 360`)
+            - sector index = floor(theta_from_12 / 30°) % 12
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            'coor_x', 'coor_y' 컬럼을 포함한 결함 좌표 DF.
+        inner_radius : float
+            Inner / Outer 경계가 되는 반지름 (mm).
+
+        Returns
+        -------
+        pd.DataFrame
+            'zone_label', 'r' (원점 거리), 'theta_deg' (수학 각도) 컬럼 추가된 사본.
+        """
+        df = df.copy()
+        r = np.hypot(df["coor_x"], df["coor_y"])
+        theta_deg = np.degrees(np.arctan2(df["coor_y"], df["coor_x"]))
+        # 시계 방향 환산: 12시 = 0°, 시계방향으로 증가
+        theta_from_12 = (90.0 - theta_deg) % 360.0
+        sector_index = (theta_from_12 // 30).astype(int) % 12
+
+        clock_str = pd.Series([CLOCK_LABELS[i] for i in sector_index], index=df.index)
+        zone_type = np.where(r <= inner_radius, "Inner", "Outer")
+
+        df["zone_label"] = [f"{zt}_{c}" for zt, c in zip(zone_type, clock_str)]
+        df["r"] = r
+        df["theta_deg"] = theta_deg
+        return df
+
+    # ------------------------------------------------------------------
+    # 4. Fine-grid 처리
+    # ------------------------------------------------------------------
+    @staticmethod
+    def assign_fine_grid(df: pd.DataFrame, cell_size_mm: float = 3.0) -> pd.DataFrame:
+        """
+        결함 좌표를 fine-grid cell 에 할당.
+
+        웨이퍼 좌표 범위 [-150, 150] × [-150, 150] (mm)를 `cell_size_mm` 크기의
+        정사각 격자로 분할하고, 각 결함이 속하는 cell의 중심 좌표와 ID를 부여.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            'coor_x', 'coor_y' 컬럼 포함 DF.
+        cell_size_mm : float
+            셀 한 변의 크기 (mm). 기본 3.0.
+
+        Returns
+        -------
+        pd.DataFrame
+            'cell_x', 'cell_y' (셀 중심 좌표 mm),
+            'cell_id' ("{int_x}_{int_y}" 형식의 unique ID) 추가된 사본.
+
+        Notes
+        -----
+        cell_id는 cell_x/cell_y를 반올림하여 정수화한 문자열이라
+        cell_size_mm가 정수 경계와 어긋나면 충돌 가능. 통상 3.0/5.0 등 정수 권장.
+        """
+        df = df.copy()
+        # 좌표 평행이동 후 floor → bin index
+        bin_x = np.floor((df["coor_x"] + 150) / cell_size_mm).astype(int)
+        bin_y = np.floor((df["coor_y"] + 150) / cell_size_mm).astype(int)
+
+        # 셀 중심 좌표 (mm)
+        df["cell_x"] = bin_x * cell_size_mm - 150 + cell_size_mm / 2
+        df["cell_y"] = bin_y * cell_size_mm - 150 + cell_size_mm / 2
+
+        cell_x_int = np.round(df["cell_x"]).astype(int)
+        cell_y_int = np.round(df["cell_y"]).astype(int)
+        df["cell_id"] = cell_x_int.astype(str) + "_" + cell_y_int.astype(str)
+        return df
+
+    @staticmethod
+    def get_cell_wafer_counts(df: pd.DataFrame) -> pd.DataFrame:
+        """
+        각 cell에서 결함이 발생한 unique wafer 수와 결함 수를 집계.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            'cell_id', 'WAF_ID' 컬럼 포함 DF.
+
+        Returns
+        -------
+        pd.DataFrame
+            index = cell_id
+            columns = ['wafer_count', 'defect_count', 'wafer_ratio']
+            - wafer_count : 해당 cell에서 결함을 보인 unique wafer 수
+            - defect_count : 해당 cell의 전체 결함 수
+            - wafer_ratio : wafer_count / 전체 unique wafer 수
+        """
+        total_wafers = df["WAF_ID"].nunique()
+        cell_stats = df.groupby("cell_id").agg(
+            wafer_count=("WAF_ID", "nunique"),
+            defect_count=("WAF_ID", "size"),
+        )
+        cell_stats["wafer_ratio"] = cell_stats["wafer_count"] / total_wafers if total_wafers else 0.0
+        return cell_stats
+
+    @staticmethod
+    def filter_by_cell_wafer_count(
+        df: pd.DataFrame,
+        n1_min_wafer: int,
+        cell_size_mm: float = 3.0,
+    ) -> pd.DataFrame:
+        """
+        Fine-grid 기반 n1 필터: 충분한 wafer에서 공통 발생한 cell의 결함만 유지.
+
+        '공통 위치에 반복 발생하는 결함만 유의미하다'는 가정을 구현.
+        unique wafer 수가 `n1_min_wafer` 미만인 cell은 노이즈로 간주 제거.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            'coor_x', 'coor_y', 'WAF_ID' 포함 DF (cell 할당은 내부에서 수행).
+        n1_min_wafer : int
+            cell이 유효하기 위해 필요한 최소 unique wafer 수.
+        cell_size_mm : float
+            fine-grid cell 크기 (mm).
+
+        Returns
+        -------
+        pd.DataFrame
+            n1 조건을 통과한 cell의 결함만 포함. 'cell_wafer_count' 컬럼 추가.
+        """
+        df = WaferUtils.assign_fine_grid(df, cell_size_mm=cell_size_mm)
+        cell_stats = WaferUtils.get_cell_wafer_counts(df)
+
+        valid_cells = cell_stats[cell_stats["wafer_count"] >= n1_min_wafer].index
+        df_filtered = df[df["cell_id"].isin(valid_cells)].copy()
+        df_filtered = df_filtered.merge(
+            cell_stats[["wafer_count", "wafer_ratio"]],
+            left_on="cell_id", right_index=True, how="left",
+        )
+        df_filtered.rename(columns={"wafer_count": "cell_wafer_count"}, inplace=True)
+        return df_filtered
+
+    @staticmethod
+    def summarize_filtering_result(
+        df_original: pd.DataFrame,
+        df_filtered: pd.DataFrame,
+    ) -> dict:
+        """
+        필터링 전후 결함/Cell 수 요약 통계.
+
+        Returns
+        -------
+        dict
+            original_defects, filtered_defects, removed_defects, removal_rate(%),
+            original_cells, valid_cells.
+        """
+        orig = len(df_original)
+        filt = len(df_filtered)
+        removed = orig - filt
+        rate = (removed / orig * 100) if orig else 0.0
+        return {
+            "original_defects": orig,
+            "filtered_defects": filt,
+            "removed_defects": removed,
+            "removal_rate": round(rate, 2),
+            "original_cells": df_original["cell_id"].nunique() if "cell_id" in df_original.columns else 0,
+            "valid_cells": df_filtered["cell_id"].nunique() if "cell_id" in df_filtered.columns else 0,
+        }
+
+    # ------------------------------------------------------------------
+    # 5. 시각화
+    # ------------------------------------------------------------------
+    @staticmethod
+    def plot_wafer_map(
+        result_df: pd.DataFrame,
+        key: str,
+        pattern_list,
+        dominant_zone: str,
+        meta: Optional[dict] = None,
+        figsize: Tuple[int, int] = (8, 8),
+        save_path: Optional[str] = None,
+        show_mode: bool = False,
+    ) -> None:
+        """
+        웨이퍼 결함 맵 시각화.
+
+        구성 요소
+        ----------
+        1. 배경 영역
+            - 환형 패턴: 전체 원 영역을 베이지색으로 표시
+            - 그 외: dominant_zone에 해당하는 wedge만 베이지색 표시
+        2. 결함 산점도
+            - inlier 컬럼이 있으면 inlier/outlier 색상 분리
+            - inlier 색상은 패턴에 따라 PATTERN_COLORS 매핑
+        3. Centroid 마커 (환형 제외)
+            - 빨간 원(10mm) + X 마커
+        4. 동심원: 30/45/60/90/120/150mm
+        5. 시계방향 그리드 + 12시·1시·...·11시 라벨
+        6. 캡션: 패턴/구역/결함수/장비/웨이퍼
+
+        Parameters
+        ----------
+        result_df : pd.DataFrame
+            'coor_x', 'coor_y', (선택) 'inlier', 'zone_label' 컬럼.
+        key : str
+            저장 파일명·캡션에 사용할 키.
+        pattern_list : list[str] | str
+            패턴명. ['환형','군집'] 같은 리스트도 허용.
+        dominant_zone : str
+            주요 zone 라벨 (예: 'Inner_03'). 'N/A' 이면 미표시.
+        meta : dict, optional
+            'main_centroid_x', 'main_centroid_y', 'wafer_count', 'EQP_NM_8030' 등.
+        figsize : (int, int)
+            Figure 크기.
+        save_path : str, optional
+            저장 경로. None이면 './result/result_figures/{key}.jpg'.
+        show_mode : bool
+            True 면 plt.show() 호출.
+        """
+        solid_radii = [45, 90, 150]
+        dashed_radii = [30, 60, 120]
+
+        # 패턴 문자열 정규화
+        if isinstance(pattern_list, list):
+            pattern_str = ", ".join(pattern_list)
+            first_pattern = pattern_list[0]
+        else:
+            pattern_str = str(pattern_list)
+            first_pattern = pattern_str.split(",")[0].strip()
+
+        color = PATTERN_COLORS.get(first_pattern, "steelblue")
+        fig, ax = plt.subplots(figsize=figsize)
+
+        # --- 배경: 환형 → 전체 원, 그 외 → dominant zone wedge ---
+        if "환형" in pattern_str:
+            ax.add_patch(Circle((0, 0), 150, facecolor="#F5F5DC",
+                                edgecolor="none", alpha=0.8, zorder=1))
+        elif dominant_zone and dominant_zone != "N/A":
+            try:
+                for zone in [z.strip() for z in dominant_zone.split(",")]:
+                    ztype, zclock = zone.split("_")
+                    r_min = 0 if ztype == "Inner" else 105
+                    r_max = 105 if ztype == "Inner" else 150
+                    if zclock in CLOCK_LABELS:
+                        idx = CLOCK_LABELS.index(zclock)
+                        # 시계 각도 → 수학 각도 변환 (Wedge는 수학 각도 사용)
+                        math_start = 90 - (idx + 1) * 30
+                        math_end = 90 - idx * 30
+                        ax.add_patch(Wedge((0, 0), r_max, math_start, math_end,
+                                           width=(r_max - r_min),
+                                           facecolor="#F5F5DC",
+                                           edgecolor="none", alpha=0.8, zorder=1))
+            except Exception:
+                # zone 파싱 실패 시 배경 생략 (시각화는 계속 진행)
+                pass
+
+        # --- 결함 산점도 ---
+        if "inlier" in result_df.columns:
+            inliers = result_df[result_df["inlier"] == True]
+            outliers = result_df[result_df["inlier"] == False]
+            ax.scatter(outliers["coor_x"], outliers["coor_y"],
+                       c="lightgray", s=15, alpha=0.3, zorder=4)
+            ax.scatter(inliers["coor_x"], inliers["coor_y"],
+                       c=color, s=35, alpha=0.5,
+                       label=f"Inlier ({pattern_str})", zorder=5)
+        else:
+            ax.scatter(result_df["coor_x"], result_df["coor_y"],
+                       c=color, s=30, alpha=0.5, zorder=5)
+
+        # --- Centroid 마커: 환형이면 생략 (ring center는 원점 근처라 정보 없음) ---
+        if meta and "환형" not in pattern_str:
+            cx = meta.get("main_centroid_x")
+            cy = meta.get("main_centroid_y")
+            if cx is not None and cy is not None:
+                ax.add_patch(Circle((cx, cy), radius=10, facecolor="none",
+                                    edgecolor="red", linewidth=2.5,
+                                    linestyle="-", alpha=0.9, zorder=7))
+                ax.scatter(cx, cy, c="red", s=80, marker="x",
+                           linewidths=2.5, zorder=8, label="Centroid")
+
+        # --- 웨이퍼 동심원 ---
+        for r in solid_radii:
+            ax.add_patch(plt.Circle((0, 0), r, color="black", fill=False,
+                                    linestyle="-", linewidth=1.2, alpha=0.7, zorder=2))
+        for r in dashed_radii:
+            ax.add_patch(plt.Circle((0, 0), r, color="gray", fill=False,
+                                    linestyle="--", linewidth=0.8, alpha=0.5, zorder=2))
+
+        # --- 시계 방향 그리드 + 라벨 ---
+        clock_angles = {0: "12시", 30: "1시", 60: "2시", 90: "3시",
+                        120: "4시", 150: "5시", 180: "6시", 210: "7시",
+                        240: "8시", 270: "9시", 300: "10시", 330: "11시"}
+        grid_end = max(solid_radii) + 12
+        label_r = grid_end * 0.93
+        for angle_deg, label_text in clock_angles.items():
+            # 시계 각도 → 수학 각도
+            math_rad = np.deg2rad(90 - angle_deg)
+            ax.plot([0, grid_end * np.cos(math_rad)],
+                    [0, grid_end * np.sin(math_rad)],
+                    color="gray", linestyle=":", linewidth=0.8, zorder=2)
+            ax.text(label_r * np.cos(math_rad), label_r * np.sin(math_rad),
+                    label_text, color="darkblue", fontsize=8,
+                    ha="center", va="center", weight="bold", alpha=0.75, zorder=3)
+
+        ax.axhline(0, color="k", linewidth=0.4, zorder=3)
+        ax.axvline(0, color="k", linewidth=0.4, zorder=3)
+        max_range = max(solid_radii) + 20
+        ax.set_xlim(-max_range, max_range)
+        ax.set_ylim(-max_range, max_range)
+        ax.set_aspect("equal", "box")
+        ax.set_xlabel("X (mm)")
+        ax.set_ylabel("Y (mm)")
+        ax.legend(loc="upper right", fontsize=8)
+        ax.grid(True, alpha=0.15)
+
+        # --- 캡션 ---
+        total = len(result_df)
+        dom_cnt = 0
+        if "zone_label" in result_df.columns and dominant_zone != "N/A":
+            dom_zones = [z.strip() for z in dominant_zone.split(",")]
+            dom_cnt = result_df[result_df["zone_label"].isin(dom_zones)].shape[0]
+        ratio = (dom_cnt / total * 100) if total else 0.0
+
+        lines = [
+            f"Key: {key}",
+            f"패턴: {pattern_str}  |  발생구역: {dominant_zone}",
+            f"전체 결함: {total}건  |  주요영역 결함: {dom_cnt}건  |  비율: {ratio:.1f}%",
+        ]
+        if meta:
+            lines.append(f"장비: {meta.get('EQP_NM_8030', '-')}  |  웨이퍼: {meta.get('wafer_count', '-')}매")
+        ax.set_title("\n".join(lines), fontsize=9, loc="left", pad=8)
+        plt.tight_layout()
+
+        if save_path is None:
+            save_dir = "./result/result_figures"
+            os.makedirs(save_dir, exist_ok=True)
+            save_path = os.path.join(save_dir, f"{key}.jpg")
+        plt.savefig(save_path, dpi=150, bbox_inches="tight")
+        if show_mode:
+            plt.show()
+        plt.close()
+
+
+# ======================================================================
+# Backward-compat: 기존 모듈 레벨 함수 alias
+# (기존 코드 `from utils import setup_korean_font, ...` 형태를 그대로 지원)
+# ======================================================================
+setup_korean_font = WaferUtils.setup_korean_font
+load_config = WaferUtils.load_config
+map_roughbin_no = WaferUtils.map_roughbin_no
+add_zone_labels = WaferUtils.add_zone_labels
+assign_fine_grid = WaferUtils.assign_fine_grid
+get_cell_wafer_counts = WaferUtils.get_cell_wafer_counts
+filter_by_cell_wafer_count = WaferUtils.filter_by_cell_wafer_count
+summarize_filtering_result = WaferUtils.summarize_filtering_result
+plot_wafer_map = WaferUtils.plot_wafer_map