AugraphyPipeline#

class augraphy.base.augmentationpipeline.AugraphyPipeline(ink_phase=[], paper_phase=[], post_phase=[], pre_phase=[], overlay_type='ink_to_paper', overlay_alpha=0.3, ink_color_range=(-1, -1), paper_color_range=(255, 255), mask=None, keypoints=None, bounding_boxes=None, save_outputs=False, fixed_dpi=False, log=False, random_seed=None)[source]#

Bases: object

Contains phases of image augmentations and their results.

Parameters:

pre_phase – Collection of Augmentations to apply
ink_phase (base.augmentationsequence or list) – Collection of Augmentations to apply.
paper_phase (base.augmentationsequence or list) – Collection of Augmentations to apply.
post_phase (base.augmentationsequence or list) – Collection of Augmentations to apply.
overlay_type (string, optional.) – Blending method to print ink into paper.
overlay_alpha (float, optional.) – The alpha value for certain overlay methods.
ink_color_range (tuple, optional) – Pair of ints determining the range from which to sample the ink color.
paper_color_range (tuple, optional) – Pair of ints determining the range from which to sample the paper color.
mask (numpy array (uint8), optional) – The mask of labels for each pixel. Mask value should be in range of 1 to 255. Value of 0 will be assigned to the filled area after the transformation.
keypoints (dictionary, optional) – A dictionary of single or multiple labels where each label is a nested list of points coordinate. For example: keypoints = {“label1”:[[xpoint1, ypoint1], [xpoint2, ypoint2]], “label2”:[[xpoint3, ypoint3]]}.
bounding_boxes (list, optional) – A nested list where each nested list contains box location (x1, y1, x2, y2). For example: bounding_boxes = [[xa1,ya1,xa2,ya2], [xb1,yb2,xb2,yb2]]
save_outputs (bool, optional) – Flag to enable saving each phase output image.
fixed_dpi (bool, optional) – Flag to enable a same DPI in both input and augmented image.
log (bool, optional) – Flag to enable logging.
random_seed (int, optional) – The initial value for PRNGs used in Augraphy.

apply_phase(data, layer, phase)[source]#

Applies every augmentation in a phase.

Parameters:

data (dictionary) – A dictionary of AugmentationResults representing the changes in each phase of the pipeline.
layer (string) – The name of current layer or phase.
phase (base.augmentationsequence or list) – Collection of Augmentations to apply.

augment(image, return_dict=1)[source]#

Applies the Augmentations in each phase of the pipeline.

Parameters:

image (numpy.array or list) – The image to apply Augmentations to. Minimum 30x30 pixels.
return_dict (int) – Flag to return output in dictionary format. Not applicable when input is 4 dimensional array. When input is 4 dimensional numpy array, output will be a 4 dimensional array too.

Returns:

A dictionary of AugmentationResults representing the changes in each phase of the pipeline if the input is image.
A list contains output images if the input is list of images.
A four dimensional numpy array if the input is a four dimensional numpy array (batch size, channels, height, width).

Return type:

dictionary
list
numpy array (B, C, H, W)

augment_single_image(image, mask, keypoints, bounding_boxes)[source]#

Applies the Augmentations in each phase of the pipeline.

Parameters:

image (numpy.array) – The image to apply Augmentations to. Minimum 30x30 pixels.
mask (numpy array (uint8), optional) – The mask of labels for each pixel. Mask value should be in range of 0 to 255.
keypoints (dictionary, optional) – A dictionary of single or multiple labels where each label is a nested list of points coordinate (x, y).
bounding_boxes (list, optional) – A nested list where each nested list contains box location (x1, y1, x2, y2).

Returns:

A dictionary of AugmentationResults representing the changes in each phase of the pipeline.

Return type:

dictionary

get_oneof_data(augmentation, result, save_path, layer_name, augmentation_name, i, n)[source]#

Get augmentation information from OneOf augmentation recursively or save the augmented image in disk.

Parameters:

augmentation (class instance) – Augmentation object of OneOf augmentation.
result (list or numpy array.) – Augmentation output, it may be nested in a list.
save_path (list) – Output path of result.
layer_name (list) – Name of current layer.
augmentation_name (list) – A combined name of augmentations, seperated by _.
i (int) – Index of current augmentation in total number of augmentations.
n (int) – Index of current augmented in total number of augmented images.

get_sequence_data(augmentation, result, save_path, layer_name, input_augmentation_name, i, n)[source]#

Get augmentation information from AugmentationSequence augmentation recursively or save the augmented image in disk.

