Skip to content

Inference

safety.InferenceHandler

학습한 Object Detection/Classification 모델을 사용하여 검사를 하기 위한 InferenceHandler class 입니다.

Usage

demo/inference.py 참고

build(config) classmethod

InferenceHandler class의 instance를 생성합니다.

Parameters:

Name Type Description Default
config Dict

InferenceHandler를 build 하기 위한 config가 담겨 있는 dictionary 입니다. 

{
    # inference_handler config
    "detection_checkpoint_path": str | None, # Detection 모델 체크포인트 경로 (default None, None인 경우 default detection model 사용)
    "classification_checkpoint_path": str | None, # Classification 모델 체크포인트 경로 (default None, None인 경우 default classification model 사용)
    "reidentification_checkpoint_path": str | None, # Reidentification 모델 체크포인트 경로 (default None, None인 경우 default reidentification model 사용)
    "inference_batch_size": int, # Batch size 설정 (default 1)
    "optimize": bool, # ONNX 모델 최적화 여부 (default True)
    "password": str | None,  # 체크포인트 패스워드 (default None)
    "device": str | int,  # GPU 번호 (int) or "cuda" (str) (default "cuda")

    # event_alarm_handlers config
    "camera_ids": list[int] | None, # 검사할 camera_id list. `InferenceHandler.register_camera`와 `InferenceHandler.release_camera`를 통해 camera_id를 등록/해제 할 수 있습니다. (default None)
}

required

Returns:

Name Type Description
InferenceHandler

build가 완료된 safety.InferenceHandler class의 instance를 반환합니다.
Note
  1. "event_type_map"은 event_alarm 모듈에서 사용하는 event_type str과 api에서 사용하는 event_type str을 매핑하는 dictionary 입니다.
    • 백엔드에서는 사용하지 않으며, 연구소 내부적으로 사용하는 빌드 파라미터입니다.
  2. "detection_checkpoint_path", "classification_checkpoint_path", "reidentification_checkpoint_path"는 각 모델의 체크포인트 경로를 설정합니다.
    • None인 경우 해당 버전의 default 모델을 사용합니다.

infer(images, camera_ids, timestamps)

현재 설정된 inference 옵션을 바탕으로 inference를 수행합니다.

Parameters:

Name Type Description Default
images list[ndarray]

inference를 수행할 이미지들의 list (shape: [H, W, C])

 required
camera_ids list[int]

images의 각 image에 대한 camera_id list

 required
timestamps list[int]

images의 각 image에 대한 timestamp list (단위: 밀리초)

 required

Returns:

Type Description
list[dict]

list[dict]: 검사 결과 

