Inference

`classification.InferenceHandler`

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

Usage

# 인퍼런스 모듈 빌드
inferene_build_config = {
    "checkpoint_path": CHECKPOINT_PATH,
    "password": PASSWORD,
    "device": DEVICE,
}
error, inference_handler = InferenceHandler.build(inferene_build_config)
assert error >= 0

# 모듈 정보 확인
error, metadata = read_metadata(CHECKPOINT_PATH)
assert error >= 0
print("Inference metadata:", metadata)

# 인퍼런스 옵션 초기값 확인
n_classes = CONFIG["n_classes"]
inference_options = {
    "outputs.class_activation_map": True,
    "outputs.time": False,
    "params.additional_scores": [10.0] * n_classes,
    "params.batch_size": 1,
}
print("Default inference options:")
for key in inference_options:
    error, value = inference_handler.get_default_inference_option(key)
    assert error >= 0
    print(f"  {key}: {value}")

# 디벨로퍼: Analyze 수행
for image_id, image_info in DATA["validation_images"].items():
    image_info["save_dir"] = os.path.join("./demo/inference_results", str(image_id))
    image = {image_id: image_info}

    error, results = inference_handler.analyze(images=image, labeled=True, use_saved_file=False)
    assert error >= 0

error, results = inference_handler.summarize_analysis(images=DATA["validation_images"], labeled=True)
assert error >= 0
print("Analysis summary:", results)

# 디벨로퍼: 인퍼런스 옵션 변경
for key, value in inference_options.items():
    error, _ = inference_handler.set_inference_option(key, value)
    assert error >= 0

# 디벨로퍼: metadata에 inference_option 저장 (예시)
metadata["inference_options"] = inference_options
error, _ = write_metadata(CHECKPOINT_PATH, metadata)
assert error >= 0

# 인퍼런스 옵션이 잘 변경되었는지 확인
print("Inference options:")
for key in inference_options:
    error, value = inference_handler.get_inference_option(key)
    assert error >= 0
    print(f"  {key}: {value}")

# 디벨로퍼: 새로운 세팅으로 Analyze 재수행
for image_id, image_info in DATA["validation_images"].items():
    image = {image_id: image_info}

    error, results = inference_handler.analyze(images=image, labeled=True, use_saved_file=True)
    assert error >= 0

error, results = inference_handler.summarize_analysis(images=DATA["validation_images"], labeled=True)
assert error >= 0
print("Analysis summary:", results)

# 런타임: 핸들러 빌드
error, metadata = read_metadata(CHECKPOINT_PATH)
assert error >= 0
inferene_build_config["inference_options"] = metadata["inference_options"]
error, inference_handler = InferenceHandler.build(inferene_build_config)
assert error >= 0

# 런타임 검사: 후처리까지 한번에 최적화된 연산으로 수행
image_id = next(iter(DATA["validation_images"]))
image_path = DATA["validation_images"][image_id]["path"]
error, output = inference_handler.infer_and_postprocess(images=[image_path])
assert error >= 0
print("Runtime (infer_and_postprocess):", output)

`build(config)` `classmethod`

InferenceHandler class의 instance를 생성합니다.

Parameters:

Name Type Description Default

config

Dict

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

{
    "checkpoint_path": str,  # 체크포인트 경로
    "inference_options": Optional[Dict], # 인퍼런스 옵션 config (default None). 구조는 `get_default_inference_option`의 Keys 참고.
    "password": Optional[str],  # 체크포인트 패스워드 (default None)
    "device": Union[int, str],  # GPU 번호 (int) or "cpu" (str) (default "cpu")
}

required

Returns:

Name	Type	Description
`InferenceHandler`	`InferenceHandler`	build가 완료된 classification.InferenceHandler class의 instance를 반환합니다.

`get_default_inference_option(key)`

Inference & postprocess 옵션의 기본 설정 값을 반환합니다.

Parameters:

Name	Type	Description	Default
`key`	`str`	옵션 key	required

Returns:

Name	Type	Description
`Any`	`Any`	옵션 value

Keys

사용 가능한 key와 value 목록:

{
    "outputs.class_activation_map": bool,  # (default True, output 중 class_activation_map 계산할 지 여부. True인 경우 계산)
    "outputs.time": bool,  # (default False, 인퍼런스 시 각 요소에 걸린 시간 측정 여부. True인 경우 측정)
    "params.additional_scores": List[Union[int, float]],  # scores_including_add를 계산할 때, scores_original에 더해지는 값입니다. 각 값은 [0, 100] 범위의 실수. (default [0.0, ... , 0.0])
    "params.batch_size": int,  # `infer_and_postprocess`에 한 번에 입력할 수 있는 최대 이미지 개수 입니다.
                               # 파라미터가 변경되는 경우 해당 값으로 warmup을 수행합니다.
                               # (default 1)
}

