Skip to content

kie

ocr.kie.DetRecKieInferencer

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

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

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

# 인퍼런스 옵션 초기값 확인
inference_options = {
    "outputs.time": False,
    "detection.box_confidence_threshold": 0.9,
    "detection.minimum_thickness_threshold": 0.005,
    "detection.absolute_slant_degree_threshold": 30.0,
    "detection.remove_complex_polygon": False,
    "recognition.regex": None,
    "recognition.recognition_confidence_threshold": 0.5,
    "params.detection_batch_size": 1,
    "params.recognition_batch_size": 16,
    "params.max_number_of_predictions": 4,
    "params.inspection_size_wh": [512, 512],
    "params.oversized_image_handling": "resize_to_fit",
}
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 수행
error, _ = inferencer.set_analysis_data(images=DATA["validation_images"], labeled=True)
assert error >= 0

error, analysis_steps = inferencer.initialize_analysis()
assert error >= 0

for _ in range(analysis_steps):
    error, _ = inferencer.step_analysis()
    assert error >= 0

error, analysis_results = inferencer.finalize_analysis()
assert error >= 0
print("Analysis results:", analysis_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 재수행
error, analysis_results = inferencer.analyze_with_existing_data()
assert error >= 0
print("Analysis results:", analysis_results)

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

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

build(config) classmethod

Inferencer class의 instance를 생성합니다.

Parameters:

Name Type Description Default
config Dict

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

{
    "checkpoint_path": str,     # 체크포인트 경로
    "password": Optional[str],  # 체크포인트 패스워드 (default None)
    "device": Union[int, str],  # GPU 번호 (int) or "cpu" (str) (default "cpu")
}

required

Returns:

Name Type Description
Inferencer

build가 완료된 ocr.DetRecKieInferencer class의 instance를 반환합니다.

build_from_checkpoint(config) classmethod

Inferencer class의 instance를 생성합니다. 개별 모듈을 조합해가며 테스트하기 위한 용도의 api method 입니다.

Parameters:

Name Type Description Default
config Dict

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

{
    "checkpoint_config": {
        "checkpoint_path_det": str,     # SceneTextDetection 체크포인트 경로
        "password_det": Optional[str],  # SceneTextDetection 체크포인트 패스워드 (default None)
        "checkpoint_path_rec": str,     # SceneTextRecognition 체크포인트 경로
        "password_rec": Optional[str],  # SceneTextRecognition 체크포인트 패스워드 (default None)
        "checkpoint_path_kie": str,     # KeyInformationExtraction 체크포인트 경로
        "password_kie": Optional[str],  # KeyInformationExtraction 체크포인트 패스워드 (default None)
    },
    "device": Union[int, str],  # GPU 번호 (int) or "cpu" (str) (default "cpu")
}

required

Returns:

Name Type Description
Inferencer

build가 완료된 ocr.DetRecKieInferencer 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.time": bool,  # (default False, 인퍼런스 시 각 요소에 걸린 시간 측정 여부. True인 경우 측정)
    "detection.box_confidence_threshold": float,  # (default 0.9, 박스 detection confidence. 높을수록 확실한 detection 결과임을 의미.)
    "detection.minimum_thickness_threshold": float,  # (default 0.005, 박스 두께 하한선. 전체 이미지 사이즈 대비 비율이며, 너무 작은 detection 결과를 필터링 하기 위해 사용.)
    "detection.absolute_slant_degree_threshold": float,  # (default 30.0, 검출된 박스의 기울어짐 정도 상한선. 너무 좌우로 많이 기울어진 (박스가 마름모에 가까워지는 방향) 텍스트를 필터링 하기 위해 사용.)
    "detection.remove_complex_polygon": bool,  # (default False, Self-intersection 이 발생하는 박스를 제거하기 위해 사용.)
    "recognition.regex": Optional[Union[List[str], List[List[str]]]]  # (default None)
        - None 일 경우엔 모델이 출력할 수 있는 모든 문자를 사용합니다.
        - List[str] 일 경우, List 내부에 포함되어 있는 모든 문자열을 합하여 문자셋을 구축합니다. 글자수에는 영향을 주지 않습니다.
        - List[List[str]] 일 경우, 문자 길이 및 위의 List[str] 을 각 위치에 지정하는 기능을 합니다.
            - 예를 들어, 첫 문자가 무조건 대문자 ABC 중 하나이고, 두번째 문자가 무조건 숫자인 경우는 아래와 같이 정의될 수 있습니다.
            - [["ABC"], ["0123456789"]] -> {길이 2, 영대문자-숫자 순으로 출력} -> recognition 결과 예시: "A0", "B1", "A8", "C0", ...
    "recognition.recognition_confidence_threshold": float,  # (default 0.5, 텍스트 인식 Score(Confidence), 인식된 텍스트에서 각 글자에 대한 확률을 평균낸 점수.)
    "params.detection_batch_size": int,  # `infer_and_postprocess`에 한 번에 입력할 수 있는 최대 이미지 개수 입니다.
                                         # 파라미터가 변경되는 경우 해당 값으로 warmup을 수행합니다.
                                         # (default 1, 1 이외의 값을 설정할 수 없습니다.)
    "params.recognition_batch_size": int,  # `infer_and_postprocess`에 한 번에 입력할 수 있는 최대 이미지 개수 입니다.
                                           # 파라미터가 변경되는 경우 해당 값으로 warmup을 수행합니다.
                                           # (default 16)
    "params.max_number_of_predictions": Optional[int],  # `infer_and_postprocess`에 한 번에 출력할 수 있는 최대 검출 개수 입니다.
                                                        # None 일 경우 최대 검출 수에 제한 없이 모든 텍스트를 검출합니다.
                                                        # int 값을 지정하는 경우 해당 값 이하의 텍스트 수가 검출됩니다.
                                                        # 이 때 detection 검출 후 detection confidence score 로 정렬하여, confidence score 가 높은 텍스트만을 검출합니다.
                                                        # (default None)
    "params.inspection_size_wh": Optional[List[int]],  # inference를 할 때, 내부 연산이 진행되는 image size 입니다.
                                                       # input image가 inspection_size_wh 넘는 경우 aspect ratio를 유지하며 resize 됩니다.
                                                       # input image가 inspection_size_wh 보다 작은 경우 부족한 부분을 zero padding으로 채웁니다.
                                                       # 파라미터가 변경되는 경우 해당 값으로 warmup을 수행합니다.
                                                       # (default None)
    "params.oversized_image_handling": str,  # inference시 inspection_size_wh 보다 큰 이미지에 대한 핸들링 옵션 입니다.
                                             # 아래 옵션들 중 한 가지를 선택할 수 있습니다.
                                             # "do_not_inspect" - 큰 이미지가 들어오면 에러 레이즈
                                             # "resize_to_fit" - 큰 이미지가 들어오면 inspection_size_wh 로 리사이즈해서 검사
                                             # (default "do_not_inspect")
}