[
    {
        "detected_objects": [ # 검출된 object들에 대한 정보 리스트
            {
                "id": int, # object ID
                "bounding_box": list[int], # object bounding box (x,y,w,h)
                "object_class": str, # object의 class 이름. (Note 3 참고)
                "object_score": int, # object의 det score. (범위: 0 ~ 100)
                "classification_scores": {
                    "helmet": int,      # helmet class의 score. (범위: 0 ~ 100)
                    "head": int,        # head class의 score. (범위: 0 ~ 100)
                    "person": int,      # person class의 score. (범위: 0 ~ 100)
                    "fire": int,        # fire class의 score. (범위: 0 ~ 100)
                    "smoke": int,       # smoke class의 score. (범위: 0 ~ 100)
                    "fall_down": int,   # fall_down class의 score. (범위: 0 ~ 100)
                    "harness": int,     # harness class의 score. (범위: 0 ~ 100)
                },
                "brightness_score": int, # object의 밝기 score. (범위: 0 ~ 100). Person class에 대해서만 존재.
                "events": { # object에 발생한 event에 대한 딕셔너리. 각 event에 대한 alarm이 비활성화(enabled=False)된 경우엔 event도 항상 False입니다.
                    "without_helmet": bool,     # 헬멧 미착용 이벤트 (person object에 대해서만 해당)
                    "without_harness": bool,    # 하네스 미착용 이벤트 (person object에 대해서만 해당)
                    "fallen_person": bool,      # 쓰러짐 이벤트 (person object에 대해서만 해당)
                    "trespass_detect": bool,    # 침입 감지 이벤트 (person object에 대해서만 해당)
                    "danger_detect": bool,      # 배회 감지 이벤트 (person object에 대해서만 해당)
                    "collision_detect": bool,   # 협착 감지 이벤트 (person object에 대해서만 해당)
                    "fire_detect": bool,        # 화재 감지 이벤트 (fire object에 대해서만 해당)
                    "smoke_detect": bool,       # 연기 감지 이벤트 (smoke object에 대해서만 해당)
                },
                "alarms": { # object에 발생한 각 event에 대해서 alarm 여부 딕셔너리.
                    "without_helmet": bool,     # 헬멧 미착용 이벤트 (person object에 대해서만 해당)
                    "without_harness": bool,    # 하네스 미착용 이벤트 (person object에 대해서만 해당)
                    "fallen_person": bool,      # 쓰러짐 이벤트 (person object에 대해서만 해당)
                    "trespass_detect": bool,    # 침입 감지 이벤트 (person object에 대해서만 해당)
                    "danger_detect": bool,      # 배회 감지 이벤트 (person object에 대해서만 해당)
                    "collision_detect": bool,   # 협착 감지 이벤트 (person object에 대해서만 해당)
                    "fire_detect": bool,        # 화재 감지 이벤트 (fire object에 대해서만 해당)
                    "smoke_detect": bool,       # 연기 감지 이벤트 (smoke object에 대해서만 해당)
                }
            }, ... # 각 image에서 검출된 object와 이에 대한 event, alarm 정보.
        ],
        "time": { # inference에 소요된 시간을 담고있는 dictionary 입니다. (단위: 밀리초)
            "load_time": float, # image load에 소요된 시간
            "detection_time": float, # detection에 소요된 시간
            "classification_time": float, # classification에 소요된 시간
            "reidentification_time": float, # person reidentification에 소요된 시간
            "tracker_time": float, # person tracker에 소요된 시간
            "event_alarm_time": float, # 이벤트 관제에 소요된 시간
        },
    }, ... # 들어온 image 수 만큼 반복 (들어온 image 순서대로)
]

warmup()

현재 설정된 inference 옵션을 바탕으로 warmup을 수행합니다. warmup은, 현재 inference_option이 잘 동작하는지 확인 + GPU를 첫 호출시 속도가 느린 이슈를 해결하기 위해, 현재 inference_option에 맞춰 더미 입력에 대한 InferenceHandler.infer를 호출합니다.

get_default_inference_option(model, key)

Model별 Postprocess 옵션의 기본 설정 값을 반환합니다.

Parameters:

Name Type Description Default
model str

"classification", "detection", 또는 "safety"

 required
key str

옵션 key

 required

Returns:

Name Type Description
Any Any

옵션 value
사용 가능한 key와 value 목록

model: detection key: DET 모델 결과 후처리 파라미터. 가능한 key는 다음과 같습니다. 

{
    "params.object_score_threshold": list[int],  # 각 클래스의 score threshold 값. 예측 box의 score가 threshold보다 작은 경우 필터링 됩니다.
                                                    # 각 값은 [0, 100] 범위의 정수. (default [30, 10, ... , 10])
    "params.object_area_threshold": list[int],  # 각 클래스의 area threshold 값. 예측 box의 면적이 threshold보다 작은 경우 필터링 됩니다.
                                                # 각 값은 0 이상의 정수. (default [0, ... , 0])
    "params.max_num_of_detected_objects": list[int],  # 각 클래스의 최대 예측 박스 개수. 예측 box의 개수가 이 값을 넘을 경우 score가 낮은 순으로 제거됩니다.
                                                        # 각 값은 -1 이상의 정수이며, 값이 -1인 경우 개수 필터링을 적용하지 않습니다. (default [30, -1, ... , -1])
}

model: classification key: CLS 모델 결과 후처리 파라미터. 가능한 key는 다음과 같습니다. 

