Skip to content

ROI

ROI 관련 API는 Preview API와 Trainer Config의 2가지로 구성됩니다.

  • Preview API: 유저가 세팅한 파라미터에 대해 ROI 미리보기 제공
  • Trainer Config: 유저가 세팅한 파라미터를 학습에 사용하기 위해 Trainer.build()에 넣어주는 config

ocr.ROIHandlerAPI

Set-ROI 기능을 위한 API입니다.

Usage 
# 핸들러 빌드. 아래는 simple mode의 예제 config이며, 자세한 설명은 ROIHandlerAPI.set() 함수 참고.
config = {
    "mode": "simple",
    "left": 0.0,
    "top": 0.0,
    "right": 1.0,
    "bottom": 1.0,
    "blind_mask": None,
}
error, roi_hander = ROIHandlerAPI.build(config)

# image에 대한 roi 계산. 리턴 결과 설명은 ROIHandlerAPI.apply() 함수 참고.
image = np.zeros((100, 100, 3), dtype=np.unit8)
error, roi_results = roi_handler.apply(image)

# roi 파라미터 변경
config["left"] = 0.1
error, _  = roi_handler.set(config)

# 변경된 파라미터로 roi 다시 계산
error, roi_results = roi_handler.apply(image)

build(config) classmethod

ROIHandlerAPI를 빌드합니다.

Parameters:

Name Type Description Default
config Dict

ROIHandlerAPI.set의 파라미터와 동일합니다.

 required

Returns:

Name Type Description
ROIHandlerAPI ROIHandlerAPI

빌드된 ROIHandlerAPI

set(config)

ROI 파라미터를 변경합니다.

Parameters:

Name Type Description Default
config Dict

ROI 파라미터의 dict입니다. mode에 따라 다른 파라미터를 가집니다. 

# simple mode:
{
    "mode": "simple",  # Simple ROI 모드.
    "left": float,  # ROI의 왼쪽 경계. [0.0, 1.0) 범위의 실수.
    "top": float,  # ROI의 위쪽 경계. [0.0, 1.0) 범위의 실수.
    "right": float,  # ROI의 오른쪽 경계. (right, 1.0] 범위의 실수.
    "bottom": float,  # ROI의 아래쪽 경계. (top, 1.0] 범위의 실수.
    "blind_mask": Optional[np.ndarray],  # blind mask 이미지. None인 경우 blind 적용 안함.
                                         # np.ndarray인 경우 (dtype=uint8, shape=(H, W))이며 픽셀 값은 0 또는 1.
                                         # mask의 값이 1인 영역이 학습/검사 시 마스킹됩니다.
                                         # bboxes와 polygons에는 blind_mask가 적용되지 않습니다.
}
# advanced mode:
{
    "mode": "advanced",  # Advanced ROI 모드.
    "intensity": List[int],  # 필터링할 [최소, 최대] 픽셀값 범위. 각 값은 [0, 255] 범위의 정수.
    "expansion": int,  # 필터링된 픽셀 영역에 대한 확장/축소 정도. [-10, 10] 범위의 정수.
    "inversion": bool,  # True인 경우 필터링된 픽셀 영역을 반전.
    "offset_left": float,  # ROI 박스의 왼쪽 사이즈. [0.0, 2.0] 범위의 실수 이며, 1인 경우 기본 크기.
    "offset_right": float,  # ROI 박스의 오른쪽 사이즈. [0.0, 2.0] 범위의 실수 이며, 1인 경우 기본 크기.
    "offset_top": float,  # ROI 박스의 위쪽 사이즈. [0.0, 2.0] 범위의 실수 이며, 1인 경우 기본 크기.
    "offset_bottom": float,  # ROI 박스의 아래쪽 사이즈. [0.0, 2.0] 범위의 실수 이며, 1인 경우 기본 크기.
    "blind_mask": Optional[np.ndarray],  # blind mask 이미지. None인 경우 blind 적용 안함.
                                         # np.ndarray인 경우 (dtype=uint8, shape=(H, W))이며 픽셀 값은 0 또는 1.
                                         # mask의 값이 1인 영역이 학습/검사 시 마스킹됩니다.
                                         # bboxes와 polygons에는 blind_mask가 적용되지 않습니다.
}

required

apply(image)

image에 대한 ROI 좌표 및 기타 결과를 계산합니다.

Parameters:

Name Type Description Default
image np.ndarray

ROI를 적용할 입력 이미지.

 required

Returns:

Name Type Description
Dict Dict

ROI 계산 결과 dict 입니다. mode에 따라 다른 결과 값들을 가집니다. 

# simple mode:
{
    "roi_coordinates": List[int],  # [left, top, right, bottom].
}
# advanced mode:
{
    "roi_coordinates": List[int],  # [left, top, right, bottom].
    "filtered_image": np.ndarray(uint8, shape=(H, W)),  # intensity, expansion, inversion이 적용된 중간 결과 이미지 입니다. (픽셀값: 0 or 1)
}

Trainer Config

Preview API에서 설정한 roi config를 그대로 Trainer.build() config의 roi 섹션에 넣어주면 학습 시 해당 roi가 적용되며, 학습에서 설정하는 roi는 validation 및 inference 시에도 동일하게 적용됩니다.

roi_config = {
    "mode": "auto",  # Trainig dataset 의 모든 라벨을 포함하는 적합한 ROI 값을 계산하는 모드
    "padding": "medium",  # ["small", "medium", "large"]
    "blind_mask": None,
}

trainer_config = {
    "model": "standard",
    ...
    "roi": roi_config,
    ...
}

error, trainer = DetTrainer.build(config=trainer_config, data)

roi mode: "auto" 설명

  • 학습 라벨 정보를 쭉 훑어서 모든 라벨 폴리곤을 타이트하게 포함하는 axis aligned bounding box를 자동으로 찾는 기능.
  • 이 때 라벨이 좀 넉넉하게 포함될 수 있도록 상하좌우로 약간의 padding을 줄 수 있는데, 이 패딩 정도만 유저가 define 해 주면 됨.
  • padding: small, medium, large 중 하나로 지정해 주기만 하면 알아서 패딩 양을 조절해 ROI를 만들어 줌 (xyxy 혹은 xywh 값으로..). 디폴트는 medium.
  • 이미지 사이즈가 각각 다른 데이터셋에서의 고정 ROI 기능을 사용하는 것은 비정상적인 사용 예로 간주하고 에러를 레이즈 하게 되어 있음.