사용 예시: 

handler.get_default_inference_option(key="recognition.regex")
handler.set_inference_option(key="recognition.regex", value=["ABCDEF"])

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에서 warmup이 필요한 [params.inspection_size_wh, params.max_batch_size]를 제외하면 동일합니다.

infer_and_postprocess(input)

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

Parameters:

Name Type Description Default
input 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 입니다.
required

Returns:

Type Description
List[Dict[str, Any]]

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

[# TODO: 각 결과값 설명 추가
    {  # 아래 키들 중 inference_options에 설정된 출력 값들만 포함.
        "path": str,  # input image path
        "width": int,  # input image width
        "height": int,  # input image height
        "predictions": [  # OCR 결과 object들의 리스트. (List[Dict])
            {  # ocr object 구조
                "polygon": [
                    [float, float],
                    ..., # times number of points
                ],
                "text": str,
                "class_index": int,
            },
            ...,  # times number of objects
        ],
        "time": {
            "imread_time": float,
            "inference_time": float,
            "detection_inference_time": float,
            "recognition_inference_time": float,
            "detection_post_processing_time": float,
            "recognition_post_processing_time": float,
            "key_information_extraction_inference_time": float,
        }
    },
    ...,  # times number of images
]

set_analysis_data(images, labeled)

Analysis를 위한 data를 세팅합니다. (for Developer)

Parameters:

Name Type Description Default
images Dict[str, Dict]

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

