콘텐츠로 이동

Task3: 침입관제

ktt.module.intrusion_monitoring.Inferencer

영상 침입 모니터링 시스템을 위한 추론 파이프라인을 제공합니다.

주요 기능
  • 비디오 클립에서 움직임 탐지 및 분석
  • 프레임별 모션 점수 계산 및 히트맵 생성
  • 최대 모션 프레임 추출 및 시각화
  • 객체 탐지 기반 침입 확인 (미구현)
Usage

demo/demo_intrusion_monitoring_inference.py 참고

build(config) classmethod

API 인스턴스를 생성합니다.

Parameters:

Name Type Description Default
config dict

핸들러 빌드를 위한 설정 딕셔너리입니다. 

{
    # 전처리 설정
    "preprocess": {
        "motion_resize": tuple[int, int],    # 모션 감지용 리사이즈 (W, H). 기본값: (320, 180)
        "detection_resize": tuple[int, int], # 객체 탐지용 리사이즈 (W, H). 기본값: (640, 360)
        "max_frames": int,                   # 비디오당 최대 프레임 수. 기본값: 150
        "sampling_stride": int,              # 프레임 샘플링 간격. 기본값: 1 (모든 프레임 사용)
        "num_workers": int,                  # 병렬 로딩 워커 수. 기본값: 4
    },
    # 모션 감지 설정
    "motion_detection": {
        "diff_thresh": float,           # 프레임 차이 임계값 (0-1 정규화). 기본값: 25.0/255.0
        "use_morphology": bool,         # 형태학적 연산 사용 여부. 기본값: True
        "topk_ratio": float,            # 상위 K 비율로 비디오 점수 집계. 기본값: 0.2
        "batch_shape": tuple[int, int], # 배치 처리 shape (H, W). 기본값: None (입력 크기 유지)
    },
    # 객체 탐지 설정 (미구현)
    "detection": dict | None,                # 객체 탐지 모델 설정. 기본값: None (미사용)
    # 공통 설정
    "motion_threshold": float,               # 침입 판정 모션 임계값 (0-1). 기본값: 0.001
    "device": str,                           # 실행 디바이스. 기본값: "cpu"
                                             # "cpu", "cuda", "cuda:0" 등
}

required

Returns:

Name Type Description
Inferencer Inferencer

빌드 완료된 침입 모니터링 추론 핸들러 인스턴스.

infer(video_paths)

입력 비디오 클립들에 대해 침입 모니터링 추론을 수행합니다.

4단계 파이프라인을 실행합니다: 1) 비디오 로딩 및 전처리 (리사이징, 정규화) 2) 프레임 차이 기반 모션 감지 3) 모션 임계값 초과 시 객체 탐지 (미구현) 4) 결과 후처리 및 시각화 데이터 생성

Parameters:

Name Type Description Default
video_paths list[str]

입력 비디오 파일 경로 리스트. 각 경로는 절대 경로 또는 상대 경로 문자열이어야 합니다.

 required

Returns:

Type Description
list[dict[str, Any]]

list[dict[str, Any]]: 각 입력 비디오에 대한 추론 결과 딕셔너리 리스트. 예시는 아래와 같습니다. 

[
    {
        "index": int,                                   # 배치 내 비디오 인덱스 (0부터 시작)
        "video_path": str,                              # 비디오 파일 경로
        "video_score": float,                           # 비디오 전체 모션 점수 (0-1)
                                                        # topk_ratio로 집계된 대표 점수
        "motion_heatmap": list[list[float]],            # 누적 모션 히트맵, shape (H, W)
                                                        # 값 범위: 0-1, 높을수록 모션 많음
        "frame_scores": list[float],                    # 프레임별 모션 점수, length (T-1)
                                                        # 각 프레임 쌍 간 차이 점수
        "best_frame_idx": int,                          # 최대 모션 프레임 인덱스 (0-based)
        "best_frame_score": float,                      # 최대 모션 프레임의 점수
        "best_frame_overlay": list[list[list[int]]],    # 최대 모션 프레임 오버레이 시각화
                                                        # shape (H, W, 3), RGB uint8
                                                        # 그레이스케일 + JET colormap 블렌딩
        # boxes_xyxy: list[list[float]] | None,         # 탐지된 객체 바운딩 박스 리스트 (미구현, 변경예정)
    },
    ...  # 추가 비디오들에 대한 결과
]

Note
  • video_score가 motion_threshold를 초과하는 비디오만 객체 탐지를 수행합니다 (미구현).
  • frame_scores의 길이는 (전체 프레임 수 - 1)입니다 (인접 프레임 차이 계산).
  • best_frame_idx는 frame_scores 기준 인덱스이므로, 실제 프레임 번호는 best_frame_idx + 1입니다.
  • motion_heatmap은 모든 프레임의 모션을 누적한 결과로, 모션이 빈번한 영역을 파악할 수 있습니다.
  • best_frame_overlay는 numpy array → list 변환된 형태로 반환되며, 저장/전송이 용이합니다.
  • 모든 모션 관련 값은 0-1 정규화되어 있으며, 임계값과 직접 비교 가능합니다.

Raises:

Type Description
ValueError

video_paths가 비어있는 경우.
RuntimeError

모든 비디오의 유효 프레임 수가 0인 경우.
FileNotFoundError

비디오 파일을 찾을 수 없는 경우.

get_default_inference_option(key)

특정 추론 옵션의 기본값을 조회합니다.

Parameters:

Name Type Description Default
key str

옵션 key (점으로 구분된 경로).

 required
Keys

사용 가능한 key와 value 목록

Returns:

Name Type Description
Any Any

옵션 value.

Raises:

Type Description
InferenceOptionKeyError

지정된 키가 존재하지 않는 경우.

get_inference_option(key)

현재 설정된 추론 옵션 값을 조회합니다.

Parameters:

Name Type Description Default
key str

옵션 key (점으로 구분된 경로).

 required

Returns:

Name Type Description
Any Any

옵션 value.
Keys

get_default_inference_option과 동일합니다.

Raises:

Type Description
InferenceOptionKeyError

지정된 키가 존재하지 않는 경우.

set_inference_option(key, value)

추론 옵션을 설정합니다.

Parameters:

Name Type Description Default
key str

설정할 옵션의 점으로 구분된 경로.

 required
value Any

설정할 새로운 값.

 required
Keys

get_default_inference_option과 동일합니다.