{
    "params.additional_scores": list[int | float],  # scores_including_add를 계산할 때, scores_original에 더해지는 값입니다. 각 값은 [0, 100] 범위의 실수. (default [0.0, ... , 0.0])
}

model: safety key: 가능한 key는 다음과 같습니다. 

{
    "outputs.time": bool,  # 인퍼런스 시 각 요소에 걸린 시간을 반환할지 여부. (default False)
}

Usage 
error, _ = handler.get_default_inference_option(model="safety", key="outputs.time")
error, _ = handler.set_inference_option(model="safety", key="outputs.time", value=False)

get_inference_option(model, key)

Model에 따른 현재 설정된 postprocess 옵션 값을 읽습니다.

Parameters:

Name Type Description Default
model str

"classification", "detection" 또는 "safety"

 required
key str

옵션 key

 required

Returns:

Name Type Description
Any Any

옵션 value
Keys

get_default_inference_option과 동일합니다.

set_inference_option(model, key, value)

Model에 따른 Postprocess 옵션을 설정합니다.

Parameters:

Name Type Description Default
model str

"classification", "detection" 또는 "safety"

 required
key str

설정하고자 하는 옵션 key 입니다.

 required
value Any

설정하고자 하는 옵션 value 입니다.

 required

Returns:

Name Type Description
None None

None
Keys

get_default_inference_option과 동일합니다.

register_camera(camera_id)

검사할 camera_id를 등록합니다.

Parameters:

Name Type Description Default
camera_id int

등록할 camera_id

 required

Returns:

Name Type Description
None None

None

Raises:

Type Description
InvalidCameraIdError

camera_id가 int가 아닌 경우 발생하는 에러
AlreadyRegisteredCameraIdError

이미 등록된 camera_id를 등록하려고 할 때 발생하는 에러

release_camera(camera_id)

등록된 camera_id를 해제합니다.

Parameters:

Name Type Description Default
camera_id int

해제할 camera_id

 required

Returns:

Name Type Description
None None

None

Raises:

Type Description
UnregisteredCameraIdError

등록되지 않은 camera_id를 해제하려고 할 때 발생하는 에러

get_registered_camera_ids()

등록된 camera_id 리스트를 반환합니다.

Returns:

Type Description
list[int]

list[int]: 등록된 camera_id 리스트

get_monitoring_area(camera_id)

등록된 camera_id에 대한 monitoring area를 반환합니다.

Parameters:

Name Type Description Default
camera_id int

monitoring area를 반환할 camera_id

 required

Returns:

Type Description
dict[str, list[list[list[int]]]]

Optional[list[list[list[int]]]]: monitoring area polygon list 

{
    "includes": [ # 포함하는 영역의 polygon 리스트 (default [])
        [[x1, y1], ..., [xn, yn]], # n개의 점으로 이루어진 polygon (n >= 3)
        ...
    ],
    "excludes": list[list[list[int]]] # 제외하는 영역의 polygon 리스트(includes와 동일).
}

Raises: UnregisteredCameraIdError: 등록되지 않은 camera_id에 대한 정보를 요청할 때 발생하는 에러

set_monitoring_area(camera_id, monitoring_area)

등록된 camera_id에 대한 monitoring area를 설정합니다.

Parameters:

Name Type Description Default
camera_id int

monitoring area를 설정할 camera_id

 required
monitoring_area dict[str, list[list[list[int]]]]

monitoring area polygon list 형태는 InferenceHandler.get_monitoring_area의 반환값과 동일합니다.

 required

Returns:

Name Type Description
None None

None

Raises:

Type Description
InvalidMonitoringAreaError

monitoring_area가 올바르지 않을 때 발생하는 에러
UnregisteredCameraIdError

등록되지 않은 camera_id에 대해 설정할 때 발생하는 에러

get_default_object_options(camera_id)

등록된 camera_id에 대한 default object options를 반환합니다.

Parameters:

Name Type Description Default
camera_id int

default object options를 반환할 camera_id

 required

Returns:

Type Description
dict[str, dict]

dict[str, dict[str, Any]]: object options 

