Augmentation

OCR 학습 시 사용 가능한 augmentation 종류는 다음과 같습니다 (총 8종류)

[
    "random_rotate90",        # NOTE: recognition에서는 제외
    "perspective_transform",  # NOTE: recognition에서는 제외
    "adjust_brightness",
    "adjust_contrast",
    "adjust_hue",
    "adjust_saturation",
    "adjust_gamma",
    "blur",
]

이를 위한 image augmentation API는 Preview API와 Trainer Config의 2가지로 구성됩니다.

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

ocr.ImageProcessor

Bases: _APIDecorator

Image Augmentation Preview를 위한 API 입니다. 각 augmentation들이 특정 파라미터 값에 대해 이미지를 어떻게 변형 시키는지 확인할 수 있습니다.

Note1

일반적으로 학습 시에는 파라미터를 특정 값이 아닌 범위로 설정하여 해당 범위에서 매번 랜덤한 값을 선택해 이미지에 적용합니다. 따라서 preview API의 입력 파라미터와 학습 시 넘겨주는 파라미터는 대부분 값 vs 범위의 차이를 가지게 됩니다. 예를 들어 preview API에서 rotate의 경우 angle (float) 값을 받지만, 학습 config에서는 angle_limit (List[float]) 범위를 받게됩니다. 각 augmentation을 학습에 사용시 필요한 config는 각 함수 설명의 Trainer Config 섹션을 참고하세요.

Note2

API 기획상, augmentation의 실제 자유도보다, 유저가 설정할 수 있는 파라미터가 적은 경우가 있습니다. (각 변 혹은 꼭짓점 마다 독립적으로 적용되는 ratio_jitter나 perspective_transform의 경우) 이러한 augmentation들은 api 호출 시, '값'을 입력 받아서, 이 '값'으로 부터 정의된 '범위'에서 필요한 값들을 랜덤하게 샘플링하게 됩니다. 이러한 augmentation들의 preview 함수를 정의할 때는, 인풋에 fixed_aug_params를 받을 수 있도록 해주어야합니다. (ImageProcessor.ratio_jitter 참고)

Usage

rotate augmentation preview 예제입니다. 상세 설명은 각 함수 설명 참고.

image = np.zeros((100, 100, 3), dtype=np.unit8)
error, message, augmented_result = ImageProcessor.rotate(image=image, angle=15)
augmented_image, augmentation_parameters = augmented_result

# In the case of 'rotate' augmentation, `augmentation_parameters` is None

random_rotate90(image, factor=0)

image를 [0, 90, 180, 270] 중 랜덤한 각도만큼 회전시킵니다.

NOTE

• 모든 이미지 픽셀은 유지되며, 회전 후 이미지 크기가 변경될 수 있습니다.
• 예시: factor가 1일 경우 90도 회전하며, 이미지 사이즈는 (W, H) -> (H, W)로 변경됩니다.

Parameters:

Name	Type	Description	Default
image	ndarray	augmentation을 적용할 image 입니다. data type: uint8 channel: H x W / H x W x 1 - Gray H x W x 3 - RGB H x W x 4 - RGBA	required
factor	int	회전하는 각도 입니다. factor에 90을 곱한 값만큼 회전합니다. (ex. factor가 1일 경우 90도) 유효범위는 다음과 같습니다 [0, 3]. Defaults to 0.	0

Returns:

Name	Type	Description
	ndarray	np.ndarray: augmentation이 적용된 image 입니다.
NoneType	None	None

Example

error, message, augmented_image = ImageProcessor.random_rotate90(image=image, factor=1)

Trainer Config

{
    "_target_": "random_rotate90",
}

perspective_transform(image, intensity=0, fixed_aug_params=None)

이미지를 투영 변환(Perspective Transform)합니다. image를 다른 각도(시점)에서 바라본 형태로 변환합니다. Perspective Transform 을 위한 네개의 도착점의 좌표 (offset)은 다음과 같이 샘플링됩니다. offset_top_left: 원본 이미지의 좌측 상단 모서리를 얼마만큼 중심부로 이동시킬 지에 대한 실수 값이 들어있습니다. 즉, Perspective Transform 의 좌측 상단점의 도착점은 아래와 같이 계산할 수 있습니다.

```
x` = 0 + width * offset_top_left[0]
y` = 0 + height * offset_top_left[1]
point_dst = (x`, y`)
```

offset_bottom_right

offset_top_left 와 동일하되 우측 하단 점을 나타냅니다. Perspective Transform 의 우측 하단점의 도착점은 아래와 같이 계산할 수 있습니다.

x` = width - width * offset_bottom_right[0]
y` = height - height * offset_bottom_right[1]
point_dst = (x`, y`)

