Analysis

rotated.AnalysisHandler

딥러닝 모델 빌드 없이, 저장된 모델 인퍼런스 결과를 이용해서 analysis를 수행하는 클래스입니다.

Usage (demo/analysis.py 참고):

# AnalysisHandler 및 SummaryHandler 빌드
n_classes = CONFIG["n_classes"]
analysis_build_config = {
    "n_classes": n_classes,
    "oriented_bboxes_format": "cxcywha_360",
}
error, message, analysis_handler = AnalysisHandler.build(analysis_build_config)
assert error >= 0, f"[CODE] ({error}) {message}"

summary_build_config = {
    "n_classes": n_classes,
}
error, message, summary_handler = SummaryHandler.build(summary_build_config)
assert error >= 0, f"[CODE] ({error}) {message}"

# 모듈 정보 확인
error, message, metadata = read_metadata(CHECKPOINT_PATH)
assert error >= 0, f"[CODE] ({error}) {message}"
print("Inference metadata:", metadata)

# 인퍼런스 옵션 초기값 확인
inference_options = {
    "params.object_score_threshold": [30] * (n_classes),
    "params.object_area_threshold": [0] * (n_classes),
    "params.max_num_of_detected_objects": [-1] * n_classes,
}
print("Default inference options:")
for key in list(inference_options):
    error, message, value = analysis_handler.get_default_inference_option(key)
    assert error >= 0, f"[CODE] ({error}) {message}"
    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, message, results = analysis_handler.analyze(images=image, labeled=True)
    assert error >= 0, f"[CODE] ({error}) {message}"

error, message, results = summary_handler.summarize_analysis(
    images=DATA["validation_images"], labeled=True
)
assert error >= 0, f"[CODE] ({error}) {message}"
print("Analysis summary:", results)

# 디벨로퍼: 인퍼런스 옵션 변경
for key, value in inference_options.items():
    error, message, _ = analysis_handler.set_inference_option(key, value)
    assert error >= 0, f"[CODE] ({error}) {message}"

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

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

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

    error, message, results = analysis_handler.analyze(images=image, labeled=True)
    assert error >= 0, f"[CODE] ({error}) {message}"

error, message, results = summary_handler.summarize_analysis(
    images=DATA["validation_images"], labeled=True
)
assert error >= 0, f"[CODE] ({error}) {message}"
print("Analysis summary:", results)

build(config) classmethod

AnalysisHandler class의 instance를 생성합니다.

Parameters:

Name	Type	Description	Default
config	dict	AnalysisHandler를 build 하기 위한 config가 담겨 있는 dictionary 입니다. { "n_classes": int, # number of data classes (including background class) "oriented_bboxes_format": str, # oriented_bboxes_format. Defaults to "cxcywha_360". "inference_options": Optional[dict], # 인퍼런스 옵션 config (default None). 구조는 `get_default_inference_option`의 Keys 참고. "iou_threshold": float, # Rotated IoU의 임계치. Metric 측정 시 실제 라벨과 추정 결과를 동일한 것으로 간주할 수 있는 두 박스이 겹치는 비율입니다. (default 0.8) }	required

Returns:

Name	Type	Description
AnalysisHandler	AnalysisHandler	build가 완료된 detection.AnalysisHandler class의 instance를 반환합니다.

get_default_inference_option(key)

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

Parameters:

Name	Type	Description	Default
key	str	옵션 key	required

Returns:

Name	Type	Description
Any	Any	옵션 value

Keys

사용 가능한 key와 value 목록:

{
    "outputs.time": bool,  # (default False, 인퍼런스 시 각 요소에 걸린 시간 측정 여부. True인 경우 측정)
    "params.object_score_threshold": list[int],  # 각 클래스의 score threshold 값. 예측 box의 score가 threshold보다 작은 경우 필터링 됩니다.
                                          # 각 값은 [0, 100] 범위의 정수. (default [30, ... , 30])
    "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 [-1, ... , -1])
    "params.num_workers": int, # 동시성 프로그래밍에 적용되는 File I/O를 위한 worker thread의 갯수입니다.
                               # (default 4)
}

사용 예시:

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

get_inference_option(key)

현재 설정된 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)

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과 동일합니다.

analyze(images, labeled)

저장된 network output으로 부터 images들에 대한 analysis 결과 계산

Args & Returns: InferenceHandler.analyze()와 동일하며, 결과 predictions에서 time은 제외됩니다.

Note1

모델 인퍼런스까지 재수행하려면 InferenceHandler.analyze()를 사용하세요.

rotated.SummaryHandler

딥러닝 모델 빌드 없이, 저장된 analysis 결과를 이용해서 analysis summary를 수행하는 클래스입니다.

Usage (demo/inference.py & demo/analysis.py 참고):