Parameters:

augmentation (class instance) – Augmentation object of OneOf augmentation.
result (list or numpy array.) – Augmentation output, it may be nested in a list.
save_path (list) – Output path of result.
layer_name (list) – Name of current layer.
augmentation_name (list) – A combined name of augmentations, seperated by _.
i (int) – Index of current augmentation in total number of augmentations.
n (int) – Index of current augmented in total number of augmented images.

print_ink_to_paper(data, overlay, background)[source]#

Applies the ink layer to the paper layer.

Parameters:

data (dictionary) – A dictionary of AugmentationResults representing the changes in each phase of the pipeline.
overlay (numpy array) – Foreground of overlay process, output from ink phase.
background (numpy array) – Background of overlay process, output from paper phase.

save_images(data)[source]#

Save each augmented image in each phases to local disk.

Parameters:: data (dictionary) – A dictionary of AugmentationResults representing the changes in each phase of the pipeline.

visualize()[source]#

wrapListMaybe(augs)[source]#: Converts a bare list to an AugmentationSequence, or does nothing.

write_log(data)[source]#

Save augmentations log to local disk.

Parameters:: data (dictionary) – A dictionary of AugmentationResults representing the changes in each phase of the pipeline.

Overview#

AugraphyPipeline is the core utility function to enable user create an augmentation pipeline. It contains 3 phases, where each of them are ink phase, paper phase and post phase. Ink phase and paper phase augmentations will be applied first and their output will be merged and become the input for post phase augmentations.

Example to use AugraphyPipeline#

This is an example to use AugraphyPipeline in the augmentation, and both of the flag to save logs and save output images are set to true.

# import libraries
from augraphy import *
import cv2
import numpy as np

ink_phase   = [InkBleed(p=0.7),
               BleedThrough(p=0.7)]
paper_phase = [WaterMark(p=0.7),
               DirtyDrum(p=0.7)]
post_phase  = [DirtyRollers(p=0.7),
               PencilScribbles(p=0.7)]
pipeline    = AugraphyPipeline(ink_phase, paper_phase, post_phase, log=True, save_outputs=True)

image = np.full((1200, 1200,3), 250, dtype="uint8")
cv2.putText(
    image,
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
    (80, 250),
    cv2.FONT_HERSHEY_SIMPLEX,
    1.2,
    0,
    3,
)

augmented_image = pipeline.augment(image)["output"]

Input image:

Augmented image:

Setting the “log” flag to true enable the logging feature. A folder in a same file level with name of “logs” will be created and a log file will be created, each of the log file name is initialized in the format of “log_(year)_(month)_(day)_(hour)_(minute)_(second).txt”. In the log file, each new line records details from an augmentation and they are in the format of “augmentation name, status, augmentation parameters”. Augmentation name shows the name of augmentation, while status shows True when augmentation is completed successfuly and False when it is not (when probability < assigned value). Augmentation parameters will be displayed only if augmentation is completed successfuly and it shows a dictionary of augmentation parameters.

An example of log file contents:

InkBleed,True,{'p': 0.7, 'intensity_range': [0.1, 0.2], 'color_range': [0, 224], 'kernel_size': [5, 5], 'severity': [0.4, 0.6]}

BleedThrough,True,{'p': 0.7, 'intensity_range': [0.1, 0.9], 'color_range': [0, 224], 'ksize': [17, 17], 'sigmaX': 1, 'alpha': (), 'offsets': [20, 20]}

WaterMark,False,

DirtyDrum,True,{'p': 0.7, 'line_width_range': [1, 4], 'line_concentration': 0.1, 'direction': 0, 'noise_intensity': 0.5, 'noise_value': [0, 30], 'ksize': [3, 3], 'sigmaX': 0}

DirtyRollers,True,{'p': 0.7, 'line_width_range': [8, 12], 'scanline_type': 0}

PencilScribbles,True,{'p': 0.7, 'size_range': [250, 400], 'count_range': [1, 10], 'stroke_count_range': [1, 6], 'thickness_range': [2, 6], 'brightness_change': 128}

Setting the “save_outputs” flag enables the feature to save images in each stage of the augmentation pipeline. A folder in a same file level with name of “augmentation_images” will be created. This folder contains another 3 sub-folders, each with name of “ink”, “paper”, “post” to store on each phase’s augmentation images. Each image name is in the format of “(index in total images)_(phase)(image index in current phase)_(augmentation name)”.

Example on augmented images in each phase:

Ink Phase:

Ink layer input