콘텐츠로 이동

Introduction

1. API Return Value

모든 API는 기본적으로 (error_code, return_value)의 tuple을 리턴합니다.

  • error_code=0인 경우, 함수가 성공적으로 동작했으며 return value는 실제 함수의 리턴 값입니다.
  • error_code≠0인 경우, 함수 실행중 error가 발생했다는 뜻이며 return value는 None입니다.

SaigeVAD.get_error_message(error_code): 입력으로 받은 error_code에 해당하는 error_message를 반환합니다.

2. 모델 파일 common

  • model dict의 common 필드에 있는 정보입니다. (key 이름 엄수)

  • common 필드는 연구팀에서 관리합니다.

    Depth 1 Depth 2 type 설명
    anomaly_cluster_meta cluster_train_images List[str] 최초 클러스터링 학습 이미지
    initial_cluster_output Dict[int, List[str]] 최초 클러스터링 학습 결과
    cluster_info List[Dict[str, int] 학습된 클러스터링 인덱스 정보 및 severity_leve
    color_complexity_mask torch.Tensor, None mask mode가 None이 아닐 때 mask를 나타내는 데이터 array


3. 학습 모델 구조

  • VAD 학습 결과가 저장된 모델의 구조는 아래와 같습니다.
  • VCls 학습 결과 및 모델 병합에 따라 “vcls” 관련 키워드가 존재하지 않을 수도 있습니다.
  • Clustering 학습 결과 및 모델 병합에 따라 “clu” 관련 키워드가 존재하지 않을 수도 있습니다.
  • Clustering 학습이 완료된 후에, save_checkpoint API에서 “inference_settings”를 입력하여 저장할 수 있습니다.

"*.saigevad"
    ├── "common"
    │   ├── "anomaly_cluster_meta"
    │   │   ├── "cluster_train_images"
    │   │   ├── "initial_cluster_output"
    │   │   └── "cluster_info"
    │   └── "color_complexity_mask"
    ├── "version"
    ├── "metadata"
    ├── "config" #encrypted
    └── "state_dict" #encrypted
        ├── "vad_weight"
        │   ├── "model_state_dict"
        │   ├── "VideoAnomalyDetection"
        │   ├── "VideoMotionDetection"
        │   ├── "VideoROICalibration"
        │   ├── "optimizer_state_dict"
        │   ├── "step"
        │   ├── "common_settings"
        │   ├── "color_complexity_mask"
        │   ├── "color_count_map"
        │   ├── "template_image_tensors"
        │   ├── "fixed_template_image_tensors"
        │   ├── "memory_units"
        │   └── "clu_weight"
        └── "clu_weight"
            └──"anomaly_clustering"
                ├── "clustering_method"
                ├── "clusters"
                ├── "cluster_data_dict"
                ├── "initial_intra_distance"
                ├── "intra_distance"
                └── "ssim_intra_distance"

4. Inference ResultContainer 구조

  • VAD inference 결과로 나오는 ResultContainer에는 아래와 같은 정보가 저장되어 있습니다.
필드 명 Type 필드 의미
is_anomaly List[bool] frame이 anomaly 인지를 나타내는 boolean. True 면 anomaly, False 면 정상.
is_motion List[bool] frame이 motion 인지를 나타내는 boolean. True 면 motion인 frame, False면 정지한 frame.
is_slow List[bool] frame이 motion 이지만, 평소보다 속도가 느려지는 경우를 나타내는 boolean. True면 slow motion인 frame이며 is_motion이 False가 됨. False면 정상 속도 frame.
is_cycle_end List[bool] cycle이 끝나는 frame을 나타내는 boolean. True면 cycle이 끝나는 frame
cycle_count List[int] 128 frames 마다 누적되는 cycle count.
frame_timestamp List[str] 현재 frame에 대한 timestamp를 나타내는 정보.
state List[InferenceState] 각 frame의 state를 나타냄. InferenceState라는 enum class. 값은 state[i].value로 접근. 서버에서는 사용 안 할 듯
state_index List[int] state와 대응되는 int. 1: no_motion, 2: inspect, 3: domain_shift_detection, 4: roi_calibration, 5: no_roi_match, 6: error, 7: slow_motion
error_codes List[int] 모듈 별 error code. 0이 아니면 모두 error. 0: "Success", 1: "SaigeVAD", 2: "VideoAnomalyDetection submodule" …
roi_coord_orig_xyxy List[Tuple] frame 별 원본 전체 이미지 기준 roi coordinate. (x1, y1, x2, y2) 순서. (ROI 변경 사항 반영됨)
is_domain_shift List[bool] 현재 frame이 domain shift가 발생한 상태인지 아닌지를 나타내는 boolean.
roi_shift_coord List[Tuple] 현재 roi를 기준으로 변화된 roi의 (x,y) coordinate 값. 예: (10,20) → x축으로 10, y축으로 20만큼 roi 변화함. (robust roi calibration mode를 택했을 때는, template based와 color complexity based를 고려한 roi 변화 coordinate값)
is_roi_shift List[bool] 기존 roi 기준으로 roi가 변화했는지를 나타내는 boolean (robust roi calibration mode를 택했을 때는, template based와 color complexity based를 고려하여 roi 변화가 있었는지 나타냄 )
is_camera_shift List[bool] 고정 roi가 변화했는지를 나타내는 boolean
camera_shift_coord List[Tuple] 현재 fixed roi를 기준으로 변화된 roi의 (x,y) coordinate 값. 예: (10,20) → x축으로 10, y축으로 20만큼 roi 변화함.
roi_shift_coord_template List[Tuple] template based roi matching 알고리즘로 roi 변화를 찾았을 때 변화된 coordinate 값 (roi_shift_coord와 같은 type)
is_roi_shift_template List[bool] template based roi matching 알고리즘이 기존 roi 기준으로 roi가 변화했는지를 나타내는 boolean
match_score_template List[float] template based roi matching알고리즘으로 변화된 roi를 찾았을 때, template과 변화된 roi의 matching score (min 0 max 1)
roi_shift_coord_cc List[Tuple] color complexity based roi matching 알고리즘로 roi 변화를 찾았을 때 변화된 coordinate 값 (roi_shift_coord와 같은 type)
is_roi_shift_cc List[bool] color complexity based roi matching 알고리즘이 기존 roi 기준으로 roi가 변화했는지를 나타내는 boolean
match_score_cc List[float] color complexity based roi matching알고리즘으로 변화된 roi를 찾았을 때, template과 변화된 roi의 matching score (min 0 max 1)
is_camera_shift List[bool] 고정 roi가 변화했는지를 나타내는 boolean
camera_shift_coord List[Tuple] 현재 fixed roi를 기준으로 변화된 roi의 (x,y) coordinate 값. 예: (10,20) → x축으로 10, y축으로 20만큼 roi 변화함.
base_score List[float] VAD 모듈에서 나오는 score 값 (환경 대응 모듈 - adaptation 모듈 적용 전 score)
base_threshold List[float] base_score 기준으로 계산된 score threshold.
adaptive_score List[float] base_score에 adaptation 모듈이 적용된 score 값.
slow_threshold List[float] adaptive_score로 계산되는 실시간 threshold 값. fast_threshold 보다 더 많은 history를 사용하여 계산함.
fast_threshold List[float] adaptive_score로 계산되는 실시간 threshold 값. slow_threshold 보다 더 적은 history를 사용하여 계산함.
final_score List[float] normalized_score에 n_sigma를 곱한 값으로 프로그램에서 최종적으로 유저에게 보여줘야 하는 score
final_threshold List[float] base_threshold, fast_threshold, slow_threshold를 종합한 값으로 프로그램에서 최종적으로 유저에게 보여줘야 하는 threshold. 유저가 주는 “임계값(n_sigma)”과 동일한 값.
normalized_score List[float] 주어진 n_sigma로 계산된 각 threshold에 대하여 base_score, adaptive_score를 종합하여 1보다 크면 anomaly, 작으면 normal이 되도록 normalize한 값.
cluster_index List[int] clustering 모델이 selected anomaly frame에 배정한 cluster index
is_indistribution List[bool] selected anomaly frame에 대해 in distribution detector가 주는 output (주어진 frame이 봤던 데이터 인지 아닌지)
is_selected_anomaly_cluster List[bool] frame sequence에서 clustering 로직에 쓰인 frame이면 True (clustering 로직에 쓰인 frame은 anomaly score가 가장 높은 frame)
in_distribution_recon_error List[float] selected anomaly frame에 대해서 in distribution detector가 in distribution인지 아닌지를 비교할 때 쓰는 error 값 (debugging용. user가 알 필요 없음)
is_indistribution_threshold List[float] in distribution detector가 계산한 error threshold (debugging용. user가 알 필요 없음)
cluster_distance List[float] 해당 image와 배정된 cluster사이의 distance
cluster_confidence List[float] 해당 image가 배정된 cluster에 속할 confidence
is_vcls List[bool] 현재 frame에서 VAD 결과 값이 VCls 결과 값으로 overwrite 되었는 지 여부를 나타내는 boolean
class_pred List[int] 현재 frame의 VCls 결과 클래스 index int 값. 0 (normal), 1 (anomaly), >1 (rare (normal로 overwrite))
softmax_pred List[Tuple] 현재 frame의 VCls 결과의 softmax 값 array. VCls 클래스 개수 만큼의 크기를 갖는 array. 예: [0.1, 0.3, 0.6]
tensor_data List[torch.Tensor] 현재 frame의 원본 input data의 torch.Tensor 형태 값.
tensor_recon List[torch.Tensor] 현재 frame의 원본 input data에 대한 VAD 모듈의 output으로 나온 reconstruction 이미지의 torch.Tensor 형태 값.
tensor_transformed List[torch.Tensor] 현재 frame의 원본 input data에 대한 adaptation 모듈의 output으로 나온 reconstruction 이미지의 torch.Tensor 형태 값.
tensor_center List[torch.Tensor] 현재 frame 이미지에서 가장 가까운 cluster center의 이미지의 torch.Tensor 형태 값
mask List[torch.Tensor] 이미지에서 유저가 검사에서 제외하고 싶은 pixel 영역을 나타내는 array. 최종 VAD output에서 mask array 값이 1인 pixel만 실제 결과에 반영됨.
tensor_recon_is_indistribution List[torch.Tensor] selected anomaly frame에 대해서 in distribution detector가 생성한 reconstruction이미지의 torch.Tensor 형태 값 (debugging용. user가 알 필요 없음)
is_mask_updated List[bool] 현재 frame에서 mask가 update 되었는지를 나타내는 boolean. 백엔드에서는 is_mask_updated==True인 frame에서만 mask를 가져가면 됨.