사용 예시:

handler.get_default_inference_option(key="outputs.class_activation_map")
handler.set_inference_option(key="outputs.class_activation_map", value=False)

`get_inference_option(key)`

현재 설정된 inference & postprocess 옵션 값을 읽습니다.

Parameters:

Name	Type	Description	Default
`key`	`str`	옵션 key	required

Returns:

Name	Type	Description
`Any`	`Any`	옵션 value

Keys

get_default_inference_option과 동일합니다.

`set_inference_option(key, value)`

Inference & postprocess 옵션을 설정합니다.

Parameters:

Name	Type	Description	Default
`key`	`str`	설정하고자 하는 옵션 key 입니다.	required
`value`	`Any`	설정하고자 하는 옵션 value 입니다.	required

Returns:

Name	Type	Description
`None`	`None`	None

Keys

get_default_inference_option과 동일합니다.

`infer_and_postprocess(images)`

image의 List를 입력으로 받아 모델 인퍼런스와 후처리를 수행합니다. (for Runtime) 실시간 검사를 위해 연산 과정이 최적화되어 있으며, 중간 결과를 제거하고 postprocess 최종 결과만을 반환합니다.

Parameters:

Name Type Description Default

images

Union[List[np.ndarray], List[str]]

- List[np.ndarray]: numpy image가 들어있는 List 입니다. 각 image는 다음 제약 조건을 갖습니다.
                    data type: uint8, uint16
                    channel: H x W / H x W x 1 - Gray
                             H x W x 3 - RGB
                             H x W x 4 - RGBA
- List[str]: image 경로가 들어있는 List 입니다.
- List[List[np.ndarray]]: multipage인 경우 사용.
- List[List[str]]: multipage인 경우 사용.

required

Returns:

Type Description

List[Dict]

List[Dict]: image의 postprocess 결과들이 들어있는 List 입니다.

[
    {   # 항상 생성되는 값.
        "scores_original": ndarray(float32, shape=(N,)),  # 모델이 예측한 점수입니다. 점수가 높을수록 해당 클래스일 확률이 높다는 뜻입니다.
        "scores_including_add": ndarray(float32, shape=(N,)),  # scores_original에 user가 설정한 additional_scores를 더한 값입니다.
        "class_index": 0 (int),  # 최종 선택된 class index 입니다. scores_including_add 값 중 가장 높은 점수를 가지는 class 입니다.

        # 아래 키들 중 inference_options에 설정된 출력 값들만 포함.
        "class_activation_map": ndarray(uint8, shape=(H, W)),  # 모델이 입력으로 받은 이미지를 특정 클래스로 분류한 이유를 나타내는 heatmap 입니다.
        "time": {  # inference에 소요된 시간을 담고있는 dictionary 입니다. (단위: ms)
            "imread_time": float,  # 실제 image를 load하여 연구팀이 사용하는 image format (PIL)으로 변경하기까지 걸리는 시간 (각 이미지 별로 걸리는 시간)
            "inference_time": float,  # resize, roi, tensorize, network forward 등을 포함하는 시간 (각 이미지 별로 걸리는 시간)
            "post_processing_time": float,  # postprocess에 걸린 시간 (각 이미지 별로 걸리는 시간)
        },
    },
    ...,  # times number of images
]

`analyze(images, labeled, use_saved_file)`

images들에 대한 analysis 결과 계산

Parameters:

Name Type Description Default

images

Dict[str, Dict]

analysis에 사용할 데이터 리스트. Trainer 빌드에 사용하는 이미지 리스트와 동일한 구조.

{
    "{image_id}": {
        "path": Union[str, List[str]],  # 이미지 경로 (multipage인 경우 경로 리스트)
        "width": int,  # image width
        "height": int,  # image height
        "class_index": int,  # ground truth label, **(labeled=False)인 경우 필요하지 않습니다.
        "save_dir": str, # 해당 이미지의 analysis 결과 저장 directory
    },
    ...,  # times number of images
}

required

labeled

bool

label 존재 여부. label 존재 여부에 따라 analysis 결과 Dict 구성 요소가 달라집니다.

required

