InferenceHandler

`safety.engine.api.InferenceHandler`

NPU edge 추론 기반으로 Safety 기능을 수행하는 InferenceHandler class 입니다.

Usage

demo/inference.py 참고

`build(config)` `classmethod`

InferenceHandler instance를 생성합니다.

Parameters:

Name Type Description Default

config

dict

InferenceHandler를 build 하기 위한 config dictionary.

{
    # inference_handler config
    "detection_checkpoint_path": str,         # Detection 모델 경로
    "classification_checkpoint_path": str,    # Classification 모델 경로
    "password": str | None,                   # 두 checkpoint 모두에 적용되는 공용 AES password.

    # event_alarm_handlers config
    # 검사할 camera_id list (default None).
    # `InferenceHandler.register_camera` / `release_camera` 로 동적 등록/해제 가능.
    "camera_ids": list[int] | None,
}

required

Returns:

Name	Type	Description
`InferenceHandler`	`InferenceHandler`	build가 완료된 instance.

Note

default_alarm_options, default_object_options는 API에서 기본적으로 비활성화합니다 (enabled=False).

Usage

err, msg, handler = InferenceHandler.build({
    "detection_checkpoint_path": "/path/to/det.saigeedge",
    "classification_checkpoint_path": "/path/to/cls.saigeedge",
    "password": "secret",
    "camera_ids": [0],
})

`infer(images, camera_ids, timestamps)`

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

Parameters:

Name	Type	Description	Default
`images`	`list[ndarray]`	inference를 수행할 BGR uint8 image list (shape: [H, W, 3])	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]: 검사 결과