{
    "person": {
        "enabled": bool,         # 해당 object_type을 검출할지 여부. 라이센스 조정을 위해 사용됩니다. (default False)
        "area_threshold": float, # 해당 object_type의 면적 threshold. 이 값보다 작은 object는 필터링 됩니다. (default 900.0)
        "score_threshold": int,  # 해당 object_type의 score threshold. 이 값보다 낮은 `object_score`를 가진 object는 필터링 됩니다. (default 30)
    },
    "fire": {
        "enabled": bool,         # default False
        "area_threshold": float, # default 900.0
        "score_threshold": int,  # default 10
    },
    "smoke": {
        "enabled": bool,         # default False
        "area_threshold": float, # default 900.0
        "score_threshold": int,  # default 10
    },
    "excavator": {
        "enabled": bool,         # default False
        "area_threshold": float, # default 900.0
        "score_threshold": int,  # default 30
    },
    "forklift": {
        "enabled": bool,         # default False
        "area_threshold": float, # default 900.0
        "score_threshold": int,  # default 30
    },
    "crane_body": {
        "enabled": bool,         # default False
        "area_threshold": float, # default 900.0
        "score_threshold": int,  # default 30
    },
    "crane_hook": {
        "enabled": bool,         # default False
        "area_threshold": float, # default 900.0
        "score_threshold": int,  # default 30
    },
    "crane_lifted_object": {
        "enabled": bool,         # default False
        "area_threshold": float, # default 900.0
        "score_threshold": int,  # default 30
    },
    "heavy_equipment": {
        "enabled": bool,         # default False
        "area_threshold": float, # default 900.0
        "score_threshold": int,  # default 30
    },
    "vehicle": {
        "enabled": bool,         # default False
        "area_threshold": float, # default 900.0
        "score_threshold": int,  # default 30
    },
}

Raises:

Type Description
UnregisteredCameraIdError

등록되지 않은 camera_id에 대한 정보를 요청할 때 발생하는 에러

get_object_options(camera_id)

등록된 camera_id에 대한 object options를 반환합니다.

Parameters:

Name Type Description Default
camera_id int

object options를 반환할 camera_id

 required

Returns:

Type Description
dict[str, dict]

dict[str, dict[str, Any]]: object options. 형태는 InferenceHandler.get_default_object_options의 반환값과 동일합니다.

Raises:

Type Description
UnregisteredCameraIdError

등록되지 않은 camera_id에 대한 정보를 요청할 때 발생하는 에러

set_object_options(camera_id, object_options)

등록된 camera_id에 대한 object options를 설정합니다.

Parameters:

Name Type Description Default
camera_id int

object options를 설정할 camera_id

 required
object_options dict[str, dict]]

object options. 형태는 InferenceHandler.get_default_object_options의 반환값과 동일합니다.

 required

Returns:

Name Type Description
None None

None

Raises:

Type Description
InvalidObjectOptionsError

object_options가 올바르지 않을 때 발생하는 에러
UnregisteredCameraIdError

등록되지 않은 camera_id에 대해 설정할 때 발생하는 에러

get_default_event_options(camera_id)

등록된 camera_id에 대한 default event options를 반환합니다.

Parameters:

Name Type Description Default
camera_id int

default event options를 반환할 camera_id

 required

Returns:

Type Description
dict[str, dict]

dict[str, dict[str, Any]]: event options 