use_saved_file

bool

기존 인퍼런스 결과인 saved_file 사용 여부

required

Returns:

Name Type Description

Dict

Analysis 결과

{
    "{image_id}": {
        "predictions": {  # 아래 키들 중 inference_options에 설정된 출력 값들만 포함.
            "scores_original": ndarray(float32, shape=(N)),  # 모델이 예측한 점수입니다. 점수가 높을수록 해당 클래스일 확률이 높다는 뜻입니다.
            "scores_including_add": ndarray(float32, shape=(N)),  # scores_original에 user가 설정한 additional_scores를 더한 값입니다.
            "class_index": int,  # 최종 선택된 class index 입니다. scores_including_add 값 중 가장 높은 점수를 가지는 class 입니다.
            "class_activation_map": ndarray(uint8, shape=(H, W)),  # 모델이 입력으로 받은 이미지를 특정 클래스로 분류한 이유를 나타내는 heatmap 입니다. (use_saved_file=False인 경우에만 나옴)
            "correct": bool,  # True면 정답, False면 오답.  **(labeled=True)인 경우에만 나옴**
            "time": {  # inference에 소요된 시간을 담고있는 dictionary 입니다. (단위: ms)
                "imread_time": float,  # 실제 image를 load하여 연구팀이 사용하는 image format (PIL)으로 변경하기까지 걸리는 시간 (각 이미지 별로 걸리는 시간)
                "inference_time": float,  # resize, roi, tensorize, network forward 등을 포함하는 시간 (각 이미지 별로 걸리는 시간)
                "post_processing_time": float,  # postprocess에 걸린 시간 (각 이미지 별로 걸리는 시간)
            },
        },
    },
    ... # 입력으로 넣어준 이미지 개수만큼 반복
}

Note1

analyze() 함수를 사용하기 위해서는 inference_options 중 outputs.class_activation_map=True & outputs.class_index=True 여야 합니다.

`summarize_analysis(images, labeled)`

Parameters:

Name Type Description Default

images

Dict[str, Dict]

analysis에 사용할 데이터 리스트. Trainer 빌드에 사용하는 이미지 리스트와 동일한 구조.

{
    "{image_id}": {
        "save_dir": str, # 해당 이미지의 analysis 결과 저장 directory
    },
    ...,  # times number of images
}

required

labeled

bool

label 존재 여부. label 존재 여부에 따라 analysis 결과 Dict 구성 요소가 달라집니다.

required

Returns:

Name	Type	Description
`Dict`	`Dict`	Analysis summary 결과 name="__codelineno-0-1" href="#__codelineno-0-1">{ "confusion_matrix": List[List[int]], # confusion matrix. 아래는 총 class가 4개일 때 예시 [ [2, 0, 0, 1], # 라벨이 class1인 image 중에 미검 1개 (class4로 예측), 맞춘 것 2개 [1, 2, 0, 0], # 라벨이 class2인 image 중에 미검 1개 (class1로 예측), 맞춘 것 2개 [0, 1, 0, 0], # 라벨이 class3인 image 중에 미검 1개 (class2로 예측), 맞춘 것 0개 [0, 0, 0, 1], # 라벨이 class4인 image 중에 미검 0개, 맞춘 것 1개 ] # Class-wise Results "class_{idx}_underkill": float, # 각 {idx} class 별 미검(underkill) 비율(0~1). "class_{idx}_overkill": float, # 각 {idx} class 별 과검(overkill) 비율(0~1). "class_{idx}_f1": float, # 각 {idx} class 별 f1 value (0~1). # Overall Results "total": int, # 검사한 이미지 개수 "correct": int, # 검사한 이미지 중 맞은 것의 개수 "wrong": int, # 검사한 이미지 중 틀린 것의 개수 "accuracy": float, # accuracy (0~1). (correct / total) "mean_f1": float, # average f1 score (0~1). class="p">},

`warmup()`

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

Inference

classification.InferenceHandler

build(config) classmethod

get_default_inference_option(key)

get_inference_option(key)

set_inference_option(key, value)

infer_and_postprocess(images)

analyze(images, labeled, use_saved_file)

summarize_analysis(images, labeled)

warmup()

`classification.InferenceHandler`

`build(config)` `classmethod`

`get_default_inference_option(key)`

`get_inference_option(key)`

`set_inference_option(key, value)`

`infer_and_postprocess(images)`

`analyze(images, labeled, use_saved_file)`

`summarize_analysis(images, labeled)`

`warmup()`