offset_top_right: offset_top_left 와 동일하되 우측 상단 점을 나타냅니다. offset_bottom_left: offset_top_left 와 동일하되 좌측 하단 점을 나타냅니다.

Parameters:

Name	Type	Description	Default
image	ndarray	augmentation을 적용할 image 입니다. data type: uint8 channel: H x W / H x W x 1 - Gray H x W x 3 - RGB H x W x 4 - RGBA	required
intensity	int	perspective transform 을 적용 강도(단위: 백분율)입니다. intensity 범위 내에서 랜덤한 값으로 샘플된 네개의 offset 을 이용해 perspective transform 을 수행합니다. 유효 범위는 [0, 49] 로, 각 도착지 점들은 이미지의 중간 선을 지나칠 수 없습니다. 이를 통해 이미지가 반전되는 정도의 왜곡을 방지합니다. Defaults to 0. (fixed_aug_params=None일 때만 작동합니다.)	0
fixed_aug_params	Dict	각 꼭짓점에 대해서 offset 비율을 직접 정해주고자 할 때 사용합니다.	None

Returns:

Name	Type	Description
	ndarray	np.ndarray: augmentation이 적용된 image 입니다.
Dict	Dict	각 꼭짓점에 적용된 offset들입니다. { "offset_top_left": Tuple[float, float], "offset_top_right": Tuple[float, float], "offset_bottom_right": Tuple[float, float], "offset_bottom_left": Tuple[float, float], }

각 꼭짓점의 offset 비율을 직접 설정

error, message, augmented_image = ImageProcessor.perspective_transform(
    image=image,
    fixed_aug_params={
        "offset_top_left": (25.0, 30.0),
        "offset_top_right": (10.0, 40.0),
        "offset_bottom_right": (0.0, 20.0),
        "offset_bottom_left": (20.0, 35.0),
    }
)

각 꼭짓점에 [0, intensity] 범위에서 랜덤하게 offset 비율을 적용

error, message, augmented_image = ImageProcessor.perspective_transform(
    image=image,
    intensity=10,
)

Trainer Config

{
    "_target_": "perspective_transform",
    "intensity_limit": List[float],  # intensity 최소 최대 범위
}

adjust_brightness(image, brightness=0.0)

image의 밝기 (brightness)를 변경합니다.

Parameters:

Name	Type	Description	Default
image	ndarray	augmentation을 적용할 image 입니다. data type: uint8 channel: H x W / H x W x 1 - Gray H x W x 3 - RGB H x W x 4 - RGBA	required
brightness	float	밝기를 변화 강도입니다. 유효 범위는 다음과 같습니다. [-1.00, 1.00]. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
	ndarray	np.ndarray: augmentation이 적용된 image 입니다.
NoneType	None	None

Example

error, message, augmented_image = ImageProcessor.adjust_brightness(image=image, brightness=0.3)

Trainer Config

{
    "_target_": "adjust_brightness",
    "brightness_limit": List[float],  # brightness 최소 최대 범위
}

adjust_contrast(image, contrast=0.0)

image의 대비 (contrast)를 변경합니다.

Parameters:

Name	Type	Description	Default
image	ndarray	augmentation을 적용할 image 입니다. data type: uint8 channel: H x W / H x W x 1 - Gray H x W x 3 - RGB H x W x 4 - RGBA	required
contrast	float	대비 변화 강도입니다. 유효 범위는 다음과 같습니다. [-1.00, 1.00]. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
	ndarray	np.ndarray: augmentation이 적용된 image 입니다.
NoneType	None	None

Example

error, message, augmented_image = ImageProcessor.adjust_contrast(image=image, contrast=0.7)

Trainer Config

{
    "_target_": "adjust_contrast",
    "contrast_limit": List[float],  # contrast 최소 최대 범위
}

adjust_hue(image, hue=0.0)

image의 색조 (hue)를 변경합니다.

Parameters:

Name	Type	Description	Default
image	ndarray	augmentation을 적용할 image 입니다. data type: uint8 channel: H x W / H x W x 1 - Gray H x W x 3 - RGB H x W x 4 - RGBA	required
hue	float	색조 변화 강도입니다. 유효 범위는 다음과 같습니다. [-1.00, 1.00]. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
	ndarray	np.ndarray: augmentation이 적용된 image 입니다.
NoneType	None	None

Example

error, message, augmented_image = ImageProcessor.adjust_hue(image=image, hue=0.7)

Trainer Config

{
    "_target_": "adjust_hue",
    "hue_limit": List[float],  # hue 최소 최대 범위
}

adjust_saturation(image, saturation=0.0)

image의 채도 (saturation)를 변경합니다.

Parameters:

Name	Type	Description	Default
image	ndarray	augmentation을 적용할 image 입니다. data type: uint8 channel: H x W / H x W x 1 - Gray H x W x 3 - RGB H x W x 4 - RGBA	required
saturation	float	채도 변화 강도입니다. 유효 범위는 다음과 같습니다. [-1.00, 1.00]. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
	ndarray	np.ndarray: augmentation이 적용된 image 입니다.
NoneType	None	None

Example

error, message, augmented_image = ImageProcessor.adjust_saturation(image=image, saturation=0.7)

Trainer Config

{
    "_target_": "adjust_saturation",
    "saturation_limit": List[float],  # saturation 최소 최대 범위
}

adjust_gamma(image, gamma=0.0)

image의 gamma를 조절하여 밝기를 변화시킵니다.

Parameters:

Name	Type	Description	Default
image	ndarray	augmentation을 적용할 image 입니다. data type: uint8 channel: H x W / H x W x 1 - Gray H x W x 3 - RGB H x W x 4 - RGBA	required
gamma	float	조절할 gamma value 입니다. 유효 범위는 다음과 같습니다. [-1.0, 1.0]. Defaults to 0.0.	0.0

Returns:

Name	Type	Description
	ndarray	np.ndarray: augmentation이 적용된 image 입니다.
NoneType	None	None

Example

error, message, augmented_image = ImageProcessor.adjust_gamma(image=image, gamma=0.5)

Trainer Config

{
    "_target_": "adjust_gamma",
    "gamma_limit": List[float],  # gamma 최소 최대 범위
}

blur(image, ksize=1)

image에 averaging blur를 적용합니다.

Parameters:

Name	Type	Description	Default
image	ndarray	augmentation을 적용할 image 입니다. data type: uint8 channel: H x W / H x W x 1 - Gray H x W x 3 - RGB H x W x 4 - RGBA	required
ksize	int	blur kernel의 크기 입니다. 유효 범위는 다음과 같습니다. [1, 100]. Defaults to 1.	1

Returns:

Name	Type	Description
	ndarray	np.ndarray: augmentation이 적용된 image 입니다.
NoneType	None	None

Example

error, message, augmented_image = ImageProcessor.blur(image=image, ksize=3)

Trainer Config

{
    "_target_": "blur",
    "ksize_limit": List[int],  # ksize 최소 최대 범위
}

Trainer Config

Trainer에 넘겨주는 augmentation config는 List[Dict] 형태이며, 적용할 augmentation들의 파라미터(Dict)를 리스트로 모은 것입니다. 해당 리스트를 Trainer.build() config의 augmentation 섹션에 넣어주면 학습 시 augmentation이 적용됩니다.

• Augmentation config 예시 (10가지 augmentation 모두 사용하는 경우, 파라미터는 유저가 선택한 값)

  augmentation_config = [
      {
          "_target_": "random_rotate90",
          "prob": 1.0,
      },
      {
          "_target_": "perspective_transform",
          "intensity_limit": [0, 30],
      },
      {
          "_target_": "adjust_brightness",
          "brightness_limit": [-0.2, 0.2],
      },
      {
          "_target_": "adjust_contrast",
          "contrast_limit": [-0.2, 0.2],
      },
      {
          "_target_": "adjust_hue",
          "hue_limit": [-0.2, 0.2],
      },
      {
          "_target_": "adjust_saturation",
          "saturation_limit": [-0.2, 0.2],
      },
      {
          "_target_": "adjust_gamma",
          "gamma_limit": [-0.2, 0.2],
      },
      {
          "_target_": "blur",
          "ksize_limit": [3, 7],
      },
  ]
  

• Augmentation config 예시2 ("perspective_transform"만 사용하는 경우)

  augmentation_config = [
      {
          "_target_": "perspective_transform",
          "intensity_limit": [0, 30],
      },
  ]
  

• Trainer build config 예시

  # Detection
  det_augmentation_config = [
      {
          "_target_": "perspective_transform",
          "intensity_limit": [0, 30],
      },
      {
          "_target_": "adjust_brightness",
          "brightness_limit": [-0.2, 0.2],
      },
  ]
  
  det_trainer_config = {
      "network_type": "v2_standard",
      ...
      "augmentation": det_augmentation_config,  # augmentation section에 삽입
      ...
  }
  
  error, det_trainer = DetTrainer.build(config=det_trainer_config, data)
  
  # Recognition
  rec_augmentation_config = []
  for aug in det_augmentation_config:
      if aug["_target_"] not in ["random_rotate90", "perspective_transform"]:
          rec_augmentation_config.append(aug)
  
  rec_trainer_config = {
      "network_type": "v2_contextual_accurate_medium",
      ...
      "augmentation": rec_augmentation_config,  # augmentation section에 삽입
      ...
  }
  error, rec_trainer = RecTrainer.build(config=rec_trainer_config, data)