# AnalysisHandler 및 SummaryHandler 빌드
n_classes = CONFIG["n_classes"]
analysis_build_config = {
    "n_classes": n_classes,
    "oriented_bboxes_format": "cxcywha_360",
}
error, message, analysis_handler = AnalysisHandler.build(analysis_build_config)
assert error >= 0, f"[CODE] ({error}) {message}"

summary_build_config = {
    "n_classes": n_classes,
}
error, message, summary_handler = SummaryHandler.build(summary_build_config)
assert error >= 0, f"[CODE] ({error}) {message}"

# 모듈 정보 확인
error, message, metadata = read_metadata(CHECKPOINT_PATH)
assert error >= 0, f"[CODE] ({error}) {message}"
print("Inference metadata:", metadata)

# 인퍼런스 옵션 초기값 확인
inference_options = {
    "params.object_score_threshold": [30] * (n_classes),
    "params.object_area_threshold": [0] * (n_classes),
    "params.max_num_of_detected_objects": [-1] * n_classes,
}
print("Default inference options:")
for key in list(inference_options):
    error, message, value = analysis_handler.get_default_inference_option(key)
    assert error >= 0, f"[CODE] ({error}) {message}"
    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, message, results = analysis_handler.analyze(images=image, labeled=True)
    assert error >= 0, f"[CODE] ({error}) {message}"

error, message, results = summary_handler.summarize_analysis(
    images=DATA["validation_images"], labeled=True
)
assert error >= 0, f"[CODE] ({error}) {message}"
print("Analysis summary:", results)

# 디벨로퍼: 인퍼런스 옵션 변경
for key, value in inference_options.items():
    error, message, _ = analysis_handler.set_inference_option(key, value)
    assert error >= 0, f"[CODE] ({error}) {message}"

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

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

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

    error, message, results = analysis_handler.analyze(images=image, labeled=True)
    assert error >= 0, f"[CODE] ({error}) {message}"

error, message, results = summary_handler.summarize_analysis(
    images=DATA["validation_images"], labeled=True
)
assert error >= 0, f"[CODE] ({error}) {message}"
print("Analysis summary:", results)

Note

위 예시처럼 AnalysisHandler가 아니라, InferenceHandler여도 상관 없습니다.

build(config) classmethod

SummaryHandler class의 instance를 생성합니다.

Parameters:

Name	Type	Description	Default
config	dict	SummaryHandler를 build 하기 위한 config가 담겨 있는 dictionary 입니다. { "n_classes": int, # number of data classes "iou_threshold": float, # Rotated IoU의 임계치. Metric 측정 시 실제 라벨과 추정 결과를 동일한 것으로 간주할 수 있는 두 박스이 겹치는 비율입니다. (default 0.8) }	required

Returns:

Name	Type	Description
SummaryHandler	SummaryHandler	build가 완료된 segmentation.SummaryHandler class의 instance를 반환합니다.

summarize_analysis(images, labeled)

images들에 대한 analysis summary 계산

Parameters:

Name	Type	Description	Default
images	dict[str, dict]	analysis에 사용할 데이터 리스트. { "{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	images들에 대한 analysis summary { # labeled=True 인 경우에만 존재 # accuracy "object/accuracy": float, # object-wise accuracy # underkill (각 class별 underkill ratio는 class_{idx}_underkill / class_{idx}_num_labels 로 구할 수 있음.) "object/underkill": int, # 라벨 object 중 검출하지 못한 라벨의 개수 (미검) "object/class_{idx}_underkill": int, # 클래스가 idx인 라벨 object 중 검출하지 못한 라벨의 개수 "object/class_{idx}_num_labels": int, # 클래스가 실제로 idx인 라벨 object의 개수 # overkill (각 class별 overkill ratio는 class_{idx}_overkill / class_{idx}_num_predictions 로 구할 수 있음.) "object/overkill": int, # 예측 object 중 틀린 예측의 개수 (과검) "object/class_{idx}_overkill": int, # 클래스를 idx로 예측한 object 중 틀린 예측의 개수 "object/class_{idx}_num_predictions": int, # 클래스를 idx로 예측한 object의 개수 # f1 "object/mean_f1": float, # object-wise mean f1-score "object/class_{idx}_f1": float, # 클래스가 idx인 box에 대한 object-wise mean f1-score # confusion matrix "object/confusion_matrix": list[list[int]], # object-wise confusion matrix, 마지막 dimension은 wrong을 의미하는 etra dimension (n_class + 1) [ # n_class == 3이라고 할 때 [1, 0, 0, 1], # 라벨이 class0인 object 중 미검 1개, 맞춘것 1개 [0, 2, 0, 4], # 라벨이 class2인 object 중에 미검 4개, 맞춘 것 2개 [0, 0, 3, 0], # 라벨이 class2인 object 중에 미검 2개, 맞춘 것 3개 [5, 0, 3, 0], # class0이라고 예측한 과검 5개, class2라고 예측한 과검 3개 ] }