카지노 환경을 가정한 Edge AI 기반 지능형 CCTV 영상관제 시스템 — Computer Vision / AI 영상분석 / Edge AI 직무(특히 한화비전) 취업 준비를 위한 포트폴리오 프로젝트.
전체 프로젝트 지침은 CLAUDE.md, 실험/문제해결 기록은 Notion(CasinoGuard AI)에 있다. 이 README는 완성된 Core MVP를 요약한다.
이 프로젝트의 목적은 "YOLO를 실행해본 사람"이 되는 것이 아니라, CCTV 영상을 Raw Video → Frame → Object → Track → Attribute → Behavior → Event → Searchable Metadata로 바꾸는 실제 영상보안 시스템을 설계·구현·검증하는 것이다. 모든 주요 결정은 Baseline 구축 → 문제 관찰 → 원인 분석 → 대안 비교 → 개선 → 재측정의 과정을 거쳤다.
카지노는 수백~수천 채널의 CCTV를 운영하며, 사람이 많고 조명이 복잡한 환경(저조도/강한 인공조명/역광)에서 부정행위 탐지·출입통제·포렌식 검색·고객경험 개선을 요구한다(한화비전 We-Ko-Pa Casino Resort 케이스스터디 참고). 이런 환경에서는 단순 Detection을 넘어 Tracking, BestShot, Event Analytics, Metadata 검색까지 이어지는 파이프라인이 필요하다.
한화비전이 공식적으로 공개한 기능(BestShot, WiseAI Object Detection, Attribute Metadata, Intrusion/Line Crossing/Loitering Video Analytics, People Counting/Heatmap, Wisenet 9 Edge NPU)의 문제 정의를 참고해, 공개 데이터와 오픈소스 기술로 동일한 문제를 재현했다. 한화비전이 공개하지 않은 내부 모델(YOLO/ByteTrack 사용 여부 등)은 절대 추정하지 않았다. 자세한 근거는 Notion [02. Hanwha Vision Research] 참고.
Public CCTV Video (Wikimedia Commons)
↓
Video Decode / Input (OpenCV)
↓
Person Detection (YOLO11n)
↓
Multi Object Tracking (ByteTrack)
↓
Object State Manager (ROI State Machine)
↓
Visual Perception Layer
├─ BestShot (Confidence+Sharpness+Size+Occlusion+Position)
├─ Intrusion Detection (Polygon ROI)
├─ Line Crossing (방향성 Crossing)
└─ Loitering (Dwell Time)
↓
Metadata Pipeline (SQLite)
↓
VMS Search API (FastAPI)
↓
Performance Benchmark
- 영상: Wikimedia Commons 공개 보행자 영상 2건 (480p/11.6s, 1080p/56.6s — Toronto Yonge-Dundas Square 횡단보도)
- Detection 평가: coco128 (person class, GT 61/128장)
- 직접 생성: 손상된 mp4, 무인 합성영상, 짧은 클립 (Robustness Test용)
- CrowdHuman/ExDark/MOT17 GT는 용량 제약(수GB)으로 이번 세션에서는 미다운로드 — 숫자를 지어내지 않고 정직하게 Stretch로 남김 (Notion [03. Dataset & Evaluation] 참고)
YOLO11n Pretrained으로 Baseline 구축. coco128에서 Confidence Threshold(0.2~0.7) Sweep 결과:
| Confidence | Precision | Recall | F1 |
|---|---|---|---|
| 0.2 | 0.776 | 0.697 | 0.734 (최고) |
| 0.4 | 0.940 | 0.555 | 0.698 |
| 0.7 | 0.990 | 0.382 | 0.551 |
imgsz 640/960/1280 비교: FPS 23→11→6으로 감소 — Accuracy(Recall)와 Latency의 Trade-off를 실측으로 확인.
ByteTrack Baseline. crowded_1080p에서 고유 Track ID 41개, 최대 동시 Track 8개, FPS 24.0. MOT17 공식 GT(5.8GB)는 미다운로드해 ID Switch/IDF1은 측정하지 못했음을 명시. 대신 스냅샷 육안 검토로 **배경 밀집 군중은 Detection 자체가 되지 않는 문제(FC-002)**를 발견했다.
Confidence-only로 대표 프레임을 고르면 클로즈업/저품질 프레임이 선택되는 문제를 발견하고, Sharpness+Size+Occlusion+Position을 더한 Composite Score로 개선했다. 32개 Track 비교에서 품질 편차가 큰 Track일수록 개선 효과가 뚜렷했다(정성적 검증, 이미지 그리드로 확인).
| Event | 방법 | 핵심 결과 |
|---|---|---|
| Intrusion (EXP-005) | Polygon ROI + Bottom Center + State Machine | Naive 방식 대비 이벤트 96.3% 감소(630→23건) |
| Line Crossing (EXP-006) | Virtual Line + 외적 부호 판정 | 방향별 Crossing 카운트, Flicker 방지 확인 |
| Loitering (EXP-007) | Dwell Time > Threshold | 5초는 과민, 20~30초는 장소 특성상 0건 — Threshold는 장소별로 다시 튜닝 필요 |
Intrusion에서 발견한 **Track 소실 시 EXIT 이벤트 유실 문제(FC-004)**는 PAR-002로 정리하고 State Machine을 수정했다.
Line Crossing은 선 근처에서 검출 박스가 몇 픽셀만 흔들려도 Crossing 이벤트가 반복 발생하는 문제(FC-007)가 있었다. 900프레임 재현 실험(EXP-014)에서 기존 방식은 57건 중 24쌍이 0.6초 이내 방향이 반전되는 왕복 중복이었고, 선까지의 거리가 band_px 이상일 때만 확정 side를 바꾸는 Hysteresis를 적용해 같은 조건에서 중복을 0건으로 제거했다(총 이벤트도 57→31건으로 정상화). Cooldown 기반 대안도 비교했으나 FPS 의존성과 기하학적 근거 부재로 채택하지 않았다 → PAR-005.
지침 23의 Baseline(항상 고화질 녹화)과 개선안(No Person→Low FPS / Person→Normal FPS /
Security Event→High FPS+Event Clip)을 구현했다. bus.jpg+Pan 900프레임(IDLE 301 /
NORMAL 338 / EVENT 261) 시나리오에서 연속 녹화 저장량이 18.7% 절감됨을 확인했다.
Event Clip(-10s~+10s)을 Event마다 독립적으로 만들면(대안 A) 간격이 짧은 두 Intrusion
Event의 Window가 완전히 겹쳐 361프레임(41.4%)이 중복 저장되는 것을 발견하고, 겹치거나
인접한 Window를 병합하는 방식(대안 B)으로 개선해 중복을 0으로 만들었다(PAR-008).
반대로 Event Clip까지 포함한 총 저장량은 이 36초짜리 데모에서는 Pre/Post-Roll(20초)이
전체 길이의 절반을 넘어 오히려 Baseline보다 47.7% 많아지는 역전 현상도 정직하게 기록했다
(장시간 실제 운영 환경에서 재검증 필요, EXP-017 참고). 최초 ROI 설계(오른쪽 절반)가
bus.jpg에 원래 있던 사람과 겹쳐 NORMAL 구간이 0프레임만 나온 실험 설계 버그도
Failure Case로 기록하고 중앙 대역 ROI로 재설계해 해결했다.
지침 21/22의 Baseline을 구현했다. Heatmap은 Detection Center 누적(Baseline)과 Track이 min_track_len 이상 관측된 뒤에만 누적하는 Track-Gated 누적(대안)을 함께 제공한다(이번 bus.jpg+Pan 12px 실측에서는 노이즈 제거 효과가 0.11%로 미미했음을 정직하게 기록). Crowd Analysis는 "그럴듯한" 고정 Threshold(한 셀에 4~5명=Crowded)를 실측 분포에 적용하자 900프레임 내내 Crowded 등급이 한 번도 발동하지 않는 문제를 발견했고, 실측 Percentile(p50/p90) 기반 Threshold로 바꿔 전체의 7.9%(859/10,800)를 정확히 Crowded로 분리했다(PAR-007).
EXP-017~022는 전부 Adaptive Recording/Circular Buffer를 독립된 스크립트로만 검증했다 — 실제
Detection+Tracking+BestShot+Metadata를 SQLite에 쌓는 파이프라인과는 한 번도 같은 루프에서
동작한 적이 없었다. 이번에 OnlineTierClassifier(신규, Two-Pass compute_tier_sequence를
프레임 단위 스트리밍으로 재현)로 실시간 단일 패스 통합을 구현해, Circular Buffer가 이미
실시간인 전체 파이프라인에 추가하는 오버헤드가 P50 기준 5.7%(3.8ms/66.5ms)에 불과함을
확인했다. 더 중요하게는, Pre-Roll을 "EVENT 구간이 끝난 뒤" 꺼내는 더 단순한 설계(대안 A)가
이 프로젝트의 실제 시나리오(Post-Roll 간격보다 가까운 반복 Intrusion으로 EVENT Tier가
261프레임 연속됨)에서 Pre-Roll의 47%(240/511프레임)를 잃어버린다는 것을 구현 전 실측으로
발견하고, "트리거 순간 즉시 추출"하는 방식(대안 B)을 채택해 511/511 완전한 Event Clip을
만들었다(PAR-014).
Track(trajectory, dwell_time, bestshot_path 등) + Event(Intrusion/LineCrossing/Loitering)를 SQLite 스키마로 통합 저장. 164 Track, 115 BestShot, 190 Event.
저장되는 dwell_frames가 항상 0이었던 문제(FC-006)를 EXP-015에서 재현·수정했다. 원인은 단순 호출 순서가 아니라 Loitering의 "연속 체류" 상태를 VMS의 "누적 총 체류 시간" 집계에 그대로 재사용한 설계였음을 확인하고, 책임을 분리한 DwellCounter로 고쳤다(PAR-006).
FastAPI로 최소 기능만 구현(Microservice/K8s/복잡한 인증 없음):
GET /tracks?min_dwell_sec=— 특정 시간 이상 체류한 Track 검색GET /tracks/{id}— Track의 이동 기록 + Event 이력GET /events?event_type=&has_clip=— 특정 Event 발생 시점 / Event Clip 유무 검색GET /events/{id}/clip— Event 전후 영상(Event Clip) 재생/다운로드 (EXP-024, PAR-015)GET /— 최소 Dashboard (Dwell 상위 5개, 최근 Event 10개 + Event Clip 링크)
API가 raw SQL로 events.detail을 파싱하지 않은 채 그대로 반환해(FC-011) event_clip_path
(EXP-023에서 부착)가 사실상 쓸 수 없었고, 영상을 실제로 재생하는 엔드포인트도 없던 문제를
MetadataStore.query_events() 재사용 + GET /events/{id}/clip(FileResponse)으로 해결했다
(PAR-015).
지침 19의 Attribute Metadata(상의/하의 색상)를 Baseline(bbox 전체 평균, 상/하 구분 불가)
→ 대안 A(고정 비율 상/하 분할 + 단순 평균) → 대안 B(상/하 분할 + 그림자/하이라이트/피부색
필터 + Hue 다수결)로 비교했다. 실제 YOLO11n Person Detection crop 5개(ultralytics 번들
zidane.jpg/bus.jpg)에 수동 Ground Truth를 라벨링하고, 조명 변형 4종(저조도/강한조명·
역광/난색·한색 Cast)으로 안정성을 측정했다.
대안 B 최초 구현이 오히려 Baseline보다 낮은 정확도(16% < 32%)를 내는 역설을 실측으로
발견 — 원인은 그림자/하이라이트 필터가 저채도인 진짜 검정 옷까지 항상 제외시켜, 클로즈업
crop에서 소수 피부색 픽셀만 남아 Hue 다수결을 오염시키는 버그였다. 피부색 필터와 "필터
통과 비율이 낮으면 신뢰하지 않고 원본으로 되돌아가는" 폴백으로 수정해 전체 Accuracy
32%(Baseline)→40%, 조명 안정성 35%→40%로 개선했다(PAR-016). n=5의 작은 평가
Dataset이라는 한계를 솔직히 명시하며, 아직 MetadataStore/VMS에는 연결하지 않았다
(검증 Dataset 확장 후 통합 예정, Next Action).
FC-012(검정 옷이 strong_light/cool_cast에서 blue로 오분류)를 고치려 Gray World
White Balance(대안 B)와 raw BGR Spread 기반 무채색 Shortcut(대안 A)을 비교했다. 전체
평균 Accuracy는 대안 B가 더 높았지만(0.44→0.48), FC-012가 실제로 겨냥하는 "GT=black"
35셀만 슬라이싱하면 Accuracy가 정확히 동일했다(15/35→15/35) — 전체 평균 개선은 전혀
다른(진짜 파란 옷) 셀이 좋아진 부수 효과였을 뿐, 겨냥한 문제는 조건별 재배치만
일어났다(cool_cast는 개선, normal/strong_light는 악화). 두 대안 모두 production
기본값으로 승격하지 않고 FC-012를 "미해결"로 유지하되, 원인을 ①채널 비율 Cast형과
②노출/대비 손실형으로 분리해 기록했다(PAR-017).
n=5(zidane.jpg/bus.jpg) 평가 Dataset의 "작고 편중됐다"는 한계를 실제로 검증하기 위해,
coco128(실제 COCO 128장, github.com/ultralytics/assets/releases/download/v0.0.0/ coco128.zip로 egress 제약 없이 접근 가능함을 새로 확인)에서 person crop 21개를 수동
라벨링해 n을 늘려 재측정했다. 모든 method의 절대 Accuracy가 n=5 때보다 큰 폭으로
낮아졌다(Baseline 32%→15%, 대안 A 28%→16%, 방법 B 40%→26%[normal 조명만 33%], B_wb
48%→32%) — method 간 상대적 순위(Baseline≈A < B < B_wb)는 유지됐지만, 이전에 기록한
절대 수치는 "작은 Dataset에서의 상대 비교 전용"으로 재규정했다. 또한 Roadmap이 다음
후보로 제안했던 "무채색 확신도 점수 기반 unknown 표시"를 설계하기 전에 후보 신호(HSV
채도, raw BGR 채널 표준편차)가 achromatic/chromatic을 실제로 분리하는지 먼저 측정했더니
둘 다 분리되지 않음을 확인했다(achromatic 채도 최댓값 158.89 > chromatic 채도
최솟값 62.92) — 검증 없이 기능부터 설계하는 것을 막은 사례다(PAR-018).
EXP-027이 다음 후보로 이월한 "더 근본적인 영역 분리 방법"을 검증했다. method b/b_wb는
고정 비율 사각형(side_margin_ratio)으로 배경을 근사적으로만 제외하는데, person Instance
Segmentation Mask(yolo11n-seg.pt)로 배경을 픽셀 단위로 정확히 제외하는 대안 C를 같은
n=21 Ground Truth로 비교했다. White Balance 없이 영역만 정확히 잘랐을 뿐인데 Overall
Accuracy가 기존 최고(b_wb, 32.4%)를 넘어 35.2%, GT=black Accuracy는 52.7%로 올랐다 —
그러나 GT=black→blue 오분류율(FC-012의 표적 실패)은 cool_cast에서 오히려 50.0%(b_wb
22.7%보다 나쁨)로, Mask는 "배경 Bleed"는 해결해도 "조명 Cast로 인한 Hue 왜곡"은 전혀
해결하지 못함을 실측으로 확인했다. 두 원인이 독립적이라는 가설에 따라 Mask+White
Balance를 결합(c_wb)하니 Overall Accuracy 38.1%, GT=black Accuracy 55.5%로 모든 method
중 최고를 기록하면서 cool_cast 오분류율도 b_wb 수준(22.7%)을 유지했다 — 단 strong_light
(노출/대비 손실형 Cast)는 여전히 개선되지 않아 FC-012는 이번에도 미해결로 유지했다. 추가
비용(Segmenter 모델)은 추론 시간 1.29배, 모델 용량 +0.57MB로 측정했다(PAR-019).
EXP-028까지는 Attribute(c_wb) 분류 자체의 Accuracy만 오프라인 정지 이미지로 측정했고, 실제
Detection+Tracking+BestShot이 매 프레임 도는 파이프라인에 연결했을 때 FPS에 미치는 영향은
측정한 적이 없었다. 매 프레임·활성 Track마다 호출하는 방식(대안 A)을 실측하자 Segmentation
추론 비용이 누적되어 FPS가 10.68→4.38(-59.0%)까지 떨어졌고, BestShot이 확정되는
순간(Track 소실/영상 종료)에만 Track당 1회 호출하는 방식(대안 B, 지침 12/19의 원래 설계
의도)은 같은 조건에서 FPS 저하가 **0.28%**에 그쳤다. 대안 B를 run_full_pipeline.py에
실제로 연결하고 MetadataStore에 upper_color/lower_color 컬럼과
update_attributes()를 추가했다(VMS API 노출은 Accuracy가 아직 production 임계치에
못 미쳐 계속 보류, PAR-020).
EXP-026(White Balance)/EXP-028(Segmentation Mask)로도 고쳐지지 않던 strong_light
(검정 옷 → blue 오분류)를 Roadmap이 제안한 Gamma Correction으로 시도했다. crop 자신의
평균 밝기로 감마를 추정하는 첫 구현(대안 A)은 "검정 옷은 어둡다"는 분류 신호 자체와
"조명이 과다 노출"이라는 신호를 crop 하나로는 구분할 수 없다는 confound 때문에 목표
지표조차 개선하지 못하고(18.2%→18.2%) 정상 조명 Accuracy를 33.3%→9.5%로 무너뜨렸다.
감마를 crop이 아니라 같은 Frame의 배경(person bbox 밖 영역)에서 추정하는 대안 B로
이 confound를 해결하자 strong_light의 목표 오분류율이 18.2%→4.6%(지금까지 측정된
모든 방법 중 최저)까지 개선됐지만, 이 synthetic Benchmark의 전역 균일 조명 변형 특성상
low_light에서 새 Regression(40.5%→4.8%)이 생겨 Overall Accuracy는 오히려 낮아졌다
(26.2%→20.0%) — 두 결과 모두 그대로 기록하고 production 승격은 보류했다(PAR-021).
EXP-026/028/030이 시도한 조명 보정 4종과 EXP-027/031이 시도한 confidence 신호 2종이
모두 부분효과 또는 반증으로 끝나자, EXP-031 Next Action이 요구한 대로 새 보정을 더
설계하는 대신 기존 Hue 다수결 로직(region_dominant_color)의 중간값(필터 폴백 여부,
예측 색 분포, Hue bin 1/2위 득표 margin)을 그대로 노출하는 진단 함수를 추가해
GT=black 110셀 전수를 직접 들여다봤다. FC-012가 "검정→blue"로 프레이밍한 것과 달리
실제 오분류의 blue 비중은 29.9%(method b)/44.9%(production c_wb)뿐이었고, 조명을
전혀 가하지 않은 normal 조건에서도 40%대가 오분류됐으며, 오분류의 3540%가
PAR-016이 도입한 filter 폴백 경로(필터 통과 픽셀 <30%→원본 전체로 복귀)에서
발생함을 확인했다 - 조명 보정 4종이 Overall Accuracy를 거의 못 올린 이유가 "보정이
미흡해서"가 아니라 "애초에 고칠 수 있는 범위가 작아서"였음을 실측으로 설명했다.
부수적으로 GT 라벨 오류 2건(흑백 사진에서 밝은 셔츠를 "어두운 자켓"으로 오라벨링)도
발견해 교정 후 재측정까지 했다(교정 2셀/110셀로 normal Accuracy +5.55.9pp, 전체
Accuracy +2.9~4.6pp — 과거 PAR-017/018/019/021/022의 상대적 순위는 바뀌지 않음을
확인). production 코드는 바꾸지 않고(진단 함수만 추가, 기존 함수는 동작 비변경
Regression Test로 고정) 다음 방향을 "filter 폴백 경로 재설계"로 구체화했다(PAR-023).
EXP-032의 Error Analysis가 가리킨 filter 폴백 경로(필터 통과 픽셀 <30%→원본 전체로
복귀)를 그대로 "정교하게"(val_min 단계적 완화 35→15→0, 대안 B) 재설계했더니
production(c_wb) Overall Accuracy가 오히려 41.43%→36.67%로 악화됐다. 더 "거친"
수정(val_min을 그냥 35→10으로 낮추는 대안 A, 폴백 설계 자체는 그대로)이 Overall
49.05%(+7.6pp)/GT=black **75.00%(+15.0pp)**로 개선됐고, 비검정 GT에도 부작용이
없었다. b_used_fallback 플래그로 직접 슬라이싱해 원인을 특정했다: 대안 B는 "폴백이
발동한" cell에서는 실제로 대안 A를 이겼지만(72.73%>70.91%), Accuracy 손실의 더 큰
원천(+31.1pp)은 EXP-032가 분석 대상에서 제외했던 "폴백이 전혀 발동하지 않는" cell에
있었다 - val_min=35가 폴백을 피할 만큼은 통과시키면서도, 그 통과한 픽셀 집합 자체가
대표성이 없었다. "오분류가 집중된 경로를 정확히 진단했다고 그 경로만 고치는 것이
최선은 아니다"는 교훈을 남기고 대안 A를 채택했지만, n=21 한계로 production 기본값
승격은 보류했다(PAR-024).
val_min=0 실제 파이프라인 직접 검증 + sat_min Sweep - 단조 추세는 끝까지, 비단조는 섣불리 가정하지 않는다 (Stretch, EXP-034, PAR-025)
EXP-033이 채택한 val_min=10의 근거(val_min을 더 낮출수록 계속 좋아진다는 사후 Sweep)는
Mask+White Balance를 뺀 근사치였다 - 실제 production 경로(classify_person_ attributes_with_mask_and_wb_relaxed)에서 val_min=0까지 직접 재측정하니 가설대로
단조 개선이 유지돼 Overall 50.48%/GT=black 79.00%(val_min=10보다도 각각
+1.43pp/+4.00pp 추가 개선)를 기록했다. 반면 같은 방식으로 sat_min(채도 하한)을
Sweep한 두 번째 실험은 "낮출수록 좋아질 것"이라는 가설이 반증됐다 - sat_min을
515로 낮추면 양쪽 극단(25, 0)보다 GT=black Accuracy가 오히려 낮아지는 비단조
(U자형) 패턴이 나타났다. 결정론적 합성 픽셀로 재현한 원인: 필터가 엄격하면(25)
중간 채도 오염이 걸려 제외되고 폴백이 발동해 진짜 어두운 다수가 이기지만, 필터를
"딱 중간만" 완화하면(515) 오염은 통과하는데 더 어두운 진짜 다수는 여전히 통과하지
못해 오염이 다수결을 가져가고, 필터를 완전히 버리면(0) 진짜 다수가 수(count) 기준
으로 다시 우세해진다. 모든 지표에서 Baseline을 역전 없이 지배하는 sat_min=20만
추가로 채택했다(val_min=0, sat_min=20 → Overall 50.95%/GT=black 79.00%/비검정 GT
25.45%, 전부 EXP-033보다 개선이거나 동일). "한 파라미터의 단조 추세를 유사한 역할의
다른 파라미터에 그대로 가정하지 않는다"는 재사용 가능한 원칙을 남기고 production
승격은 여전히 보류했다(PAR-025).
GT 라벨 21 crop × 42 영역 전수 재검증 - 틀린 라벨이 모델 편향과 같은 방향이면 Accuracy를 거짓으로 검증해준다 (Stretch, EXP-035, PAR-026)
EXP-032부터 3회 이월됐던 "GT 라벨 21개 crop × 42개 영역 전체 재검증"을 실제로
수행했다. EXP-032는 오분류로 보고된 110셀 중 10셀(normal 조건)만 육안
재확인했는데, 이 범위는 "GT가 틀렸는데 classifier와 우연히 일치해 정답으로
집계된 셀"을 원천적으로 볼 수 없다는 사각지대가 있었다. results/EXP-027/ crops/*.jpg 21개 전체를 3배 Upscale해 42개 라벨 전부를 처음부터 재검토한 결과
신규 오류 5건(370_0 upper pink→white, 415_0 lower white→blue, 536_0 upper/lower
black→purple, 623_0 lower pink→black - 인접 인물 옷 Bleed)을 추가로 발견했다
(기존 EXP-032의 2건과 합쳐 7/42=16.7%). 동시에 GROUND_TRUTH가 6개 스크립트
(EXP-027/028/030/031/032/033/034)에 복사-붙여넣기되어 있어, EXP-032 자신을
포함한 5개 스크립트에는 그 교정 2건조차 반영되지 않은 Drift가 실제로 존재함을
grep 대조로 확인했다. evaluation/attribute_color/coco128_ground_truth.py를
단일 진실 공급원으로 신설해 교체했다. 교정된 GT로 EXP-034의 최종 후보
(val_min=0, sat_min=20)를 재측정하니 "교정하면 개선될 것"이라는 가설이 반증
됐다(Overall 50.95%→50.00%, -0.95pp) - 원인은 000000000536_0(와인색
원피스)의 틀린 black 라벨이 candidate config의 "어두우면 black으로 분류"하는
체계적 편향과 우연히 일치해 10개 cell 중 8개를 부당하게 "정답"으로 집계하고
있었기 때문이다. 그래도 candidate가 baseline(val_min=35, sat_min=25)을 역전
없이 지배한다는 순위 결론은 유지됐다(Overall 50.00%>41.43%, GT=black
78.95%>61.05%, 비검정 GT 26.09%>25.22%) - 다만 candidate의 우위 폭은 라벨
오류로 일부 부풀려져 있었다는 것을 정량적으로 확인했다. production 승격은
여전히 보류했다(PAR-026).
지침 18 Person Re-ID의 첫 Baseline을 구축했다. Market-1501/MSMT17 같은 정식
Multi-Camera Re-ID Dataset은 대부분 전용 서버/Google Drive 호스팅이라 이 세션의
egress 정책(pypi/GitHub Release Asset만 허용)에서 접근이 막혀(drive.google.com
403 실측 확인), coco128 실제 person crop 45명(results/EXP-027/crops/*.jpg)을
Gallery로 쓰고 조명 Cast/Occlusion/Bbox Jitter/수평 Flip 합성 Query 변형으로
평가했다(실제 재촬영이 아닌 근사라는 한계 명시).
대안 A(OSNet, torchreid)는 Pretrained Weight가 Google Drive에만 있어 접근 불가 확인 후 코드를 작성하지 않고 기각했다. 대안 B(이미 파이프라인이 쓰는 YOLO11n-cls 분류 Backbone의 GAP 특징 재사용)를 고전적 HSV Color Histogram Baseline과 비교한 결과, 전체 평균(Top-1)은 대안 B가 더 높았지만(49.21%→59.68%) Variant별로 분해하면 Baseline은 공간 변형(Flip 100%/Bbox Jitter 95.6%/Occlusion 84.4%)에, 대안 B는 조명 Cast(warm/cool_cast 100%)에 서로 완전히 다른 강점을 가진다는 것을 발견했다 - 평균만 보고 대안 B로 교체했다면 카지노의 핵심 문제인 Occlusion에서 20pp Regression을 놓쳤을 것이다. "그럼 둘을 합치면 더 좋을 것"이라는 직관적인 다음 가설(50:50 Score Fusion)도 실측으로 반증했다 - Baseline이 "확신 있게 틀리는" warm/cool_cast에서 평균이 대안 B의 거의 완벽한 신호까지 끌어내려 (100%→26.7%/20.0%) 전체 지표가 대안 B 단독보다 오히려 낮아졌다(Top-1 52.38%<59.68%).
두 방법 모두 극단적 노출 변화(low_light/strong_light)에서 거의 무작위로 붕괴하는 것을 FC-013으로 등록했다. n=45(합성 Query)·production 미승격 상태이며, MetadataStore/VMS 연결은 FC-013 해결 또는 실제 Multi-Frame Track 기반 재검증 이후로 보류한다.
| 단계 | FPS | P95 Latency |
|---|---|---|
| Video I/O만 | 474~3011 | 0.6~3.5ms |
| Detection만 | 23.4~27.4 | 51~57ms |
| 전체 통합 파이프라인 | 27.7 | 41.8ms |
MacBook Air M3에서 원본 영상 FPS(24~30)보다 빠르게 전체 파이프라인이 동작 — 실시간 처리 가능함을 확인했다.
| ID | 내용 | 상태 |
|---|---|---|
| FC-001 | 손상된 mp4는 OpenCV가 아예 못 엶(moov atom) | 예외 없이 안전 처리 완료 |
| FC-002 | 배경 밀집 군중 Detection 실패 | Wikimedia 영상 접근 복구되는 다음 세션으로 이월 |
| FC-003 | BestShot Position Score 경계 페널티 부정확 | PAR-009로 수정 완료 |
| FC-004 | Track 소실 시 EXIT 유실 | PAR-002로 수정 완료 |
| FC-005 | BestShot 후보 무제한 누적 Memory Leak | PAR-004로 수정 완료 |
| FC-006 | Track 체류시간(dwell_frames)이 전부 0으로 저장됨 | PAR-006로 수정 완료 |
| FC-007 | 선 근처 박스 흔들림으로 Line Crossing 왕복 중복 이벤트 | PAR-005로 수정 완료 |
| FC-008 | Adaptive Recording Event Clip Pre-Roll이 IDLE Tier까지 파고들면 Naive Stream Copy가 조용히 불완전한 Clip을 만듦 | PAR-010로 수정 완료 |
| FC-009 | Circular Buffer가 원본 BGR 프레임을 무압축 버퍼링해 채널당 628~753MB 필요 | PAR-012로 수정 완료 |
| FC-010 | Adaptive Recording+Circular Buffer 통합 시 Post-Roll이 영상/세션 종료 전에 끝나지 않으면 Event Clip이 잘림 | truncated_at_video_end 플래그로 명시 처리(EXP-023), Edge Camera 재시작 시 재현 가능성은 백로그 |
| FC-011 | VMS Search API가 raw SQL로 event_clip_path가 담긴 detail을 파싱하지 않고 그대로 반환 + Event Clip 재생 엔드포인트 자체가 없었음 |
PAR-015로 수정 완료 |
| FC-012 | Attribute 색상 분류에서 검정 옷이 strong_light/cool_cast 조명 하에서 반복적으로 blue로 오분류됨 |
EXP-026/PAR-017로 재검토: Gray World WB는 cool_cast(채널 비율 Cast)만 부분 개선하고 strong_light(노출/대비 손실)는 악화시킴 — 겨냥한 검정 GT 셀 전체 Accuracy는 변화 없음(15/35→15/35). EXP-027/PAR-018: 제안된 "무채색 확신도" 대안도 신호(채도/raw BGR std)가 achromatic/chromatic을 분리 못 해 보류. EXP-028/PAR-019: Segmentation Mask(대안 C)도 cool_cast를 단독으로는 개선 못 함(50.0%, b_wb보다 나쁨) — Mask+WB 결합(c_wb)으로 cool_cast는 b_wb 수준(22.7%) 유지하지만 strong_light는 그대로. EXP-030/PAR-021: Gamma Correction 대안 A(crop 자체 밝기)는 confound로 전체 Accuracy 붕괴(기각), 대안 B(배경 기반)는 strong_light→blue 오분류율을 18.2%→4.6%(최저)로 개선했으나 synthetic Benchmark 한계로 low_light에 새 Regression 발생. EXP-031/PAR-022: Frame 노출/Cast 기반 confidence 표시도 가설과 정반대로 반증(unflagged Accuracy가 flagged보다 낮음). EXP-032/PAR-023: 더 이상 새 보정을 추가하지 않고 오분류 자체를 Hue 다수결 중간값 단위로 직접 진단 — "검정→blue" 프레이밍은 실제 오분류의 29.9evaluation/attribute_color/coco128_ground_truth.py 단일 진실 공급원으로 교체. 교정된 GT로 재측정하니 Overall Accuracy가 오히려 50.95%→50.00%로 하락(가설 반증) — 원인은 와인색 원피스(536_0)의 틀린 black 라벨이 candidate config의 "어두우면 black" 편향과 우연히 일치해 Accuracy를 부당하게 높이고 있었기 때문. candidate가 baseline을 역전 없이 지배한다는 순위 결론은 유지되지만 우위 폭(GT=black)은 19.00pp→17.90pp로 축소 — 라벨 오류가 모델 편향과 같은 방향이면 Accuracy를 거짓으로 검증해줄 수 있다는 교훈 |
| FC-013 | Person Re-ID 임베딩(Color Histogram, YOLO Backbone 둘 다)이 극단적 전역 노출 변화(low_light/strong_light)에서 거의 무작위 수준으로 붕괴(대안 B strong_light Top-1 0.0%) |
EXP-036/PAR-027로 발견, 두 방법이 같은 약점을 공유해 Score Fusion으로도 구제되지 않음을 확인. 수정은 다음 세션 과제(백로그) |
- ByteTrack (Baseline, BoT-SORT는 아직 미비교 — Stretch)
- Bottom Center (ROI/Line 판정 기준점 — 사람이 서 있는 바닥 위치에 가장 가까움)
- SQLite vs PostgreSQL — 단일 프로세스 데모 규모에 적합해 SQLite 채택
- OpenCV VideoCapture (Baseline, FFmpeg 직접 제어는 Stretch)
- YOLO11n-cls Backbone 재사용 vs OSNet (Person Re-ID 임베딩) — OSNet Pretrained Weight가 Google Drive 전용 호스팅이라 egress 정책상 접근 불가(실측 403 확인), 이미 파이프라인이 쓰는 YOLO 계열 모델을 재사용하는 쪽을 채택(EXP-036, PAR-027). 다만 Color Histogram Baseline과 상호 배타적 강점(공간 변형 vs 조명 Cast)을 가져 production 단일 채택은 보류.
- PAR-001: Confidence-only BestShot → Composite Score로 개선 (정성적 검증)
- PAR-002: Intrusion EXIT 이벤트 유실 → forget_track() 수정 (Unit Test로 검증)
- PAR-003: "ONNX/INT8이 항상 빠르다"는 통념이 M3에서는 성립하지 않음을 실측으로 확인 (PyTorch FP32 25.1 FPS > ONNX INT8 22.0 FPS > ONNX FP32 19.2 FPS)
- PAR-004: Long Running Test로 BestShot 후보 무제한 누적 Memory Leak 발견 → Incremental Best-Tracking(O(1))으로 개선 (349초 만에 +3157MB/안전중단 → 32분간 +6MB 수준으로 평탄화)
- PAR-005: Line Crossing 왕복 중복 이벤트(FC-007) → 선까지 거리 기반 Hysteresis(band_px)로 개선, Cooldown 대안 대비 채택 이유 포함 (900프레임 재현에서 중복 24쌍 → 0쌍, 총 이벤트 57 → 31건)
- PAR-006: Track 체류시간(dwell_frames)이 항상 0으로 저장되는 문제(FC-006) → 호출 순서 교정만으로는 실제 케이스의 2/3가 여전히 실패함을 실측으로 확인하고, Loitering의 연속-스트릭 상태와 분리된 DwellCounter로 근본 수정 (통제된 시나리오 3종 모두 Ground Truth와 일치, 실제 YOLO+ByteTrack 실행에서 dwell>0 Track 비율 0%→83.3%)
- PAR-007: Crowd Analysis 고정 Threshold가 실측 분포와 어긋나 Crowded 등급이 전혀 발동하지 않는 문제(Degenerate Classification) → Percentile 기반 Threshold 도출로 개선 (Crowded 분류 비율 0.0%→7.9%, 859/10,800건)
- PAR-008: Adaptive Recording Event Clip을 Event마다 독립적으로 저장하면(대안 A) 간격이 짧은 두 Event의 Window가 겹쳐 중복 저장되는 문제 → 겹치거나 인접한 Window를 병합하는 방식(대안 B)으로 개선 (중복 361프레임(41.4%) → 0, 연속 녹화 저장량 18.7% 절감)
- PAR-009: BestShot Position Score의 margin_ratio 근접 판정이 실제 경계 접촉과 달라 부정확한 문제(FC-003) → boundary_eps(2px) 실제 접촉 판정으로 교체 (근접-비잘림 구간 False Positive Rate 91.7%→25.0%)
- PAR-010: Adaptive Recording Event Clip 재인코딩 낭비 → FFmpeg Stream Copy Hybrid로 개선하는 과정에서 Naive Stream Copy가 IDLE Tier와 겹치는 Pre-Roll을 조용히 누락시키는 문제(FC-008)를 발견해 IDLE 겹침 구간만 재인코딩하도록 수정 (완전성 유지, Clip 생성 CPU 시간 74.6~85.6% 절감)
- PAR-011: 지침 23 Circular Buffer를 실제 구현하는 과정에서 버퍼 용량=Pre-Roll 길이로 설정하면 트리거 프레임 자신이 evict되어 정확히 1프레임이 모자라는 Off-by-One 발견 →
required_capacity_for_pre_roll()(pre_roll+1+안전마진)로 수정 - PAR-012: Circular Buffer가 원본 BGR 프레임을 무압축 버퍼링해 채널당 628~753MB가 필요한 문제(FC-009) → push/pop 경계에서 JPEG 인코딩/디코딩을 추가해 메모리 90.8% 절감(789.94MB→72.47MB), Event Clip 완전성과 화질(MAE 2.61/255) 유지
- PAR-013: Circular Buffer quality를 Uniform하게 낮추면(대안 A) 실제 사고(EVENT) 프레임 화질을 가장 많이 희생시키는 문제 발견(EVENT MAE 2.59→5.40) → EVENT quality만 보존하는 Tier 차등 방식(대안 B)으로 EVENT MAE를 Baseline보다 개선(1.34)하면서 IDLE 메모리 41.1% 추가 절감
- PAR-014: Adaptive Recording/Circular Buffer를 실시간 Detection+Tracking+Metadata 파이프라인에 처음 통합하며, Pre-Roll을 EVENT 종료 후 꺼내는 방식(대안 A)이 실제 시나리오에서 47%(240/511프레임) 손실됨을 구현 전 실측 발견 → 트리거 순간 즉시 추출하는 방식(대안 B)으로 511/511 완전성 확보, Circular Buffer 통합 오버헤드는 전체 파이프라인의 P50 5.7%로 측정
- PAR-015: VMS Search API가
MetadataStore를 거치지 않고 raw SQL로event_clip_path가 담긴detailJSON을 파싱 없이 반환해(FC-011) 영상 재생이 불가능했던 문제 → API가MetadataStore.query_events()를 재사용하도록 바꾸고GET /events/{id}/clip(FileResponse)을 신설해 해결 (실제 EXP-023 산출물로 Event Clip 27,033,338 bytes를 byte-for-byte 서빙 확인, has_clip 필터로 ENTER 4건/EXIT 4건 정확히 분리) - PAR-016: Attribute 색상 분류(대안 B)의 그림자/하이라이트 필터가 저채도인 진짜 검정 옷까지 항상 제외시켜, 클로즈업 crop에서 소수 피부색 픽셀만 남아 Hue 다수결을 오염시키는 버그 발견(대안 B 최초 구현이 Baseline보다 낮은 Accuracy를 내는 역설로 실측) → 피부색 필터 + 필터 통과 비율 기반 폴백으로 수정 (전체 Accuracy 16%→40%, Baseline(32%)/대안 A(28%) 모두 상회, 조명 안정성 15%→40%)
- PAR-017: FC-012(검정 옷→blue 오분류) 수정을 위해 Gray World White Balance를 추가했더니 전체 평균 Accuracy는 올랐지만(0.44→0.48), FC-012가 겨냥하는 "GT=black" 35셀만 슬라이싱하면 Accuracy가 정확히 동일했음(15/35→15/35) → 평균 개선은 무관한 셀(진짜 파란 옷)의 부수 효과였음을 발견하고 production에 반영하지 않음(가설 기각을 정확한 Metric 슬라이싱으로 검증)
- PAR-018: n=5 평가 Dataset의 Attribute Accuracy(32
48%)를 coco128 실제 crop 21개로 재검증하니 1532%로 하락(method 순위는 유지) → 작은 Dataset 수치를 "운영 가능한 성능"으로 재인용하지 않기로 함. 동시에 "무채색 확신도" fallback 설계 전에 후보 신호(채도/raw BGR std)의 achromatic/chromatic 분리도를 먼저 측정해 둘 다 분리되지 않음을 확인하고 구현을 보류(검증 없는 기능 추가 방지) - PAR-019: Attribute 색상 분류의 고정 비율 사각형 영역이 배경을 구조적으로 포함하는 문제 → person Segmentation Mask로 배경을 픽셀 단위 제외(대안 C)하니 White Balance 없이도 Overall Accuracy가 기존 최고(b_wb 32.4%)를 넘어 35.2%로 개선, 단 FC-012의 표적 실패(cool_cast 흑→blue)는 그대로임을 확인(50.0%, b_wb보다 나쁨) → Mask+WB 결합(c_wb)으로 Overall/GT=black Accuracy 최고치(38.1%/55.5%) 달성하면서 cool_cast 오분류율도 b_wb 수준 유지(두 기법이 독립적인 원인을 해결함을 실측으로 확인)
- PAR-020: Attribute 분류를 실시간 파이프라인에 연결할 때 호출 빈도를 검증 없이 정하면 위험하다는 것을 매 프레임 호출(대안 A)의 실측 FPS 저하(10.68→4.38, -59.0%)로 먼저 확인 → BestShot 확정 시점에 Track당 1회만 호출하는 방식(대안 B)으로
run_full_pipeline.py에 실제로 연결해 FPS 저하를 0.28%로 줄임(Attribute 호출 수 2045→16, 900프레임 기준) - PAR-021: FC-012(
strong_light) 복원을 위해 crop 자신의 밝기로 Gamma를 추정하는 대안 A를 구현했더니, "검정 옷은 어둡다"는 분류 신호와 "조명이 과다 노출"이라는 신호가 crop 하나로는 분리되지 않는 confound 때문에 목표 지표도 개선 못 하고 정상 조명 Accuracy까지 33.3%→9.5%로 붕괴(기각) → 감마를 crop이 아니라 같은 Frame의 배경에서 추정하는 대안 B로 confound를 해결해strong_light→blue 오분류율을 18.2%→4.6%(최저)로 개선, 단 synthetic Benchmark의 전역 균일 조명 특성상low_light에 새 Regression이 생겨 Overall은 b보다 낮음을 그대로 기록(production 승격 보류) - PAR-022: FC-012 "구간 단위 낮은 신뢰도 표시" 설계를 Frame 밝기/Cast 편차 신호로 구현·검증했으나 세 Threshold 변형 모두 가설과 정반대로 반증됨(저신뢰도 표시 구간 Accuracy가 고신뢰도 표시 구간보다 오히려 높음, 30.6
31.9% > 11.522.3%) → 노출 신호가 가장 강하게 Flag하는 low_light가 이 classifier에서는 가장 정확한 조건(40.5%)이었기 때문임을 원인으로 특정하고 production 미연결 유지 - PAR-023: FC-012를 겨냥한 조명 보정 4종+confidence 신호 2종이 모두 실패한 이유를, 새 보정을 추가하는 대신 오분류 자체를 Hue 다수결 중간값(필터 폴백 여부/예측 색 분포/margin) 단위로 직접 진단해 찾음 → "검정→blue" 프레이밍은 오분류의 29.9
44.9%만 설명했고, 조명 무변형(normal) 상태에서도 40%대가 오분류됐으며, 오분류의 3540%가 PAR-016 filter 폴백 경로에서 발생함을 확인(조명 보정이 거의 효과 없었던 이유를 실측으로 설명). 부수적으로 GT 라벨 오류 2건도 발견해 교정 재측정(normal Accuracy +5.5~5.9pp, 과거 PAR들의 상대적 순위는 불변). 다음 방향을 "filter 폴백 경로 재설계"로 구체화 - PAR-024: PAR-023의 Error Analysis가 가리킨 filter 폴백 경로를 "정교하게"(val_min 단계적 완화 35→15→0, 대안 B) 재설계했더니 production Overall Accuracy가 오히려 41.43%→36.67%로 악화됨 → 더 "거친" 수정(val_min을 그냥 35→10으로 완화, 대안 A)이 Overall 49.05%(+7.6pp)/GT=black 75.00%(+15.0pp)로 개선 - 이득의 대부분(+31.1pp)이 EXP-032 분석이 제외한 "폴백 미발동" cell에서 나왔음을 직접 슬라이싱으로 확인(정교한 진단이 가리킨 narrow한 수정이 더 거친 수정보다 못할 수 있다는 교훈)
- PAR-025: PAR-024의 val_min=10 선택을 근사(Mask/WB 제외)로만 검증했던 한계를 메우기 위해 실제 production 경로(Mask+WB 포함)에서 val_min=0까지 직접 재측정하니 Overall 49.05%→50.95%로 더 개선됨을 확인(가설 확인) → 반면 같은 방식으로 sat_min(채도 하한)을 낮추는 두 번째 실험은 "낮출수록 좋아질 것"이라는 가설이 반증되어 비단조(U자형, sat_min=5~15 구간이 양쪽 극단보다 나쁨) 패턴을 발견 - 모든 지표에서 Baseline을 역전 없이 지배하는 sat_min=20만 추가로 채택(val_min 단조 추세를 다른 유사 파라미터에 그대로 가정하지 않는다는 원칙 확립)
- PAR-026: 3회 이월된 GT 라벨 21 crop × 42 영역 전수 재검증(오분류 보고 셀만 보던 EXP-032의 사각지대를 포함) → 신규 라벨 오류 5건 발견 + GROUND_TRUTH 6개 스크립트 복사-붙여넣기 Drift(EXP-032 자신의 교정조차 5개 스크립트에 미반영) 확인, 단일 진실 공급원 모듈로 교체 → 교정된 GT로 production 후보를 재측정하니 Overall Accuracy가 오히려 50.95%→50.00%로 하락(가설 반증, 와인색 원피스의 틀린 black 라벨이 모델의 black 예측 편향과 우연히 일치해 Accuracy를 부풀리고 있었음) → candidate가 baseline을 역전 없이 지배한다는 순위 결론은 유지되지만 우위 폭은 19.00pp→17.90pp로 축소(GT 라벨 오류가 모델 편향과 같은 방향이면 Accuracy를 거짓으로 검증해줄 수 있다는 교훈)
- PAR-027: Person Re-ID 첫 Baseline에서 Color Histogram과 YOLO Backbone 임베딩의 전체 평균 Top-1(49.21%→59.68%)만 보면 대안 B가 더 낫다고 결론 내리기 쉽지만, Variant별 분해로 Baseline이 공간 변형(Flip/Bbox Jitter/Occlusion)에, 대안 B가 조명 Cast에 서로 완전히 다른 강점을 가진 상호 배타적 관계임을 발견 → "그럼 합치면 더 좋을 것"이라는 다음 가설(50:50 Score Fusion)도 실측으로 반증(Top-1 52.38%<59.68%) - Baseline이 확신 있게 틀리는 조건에서 평균이 대안 B의 거의 완벽한 신호까지 끌어내리는 메커니즘을 직접 확인(평균 지표의 착시와 "합치면 항상 안전하다"는 가정 모두에 대한 반증 사례)
Full Pipeline(Detection+Tracking+ROI/Line/Loitering+BestShot+Metadata)을 실제 사람이 찍힌 정지 장면 (+합성 Pan/Jitter)으로 연속 실행해 Memory/FPS 안정성을 측정했다. 기존 BestShot 로직은 Track마다 관측된 모든 crop을 무제한으로 쌓아 349초 만에 Memory가 +3.1GB 증가해 안전 중단되었고(≈9MB/초, FPS도 −12.4% 하락), 매 프레임 즉시 채점해 최고 점수 1개만 유지하는 Incremental Best-Tracking으로 바꾼 뒤에는 32.1분 (15,000프레임) 연속 실행에서도 Memory 증가가 워밍업 이후 사실상 0(+6MB)에 수렴함을 확인했다. (이번 세션은 네트워크 정책상 기존 Wikimedia 영상을 재확보할 수 없어 대체 입력을 사용함 — EXP-010 experiment.md Decision 참고. 실제 다양한 군중 영상으로의 교차 검증은 다음 세션 Next Action으로 남김.)
MacBook Air M3(CPU/MPS)에서 CUDA/TensorRT 없이 YOLO11n Pretrained로 실시간 처리를 달성했다(EXP-008 참고). Edge Optimization(EXP-009)에서 PyTorch FP32 → ONNX FP32 → ONNX INT8(Dynamic Quantization)을 실측 비교한 결과:
| Model | Size(MB) | F1 | FPS |
|---|---|---|---|
| PyTorch FP32 | 5.61 | 0.698 | 25.14 |
| ONNX FP32 | 10.74 | 0.700 | 19.20 |
| ONNX INT8 (Dynamic) | 3.05 | 0.686 | 21.95 |
"ONNX/INT8이 항상 더 빠르다"는 통념과 반대로, M3에서는 PyTorch 원본이 가장 빨랐다(PAR-003). ONNX Runtime의 CPUExecutionProvider가 Apple Silicon 네이티브 커널보다 느리고, Dynamic Quantization은 가중치만 압축할 뿐 Convolution 연산 자체를 가속하지 못하는 것이 원인으로 분석된다. 모델 크기가 중요한 실제 Edge Camera 배포 시에는 Static Quantization/CoreML 변환을 추가로 검토해야 한다(미검증, 백로그). C++ 포팅(Video Frame Reader, ROI 계산, Line Crossing, Event State Machine 등)은 아직 Stretch Goal로 남아 있다.
- 카지노와 가장 유사한 "실내 상업시설 CCTV" 공개 Dataset이 거의 없어 리테일/캠퍼스/거리 Dataset(Wikimedia, coco128)으로 대체했다.
- MOT17/CrowdHuman/ExDark 등 대용량 GT Dataset은 용량 제약으로 미다운로드 — 정량 지표(ID Switch, Occlusion Recall 등)를 일부 측정하지 못했다.
- 다중 카메라 Person Re-ID는 한화비전 공식 자료에 없어 실제 구현과 연결짓지 않는다. Baseline은 구축했으나(EXP-036, PAR-027) Market-1501/MSMT17급 정식 Multi-Camera Dataset 없이 합성 Query로 평가했다는 한계가 있고, 극단적 노출 변화(FC-013)에서 두 임베딩 방식 모두 붕괴해 production에는 아직 연결하지 않았다.
- Ground Truth 없이 정성적으로만 검증한 부분(BestShot 등)이 있다.
현재는 공개 mp4/webm 파일을 입력으로 사용한다. 추후 실제 IP Camera를 확보하면 RTSP 스트림 입력과 ONVIF 기반 카메라 제어로 확장할 계획이다.
cd cctv
python3 -m venv .venv && source .venv/bin/activate
pip install opencv-python ultralytics numpy fastapi "uvicorn[standard]" pytest lap matplotlib
# 단위 테스트 (295개, 7 skipped)
pytest tests/ -q
# 각 Phase 실험 재현
python scripts/run_exp001_video_input_baseline.py
python scripts/run_exp002_detection_baseline.py
python scripts/run_exp003_tracking_baseline.py
python scripts/run_exp004_bestshot.py
python scripts/run_exp005_intrusion.py
python scripts/run_exp006_line_crossing.py
python scripts/run_exp007_loitering.py
python scripts/run_exp010_long_running_test.py --mode baseline # Memory Leak 재현 (PAR-004)
python scripts/run_exp010_long_running_test.py --mode fixed # 수정 후 재측정
python scripts/run_exp014_line_crossing_hysteresis.py # FC-007 재현 + band_px A/B (PAR-005)
python scripts/run_exp015_dwell_time_fix.py # FC-006 재현 + DwellCounter 수정 검증 (PAR-006)
python scripts/run_exp016_heatmap_crowd.py # Heatmap Detection Center vs Track-Gated, Crowd Threshold 비교 (PAR-007)
python scripts/run_exp017_adaptive_recording.py # Adaptive Recording Baseline vs 개선, Event Clip 병합 A/B (PAR-008)
python scripts/run_exp018_bestshot_position_score_fix.py # FC-003 재현 + boundary_eps 수정 검증 (PAR-009)
python scripts/run_exp019_event_clip_copy.py # FC-008 재현 + FFmpeg Stream Copy Hybrid (PAR-010)
python scripts/run_exp020_circular_buffer.py # Circular Buffer Off-by-One 발견/수정 (PAR-011)
python scripts/run_exp021_compressed_circular_buffer.py # FC-009 재현 + JPEG 압축 버퍼링 (PAR-012)
python scripts/run_exp022_tier_quality_circular_buffer.py # Circular Buffer Tier별 quality 차등 (PAR-013)
python scripts/run_exp023_pipeline_integration.py # Adaptive Recording+Circular Buffer 실시간 파이프라인 통합, Pre-Roll 추출 시점 A/B (PAR-014)
python scripts/run_exp025_attribute_color.py # Attribute 상/하의 색상 분류 Baseline/A/B + 조명 안정성 (PAR-016)
python scripts/run_exp026_fc012_white_balance.py # FC-012 재현 + White Balance/Achromatic Shortcut 대안 비교 (PAR-017)
python scripts/run_exp027_attribute_coco128.py # coco128 기반 n 확장 재검증 + 무채색 신호 분리도 분석 (PAR-018)
python scripts/run_exp028_attribute_segmentation_mask.py # Segmentation Mask 기반 영역 분리 대안 C + Mask/WB 결합 (PAR-019)
python scripts/run_exp029_attribute_pipeline_integration.py # Attribute 실시간 통합 호출 빈도 A(매 프레임)/B(Track당 1회) 비교 (PAR-020)
python scripts/run_exp030_attribute_gamma_correction.py # FC-012 strong_light Gamma Correction A(crop 자체)/B(배경 기반) 비교 (PAR-021)
python scripts/run_exp031_attribute_confidence_flag.py # FC-012 구간 단위 신뢰도 표시 Frame 노출/Cast 신호 A/B/C 비교 (PAR-022)
python scripts/run_exp032_attribute_black_error_analysis.py # GT=black 오분류 Hue 다수결 단위 Error Analysis + GT 라벨 오류 교정 (PAR-023)
python scripts/run_exp033_fallback_redesign.py # filter 폴백 재설계 val_min 완화(A) vs 단계적 폴백(B) 비교 (PAR-024)
python scripts/run_exp034_val_min_zero_sat_min_sweep.py # val_min=0 실제 파이프라인 재검증 + sat_min Sweep (PAR-025)
python scripts/run_exp035_ground_truth_audit.py # GT 21 crop x 42 영역 전수 재검증 + 단일 진실 공급원 전환 (PAR-026)
python scripts/run_exp036_person_reid_baseline.py # Person Re-ID Baseline: Color Histogram vs YOLO Backbone + Score Fusion (PAR-027)
# 통합 파이프라인 + VMS Search API
python scripts/run_full_pipeline.py
uvicorn api.main:app --app-dir src --reload
# http://127.0.0.1:8000 (Dashboard), http://127.0.0.1:8000/docs (Swagger)cctv/
CLAUDE.md # 프로젝트 지침 (전체 원칙)
src/
video_pipeline/ # Phase 1
detection/ # Phase 2 평가 유틸
bestshot/ # Phase 4 (+ tracker.py: Incremental Best, PAR-004)
events/ # Phase 5~7 (ROI/Line/Loitering) + dwell.py (누적 체류, PAR-006)
analytics/ # Heatmap + Crowd Analysis (EXP-016, PAR-007)
recording/ # Adaptive Recording Tier/Event Clip 계획 (EXP-017, PAR-008)
metadata/ # Metadata Store (SQLite)
attributes/ # 상/하의 색상 분류 (EXP-025~029) + pipeline.py(Track당 1회 호출, PAR-020)
reid/ # Person Re-ID: matching.py(Cosine/랭킹/mAP, cv2/torch 비의존) + embedding.py (EXP-036, PAR-027)
api/ # VMS Search API (FastAPI)
evaluation/ # Ground Truth 단일 진실 공급원 (attribute_color/coco128_ground_truth.py, EXP-035, PAR-026)
scripts/ # EXP-001~036 실행 스크립트 + 통합 파이프라인
tests/ # Unit Test 295개
experiments/ # EXP-001~036, PAR-001~027 기록
results/ # 실행 결과(CSV, 스냅샷, BestShot 그리드)
data/ # raw/test 영상 (대용량은 git 제외)