{
    "fire_detect": {
        "fire_score_threshold": int,    # fire score threshold. 이 값보다 높은 fire score를 가진 object에 대해서만 이벤트를 발생시킵니다. (default 10)
    },
    "smoke_detect": {
        "smoke_score_threshold": int,   # smoke score threshold. 이 값보다 높은 smoke score를 가진 object에 대해서만 이벤트를 발생시킵니다. (default 10)
    },
    "without_helmet": {
        "ignore_dark_object": bool,     # 어두운 객체에 대한 이벤트를 무시할지 여부. (default True)
        "head_score_threshold": int,    # head score threshold. 이 값보다 높은 head score를 가진 object에 대해서만 이벤트를 발생시킵니다. (default 90)
        "helmet_score_threshold": int,  # helmet score threshold. 이 값보다 낮은 helmet score를 가진 object에 대해서만 이벤트를 발생시킵니다. (default 30)
    },
    "without_harness": {
        "ignore_dark_object": bool,     # 어두운 객체에 대한 이벤트를 무시할지 여부. (default True)
        "harness_score_threshold": int, # harness score threshold. 이 값보다 낮은 harness score를 가진 object에 대해서만 이벤트를 발생시킵니다. (default 30)
    },
    "fallen_person": {
        "ignore_crossing_image_border_object": bool, # 이미지 경계를 넘어가는 객체에 대한 이벤트를 무시할지 여부. (default True)
        "ignore_dark_object": bool,                  # 어두운 객체에 대한 이벤트를 무시할지 여부. (default True)
        "fall_down_score_threshold": int,            # fall_down score threshold. 이 값보다 높은 fall_down score를 가진 object에 대해서만 이벤트를 발생시킵니다. (default 70)
    },
    "trespass_detect": {
        "area_ratio_threshold": int,                 # area_ratio_threshold. (default 95)
                                                     # 이 값보다 높은 intersection area ratio (intersection_area / object_area) 를 가진 object에 대해서만 이벤트를 발생시킵니다.
        "polygons": list[list[list[int]]],     # 침입 감지할 영역의 polygon list. (default [])
            ```python
                [
                    [[x1, y1], ..., [xn, yn]], # n개의 점으로 이루어진 polygon (n >= 3)
                    ...
                ]
            ```
    },
    "danger_detect": {
        "area_ratio_threshold": int,                 # area_ratio_threshold. (default 95)
                                                     # 이 값보다 높은 intersection area ratio (intersection_area / object_area) 를 가진 object에 대해서만 이벤트를 발생시킵니다.
        "polygons": list[list[list[int]]],     # 배회 감지할 영역의 polygon list. (default [])
            ```python
                [
                    [[x1, y1], ..., [xn, yn]], # n개의 점으로 이루어진 polygon (n >= 3)
                    ...
                ]
            ```
    }
    "collision_detect": {
        "area_ratio_threshold": int,                 # area_ratio_threshold. (default 50)
                                                     # 이 값보다 높은 intersection area ratio (intersection_area / object_area) 를 가진 object에 대해서만 이벤트를 발생시킵니다.
        "center_y_offset_ratio": float,              # 협착 위험 박스의 cy를 아래로 이동시키는 비율. (default 1.0)
        "width_scale": float,                        # 협착 위험 박스의 w를 늘리는 비율. (default 1.2)
        "height_scale": float,                       # 협착 위험 박스의 h를 늘리는 비율. (default 0.5)
                                                     # 협착 위협 객체의 bounding box가 [c_x (박스 중심 x 좌표), c_y (박스 중심 y 좌표), w, h]일 때,
                                                     # 협착 위험 박스는 [c_x, c_y + h / 2 * center_y_offset_ratio, w * width_scale, h * height_scale] 으로 계산됩니다.
}

get_event_options(camera_id)

등록된 camera_id에 대한 event options를 반환합니다.

Parameters:

Name Type Description Default
camera_id int

event options를 반환할 camera_id

 required

Returns:

Type Description
dict[str, dict]

dict[str, dict[str, Any]]: event options. 형태는 InferenceHandler.get_default_event_options의 반환값과 동일합니다.

Raises:

Type Description
UnregisteredCameraIdError

등록되지 않은 camera_id에 대한 정보를 요청할 때 발생하는 에러

set_event_options(camera_id, event_options)

등록된 camera_id에 대한 event options를 설정합니다.

Parameters:

Name Type Description Default
camera_id int

event options를 설정할 camera_id

 required
event_options dict[str, dict]]

event options. 형태는 InferenceHandler.get_default_event_options의 반환값과 동일합니다.

 required

Returns:

Name Type Description
None None

None

Raises:

Type Description
InvalidEventOptionsError

event_options가 올바르지 않을 때 발생하는 에러
UnregisteredCameraIdError