{
    "{image_id}": {
        "path": str,  # 이미지 경로
        "width": int,  # image width
        "height": int,  # image height
        "labels": [  # (labeled = False)인 경우 필요하지 않습니다.
            {
                "polygon": [
                    [float, float],
                    ..., # times number of points
                ],
                "text": str,
                "class_index": int,
            },
            ...,  # times number of labels in the image
        ],
    },
    ...,  # times number of images
}

required
labeled bool

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

 required

Returns:

Name Type Description
None None

None
Note1

Analysis를 위한 api는 정해진 순서대로 호출되어야 하며, 순서를 벗어나는 경우 에러를 raise합니다.

API호출 예시: 

error, _ = inferencer.set_analysis_data(images, labeled)  # 데이터 지정
error, total_steps = inferencer.initialize_analysis()  # 초기화
for _ in range(total_steps):
    error, _ = inferencer.step_analysis()  # 정해진 수 만큼 스텝 수행
error, results = inferencer.finalize_analysis()  # 마무리 & 결과 리턴

for key, value in inference_options.items():  # 인퍼런스 옵션 변경
    error, _ = inference_handler.set_inference_option(key, value)
error, total_steps = inferencer.initialize_analysis()  # 초기화
for _ in range(total_steps):
    error, _ = inferencer.step_analysis()  # 정해진 수 만큼 스텝 수행
error, results = inferencer.finalize_analysis()  # 마무리 & 결과 리턴

for key, value in inference_options.items():  # 인퍼런스 옵션 변경
    error, _ = inference_handler.set_inference_option(key, value)
error, results = inferencer.analyze_with_existing_data()  # 초기화 - 스텝 - 마무리를 한 번에 수행 후 결과 리턴

initialize_analysis()

Analysis를 위한 준비 스텝을 수행.

Returns:

Name Type Description
int int

Analysis 완료를 위해 수행되어야 하는 step_analysis 호출 횟수.

step_analysis()

Analysis를 1스텝 수행.

Returns:

Name Type Description
None None

None

finalize_analysis()

Analysis를 마무리하고 결과를 리턴.

Returns:

Name Type Description
Dict Dict

Analysis 결과 

{ # TODO: 각 결과값 설명 추가
    "images": {
        "{image_id}": {
            "path": "",
            "width": 0,
            "height": 0,
            "predictions": [
                {
                    "polygon": [
                        [float, float],
                        ..., # times number of points
                    ],
                    "text": str,
                    "det_scores": {
                        "confidence": float,
                        "thickness": float,
                        "slant": float,
                        "simple_contour_flag": bool,
                    },
                    "string_score": float,
                    "is_valid_string": bool,
                    "is_valid_patch": bool,
                    "class_index": int,
                    # TODO: kie confidence score and postprocessor
                },
                ..., # 이미지 상의 텍스트 뭉치 수만큼 반복
            ],
            "time": {
                "imread_time": float,
                "inference_time": float,
                "detection_inference_time": float,
                "recognition_inference_time": float,
                "detection_post_processing_time": float,
                "recognition_post_processing_time": float,
                "key_information_extraction_inference_time": float,
            }
        },
        ..., # 입력으로 넣어준 이미지 개수만큼 반복
    },
    "summary": {  # **(labeled=True)인 경우에만 나옴**
        "acc_total": float,  # total accuracy
        "acc_key": float,    # key class accuracy
        "acc_value": float,  # value class accuracy
        "sim_total": float,  # total similarity
        "sim_key": float,    # key class similarity
        "sim_value": float,  # value class similarity
    },
}

analyze_with_existing_data()

기존에 세팅된 데이터를 이용해 전체 analysis를 루틴을 수행하고 최종 결과를 리턴.

Note

해당 함수는 아래 루틴을 호출하는 것과 동일함: 

total_steps = inferencer.initialize_analysis()  # 초기화
for _ in range(total_steps):
    inferencer.step_analysis()  # 정해진 수 만큼 스텝 수행
results = inferencer.finalize_analysis()  # 마무리 & 결과 리턴

Returns:

Name Type Description
Dict Dict

Analysis 결과 (Inferencer.finalize_analysis 리턴 값과 동일)

warmup()

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