name="__codelineno-0-1" href="#__codelineno-0-1">[ { "detected_objects": [ # 검출된 object들에 대한 정보 리스트 { "id": int, # tracker가 부여한 object ID "bounding_box": list[int], # object bounding box (x, y, w, h) "object_class": str, # object의 class 이름. "person" | "fire" "object_score": int, # object의 det score. (범위: 0 ~ 100) "class_index": int, # 0=person, 1=fire "classification_scores": { # person object에 대해서만 존재. 그 외 None. "helmet_on": float,    # helmet 착용 score. (범위: 0 ~ 100) "helmet_off": float,   # helmet 미착용 score. (범위: 0 ~ 100) } | None, # 각 event 의 alarm 이 비활성화(enabled=False)면 항상 False. "events": { "without_helmet": bool, # 헬멧 미착용 (person object 한정) "fire_detect": bool,    # 화재 감지 (fire object 한정) }, "alarms": { # object에 발생한 각 event에 대한 alarm 발화 여부. "without_helmet": bool, # 헬멧 미착용 alarm (person object에 대해서만 해당) "fire_detect": bool,    # 화재 감지 alarm (fire object에 대해서만 해당) }, "event_status": { # event 중간 상태 문자열. 각 event에 대한 alarm이 비활성화된 경우엔 None. "without_helmet": str | None, "fire_detect": str | None, }, }, ... # 해당 image에서 검출된 object 수만큼 반복. ], "time": { # 해당 image의 추론에 소요된 시간을 담고있는 dictionary. (단위: 밀리초) "preprocess_time": float,       # 이미지 및 기타 전처리에 소요된 시간 "inference_det_time": float,    # detection 추론에 소요된 시간 "postprocess_det_time": float,  # detection 후처리에 소요된 시간 "inference_cls_time": float,    # classification 추론에 소요된 시간 "postprocess_cls_time": float,  # classification 후처리에 소요된 시간 "tracker_time": float,          # tracker에 소요된 시간 "event_alarm_time": float,      # event/alarm 처리에 소요된 시간 }, }, ... # 들어온 image 수 만큼 반복 (들어온 image 순서대로) class="p">]

Raises:

Type	Description
`InvalidNumberOfInputsError`	images, camera_ids, timestamps의 길이가 서로 다를 때
`UnregisteredCameraIdError`	등록되지 않은 camera_id가 포함된 경우
`InvalidTimestampError`	timestamp가 음수이거나 같은 camera_id에 대해 중복일 때

Usage

err, msg, results = handler.infer(
    images=[frame_a, frame_b],
    camera_ids=[0, 0],
    timestamps=[0, 100],
)
for result in results:
    for obj in result["detected_objects"]:
        print(obj["object_class"], obj["events"])

`warmup()`

더미 입력으로 NPU pipeline을 사전 warmup 합니다.

Usage

err, msg, _ = handler.warmup()

`register_camera(camera_id)`

검사할 camera_id를 등록합니다.

Parameters:

Name	Type	Description	Default
`camera_id`	`int`	등록할 camera_id	required

Raises:

Type	Description
`InvalidCameraIdError`	camera_id가 비음수 int가 아닐 때
`AlreadyRegisteredCameraIdError`	이미 등록된 camera_id일 때

Usage

err, msg, _ = handler.register_camera(camera_id=0)
err, msg, cam_ids = handler.get_registered_camera_ids()
0 in cam_ids
# True

`release_camera(camera_id)`

등록된 camera_id를 해제합니다.

Parameters:

Name	Type	Description	Default
`camera_id`	`int`	해제할 camera_id	required

Raises:

Type	Description
`UnregisteredCameraIdError`	등록되지 않은 camera_id일 때

Usage

err, msg, _ = handler.release_camera(camera_id=0)
err, msg, cam_ids = handler.get_registered_camera_ids()
0 in cam_ids
# False

`get_registered_camera_ids()`

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

Returns:

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

Usage

err, msg, cam_ids = handler.get_registered_camera_ids()
print(cam_ids)
# [0]

`get_default_tracker_option(camera_id)`

기본 tracker option을 반환합니다.

Parameters:

Name	Type	Description	Default
`camera_id`	`int`	사용하지 않음, API 일관성을 위해 존재.	required

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: tracker option

Usage

err, msg, option = handler.get_default_tracker_option(camera_id=0)
print(option)
# {"iou_threshold": 0.3, "reid_weight": 0.0, ...}

`get_tracker_option(camera_id)`

등록된 camera_id에 대한 tracker option을 반환합니다.

Parameters:

Name	Type	Description	Default
`camera_id`	`int`	tracker option을 반환할 camera_id	required

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: tracker option

Raises:

Type	Description
`UnregisteredCameraIdError`	등록되지 않은 camera_id일 때

Usage

err, msg, option = handler.get_tracker_option(camera_id=0)
print(option)
# 사용자가 설정한 값이 반환됩니다.

`set_tracker_option(camera_id, tracker_option)`

등록된 camera_id에 대한 tracker option을 설정합니다.

Parameters:

Name	Type	Description	Default
`camera_id`	`int`	tracker option을 설정할 camera_id	required
`tracker_option`	`dict[str, Any]`	tracker option	required

Raises:

Type	Description
`UnregisteredCameraIdError`	등록되지 않은 camera_id일 때

Usage

err, msg, option = handler.get_tracker_option(camera_id=0)
option["iou_threshold"] = 0.5
err, msg, _ = handler.set_tracker_option(camera_id=0, tracker_option=option)

`get_default_object_options(camera_id)`

기본 object options을 반환합니다 (enabled=False 강제).

Parameters:

Name	Type	Description	Default
`camera_id`	`int`	사용하지 않음, API 일관성을 위해 존재.	required

Returns:

Type	Description
`dict[str, dict]`	dict[str, dict]: 각 object class별 default option dict

Usage

err, msg, options = handler.get_default_object_options(camera_id=0)
print(options["person"])
# {"enabled": False, ...}

`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]: object options

Raises:

Type	Description
`UnregisteredCameraIdError`	등록되지 않은 camera_id일 때

Usage

err, msg, options = handler.get_object_options(camera_id=0)
print(options["person"]["enabled"])
# False  (build / register_camera 직후엔 모두 False)

`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	required

Raises:

Type	Description
`UnregisteredCameraIdError`	등록되지 않은 camera_id일 때

Usage

err, msg, options = handler.get_object_options(camera_id=0)
options["person"]["enabled"] = True
err, msg, _ = handler.set_object_options(camera_id=0, object_options=options)

`get_default_event_options(camera_id)`

기본 event options을 반환합니다.

Parameters:

Name	Type	Description	Default
`camera_id`	`int`	사용하지 않음, API 일관성을 위해 존재.	required

Returns:

Type	Description
`dict[str, dict]`	dict[str, dict]: API event type을 key로 하는 default event options

Usage

err, msg, options = handler.get_default_event_options(camera_id=0)
print(options["without_helmet"])

`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]: API event type을 key로 하는 event options

Raises:

Type	Description
`UnregisteredCameraIdError`	등록되지 않은 camera_id일 때

Usage

err, msg, options = handler.get_event_options(camera_id=0)
print(options["fire_detect"])

`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]`	API event type을 key로 하는 event options	required

Raises:

Type	Description
`UnregisteredCameraIdError`	등록되지 않은 camera_id일 때

Usage

err, msg, options = handler.get_event_options(camera_id=0)
options["without_helmet"]["helmet_off_score_threshold"] = 60
err, msg, _ = handler.set_event_options(camera_id=0, event_options=options)

`get_default_alarm_options(camera_id)`

기본 alarm options을 반환합니다 (enabled=False 강제).

Parameters:

Name	Type	Description	Default
`camera_id`	`int`	사용하지 않음, API 일관성을 위해 존재.	required

Returns:

Type	Description
`dict[str, dict]`	dict[str, dict]: API event type을 key로 하는 default alarm options

Usage

err, msg, options = handler.get_default_alarm_options(camera_id=0)
print(options["without_helmet"])
# {"enabled": False, ...}

`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]: API event type을 key로 하는 alarm options

Raises:

Type	Description
`UnregisteredCameraIdError`	등록되지 않은 camera_id일 때

Usage

err, msg, options = handler.get_alarm_options(camera_id=0)
print(options["fire_detect"]["enabled"])
# False  (build / register_camera 직후엔 모두 False)

`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]`	API event type을 key로 하는 alarm options	required

Raises:

Type	Description
`UnregisteredCameraIdError`	등록되지 않은 camera_id일 때

Usage

err, msg, options = handler.get_alarm_options(camera_id=0)
options["without_helmet"]["enabled"] = True
options["without_helmet"]["alarm_interval"] = 60
err, msg, _ = handler.set_alarm_options(camera_id=0, alarm_options=options)

`reset()`

모든 camera의 tracker / alarm state를 초기화합니다.

Usage

err, msg, _ = handler.reset()

`release()`

모든 inferencer가 잡고 있는 NPU backend 리소스를 해제합니다.

Usage

err, msg, _ = handler.release()

# 또는 context manager 패턴 권장:
with handler:
    err, msg, results = handler.infer(...)
# __exit__에서 release() 자동 호출

InferenceHandler

safety.engine.api.InferenceHandler

build(config) classmethod

infer(images, camera_ids, timestamps)

warmup()

register_camera(camera_id)

release_camera(camera_id)

get_registered_camera_ids()

get_default_tracker_option(camera_id)

get_tracker_option(camera_id)

set_tracker_option(camera_id, tracker_option)

get_default_object_options(camera_id)

get_object_options(camera_id)

set_object_options(camera_id, object_options)

get_default_event_options(camera_id)

get_event_options(camera_id)

set_event_options(camera_id, event_options)

get_default_alarm_options(camera_id)

get_alarm_options(camera_id)

set_alarm_options(camera_id, alarm_options)

reset()

release()

`safety.engine.api.InferenceHandler`

`build(config)` `classmethod`

`infer(images, camera_ids, timestamps)`

`warmup()`

`register_camera(camera_id)`

`release_camera(camera_id)`

`get_registered_camera_ids()`

`get_default_tracker_option(camera_id)`

`get_tracker_option(camera_id)`

`set_tracker_option(camera_id, tracker_option)`

`get_default_object_options(camera_id)`

`get_object_options(camera_id)`

`set_object_options(camera_id, object_options)`

`get_default_event_options(camera_id)`

`get_event_options(camera_id)`

`set_event_options(camera_id, event_options)`

`get_default_alarm_options(camera_id)`

`get_alarm_options(camera_id)`

`set_alarm_options(camera_id, alarm_options)`

`reset()`

`release()`