등록되지 않은 camera_id에 대해 설정할 때 발생하는 에러

get_default_alarm_options(camera_id)

등록된 camera_id에 대한 default alarm options를 반환합니다.

Parameters:

Name Type Description Default
camera_id int

default alarm options를 반환할 camera_id

 required

Returns:

Type Description
dict[str, dict]

dict[str, dict]: alarm options 

{
    "fire_detect": {
        "enabled": bool,                # 해당 event_type에 대한 알람 활성화 여부. (default False)
        "start_time": int,              # 알람 활성화 시작 시각. 00:00:00 (단위: 초, default 0)
        "end_time": int,                # 알람 활성화 종료 시각. 24:00:00 (단위: 초, default 86400)
        "alarm_interval": int,          # 한번 울린 알람이 다시 울리기 까지 시간. (단위: 초, default 300)
        "repeat_threshold": int,        # 해당 기간 동안 일정 비율 이상의 event가 발생해야 알람이 발생. (단위: 초, default 3)
        "alarm_ratio_threshold": int,   # repeat_threshold 기간 동안 event가 발생한 비율이 이 값보다 크면 알람 발생. (단위: %, default 50)
    },
    "smoke_detect": {
        "enabled": bool,
        "start_time": int,
        "end_time": int,
        "alarm_interval": int,
        "repeat_threshold": int,
        "alarm_ratio_threshold": int,
    },
    "without_helmet": {
        "enabled": bool,
        "start_time": int,
        "end_time": int,
        "alarm_interval": int,
        "repeat_threshold": int,
        "alarm_ratio_threshold": int,
    },
    "without_harness": {
        "enabled": bool,
        "start_time": int,
        "end_time": int,
        "alarm_interval": int,
        "repeat_threshold": int,
        "alarm_ratio_threshold": int,
    },
    "fallen_person": {
        "enabled": bool,
        "start_time": int,
        "end_time": int,
        "alarm_interval": int,
        "repeat_threshold": int,
        "alarm_ratio_threshold": int,
    },
    "trespass_detect": {
        "enabled": bool,
        "start_time": int,
        "end_time": int,
        "alarm_interval": int,
        "repeat_threshold": int,
        "alarm_ratio_threshold": int,
    },
    "danger_detect": {
        "enabled": bool,
        "start_time": int,
        "end_time": int,
        "alarm_interval": int,
        "repeat_threshold": int,
        "alarm_ratio_threshold": int,
    },
    "collision_detect": {
        "enabled": bool,
        "start_time": int,
        "end_time": int,
        "alarm_interval": int,
        "repeat_threshold": int,
        "alarm_ratio_threshold": int,
    },
}

Note
  1. start_time == end_time인 경우, 항상 알람이 활성화 됩니다.

Raises:

Type Description
UnregisteredCameraIdError

등록되지 않은 camera_id에 대한 정보를 요청할 때 발생하는 에러

get_alarm_options(camera_id)

등록된 camera_id에 대한 alarm options를 반환합니다.

Parameters:

Name Type Description Default
camera_id int

alarm options를 반환할 camera_id

 required

Returns:

Type Description
dict[str, dict]

dict[str, dict]: alarm options. 형태는 InferenceHandler.get_default_alarm_options의 반환값과 동일합니다.

Raises:

Type Description
UnregisteredCameraIdError

등록되지 않은 camera_id에 대한 정보를 요청할 때 발생하는 에러

set_alarm_options(camera_id, alarm_options)

등록된 camera_id에 대한 alarm options를 설정합니다.

Parameters:

Name Type Description Default
camera_id int

alarm options를 설정할 camera_id

 required
alarm_options dict[str, dict]]

alarm options. 형태는 InferenceHandler.get_default_alarm_options의 반환값과 동일합니다.

 required

Returns:

Name Type Description
None None

None

Raises:

Type Description
InvalidAlarmOptionsError

alarm_options가 올바르지 않을 때 발생하는 에러
UnregisteredCameraIdError

등록되지 않은 camera_id에 대해 설정할 때 발생하는 에러

reset()

InferenceHandler의 상태를 초기화합니다.