{"id":50324991,"url":"https://github.com/pathcosmos/jeju_masking","last_synced_at":"2026-05-29T05:04:28.359Z","repository":{"id":331408619,"uuid":"1126499112","full_name":"pathcosmos/jeju_masking","owner":"pathcosmos","description":"4K 영상 자동 마스킹 도구 - YOLO12x + TensorRT + GPU 가속 (사람/번호판 마스킹, NVDEC/NVENC, 멀티스레딩, 2-Pass 모드)","archived":false,"fork":false,"pushed_at":"2026-01-15T01:55:29.000Z","size":234,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-15T07:59:49.481Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pathcosmos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-02T03:20:18.000Z","updated_at":"2026-01-15T01:55:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pathcosmos/jeju_masking","commit_stats":null,"previous_names":["pathcosmos/jeju_masking"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pathcosmos/jeju_masking","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathcosmos%2Fjeju_masking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathcosmos%2Fjeju_masking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathcosmos%2Fjeju_masking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathcosmos%2Fjeju_masking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pathcosmos","download_url":"https://codeload.github.com/pathcosmos/jeju_masking/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathcosmos%2Fjeju_masking/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33637486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T05:04:15.133Z","updated_at":"2026-05-29T05:04:28.318Z","avatar_url":"https://github.com/pathcosmos.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Video Privacy Masking Tool\n\n4K 영상에서 얼굴과 차량 번호판을 자동으로 감지하고 마스킹하는 도구입니다.\nNVIDIA CUDA / Apple Silicon MPS GPU 가속, 멀티스레딩, 트래킹 보간 등 다양한 최적화 기법을 적용하여 고해상도 영상도 효율적으로 처리합니다.\n\n## 주요 기능\n\n- **사람 전체 마스킹**: YOLO12x 모델로 사람 감지 후 전신 마스킹 (얼굴만이 아닌 전체)\n- **차량 번호판 마스킹**: 차량 감지 + 번호판 영역 추정 마스킹\n- **적응형 색보정**: 장면별 자동 분석 + 시네마틱 필터 적용 (선택적)\n- **배치 처리 시스템**: 여러 영상 동시 처리 + 자동 큐 관리\n- **TensorRT 가속**: YOLO 모델을 TensorRT 엔진으로 변환하여 최대 성능 (기본 활성화)\n- **GPU 블러**: OpenCV CUDA 가우시안 블러 (CPU 대비 13배 빠름)\n- **GPU 색보정**: OpenCV CUDA 기반 색보정 가속\n- **NVDEC 하드웨어 디코딩**: GPU에서 직접 영상 디코딩\n- **NVENC 하드웨어 인코딩**: RTX GPU에서 H.264/HEVC 하드웨어 인코딩\n- **FP16 반정밀도 추론**: NVIDIA GPU에서 메모리 절약 및 속도 향상\n- **MPS GPU 가속**: Apple Silicon에서 Metal Performance Shaders 활용\n- **멀티스레딩 파이프라인**: 읽기/처리/쓰기 분리로 성능 향상\n- **프레임 스킵 + 트래킹 보간**: ByteTrack/BoT-SORT로 추적, 중간 프레임 보간\n- **해상도 다운스케일 감지**: 감지는 축소 해상도, 출력은 원본 해상도 유지\n\n## 파일 구조\n\n```\njeju_masking/\n├── mask_video.py            # CLI 인터페이스 (권장 진입점)\n├── video_masker.py          # 핵심 마스킹 클래스 (VideoMasker, VideoMaskerOptimized)\n├── adaptive_color_grade.py  # 적응형 색보정 모듈 (ColorGrader 클래스)\n├── batch_masking.py         # 배치 처리 큐 시스템\n├── masking_utils.py         # 공용 유틸리티 (로거, 시간 파싱 등)\n├── encoding_utils.py        # 인코딩 유틸리티 (NVENC 설정, 시스템 최적화)\n├── two_pass.py              # 2-Pass 모드 함수\n├── high_performance.py      # 고성능 모드 함수\n├── models/                  # 감지 모델 (자동 다운로드)\n├── movs/                    # 입출력 영상 폴더\n│   └── 4k_420_10bit/        # 4K 10bit 영상 폴더\n│       ├── day/             # 주간 영상\n│       │   └── masking/     # 마스킹 출력 폴더\n│       └── night/           # 야간 영상\n│           └── masking/     # 마스킹 출력 폴더\n├── SETUP.md                 # 환경 설정 가이드\n└── README.md                # 이 파일\n```\n\n---\n\n## 설치\n\n### 1. 시스템 의존성\n\n#### macOS (Apple Silicon)\n\n```bash\n# ffmpeg 설치 (HEVC 인코딩용)\nbrew install ffmpeg\n```\n\n#### Ubuntu/Linux (NVIDIA GPU)\n\n```bash\n# ffmpeg 및 빌드 도구 설치\nsudo apt update\nsudo apt install -y ffmpeg build-essential cmake git pkg-config\n```\n\n### 2. Python 환경 설정\n\n#### 기본 설치 (pip OpenCV - CUDA 없음)\n\n```bash\n# uv 설치 (없는 경우)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# 가상환경 생성\nuv venv --python 3.12\n\n# 가상환경 활성화\nsource .venv/bin/activate\n\n# 패키지 설치\nuv pip install ultralytics opencv-contrib-python numpy lap pyyaml torch torchvision\n```\n\n#### NVIDIA GPU 최적화 설치 (OpenCV CUDA 빌드)\n\nNVIDIA GPU에서 OpenCV DNN CUDA 백엔드를 사용하려면 OpenCV를 소스에서 빌드해야 합니다.\npip로 설치되는 opencv-python 패키지는 CUDA 지원이 포함되어 있지 않습니다.\n\n자세한 빌드 가이드는 아래 [OpenCV CUDA 빌드 가이드](#opencv-cuda-빌드-가이드-nvidia-gpu) 섹션을 참조하세요.\n\n---\n\n## 빠른 시작 (Quick Start)\n\n### 1. 최초 실행 전 TensorRT 엔진 준비 (선택사항)\n\n최초 실행 시 TensorRT 엔진이 자동 생성되지만, 사전에 생성하면 시간을 절약할 수 있습니다.\n\n```bash\nsource .venv/bin/activate\n\n# TensorRT 엔진 생성 (약 2-5분 소요)\nyolo export model=yolo12x.pt format=engine half=True device=0\n```\n\n### 2. 기본 실행\n\n```bash\n# 영상 마스킹 (사람 + 번호판)\npython mask_video.py input.mp4 --hevc\n```\n\n### 3. 출력 확인\n\n```bash\n# 출력 파일: input_masked.mp4 (기본 경로)\nls -la input_masked.mp4\n```\n\n---\n\n## 사용법\n\n### 기본 실행\n\n```bash\nsource .venv/bin/activate\npython mask_video.py input.mp4\n```\n\n### 처리 모드 선택\n\n| 모드 | 옵션 | 특징 | 권장 사용 |\n|------|------|------|-----------|\n| **최적화 모드** | (기본) | 1-Pass, 멀티스레딩 파이프라인 | 일반 처리 |\n| **고성능 모드** | `--high-performance` | 1-Pass, 배치 GPU 추론 + NVENC | RTX GPU 최대 활용 |\n| **2-Pass 모드** | `--2pass` | Pass1(분석) + Pass2(인코딩) 분리 | JSON 재작업, 대용량 처리 |\n| **간단 모드** | `--simple` | 최적화 없음, 기본 설정 | CPU 환경, 빠른 테스트 |\n\n### 옵션 전체 목록\n\n#### 입출력 옵션\n\n| 옵션 | 설명 | 기본값 |\n|------|------|--------|\n| `input` | 입력 비디오 파일 (필수) | - |\n| `-o, --output` | 출력 파일 경로 | `{input}_masked.mp4` |\n| `--start` | 시작 시간 (예: `23:00`, `1:30:00`) | 처음부터 |\n| `--end` | 종료 시간 (예: `28:00`) | 끝까지 |\n| `--hevc` | HEVC(H.265) 인코딩 사용 | 비활성화 |\n\n#### 마스킹 옵션\n\n| 옵션 | 설명 | 기본값 |\n|------|------|--------|\n| `--no-persons` | 사람 마스킹 비활성화 | - |\n| `--no-plates` | 번호판 마스킹 비활성화 | - |\n| `--mask-type` | `blur` 또는 `mosaic` | `blur` |\n| `--blur-strength` | 블러 강도 (홀수 값, GPU는 31 이하) | `31` |\n| `--mosaic-size` | 모자이크 블록 크기 | `15` |\n\n#### 색보정 옵션 (적응형 필터)\n\n| 옵션 | 설명 | 기본값 |\n|------|------|--------|\n| `--color-grade` | 적응형 색보정 활성화 | 비활성화 |\n| `--cg-interval` | 분석 주기 (프레임 단위) | `1000` |\n| `--cg-smooth` | 부드러운 전환 윈도우 (프레임 단위) | `300` |\n\n#### 감지 파라미터\n\n| 옵션 | 설명 | 기본값 |\n|------|------|--------|\n| `--person-conf` | 사람 감지 신뢰도 임계값 | `0.4` |\n| `--vehicle-conf` | 차량 감지 신뢰도 임계값 | `0.3` |\n| `--person-expand` | 사람 영역 확장 비율 | `0.2` |\n| `--plate-expand` | 번호판 영역 확장 비율 | `0.5` |\n| `--max-mask-ratio` | 프레임 대비 최대 마스킹 비율 | `0.4` |\n\n#### 2-Pass 모드 옵션\n\n| 옵션 | 설명 | 기본값 |\n|------|------|--------|\n| `--2pass` | 2-Pass 모드 활성화 (분석→인코딩 분리) | 비활성화 |\n| `--analyze-only` | Pass 1만 실행: 마스크 좌표를 JSON으로 저장 | - |\n| `--encode-only` | Pass 2만 실행: JSON 마스크 데이터로 인코딩 | - |\n| `--mask-json` | 마스크 JSON 파일 경로 (`--encode-only`와 함께) | - |\n| `--keep-json` | 2-Pass 완료 후 JSON 파일 유지 | 삭제 |\n\n#### 성능 최적화 옵션\n\n| 옵션 | 설명 | 기본값 |\n|------|------|--------|\n| `--device` | 연산 디바이스 (`auto`, `mps`, `cuda`, `cpu`) | `auto` |\n| `--yolo-model` | YOLO 모델 (`yolov8n`~`yolov8x`, `yolo11n`~`yolo11x`, `yolo12n`~`yolo12x`) | `yolo12x` |\n| `--tensorrt` | TensorRT 가속 (.engine 파일 필요) | **활성화** |\n| `--no-tensorrt` | TensorRT 비활성화 (PyTorch 모델 사용) | - |\n| `--fp16` | FP16 반정밀도 추론 (NVIDIA GPU 전용) | 비활성화 |\n| `--nvdec` | NVDEC GPU 디코딩 | **활성화** |\n| `--no-nvdec` | NVDEC 비활성화 (CPU 디코딩) | - |\n| `--detect-interval` | 감지 수행 프레임 간격 (1=매 프레임, -1=자동) | `-1` |\n| `--detect-scale` | 감지용 해상도 스케일 (0.5 = 50%, -1=자동) | `-1` |\n| `--batch-size` | 배치 추론 크기 (-1=자동) | `-1` |\n| `--queue-size` | 프레임 큐 크기 (-1=자동, 병렬처리 시 64 권장) | `-1` |\n| `--high-performance` | 고성능 모드: FFmpeg 파이프라인 + 배치 GPU 추론 | 비활성화 |\n| `--no-auto` | 자동 최적화 비활성화 | - |\n\n#### 트래킹 파라미터\n\n| 옵션 | 설명 | 기본값 |\n|------|------|--------|\n| `--tracker` | 트래커 종류 (`bytetrack`, `botsort`) | `bytetrack` |\n| `--track-buffer` | 트래킹 버퍼 크기 (손실 허용 프레임) | `30` |\n| `--match-thresh` | 트래킹 매칭 임계값 | `0.8` |\n| `--iou-thresh` | IoU 임계값 | `0.5` |\n\n#### 로깅 옵션\n\n| 옵션 | 설명 | 기본값 |\n|------|------|--------|\n| `--log` | 로그 파일 경로 | 자동 생성 |\n| `--verbose, -v` | 상세 로그 출력 | 비활성화 |\n\n---\n\n## 사용 예시\n\n### 기본 마스킹\n\n```bash\n# 전체 영상 마스킹 (사람 + 번호판 블러)\npython mask_video.py video.mp4\n\n# 특정 구간만 처리 (23분~28분)\npython mask_video.py video.mp4 --start 23:00 --end 28:00\n\n# HEVC 인코딩 (RTX GPU에서 NVENC 자동 사용)\npython mask_video.py video.mp4 --hevc\n```\n\n### 고성능 모드 (RTX GPU 권장)\n\n```bash\n# 1-Pass 고성능 모드: 배치 GPU 추론 + NVENC 인코딩\n# RTX 4070 SUPER 기준 4K 60fps에서 ~48 fps 달성\npython mask_video.py video.mp4 --high-performance --hevc\n\n# FP16 반정밀도 추론 (메모리 절약, 속도 향상)\npython mask_video.py video.mp4 --high-performance --fp16 --hevc\n```\n\n### 2-Pass 모드 (GPU 최대 활용, 재작업 가능)\n\n```bash\n# 2-Pass 모드: Pass1(분석) → Pass2(인코딩) 순차 실행\npython mask_video.py video.mp4 --2pass --hevc\n\n# JSON 파일 유지 (재인코딩 가능)\npython mask_video.py video.mp4 --2pass --hevc --keep-json\n```\n\n### 2-Pass 분리 실행 (일괄 처리)\n\n```bash\n# 여러 영상을 분석만 먼저 실행 (GPU 100% YOLO 추론)\npython mask_video.py video1.mp4 --analyze-only\npython mask_video.py video2.mp4 --analyze-only\npython mask_video.py video3.mp4 --analyze-only\n\n# 분석 완료 후 순차 인코딩 (GPU 100% NVENC)\npython mask_video.py video1.mp4 --encode-only --mask-json video1_masks.json --hevc\npython mask_video.py video2.mp4 --encode-only --mask-json video2_masks.json --hevc\npython mask_video.py video3.mp4 --encode-only --mask-json video3_masks.json --hevc\n```\n\n### 적응형 색보정 + 마스킹\n\n```bash\n# 마스킹 + 시네마틱 색보정 (기본 설정)\npython mask_video.py video.mp4 --color-grade --hevc\n\n# 색보정 분석 주기 조정 (500프레임마다 분석)\npython mask_video.py video.mp4 --color-grade --cg-interval 500 --hevc\n\n# 색보정 전환 부드럽게 (600프레임 윈도우)\npython mask_video.py video.mp4 --color-grade --cg-smooth 600 --hevc\n```\n\n### 배치 처리 (여러 영상 자동 큐)\n\n```bash\n# 기본 배치 처리 (2개 동시 처리)\npython batch_masking.py /path/to/video/folder\n\n# 동시 처리 개수 지정\npython batch_masking.py /path/to/video/folder --workers 3\n\n# 색보정 비활성화\npython batch_masking.py /path/to/video/folder --no-color-grade\n\n# 출력 경로 지정\npython batch_masking.py /path/to/input --output-dir /path/to/output\n\n# 작업 미리보기 (실제 실행 안 함)\npython batch_masking.py /path/to/video/folder --dry-run\n```\n\n### 번호판/사람 선택 마스킹\n\n```bash\n# 번호판만 마스킹 (사람 제외)\npython mask_video.py video.mp4 --no-persons\n\n# 사람만 마스킹 (번호판 제외)\npython mask_video.py video.mp4 --no-plates\n\n# 모자이크 처리\npython mask_video.py video.mp4 --mask-type mosaic --mosaic-size 20\n```\n\n### 정확도 vs 속도 조절\n\n```bash\n# 매 프레임 감지 (정확도 최대, 속도 느림)\npython mask_video.py video.mp4 --detect-interval 1\n\n# 5프레임마다 감지 (속도 최대, 정확도 감소)\npython mask_video.py video.mp4 --detect-interval 5 --detect-scale 0.25\n```\n\n### 트래킹 조정\n\n```bash\n# 긴 트래킹 버퍼 (객체가 일시적으로 사라져도 추적 유지)\npython mask_video.py video.mp4 --track-buffer 60\n```\n\n### 실시간 로그 모니터링\n\n```bash\n# 상세 로그 + 파일 저장\npython mask_video.py video.mp4 -v --log masking.log\n\n# 별도 터미널에서 실시간 확인\ntail -f masking.log\n```\n\n---\n\n## 적응형 색보정 (Adaptive Color Grading)\n\n### 개요\n\n적응형 색보정은 영상의 장면별 특성을 분석하여 자동으로 시네마틱 필터를 적용합니다.\n일반적인 LUT(Look-Up Table) 방식과 달리, 각 장면의 밝기와 채도를 분석하여\n최적의 보정값을 실시간으로 계산합니다.\n\n### 작동 원리\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ 1. 분석 단계 (프레임 0, 1000, 2000, ...)                      │\n│                                                             │\n│   프레임 → [밝기 분석] → [채도 분석] → 보정 파라미터 계산     │\n│            (HSV V채널)    (HSV S채널)                         │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│ 2. 보간 단계 (중간 프레임)                                    │\n│                                                             │\n│   키프레임 A ─── [선형 보간] ─── 키프레임 B                   │\n│   (프레임 0)     (프레임 500)     (프레임 1000)                │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│ 3. 스무딩 단계 (이동평균)                                     │\n│                                                             │\n│   [보간된 값] → [이동평균 필터] → 최종 보정 파라미터          │\n│                (윈도우: 300 프레임)                           │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### C 스타일 필터 특성\n\n기본 적용되는 \"C 스타일\"은 시네마틱한 느낌을 연출합니다:\n\n| 파라미터 | 값 | 설명 |\n|----------|----|----- |\n| 목표 밝기 | 115 | 약간 밝은 톤 |\n| 목표 채도 | 130 | 생생한 색감 |\n| 대비 | 1.15 | 살짝 강조된 대비 |\n| 따뜻함 | 15 | 오렌지/골드 톤 |\n| 하이라이트 보호 | 0.8 | 과노출 방지 |\n\n### GPU 가속\n\nOpenCV CUDA가 사용 가능한 경우 GPU에서 색보정을 처리합니다:\n\n```python\n# GPU 사용 여부 자동 감지\n# cv2.cuda.getCudaEnabledDeviceCount() \u003e 0 이면 GPU 사용\n\n# GPU 색보정 파이프라인:\n# 1. cv2.cuda_GpuMat.upload() - CPU → GPU 전송\n# 2. cv2.cuda.cvtColor() - 색공간 변환\n# 3. cv2.cuda.split/merge() - 채널 분리/병합\n# 4. cv2.cuda_GpuMat.download() - GPU → CPU 전송\n```\n\n### 파라미터 조정 가이드\n\n| 상황 | 권장 설정 |\n|------|-----------|\n| **급격한 장면 변화** | `--cg-interval 500` (더 자주 분석) |\n| **일정한 조명** | `--cg-interval 2000` (분석 빈도 감소) |\n| **부드러운 전환** | `--cg-smooth 600` (큰 윈도우) |\n| **빠른 반응** | `--cg-smooth 100` (작은 윈도우) |\n\n---\n\n## 배치 처리 시스템\n\n### 개요\n\n`batch_masking.py`는 여러 영상을 자동으로 처리하는 큐 시스템입니다.\n지정된 수의 영상을 동시에 처리하고, 하나가 완료되면 다음 파일을 자동으로 시작합니다.\n\n### 사용법\n\n```bash\n# 기본 사용 (2개 동시 처리, 색보정 활성화)\npython batch_masking.py /path/to/videos\n\n# 옵션\npython batch_masking.py /path/to/videos \\\n    --output-dir /path/to/output \\   # 출력 경로\n    --workers 3 \\                     # 동시 처리 개수\n    --no-color-grade \\                # 색보정 비활성화\n    --log-dir /path/to/logs \\         # 로그 경로\n    --dry-run                         # 미리보기\n```\n\n### 로그 구조\n\n```\nmasking/logs/\n├── batch_20260112_010317.log   # 마스터 로그 (전체 진행)\n├── 01-111_4k_420_10bit.log     # 개별 로그 (파일별 상세)\n├── 01-222_4k_420_10bit.log\n└── ...\n```\n\n### 마스터 로그 예시\n\n```\n[2026-01-12 01:03:17] ==================================================\n[2026-01-12 01:03:17] 배치 마스킹 작업 시작\n[2026-01-12 01:03:17] 총 파일: 10개, 동시 처리: 2개\n[2026-01-12 01:03:17] ==================================================\n[2026-01-12 01:03:17] ▶ 시작: 01-111_4k_420_10bit.mp4\n[2026-01-12 01:03:17] ▶ 시작: 01-222_4k_420_10bit.mp4\n[2026-01-12 02:15:30] ✓ 완료: 01-222_4k_420_10bit.mp4 (1시간 12분 13초)\n[2026-01-12 02:15:30]    진행: 1/10 완료, 9개 남음\n[2026-01-12 02:15:30] ▶ 시작: 01-333_4k_420_10bit.mp4\n```\n\n### 권장 동시 처리 수\n\n| 시스템 RAM | GPU VRAM | 권장 workers |\n|-----------|----------|--------------|\n| 16GB | 8GB | 1 |\n| 32GB | 12GB | **2** |\n| 64GB | 12GB+ | 3-4 |\n\n---\n\n## 권장 파라미터 설정\n\n### 시나리오별 권장 설정\n\n#### 🎯 일반 사용 (품질 우선)\n\n```bash\n# 기본 설정 - 대부분의 경우 충분\npython mask_video.py video.mp4 --hevc\n\n# 자동 최적화가 적용됨:\n# - yolo12x TensorRT 모델\n# - GPU 블러 (blur-strength 31)\n# - NVDEC 디코딩 + NVENC 인코딩\n# - 시스템 RAM/VRAM 기반 자동 배치 크기\n```\n\n#### ⚡ 최대 속도 (처리량 우선)\n\n```bash\n# 고성능 모드 + FP16\npython mask_video.py video.mp4 --high-performance --fp16 --hevc\n\n# 또는 배치 크기 수동 지정\npython mask_video.py video.mp4 --batch-size 32 --detect-interval 2 --hevc\n```\n\n#### 🎬 여러 영상 동시 처리 (병렬 처리)\n\n```bash\n# 3개 영상 동시 처리 (RAM 32GB 기준)\npython mask_video.py video1.mp4 --queue-size 64 --hevc -o out1.mp4 \u0026\npython mask_video.py video2.mp4 --queue-size 64 --hevc -o out2.mp4 \u0026\npython mask_video.py video3.mp4 --queue-size 64 --hevc -o out3.mp4 \u0026\nwait\n```\n\n#### 🎨 마스킹 + 색보정 통합 처리\n\n```bash\n# 단일 영상: 마스킹 + 시네마틱 색보정\npython mask_video.py video.mp4 --color-grade --hevc\n\n# 배치 처리: 폴더 내 모든 영상 자동 처리\npython batch_masking.py ./videos --workers 2\n```\n\n#### 🔬 정확도 최대 (느리지만 정밀)\n\n```bash\n# 매 프레임 감지 + 큰 모델\npython mask_video.py video.mp4 --detect-interval 1 --yolo-model yolo12x --hevc\n```\n\n#### 💾 낮은 RAM 환경 (16GB 이하)\n\n```bash\n# 큐 크기 줄이기\npython mask_video.py video.mp4 --queue-size 32 --batch-size 8 --hevc\n```\n\n### 기본 파라미터 값 요약\n\n| 파라미터 | 기본값 | 설명 | 조정 시점 |\n|----------|--------|------|-----------|\n| `--yolo-model` | `yolo12x` | YOLO 모델 | 속도 필요시 `yolo11x` |\n| `--tensorrt` | `True` | TensorRT 가속 | 호환 문제시 `--no-tensorrt` |\n| `--fp16` | `False` | FP16 추론 | NVIDIA GPU에서 `--fp16` 권장 |\n| `--nvdec` | `True` | GPU 디코딩 | CPU 디코딩 필요시 `--no-nvdec` |\n| `--detect-interval` | `-1` (자동) | 감지 주기 | 정확도 필요시 `1`, 속도 필요시 `3-5` |\n| `--detect-scale` | `-1` (자동) | 감지 해상도 | 속도 필요시 `0.5` |\n| `--batch-size` | `-1` (자동) | 배치 크기 | VRAM 부족시 `8-16` |\n| `--queue-size` | `-1` (자동) | 프레임 큐 | 병렬 처리시 `64`, RAM 부족시 `32` |\n| `--blur-strength` | `31` | 블러 강도 | GPU는 31 이하 권장 |\n| `--person-conf` | `0.4` | 사람 감지 신뢰도 | 놓침 많으면 `0.3`, 오탐 많으면 `0.5` |\n| `--vehicle-conf` | `0.3` | 차량 감지 신뢰도 | 놓침 많으면 `0.2`, 오탐 많으면 `0.4` |\n| `--person-expand` | `0.2` | 사람 영역 확장 | 마스킹 부족시 `0.3` |\n| `--plate-expand` | `0.5` | 번호판 영역 확장 | 마스킹 부족시 `0.6-0.7` |\n| `--track-buffer` | `60` | 트래킹 버퍼 | 끊김 많으면 `90-120` |\n\n### 자동 최적화 (-1 = auto)\n\n`-1` 값은 시스템 사양에 따라 자동 설정됩니다:\n\n| 항목 | 자동 계산 기준 |\n|------|---------------|\n| `detect-interval` | VRAM 12GB 이상: 1, 미만: 2 |\n| `detect-scale` | 4K 영상: 0.5, FHD: 1.0 |\n| `batch-size` | VRAM의 70% 기준 계산 |\n| `queue-size` | RAM의 25% 기준, 최대 512 |\n\n---\n\n## 성능 참고\n\n### 테스트 환경\n\n- **GPU**: NVIDIA RTX 4070 SUPER (12GB VRAM)\n- **CPU**: Intel i5-13400 (10코어, 16스레드)\n- **RAM**: 32GB DDR5\n- **입력**: 4K 60fps HEVC 10bit 영상 (3840x2160)\n\n### 처리 모드별 성능 비교 (yolo12x TensorRT)\n\n| 모드 | 속도 (fps) | 특징 | 권장 사용 |\n|------|------------|------|-----------|\n| **최적화 모드** (기본) | ~32 fps | yolo12x TRT + GPU 블러 + NVENC | **일반 권장** |\n| **고성능 모드** (`--high-performance`) | ~48 fps | 배치 GPU 추론 + 파이프라인 | 빠른 처리 |\n| **2-Pass 모드** (`--2pass`) | ~22 fps + ~20 fps | 분석/인코딩 분리 | JSON 재작업 |\n\n### YOLO 모델별 성능 비교\n\n| 모델 | TensorRT | 정확도 | 속도 (fps) | 권장 |\n|------|----------|--------|------------|------|\n| **yolo12x** | ✅ | 최고 | ~32 fps | **기본값** |\n| **yolo11x** | ✅ | 매우 높음 | ~33 fps | 대안 |\n| **yolov8x** | ✅ | 높음 | ~35 fps | 속도 중시 |\n| **yolov8n** | ✅ | 낮음 | ~45 fps | 테스트용 |\n\n### 병렬 처리 (여러 영상 동시 처리)\n\n여러 영상을 동시에 처리하여 총 처리량을 높일 수 있습니다.\n\n#### 병렬 처리 설정\n\n| 설정 | RAM 사용 | 개별 속도 | 총 처리량 | 권장 |\n|------|----------|-----------|-----------|------|\n| 단일 (기본) | ~10GB | 28 fps | 28 fps | 일반 |\n| **3개 병렬** (`--queue-size 64`) | ~23GB | 19-23 fps | **~63 fps** | **권장** |\n\n#### 병렬 처리 사용법\n\n```bash\n# 3개 영상 동시 처리 (--queue-size 64 필수!)\npython mask_video.py video1.mp4 --queue-size 64 --hevc -o out1.mp4 \u0026\npython mask_video.py video2.mp4 --queue-size 64 --hevc -o out2.mp4 \u0026\npython mask_video.py video3.mp4 --queue-size 64 --hevc -o out3.mp4 \u0026\nwait  # 모든 프로세스 완료 대기\n```\n\n#### 병렬 처리 핵심 포인트\n\n- **`--queue-size 64` 필수**: 기본값(512)은 프레임 버퍼가 커서 RAM 부족 발생\n- **RAM 32GB 기준 최대 3개**: 프로세스당 ~8GB RAM 사용\n- **총 처리량 2배 이상**: 단일 28fps → 병렬 63fps (2.25배)\n- **GPU/VRAM 여유**: GPU 17%, VRAM 4.5GB/12GB (병목 아님)\n\n#### 권장 병렬 수 (RAM 기준)\n\n| 시스템 RAM | 권장 병렬 수 | `--queue-size` |\n|-----------|-------------|----------------|\n| 16GB | 1개 | 기본값 |\n| 32GB | **3개** | 64 |\n| 64GB | 5-6개 | 64 |\n\n### 2-Pass 모드 상세\n\n| Pass | 동작 | GPU 사용 | 출력 |\n|------|------|----------|------|\n| **Pass 1** (분석) | YOLO 배치 추론 | GPU 100% 추론 | JSON 마스크 파일 |\n| **Pass 2** (인코딩) | 마스크 적용 + NVENC | GPU 100% 인코딩 | 마스킹된 영상 |\n\n### NVENC 인코딩 최적화\n\n시스템 사양에 따라 자동으로 최적화된 NVENC 설정이 적용됩니다:\n\n| 항목 | RTX 4070 SUPER (12GB) | RTX 3060 (8GB) | GTX 1660 (6GB) |\n|------|----------------------|----------------|----------------|\n| 프리셋 | p4 (quality) | p3 (balanced) | p2 (fast) |\n| Lookahead | 32 프레임 | 24 프레임 | 16 프레임 |\n| B-프레임 | 4 | 3 | 2 |\n| Surfaces | 16 | 12 | 8 |\n| FP16 추론 | 활성화 | 활성화 | 비활성화 |\n\n### 감지 통계 예시 (1분 4K 영상)\n\n- 처리 프레임: 3,596\n- 감지된 사람: 0\n- 감지된 번호판: 19,021\n\n---\n\n## 2-Pass 모드 상세\n\n### 작동 원리\n\n2-Pass 모드는 GPU 자원을 최대한 활용하기 위해 분석과 인코딩을 분리합니다:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Pass 1: 분석 (GPU 100% YOLO 추론)                            │\n│                                                             │\n│   비디오 → [디코더] → [YOLO 배치 추론] → JSON 마스크 파일     │\n│                     (사람/번호판 감지)                        │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│ Pass 2: 인코딩 (GPU 100% NVENC)                              │\n│                                                             │\n│   비디오 + JSON → [마스크 적용] → [NVENC 인코딩] → 출력 영상  │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### JSON 마스크 형식\n\n```json\n{\n  \"metadata\": {\n    \"version\": \"1.0\",\n    \"input\": \"video.mp4\",\n    \"width\": 3840,\n    \"height\": 2160,\n    \"fps\": 59.94,\n    \"total_frames\": 3596,\n    \"start_frame\": 0,\n    \"end_frame\": 3596,\n    \"created\": \"2026-01-04T12:51:53\"\n  },\n  \"stats\": {\n    \"total_persons\": 0,\n    \"total_plates\": 19021\n  },\n  \"frames\": {\n    \"0\": {\n      \"persons\": [],\n      \"plates\": [[1520, 1080, 1680, 1140]]\n    },\n    \"1\": {\n      \"persons\": [],\n      \"plates\": [[1522, 1082, 1682, 1142], [2100, 1500, 2200, 1550]]\n    }\n  }\n}\n```\n\n### 사용 시나리오\n\n| 시나리오 | 명령어 | 설명 |\n|----------|--------|------|\n| 일반 처리 | `--2pass` | Pass1 + Pass2 순차 실행, JSON 자동 삭제 |\n| 재작업 대비 | `--2pass --keep-json` | JSON 파일 유지 |\n| 일괄 분석 | `--analyze-only` | 여러 영상 분석만 먼저 실행 |\n| 일괄 인코딩 | `--encode-only --mask-json file.json` | 분석된 영상 순차 인코딩 |\n| 파라미터 변경 | `--encode-only --mask-json file.json --mask-type mosaic` | 동일 분석 결과로 다른 마스킹 |\n\n---\n\n## 모델 정보\n\n| 모델 | 용도 | 소스 | 비고 |\n|------|------|------|------|\n| **YOLO12x** | 사람/차량 감지 | Ultralytics | **기본값**, 최신 모델 |\n| YOLO11x | 사람/차량 감지 | Ultralytics | 높은 정확도 |\n| YOLOv8x | 사람/차량 감지 | Ultralytics | 안정적 |\n| YOLOv8n | 사람/차량 감지 | Ultralytics | 속도 우선 |\n| ByteTrack | 객체 추적 | Ultralytics 내장 | **기본값** |\n| BoT-SORT | 객체 추적 | Ultralytics 내장 | 대안 |\n\n### TensorRT 엔진 생성 (상세 가이드)\n\nTensorRT 엔진은 YOLO 모델을 GPU에 최적화하여 추론 속도를 2-3배 향상시킵니다.\n**최초 실행 시 자동 생성**되지만, 사전에 수동 생성하면 첫 실행 시간을 절약할 수 있습니다.\n\n\u003e ⚠️ **주의**: `.engine` 파일은 **시스템 종속적**입니다. GPU, CUDA, TensorRT 버전이 다른 시스템에서는 재생성해야 합니다.\n\n#### 방법 1: YOLO CLI (권장)\n\n```bash\n# 기본 FP16 엔진 생성 (권장)\nyolo export model=yolo12x.pt format=engine half=True device=0\n\n# 특정 배치 크기로 생성 (배치 추론용)\nyolo export model=yolo12x.pt format=engine half=True device=0 batch=32\n\n# 동적 배치 크기 엔진 (유연성 필요 시)\nyolo export model=yolo12x.pt format=engine half=True device=0 dynamic=True\n```\n\n#### 방법 2: trtexec (고급 설정)\n\nONNX 모델을 거쳐 TensorRT 엔진을 세밀하게 제어할 수 있습니다.\n\n```bash\n# Step 1: PyTorch → ONNX 변환\nyolo export model=yolo12x.pt format=onnx half=True simplify=True opset=17\n\n# Step 2: ONNX → TensorRT 엔진 변환\ntrtexec --onnx=yolo12x.onnx \\\n        --saveEngine=yolo12x.engine \\\n        --fp16 \\\n        --workspace=4096 \\\n        --verbose\n\n# 고정 배치 크기 (최적 성능)\ntrtexec --onnx=yolo12x.onnx \\\n        --saveEngine=yolo12x_b32.engine \\\n        --fp16 \\\n        --shapes=images:32x3x640x640 \\\n        --workspace=4096\n\n# 동적 배치 크기 (유연성)\ntrtexec --onnx=yolo12x.onnx \\\n        --saveEngine=yolo12x_dynamic.engine \\\n        --fp16 \\\n        --minShapes=images:1x3x640x640 \\\n        --optShapes=images:16x3x640x640 \\\n        --maxShapes=images:64x3x640x640 \\\n        --workspace=4096\n```\n\n#### 주요 trtexec 옵션\n\n| 옵션 | 설명 | 권장값 |\n|------|------|--------|\n| `--fp16` | FP16 반정밀도 (속도 2배, 정확도 유지) | **필수** |\n| `--workspace` | 빌드 시 GPU 메모리 (MB) | 4096 |\n| `--shapes` | 고정 입력 크기 (batch×channels×height×width) | 32x3x640x640 |\n| `--minShapes/optShapes/maxShapes` | 동적 배치 범위 | 1/16/64 |\n| `--best` | INT8 양자화 (캘리브레이션 필요) | 선택적 |\n\n#### 배치 크기별 엔진 파일 관리\n\n```bash\n# 여러 배치 크기 엔진 사전 생성\nfor bs in 16 24 32 48 64; do\n  yolo export model=yolo12x.pt format=engine half=True device=0 batch=$bs\n  mv yolo12x.engine yolo12x_b${bs}.engine\ndone\n```\n\n#### 엔진 파일 위치\n\n생성된 `.engine` 파일은 모델 파일과 같은 디렉토리에 저장됩니다:\n- 자동 생성: `~/.cache/ultralytics/` 또는 현재 디렉토리\n- 수동 지정: `--yolo-model /path/to/yolo12x.engine`\n\n\u003e 💡 **팁**: Git에 `.engine` 파일을 포함하지 마세요 (`.gitignore`에 추가)\n\n---\n\n## 변경 이력\n\n### v3.4 - 2026-01-12 (현재)\n\n**적응형 색보정 시스템 추가**\n- **장면별 자동 분석**: 지정된 프레임 간격(기본 1000프레임)마다 밝기/채도 분석\n- **시네마틱 필터 적용**: 따뜻한 톤, 대비 향상, 채도 조절 (C 스타일)\n- **부드러운 전환**: 장면 변화 시 급격한 필터 변화 방지 (보간 + 이동평균)\n- **GPU 가속**: OpenCV CUDA 기반 색보정으로 CPU 대비 빠른 처리\n- **마스킹 통합**: 읽기 → 색보정 → 마스킹 → 인코딩 단일 패스로 효율적 처리\n\n**배치 처리 큐 시스템 (`batch_masking.py`)**\n- **동시 처리 지원**: 최대 N개 영상 병렬 처리 (기본 2개)\n- **자동 큐 관리**: 하나 완료 시 다음 파일 자동 시작\n- **상세 로그 시스템**:\n  - 마스터 로그: 전체 진행 상황 기록\n  - 개별 로그: 파일별 상세 처리 로그 (`logs/파일명.log`)\n- **색보정 통합**: `--color-grade` 옵션 기본 활성화\n- **에러 핸들링**: TensorRT 배치 호환 문제로 PyTorch 모델 사용 (`--no-tensorrt`)\n\n**파일 조직화**\n- 영상 밝기 기반 day/night 폴더 자동 분류\n- 각 폴더별 masking 출력 디렉토리 구조\n\n**새로운 CLI 옵션**\n- `--color-grade`: 적응형 색보정 활성화\n- `--cg-interval`: 분석 주기 (프레임 단위, 기본 1000)\n- `--cg-smooth`: 부드러운 전환 윈도우 (프레임 단위, 기본 300)\n\n**신규 파일**\n- `adaptive_color_grade.py`: 적응형 색보정 모듈\n  - `ColorGrader` 클래스: 마스킹 파이프라인 통합용\n  - `TargetStyle`: 목표 스타일 파라미터 (C 스타일 기본)\n  - `CorrectionParams`: 프레임별 보정 파라미터\n  - GPU/CPU 자동 선택 (`apply_correction_gpu`, `apply_correction`)\n- `batch_masking.py`: 배치 처리 큐 시스템\n\n### v3.3 - 2026-01-05\n\n**문서 개선**\n- TensorRT 엔진 제작 가이드 강화 (YOLO CLI, trtexec)\n- 권장 파라미터 설정 섹션 추가\n- 빠른 시작 가이드 추가\n\n### v3.2 - 2026-01-04\n\n**YOLO 모델 업그레이드**\n- **기본 모델 변경**: yolov8n → **yolo12x** (최신 고정확도 모델)\n- **TensorRT 기본 활성화**: `--tensorrt` 옵션 기본값 True\n- **지원 모델 확장**: YOLO11 시리즈 (yolo11n~yolo11x), YOLO12 시리즈 (yolo12n~yolo12x) 추가\n\n**GPU 최적화**\n- **GPU 블러**: OpenCV CUDA 가우시안 블러 적용 (CPU 대비 13배 빠름)\n  - 커널 크기 31 이하에서 GPU 사용, 초과 시 CPU 폴백\n  - 블러 필터 캐시로 재생성 오버헤드 제거\n- **기본 블러 강도**: 51 → 31 (GPU 최적화)\n- **NVDEC 기본 활성화**: `--nvdec` 옵션 기본값 True\n\n**마스킹 영역 확장**\n- **사람 영역 확장**: `person_expand` 0.1 → 0.2 (여유있게 마스킹)\n- **번호판 영역 확장**: `plate_expand` 0.3 → 0.5 (여유있게 마스킹)\n\n**버그 수정**\n- **VRAM 감지 임계값 수정**: 12GB → 11.5GB (12282 MiB / 1024 = 11.99GB 문제 해결)\n- **인코딩 크래시 수정**: FrameWriter 스레드 동기화 문제 해결\n  - `daemon=True` → `daemon=False` 변경\n  - `finished` Event 추가로 완료 대기\n  - `wait_finished()` 메서드로 안전한 종료 보장\n  - VideoCapture/Writer 안전한 해제\n\n**병렬 처리 지원**\n- **`--queue-size` 옵션 추가**: 프레임 큐 크기 조절로 RAM 최적화\n- **3개 동시 처리 가능**: `--queue-size 64`로 RAM 사용량 감소\n- **총 처리량 2.25배 향상**: 단일 28fps → 병렬 63fps\n\n**성능 (RTX 4070 SUPER, 4K 60fps)**\n- 단일 처리: yolo12x TensorRT ~32 fps\n- **병렬 처리 (3개)**: 총 ~63 fps (개별 19-23 fps)\n- 15분 영상: 41.5분 (단일) → ~18분 (병렬 3개 추정)\n\n### v3.1 - 2026-01-04\n\n**코드 모듈화**\n- **파일 분리**: 대규모 단일 파일을 기능별 모듈로 분리\n  - `encoding_utils.py`: 시스템 정보 수집, NVENC 설정, FFmpeg 명령어 빌더\n  - `two_pass.py`: 2-Pass 모드 함수 (`analyze_video`, `encode_with_masks`, `process_video_2pass`)\n  - `high_performance.py`: 고성능 모드 함수 (`process_video_high_performance`)\n  - `masking_utils.py`: 공용 유틸리티 (로거 설정, 시간 파싱)\n- **CLI 통합**: `mask_video.py`를 단일 진입점으로 통합\n  - 기존 `mask_video_optimized.py`, `mask_video_advanced.py` 기능 포함\n\n**2-Pass 멀티스레딩**\n- **Pass 1 멀티스레딩**: `decoder_thread` + `analyzer_thread` 비동기 처리\n- **Pass 2 멀티스레딩**: `decoder_thread` + `masker_thread` + `encoder_thread` 파이프라인\n- **성능 개선**: 2-Pass 총 시간 6.7분 → 5.5분 (18% 향상)\n\n### v3.0 - 2026-01-04\n\n**NVENC 인코딩 최적화**\n- **최적화된 NVENC 설정**: `build_nvenc_command()` 함수 추가\n  - `rc-lookahead`: 프레임 미리보기로 품질 향상 (최대 32프레임)\n  - `spatial-aq`: 공간 적응형 양자화 (디테일 보존)\n  - `temporal-aq`: 시간 적응형 양자화 (움직임 품질)\n  - `surfaces`: 동시 인코딩 표면 (처리량 증가)\n  - `b_ref_mode`: B-프레임 참조 (압축 효율)\n- **시스템 자동 최적화**: `get_optimal_settings()` 함수 개선\n  - CPU 코어/스레드 기반 FFmpeg 스레드 수 자동 설정\n  - RAM 용량 기반 큐 크기 자동 조정\n  - VRAM 용량 기반 배치 크기 자동 계산\n  - GPU 아키텍처 기반 FP16/프리셋 자동 선택\n\n**2-Pass 모드 추가**\n- **Pass 1 (분석)**: GPU 100% YOLO 추론, 마스크 좌표를 JSON으로 저장\n  - 프레임별 마스크 바운딩 박스 저장\n  - 사람/번호판 감지 통계 포함\n  - 메타데이터 (해상도, FPS, 총 프레임 수) 저장\n- **Pass 2 (인코딩)**: GPU 100% NVENC 인코딩, JSON 마스크 적용\n  - JSON 마스크 데이터 로드\n  - 프레임별 마스크 적용 + NVENC 하드웨어 인코딩\n- **분리 실행 지원**: `--analyze-only`, `--encode-only`, `--mask-json` 옵션\n  - 여러 영상 일괄 분석 후 순차 인코딩 가능\n  - JSON 파일 유지로 재인코딩 지원 (`--keep-json`)\n\n**고성능 모드 개선**\n- **멀티스레딩 파이프라인**: 디코딩, 추론, 인코딩 비동기 처리\n  - `decoder_thread`: 비동기 프레임 읽기\n  - `processor_thread`: 배치 GPU 추론 + 마스킹\n  - `encoder_thread`: NVENC 순서 보장 인코딩\n- **RTX 4070 SUPER 기준**: 4K 60fps에서 ~48 fps 달성\n\n### v2.4.1 - 2026-01-03\n\n**버그 수정**\n- **FP16 추론 오류 수정**: `yolo_half` 변수 초기화 시 잘못된 변수 참조 수정\n  - 이전: `self.yolo_half = use_fp16 and self.device == 'cuda'` (파라미터 `use_fp16`은 `None`일 수 있음)\n  - 수정: `self.yolo_half = self.use_fp16 and self.device == 'cuda'` (인스턴스 변수 사용)\n  - 증상: `unsupported operand type(s) for \u0026=: 'NoneType' and 'bool'` 오류로 배치 처리 실패\n  - 영향: 모든 프레임에서 마스킹이 적용되지 않고 원본 프레임만 인코딩됨\n\n### v2.4 - 2026-01-03\n\n**NVIDIA CUDA 최적화**\n- **OpenCV DNN CUDA 백엔드 지원**: 얼굴 감지를 GPU에서 처리\n  - `check_opencv_cuda_support()`: OpenCV CUDA/cuDNN 지원 여부 확인\n  - `FaceDetectorDNN` 클래스에 CUDA 백엔드 자동 선택 로직 추가\n  - CUDA 사용 불가 시 자동으로 CPU fallback\n- **시스템 하드웨어 자동 감지**: `get_system_info()` 함수 추가\n  - CPU 모델, 코어/스레드 수, 최대 클럭\n  - RAM 총량 및 사용 가능량\n  - GPU 모델, VRAM, CUDA 버전, 아키텍처 감지\n- **하드웨어 기반 자동 최적화**: `optimize_settings_for_hardware()` 함수\n  - CPU 스레드 수 기반 워커 수 자동 조정 (threads // 2)\n  - RAM 기반 프레임 큐 크기 계산\n  - VRAM 기반 배치 크기 자동 계산 (VRAM 70% 활용)\n  - 12GB+ VRAM: detect_interval=1 (매 프레임 감지 가능)\n- **GPU 메모리 최적화**:\n  - cuDNN benchmark 모드 활성화\n  - TF32 연산 활성화 (Ampere+)\n  - 주기적 GPU 캐시 정리\n- **NVENC 하드웨어 인코딩**: RTX GPU에서 hevc_nvenc 자동 사용\n  - NVENC 실패 시 libx265 소프트웨어 인코딩 fallback\n\n**Python 환경 변경**\n- Python 3.11 → 3.12로 업그레이드 (OpenCV CUDA 빌드 호환성)\n- NumPy 2.x → 1.26.4로 다운그레이드 (OpenCV 바인딩 호환성)\n\n### v2.1 - 2026-01-02\n\n**버그 수정**\n- **차량 감지 버그 수정**: `detect_batch()`에서 `predict()` 대신 `track()` 사용\n  - 이전: 배치 추론 시 `track_id`가 None이 되어 차량 감지 수가 항상 0\n  - 수정: 프레임별 `track()` 호출로 트래킹 ID 유지\n- **폴백 ID 생성**: `track_id`가 None인 경우 `_get_next_vehicle_id()`로 고유 ID 할당\n- **배치 결과 초기화**: `batch_detections` 리스트 사전 초기화로 인덱스 오류 방지\n\n**개선**\n- 실시간 로그 출력을 위한 `FlushStreamHandler` 추가\n- 진행률 로그 포맷 개선 (fps, 남은 시간, 감지 수 표시)\n\n### v2.0 - 2026-01-02\n\n**성능 최적화 (mask_video_optimized.py 신규 생성)**\n- **MPS GPU 가속**: Apple Silicon에서 Metal Performance Shaders 활용\n  - `get_optimal_device()` 함수로 자동 감지\n  - YOLO `track()` 호출 시 `device` 파라미터 전달\n- **멀티스레딩 파이프라인**:\n  - `FrameReader`: 별도 스레드에서 프레임 읽기\n  - `FrameWriter`: 별도 스레드에서 프레임 쓰기\n  - Queue 기반 비동기 처리\n- **프레임 스킵 + 트래킹 보간**:\n  - `--detect-interval` 옵션으로 감지 주기 설정\n  - `TrackingInterpolator` 클래스로 중간 프레임 위치 예측\n  - 속도 기반 선형 보간으로 부드러운 마스킹\n- **해상도 다운스케일 감지**:\n  - `--detect-scale` 옵션으로 감지용 해상도 축소\n  - 출력은 원본 해상도 유지\n- **배치 추론**:\n  - `--batch-size` 옵션으로 동시 처리 프레임 수 설정\n  - `detect_batch()` 메서드로 여러 프레임 동시 처리\n- **확장된 트래킹 파라미터**:\n  - `--tracker`: bytetrack 또는 botsort 선택\n  - `--track-buffer`: 트래킹 버퍼 크기\n  - `--match-thresh`: 매칭 임계값\n  - `--iou-thresh`: IoU 임계값\n  - `create_custom_tracker_config()`: 커스텀 YAML 설정 생성\n\n### v1.0 - 초기 버전\n\n**기본 기능 (mask_video_advanced.py)**\n- OpenCV DNN 기반 얼굴 감지\n- YOLOv8n 기반 차량 감지\n- 기본 ByteTrack 트래킹\n- 블러/모자이크 마스킹\n- 시작/종료 시간 구간 설정\n- HEVC 인코딩 옵션\n\n---\n\n## 문제 해결\n\n### MPS 사용 불가\n\n```\nRuntimeError: MPS backend out of memory\n```\n\n해결: 배치 크기 줄이기\n```bash\npython mask_video_optimized.py video.mp4 --batch-size 2\n```\n\n### 감지 누락이 많은 경우\n\n해결: 감지 간격 줄이기 + 신뢰도 낮추기\n```bash\npython mask_video_optimized.py video.mp4 --detect-interval 1 --face-conf 0.3 --vehicle-conf 0.2\n```\n\n### 트래킹이 자주 끊기는 경우\n\n해결: 트래킹 버퍼 늘리기 + 매칭 임계값 낮추기\n```bash\npython mask_video_optimized.py video.mp4 --track-buffer 60 --match-thresh 0.6\n```\n\n### 처리 속도가 너무 느린 경우\n\n해결: 감지 간격 늘리기 + 해상도 낮추기\n```bash\npython mask_video_optimized.py video.mp4 --detect-interval 5 --detect-scale 0.25\n```\n\n### NVENC/NVDEC 하드웨어 가속 실패\n\nNVIDIA 하드웨어 인코더/디코더는 **지원하는 픽셀 포맷이 제한적**입니다.\n\n#### 지원 포맷\n\n| 포맷 | NVDEC | NVENC | 비고 |\n|------|-------|-------|------|\n| **8bit 4:2:0** (yuv420p) | ✅ | ✅ | 가장 호환성 좋음 |\n| **10bit 4:2:0** (p010le) | ✅ | ✅ | HDR/고품질 권장 |\n| 8bit 4:2:2 (yuv422p) | ❌ | ❌ | 미지원 |\n| **10bit 4:2:2** (yuv422p10le) | ❌ | ❌ | 미지원 |\n| 8bit 4:4:4 (yuv444p) | ❌ | ⚠️ | 일부 GPU만 지원 |\n\n#### 증상\n\n```\n[hevc_nvenc @ 0x...] No capable devices found\n```\n또는\n```\nError initializing output stream -- Hardware does not support this format\n```\n\n#### 해결: 입력 영상을 4:2:0으로 변환\n\n```bash\n# 10bit 4:2:2 → 10bit 4:2:0 변환 (NVENC 사용)\nffmpeg -i input_422.mp4 -c:v hevc_nvenc -preset p4 -pix_fmt p010le -c:a copy output_420.mp4\n\n# 소프트웨어 인코더로 변환 (더 호환성 높음)\nffmpeg -i input_422.mp4 -c:v libx265 -pix_fmt yuv420p10le -crf 18 -c:a copy output_420.mp4\n\n# 8bit로 변환 (파일 크기 작음)\nffmpeg -i input_422.mp4 -c:v hevc_nvenc -preset p4 -pix_fmt yuv420p -c:a copy output_420_8bit.mp4\n```\n\n#### 입력 영상 포맷 확인\n\n```bash\n# 픽셀 포맷 확인\nffprobe -v error -select_streams v:0 -show_entries stream=pix_fmt -of default=nw=1 input.mp4\n\n# 상세 정보 확인\nffprobe -v error -select_streams v:0 -show_entries stream=codec_name,pix_fmt,color_space,color_transfer -of default=nw=1 input.mp4\n```\n\n#### 일괄 변환 스크립트\n\n```bash\n#!/bin/bash\n# convert_to_420.sh - 4:2:2 영상을 4:2:0으로 일괄 변환\n\nfor f in *.mp4; do\n  pix_fmt=$(ffprobe -v error -select_streams v:0 -show_entries stream=pix_fmt -of csv=p=0 \"$f\")\n  if [[ \"$pix_fmt\" == *\"422\"* ]]; then\n    echo \"Converting $f ($pix_fmt → p010le)\"\n    ffmpeg -y -i \"$f\" -c:v hevc_nvenc -preset p4 -pix_fmt p010le -c:a copy \"${f%.mp4}_420.mp4\"\n  fi\ndone\n```\n\n\u003e 💡 **팁**: 원본이 10bit 4:2:2인 경우, 10bit 4:2:0 (p010le)으로 변환하면 색상 정보 손실을 최소화할 수 있습니다.\n\n---\n\n## TODO (개선 필요 사항)\n\n### 1. 자동차 번호판 위치 탐지 정확도 개선\n\n- **현재 문제**: 차량마다 번호판 위치가 상이하여 정확한 탐지가 어려움\n- **원인 추정**: YOLOv8n은 차량 전체를 감지하며, 번호판 영역은 차량 바운딩 박스 하단 일부로 추정\n- **개선 방향**:\n  - 번호판 전용 감지 모델 도입 (예: 번호판 특화 YOLO 모델)\n  - 차량 종류별 번호판 위치 비율 학습\n  - OCR 기반 번호판 텍스트 영역 감지\n\n### 2. 화면 전체 마스킹 오류 수정\n\n- **현재 문제**: 특정 프레임 또는 연속된 프레임에서 화면 전체가 마스킹되는 현상 발생\n- **원인 추정**:\n  - 트래킹 보간 시 비정상적으로 큰 바운딩 박스 생성\n  - 감지 결과의 좌표값 오류\n  - 스케일 변환 시 좌표 계산 오류\n- **개선 방향**:\n  - 바운딩 박스 크기 상한선 설정 (화면 대비 비율 제한)\n  - 이상치 감지 및 필터링 로직 추가\n  - 프레임 간 바운딩 박스 크기 급변 감지\n\n### 3. 사람 얼굴 감지 및 마스킹 개선\n\n- **현재 문제**: 얼굴 인식 및 마스킹 기능이 부족함\n- **원인 추정**:\n  - OpenCV DNN SSD 모델의 한계 (정면 얼굴 위주, 원거리/측면 감지 약함)\n  - 4K 영상에서 작은 얼굴 감지 어려움\n- **개선 방향**:\n  - 사람 객체 전체 감지 후 전신 마스킹 옵션 추가\n  - 더 강력한 얼굴 감지 모델 도입 (RetinaFace, YOLO-Face 등)\n  - 사람 감지 + 얼굴 감지 2단계 파이프라인 구성\n  - `--mask-person` 옵션으로 사람 전체 마스킹 선택 가능하도록\n\n### 4. NVIDIA GPU 최적화 세팅 (v2.4에서 일부 완료)\n\n- **완료된 항목** (v2.4):\n  - ✅ OpenCV DNN CUDA 백엔드 지원 (얼굴 감지 GPU 가속)\n  - ✅ 시스템 하드웨어 자동 감지 및 최적화\n  - ✅ VRAM 기반 배치 크기 자동 계산\n  - ✅ cuDNN benchmark 모드, TF32 활성화\n  - ✅ NVENC 하드웨어 인코딩 지원\n  - ✅ FP16 추론 (half=True)\n- **추가 개선 필요**:\n  - TensorRT 변환을 통한 추론 속도 향상\n  - 멀티 GPU 지원 (대용량 영상 병렬 처리)\n  - CUDA 스트림을 활용한 비동기 처리\n  - Docker 이미지 제공 (CUDA 환경 포함)\n\n---\n\n## OpenCV CUDA 빌드 가이드 (NVIDIA GPU)\n\npip로 설치되는 `opencv-python` 패키지는 CUDA 지원이 포함되어 있지 않습니다.\nOpenCV DNN CUDA 백엔드를 사용하려면 소스에서 직접 빌드해야 합니다.\n\n### 테스트 환경\n\n| 항목 | 버전 |\n|------|------|\n| OS | Ubuntu 24.04 LTS |\n| GPU | NVIDIA RTX 4070 Super (12GB VRAM) |\n| CUDA | 12.0 |\n| cuDNN | 9.17.1 |\n| Python | 3.12.3 |\n| OpenCV | 4.10.0 |\n| GCC | 12 (CUDA 12.0 호환) |\n\n### 1. 빌드 의존성 설치\n\n```bash\nsudo apt update\nsudo apt install -y \\\n    build-essential cmake git pkg-config \\\n    libjpeg-dev libpng-dev libtiff-dev \\\n    libavcodec-dev libavformat-dev libswscale-dev \\\n    libv4l-dev libxvidcore-dev libx264-dev \\\n    libgtk-3-dev libatlas-base-dev gfortran \\\n    python3.12-dev python3-numpy \\\n    libtbb-dev libdc1394-dev \\\n    gcc-12 g++-12\n```\n\n\u003e **중요**: CUDA 12.0은 GCC 12 이하만 지원합니다. Ubuntu 24.04는 기본 GCC 13+를 사용하므로 gcc-12를 별도 설치해야 합니다.\n\n### 2. OpenCV 소스 다운로드\n\n```bash\ncd /tmp\ngit clone --depth 1 --branch 4.10.0 https://github.com/opencv/opencv.git\ngit clone --depth 1 --branch 4.10.0 https://github.com/opencv/opencv_contrib.git\n```\n\n### 3. CMake 설정 및 빌드\n\n```bash\nmkdir -p /tmp/opencv_build \u0026\u0026 cd /tmp/opencv_build\n\n# GCC 12 지정 (CUDA 12.0 호환성)\nexport CC=/usr/bin/gcc-12\nexport CXX=/usr/bin/g++-12\n\n# GPU 아키텍처 확인 (예: RTX 4070 = 8.9)\n# https://developer.nvidia.com/cuda-gpus 참조\n\ncmake \\\n    -D CMAKE_BUILD_TYPE=RELEASE \\\n    -D CMAKE_INSTALL_PREFIX=/usr/local \\\n    -D OPENCV_EXTRA_MODULES_PATH=/tmp/opencv_contrib/modules \\\n    -D CMAKE_C_COMPILER=/usr/bin/gcc-12 \\\n    -D CMAKE_CXX_COMPILER=/usr/bin/g++-12 \\\n    -D WITH_CUDA=ON \\\n    -D WITH_CUDNN=ON \\\n    -D OPENCV_DNN_CUDA=ON \\\n    -D ENABLE_FAST_MATH=ON \\\n    -D CUDA_FAST_MATH=ON \\\n    -D CUDA_ARCH_BIN=8.9 \\\n    -D WITH_CUBLAS=ON \\\n    -D WITH_TBB=ON \\\n    -D WITH_V4L=ON \\\n    -D BUILD_opencv_python3=ON \\\n    -D PYTHON3_EXECUTABLE=/usr/bin/python3.12 \\\n    -D BUILD_EXAMPLES=OFF \\\n    -D BUILD_TESTS=OFF \\\n    -D BUILD_PERF_TESTS=OFF \\\n    /tmp/opencv\n\n# 빌드 (CPU 코어 수에 맞게 -j 옵션 조정)\nmake -j16\n\n# 설치\nsudo make install\nsudo ldconfig\n```\n\n#### GPU 아키텍처 (CUDA_ARCH_BIN) 참조\n\n| GPU 시리즈 | 아키텍처 | CUDA_ARCH_BIN |\n|-----------|----------|---------------|\n| RTX 40xx (Ada Lovelace) | sm_89 | 8.9 |\n| RTX 30xx (Ampere) | sm_86 | 8.6 |\n| RTX 20xx (Turing) | sm_75 | 7.5 |\n| GTX 10xx (Pascal) | sm_61 | 6.1 |\n\n### 4. Python 가상환경 설정\n\n```bash\ncd /path/to/jeju_masking\n\n# Python 3.12로 가상환경 생성 (OpenCV 빌드 버전과 일치)\nuv venv --python python3.12\nsource .venv/bin/activate\n\n# 필수 패키지 설치 (opencv 제외)\nuv pip install ultralytics torch torchvision numpy lap pyyaml\n\n# pip opencv 제거 (의존성으로 설치된 경우)\nuv pip uninstall opencv-python opencv-python-headless opencv-contrib-python 2\u003e/dev/null || true\n\n# 시스템 OpenCV CUDA를 venv에 심링크\nSITE_PACKAGES=$(.venv/bin/python -c \"import site; print(site.getsitepackages()[0])\")\nln -sf /usr/local/lib/python3.12/dist-packages/cv2 $SITE_PACKAGES/cv2\n\n# NumPy 다운그레이드 (OpenCV 바인딩 호환성)\nuv pip install \"numpy\u003c2\"\n```\n\n### 5. 설치 확인\n\n```bash\n.venv/bin/python -c \"\nimport cv2\nprint('OpenCV version:', cv2.__version__)\nprint('CUDA devices:', cv2.cuda.getCudaEnabledDeviceCount())\n\n# CUDA 빌드 정보 확인\nbuild = cv2.getBuildInformation()\nfor line in build.split('\\n'):\n    if 'CUDA' in line or 'cuDNN' in line:\n        print(line)\n\"\n```\n\n예상 출력:\n```\nOpenCV version: 4.10.0\nCUDA devices: 1\n  NVIDIA CUDA:                   YES (ver 12.0, CUFFT CUBLAS FAST_MATH)\n    NVIDIA GPU arch:             89\n  cuDNN:                         YES (ver 9.17.1)\n```\n\n### 6. 문제 해결\n\n#### GCC 버전 오류\n\n```\nerror: #error -- unsupported GNU version! gcc versions later than 12 are not supported!\n```\n\n해결: CMake에서 GCC 12 명시적 지정\n```bash\nexport CC=/usr/bin/gcc-12\nexport CXX=/usr/bin/g++-12\ncmake -D CMAKE_C_COMPILER=/usr/bin/gcc-12 -D CMAKE_CXX_COMPILER=/usr/bin/g++-12 ...\n```\n\n#### NumPy 버전 오류\n\n```\nA module that was compiled using NumPy 1.x cannot be run in NumPy 2.x\n```\n\n해결: NumPy 다운그레이드\n```bash\nuv pip install \"numpy\u003c2\"\n```\n\n#### Python 버전 불일치\n\nOpenCV는 빌드 시 지정한 Python 버전의 바인딩만 생성합니다.\nvenv Python 버전이 빌드 시 사용한 버전과 일치해야 합니다.\n\n```bash\n# 빌드 시 Python 3.12 사용한 경우\nuv venv --python python3.12\n```\n\n---\n\n## 라이선스\n\n이 프로젝트는 개인 프라이버시 보호를 위한 목적으로 제작되었습니다.\n\n### 사용된 오픈소스\n\n- [Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics) - AGPL-3.0\n- [OpenCV](https://opencv.org/) - Apache 2.0\n- [ByteTrack](https://github.com/ifzhang/ByteTrack) - MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpathcosmos%2Fjeju_masking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpathcosmos%2Fjeju_masking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpathcosmos%2Fjeju_masking/lists"}