swtloc.abstractions.SWTImage

class swtloc.abstractions.SWTImage(image: numpy.ndarray, image_name: str, input_flag: ByteString, cfg: Dict)[source]

Bases: swtloc.base.TextTransformBase

This class houses the procedures for

  • Transforming

  • Localizing Letters

  • Localizing Words

Objects of this class are made and stored in SWTLocalizer class attribute swtimages

This class serves as an abstraction to various operations that can be performed via transforming the image through the Stroke Width Transform. This class also includes helper functions to extend the ability to save, show and crop various localizations and intermediary stages as well.

Methods

SWTImage.__init__(image, image_name, ...)

Create an SWTImage, an abstraction to various procedures to be performed on a *single* input image.

SWTImage.getLetter(key[, localize_by, display])

SWTImage.getWord(key[, localize_by, display])

SWTImage.letterIterator([localize_by, display])

SWTImage.localizeLetters([...])

SWTImage.localizeWords([localize_by, ...])

SWTImage.saveCrop(save_path[, crop_of, ...])

SWTImage.showImage([image_codes, ...])

Function to display a group of ImageCodes (maximum 4), explanation for those codes can be found in the table below : .. csv-table:: :header: Image Code, Explanation.

SWTImage.transformImage([text_mode, engine, ...])

Transform the input image into its Stroke Width Transform.

SWTImage.wordIterator([localize_by, display])

getLetter(key: int, localize_by: Optional[str] = 'min_bbox', display: Optional[bool] = True)[source]

Note

This function need to be run only after localizeLetters has been run.

Get a particular letter being housed in letters attribute

Parameters

  • key (int) – Letter key associated to letters attribute

  • localize_by (Optional[str]) – Which localization to apply [default = ‘min_bbox’] 1) min_bbox - Minimum Bounding Box (Rotating Bounding Box) 2) ext_bbox - External Bounding Box 3) outline - Contour

  • display (Optional[bool]) – If set to True this will display the following images [default = True] IMAGE_INDIVIDUAL_LETTER_LOCALIZATION = b’17’ -> Individual Letter Localized over Pruned RGB Image IMAGE_ORIGINAL_INDIVIDUAL_LETTER_LOCALIZATION = b’18’ -> Individual Letter Localized over Original Image

Returns

Individual Letter which was queried (np.ndarray) : Localization on Edge and SWT Image (np.ndarray) : Localization on Original Image

Return type

(Letter)

Raises

SWTImageProcessError, SWTValueError –

Example:

>>> # Localizing Letters
>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letter = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                              maximum_pixls_per_cc=5200,
>>>                                              localize_by='min_bbox', display=False)

>>> # Access all the letters which have been localized
>>> swtImgObj.letters
{1: Letter-1, 2: Letter-2, 3: Letter-3, 4: Letter-4 ...

>>> # Accessing an individual letter by its key in `swtImgObj.letters` dictionary
>>> _letter, _edgeswt_letter, _orig_image_letter = swtImgObj.getLetter(1, display=True)

>>> # Accessing `getLetter` for a `localize_by` which hasn't been run already by the
>>> # `localizeLetters` function will raise an error -> SWTImageProcessError will be raised
>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letters = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                               maximum_pixels_per_cc=5200,
>>>                                               localize_by='min_bbox', display=False)
>>> # Accessing `min_bbox` wont raise any error as that has been run already by the localizeLetters function
>>> _letter, _edgeswt_letter, _orig_image_letter = swtImgObj.getLetter(1, localize_by='min_bbox', display=True)
>>> # Accessing `ext_bbox` when `ext_bbox` hasn't been run already by the localizeLetters function
>>> _letter, _edgeswt_letter, _orig_image_letter = swtImgObj.getLetter(1, localize_by='ext_bbox', display=True)
SWTImageProcessError: 'SWTImage.localizeLetters' with localize_by='ext_bbox' should be run before this.
>>> # Solution : Run the `localizeLetters` function with `ext_bbox` and then access getLetter for `ext_bbox`
>>> localized_letters = swtImgObj.localizeLetters(localize_by='ext_bbox', display=False)
>>> _letter, _edgeswt_letter, _orig_image_letter = swtImgObj.getLetter(1, localize_by='min_bbox', display=True)
>>> _letter, _edgeswt_letter, _orig_image_letter = swtImgObj.getLetter(1, localize_by='ext_bbox', display=True)
getWord(key, localize_by: Optional[str] = 'bubble', display: Optional[bool] = True)[source]

Note

This function can run only after localizeWords has been run with parameter localize_type parameter.

Get a particular word being housed in words attribute

Parameters

  • key (int) – Word key associated to words attribute

  • localize_by (Optional[str]) – Which localization to apply 1) bubble - Bubble Boundary 2) bbox - Bounding Box 3) polygon - Contour Boundary

  • display (Optional[bool]) – If set to True, this will show [default = True] IMAGE_INDIVIDUAL_WORD_LOCALIZATION = b’19’ -> Individual word localized over Pruned RGB Image IMAGE_ORIGINAL_INDIVIDUAL_WORD_LOCALIZATION = b’20’ -> Individual word localized over Original Image

Returns

Individual Word which was queried (np.ndarray) : Localization on Edge and SWT Image (np.ndarray) : Localization on Original Image

Return type

(Word)

Raises

SWTImageProcessError, SWTValueError, SWTTypeError –

Example:

>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letter = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                              maximum_pixels_per_cc=5200,
>>>                                              localize_by='min_bbox', display=False)
>>> localized_words = swtImgObj.localizeWords(display=False)
>>> # Access all the words which have been localized
>>> swtImgObj.words
{0: Word-0, 1: Word-1, 2: Word-2, 3: Word-3, 4: Word-4, ...
>>> # Accessing an individual word by its key in `swtImgObj.words` dictionary
>>> _word, _edgeswt_word, _orig_image_word = swtImgObj.getWord(1, display=True)

>>> # Accessing `getWord` for a `localize_by` which hasn't been run already by the
>>> # `localizeLetters` function will raise an error -> SWTImageProcessError will be raised
>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letter = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                              maximum_pixels_per_cc=5200,
>>>                                              localize_by='min_bbox', display=False)
>>> localized_words = swtImgObj.localizeWords(display=False)
>>> # Accessing an individual word by its key in `swtImgObj.words` dictionary
>>> _word, _edgeswt_word, _orig_image_word = swtImgObj.getWord(1, localize_by='polygon', display=True)
SWTImageProcessError: 'SWTImage.localizeWords' with localize_by='polygon' should be run before this.

>>> # Solution:  Run the `localizeWords` function with localize_by=`polygon` and then access getWord for `polygon`
>>> localized_words = swtImgObj.localizeWords(localize_by='polygon', display=False)
>>> _word, _edgeswt_word, _orig_image_word = swtImgObj.getWord(4, localize_by='polygon', display=True)
letterIterator(localize_by: Optional[str] = 'min_bbox', display: Optional[bool] = True)[source]

Note

This function can run only after localizeLetters has been for the particular localize_type.

Generator to Iterate over all the letters in IPython/Jupyter interactive environment.

Args:
localize_by (Optional[str])Which localization to apply [defautl = ‘min_bbox’]

  1. min_bbox - Minimum Bounding Box (Rotating Bounding Box)

  2. ext_bbox - External Bounding Box

  3. outline - Contour

display (Optional[bool])If set to True this will display the following images [default = True]

IMAGE_INDIVIDUAL_LETTER_LOCALIZATION = b’17’ -> Individual Letter Localized over Pruned RGB Image IMAGE_ORIGINAL_INDIVIDUAL_LETTER_LOCALIZATION = b’18’ -> Individual Letter Localized over Original Image

Returns

Individual Letter which was queried (np.ndarray) : Localization on Edge and SWT Image (np.ndarray) : Localization on Original Image

Return type

(Letter)

Example:

>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letters = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                               maximum_pixels_per_cc=5200,
>>>                                               localize_by='min_bbox', display=False)
>>> # (A plot will be displayed as well at every `next` call to this generator since display=True)
>>> # Ensure the localize_by parameter has already been run in `localizeLetters` function.
>>> localized_letter_generator = swtImgObj.letterIterator(localize_by='min_bbox', display=False)
>>> _letter, _edgeswt_letter, _orig_image_letter = next(localized_letter_generator)
localizeLetters(minimum_pixels_per_cc: Optional[int] = 50, maximum_pixels_per_cc: Optional[int] = 10000, acceptable_aspect_ratio: Optional[float] = 0.2, localize_by: Optional[str] = 'min_bbox', padding_pct: Optional[float] = 0.01, display: Optional[bool] = True) → Dict[int, swtloc.abstractions.Letter][source]

Note

This function need to be run only after SWTImage.transformImage has been run.

After having found and pruned the individual connected components, this function add boundaries to the Letter’s so found in the SWTImage.transformImage.

Parameters

  • minimum_pixels_per_cc (Optional[int]) – Minimum pixels for each components to make it eligible for being a Letter. [default = 50]

  • maximum_pixels_per_cc (Optional[int]) – Maximum pixels for each components to make it eligible for being a Letter. [default = 10_000]

  • acceptable_aspect_ratio (Optional[float]) – Acceptable Aspect Ratio of each component to make it eligible for being a Letter. [default = 0.2]

  • localize_by (Optional[str]) – Which method to localize the letters from : [default = ‘min_bbox’] 1) min_bbox - Minimum Bounding Box (Rotating Bounding Box) 2) ext_bbox - External Bounding Box 3) outline - Contour

  • padding_pct (Optional[float]) – How much padding to apply to each localizations [default = 0.01]

  • display (Optional[bool]) – If set to True, this will display the following [default = True] IMAGE_PRUNED_3C_LETTER_LOCALIZATIONS = b’11’ -> Localization on Pruned RGB channel image IMAGE_ORIGINAL_LETTER_LOCALIZATIONS = b’12’ -> Localization on Original image IMAGE_ORIGINAL_MASKED_LETTER_LOCALIZATIONS = b’13’ -> Localization masked on original image

Returns

A dictionary with keys as letter labels and values as Letter class objects

Return type

Dict[int, Letter]

Raises

SWTImageProcessError, SWTValueError, SWTTypeError –

Example:

>>> # Localizing Letters
>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> # (A plot will be displayed as well)
>>>  localized_letters = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                                maximum_pixels_per_cc=5200,
>>>                                                localize_by='min_bbox')

>>> # Running `localizeLetters` before having run `transformImage` -> Raises SWTImageProcessError
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> localized_letters = swtImgObj.localizeLetters(localize_by='min_bbox')
SWTImageProcessError: `SWTImage.transformImage` must be called before this function
localizeWords(localize_by: Optional[str] = 'bubble', lookup_radius_multiplier: Optional[float] = 1.1, acceptable_stroke_width_ratio: Optional[float] = 2.0, acceptable_color_deviation: Optional[List] = [13, 13, 13], acceptable_height_ratio: Optional[float] = 1.5, acceptable_angle_deviation: Optional[float] = 30.0, polygon_dilate_iterations: Optional[int] = 5, polygon_dilate_kernel: Optional[int] = (5, 5), display: Optional[bool] = True) → Dict[int, swtloc.abstractions.Word][source]

Note

This function can run only after localizeLetters has been for the particular localize_type=”min_bbox”.

Once the letters attribute has been populated with the pruned connected components, these components can be fused together into Word’s. This fusion process is taken care of by the Fusion class which groups a Letter with another based on comparisons such as :

  • Ratio between two individual Letter’s

  • Ratio between two individual Letter’s heights

  • Difference between two individual Letter’s minimum bounding box rotation angle

  • Difference between two individual Letter’s color vectors

Letter’s which come under consideration of being grouped for a particular Letter, will be in the close proximity of the Letter, which is gauged by components minimum bouncing box circum circle.

Dilation is performed before finding the localization for a word when localize_by parameter is “polygon”, so as to merge the nearby bounding box.

Parameters

  • localize_by (Optional[str]) – One of the three localizations can be performed : [default = ‘bubble’] - ‘bubble’ : Bubble Boundary - ‘bbox’ : Bounding Box - ‘polygon’ : Contour Boundary

  • lookup_radius_multiplier (Optional[float]) – Circum Radius multiplier, to inflate the lookup range. [default = 1.1]

  • acceptable_stroke_width_ratio (Optional[float]) – Acceptable stroke width ratio between two Letter’s to make them eligible to be a part of a word. [default = 2.0]

  • acceptable_color_deviation (Optional[List]) – Acceptable color deviation between two Letter’s to make them eligible to be a part of a word.. [default = [13, 13, 13]]

  • acceptable_height_ratio (Optional[float]) – Acceptable height ratio between two Letter’s to make them eligible to be a part of a word.. [default = 1.5]

  • acceptable_angle_deviation (Optional[float]) – Acceptable angle deviation between two Letter’s to make them eligible to be a part of a word.. [default = 30.0]

  • polygon_dilate_iterations (Optional[int]) – Only required when localize_by = ‘polygon’. Number of iterations to be performed before finding contour. [default = 5]

  • polygon_dilate_kernel (Optional[int]) – Only required when localize_by = ‘polygon’, dilation kernel. [default = (5,5)]

  • display (Optional[bool]) – If set tot True, this function will display . [default = ‘bubble’] IMAGE_PRUNED_3C_WORD_LOCALIZATIONS = b’14’ -> Pruned RGB Image with Word Localizations IMAGE_ORIGINAL_WORD_LOCALIZATIONS = b’15’ -> Original Image with Word Localizations IMAGE_ORIGINAL_MASKED_WORD_LOCALIZATIONS = b’16’ -> Original Image mask with Word Localizations

Returns

A dictionary with keys as word labels and values as Word class objects

Return type

Dict[int, Word]

Raises

SWTImageProcessError, SWTValueError, SWTTypeError –

Example:

>>> # To Localize Words, after having localized Letters
>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letter = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                              maximum_pixels_per_cc=5200,
>>>                                              localize_by='min_bbox', display=False)
>>> # (A plot will be displayed as well)
>>> localized_words = swtImgObj.localizeWords()

>>> # If `localizeWords` is run before having run `localizeLetters`, it will
>>> # raise an error -> SWTImageProcessError will be raised
>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_words = swtImgObj.localizeWords()
SWTImageProcessError: `SWTImage.localizeLetters` with localize_by='min_bbox' must be called before this function

>>> # Before running `localizeWords` its required that `localizeLetters` has been
>>> # run with localize_by='min_bbox' parameter. Otherwise SWTImageProcessError is raised
>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letter = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                              maximum_pixels_per_cc=5200,
>>>                                              localize_by='ext_bbox', display=False)
>>> localized_words = swtImgObj.localizeWords()
SWTImageProcessError: `SWTImage.localizeLetters` with localize_by='min_bbox' must be called before this function
saveCrop(save_path: str, crop_of: Optional[str] = 'words', crop_key: Optional[int] = 0, crop_on: Optional[ByteString] = b'01', crop_type: Optional[str] = 'bubble', padding_pct: Optional[float] = 0.05)[source]

Note

  • To see the full list of ImageCodes (value for crop_on) available and their meaning , look at the

showImage function documentation

  • For crop_of = ‘words’, ensure localizeWords function has been run prior to this with the same localize_type as crop_type

  • For crop_of = ‘letters’, ensure localizeLetters function has been run prior to this with the same localize_type as crop_type

Parameters

  • save_path (str) – The directory to save the image at

  • crop_of (Optional[str]) – Generate the crop of ‘letters’ or ‘words’. [default = ‘words’]

  • crop_key (Optional[int]) – Which key to query from letters (if crop_of=’letters’) or words (if crop_of = ‘words’).[default = 0]

  • crop_on (Optional[ByteString]) – [default = IMAGE_ORIGINAL]

  • crop_type (Optional[str]) –

    Which localization to crop with. [default = ‘bubble’] For crop_of = ‘words’, available options are :

    • bubble

    • bbox

    • polygon

    For crop_of = ‘letters’,available options are

    • min_bbox

    • ext_bbox

    • outline

  • padding_pct (Optional[float]) – Padding applied to each localization [default = 0.05]

Raises

SWTValueError, SWTImageProcessError, SWTTypeError –

Example:

>>> from swtloc import SWTLocalizer
>>> from swtloc.configs import IMAGE_PRUNED_3C_WORD_LOCALIZATIONS
>>> from swtloc.configs import IMAGE_PRUNED_3C_LETTER_LOCALIZATIONS
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letter = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                              maximum_pixels_per_cc=5200,
>>>                                              display=False)
>>> localized_words = swtImgObj.localizeWords(display=False)
>>> # To generate and save the crops of `letters`
>>> swtImgObj.saveCrop(save_path='../', crop_of='letters', crop_key=3, crop_on=IMAGE_PRUNED_3C_LETTER_LOCALIZATIONS,
>>>                    crop_type='outline', padding_pct=0.01)
>>> # To generate and save the crops of `words`
>>> swtImgObj.saveCrop(save_path='../', crop_of='words', crop_key=8, crop_on=IMAGE_PRUNED_3C_WORD_LOCALIZATIONS,
>>>                    crop_type='bubble', padding_pct=0.01)


>>> # An error will be raised if `.saveCrops` functions is called for `crop_of='letters'`
>>> # even before `.localizeLetters` for localize_by = crop_type hasn't been called before
>>> # -> SWTImageProcessError will be raised
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> swtImgObj.saveCrop(save_path='../', crop_of='letters', crop_key=3, crop_on=IMAGE_PRUNED_3C_LETTER_LOCALIZATIONS,
>>>                    crop_type='outline', padding_pct=0.01)
Call .localizeLetters method for this Image Code to be populated
SWTImageProcessError: None of the [b'11'] are available!

>>> # An error will be raised if `.saveCrops` functions is called for `crop_of='words'`
>>> # even before `.localizeWords` for localize_by = crop_type hasn't been called before
>>> # -> SWTImageProcessError will be raised
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letter = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                              maximum_pixels_per_cc=5200,
>>>                                              display=False)
>>> swtImgObj.saveCrop(save_path='../', crop_of='words', crop_key=8, crop_on=IMAGE_PRUNED_3C_WORD_LOCALIZATIONS,
>>>                    crop_type='bubble', padding_pct=0.01)
Call .localizeWords method for this Image Code to be populated
SWTImageProcessError: None of the [b'14'] are available!
showImage(image_codes: Optional[List[ByteString]] = None, plot_title: Optional[str] = 'SWTImage Plot', plot_sup_title: Optional[str] = '', save_dir: Optional[str] = '', save_fig: Optional[bool] = False, dpi: Optional[int] = 200)[source]

Function to display a group of ImageCodes (maximum 4), explanation for those codes can be found in the table below : .. csv-table:

:header: Image Code, Explanation

IMAGE_ORIGINAL,  "Original Image"
IMAGE_GRAYSCALE, "Gray-Scaled Image"
IMAGE_EDGED, "Edge Image"
IMAGE_SWT_TRANSFORMED, "SWT Transformed Image"
IMAGE_CONNECTED_COMPONENTS_1C, "Connected Components Single Channel"
IMAGE_CONNECTED_COMPONENTS_3C, "Connected Components RGB Channel"
IMAGE_CONNECTED_COMPONENTS_3C_WITH_PRUNED_ELEMENTS, "Connected Components Regions which were pruned (in red)"
IMAGE_CONNECTED_COMPONENTS_PRUNED_1C, "Pruned Connected Components Single Channel"
IMAGE_CONNECTED_COMPONENTS_PRUNED_3C, "Pruned Connected Components RGB Channel"
IMAGE_CONNECTED_COMPONENTS_OUTLINE, "Connected Components Outline"
IMAGE_PRUNED_3C_LETTER_LOCALIZATIONS, "Pruned RGB Channel SWT Image With Letter Localizations"
IMAGE_ORIGINAL_LETTER_LOCALIZATIONS, "Original Image With Letter Localizations"
IMAGE_ORIGINAL_MASKED_LETTER_LOCALIZATIONS, "Original Image With Masked Letter Localizations"
IMAGE_PRUNED_3C_WORD_LOCALIZATIONS, "Pruned RGB Channel SWT Image With Words Localizations"
IMAGE_ORIGINAL_WORD_LOCALIZATIONS, "Original Image With Words Localizations"
IMAGE_ORIGINAL_MASKED_WORD_LOCALIZATIONS, "Original Image With Masked Words Localizations"
IMAGE_INDIVIDUAL_LETTER_LOCALIZATION, "Individual Letter With Localizations Over Edged + SWT"
IMAGE_ORIGINAL_INDIVIDUAL_LETTER_LOCALIZATION, "Individual Letter With Localizations Over Original"
IMAGE_INDIVIDUAL_WORD_LOCALIZATION, "Individual Word With Localizations Over Edged + SWT"
IMAGE_ORIGINAL_INDIVIDUAL_WORD_LOCALIZATION, "Individual Word With Localizations Over Original"
Parameters

  • image_codes (Optional[List[ByteString]]) – List of image codes to display. [default = IMAGE_ORIGINAL]

  • plot_title (Optional[str]) – Title of the plot

  • plot_sup_title (Optional[str]) – Sub title of the plot

  • save_dir (Optional[str]) – Directory in which to save the prepared plot

  • save_fig (Optional[bool]) – Whether to save the prepared plot or not

  • dpi (Optional[int]) – DPI of the figure to be saved

Raises

SWTValueError, SWTTypeError –

Returns

Returns the location where the image was saved if save_dir=True and save_path is given.

Return type

(str)

Example:

>>> from swtloc import SWTLocalizer
>>> from swtloc.configs import IMAGE_ORIGINAL
>>> from swtloc.configs import IMAGE_SWT_TRANSFORMED
>>> from swtloc.configs import IMAGE_PRUNED_3C_LETTER_LOCALIZATIONS

>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letter = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                              maximum_pixels_per_cc=5200,
>>>                                              display=False)
>>> swtImgObj.showImage(image_codes=[IMAGE_ORIGINAL,
>>>                                  IMAGE_SWT_TRANSFORMED,
>>>                                  IMAGE_PRUNED_3C_LETTER_LOCALIZATIONS],
>>>                     plot_title="Process Flow",
>>>                     plot_sup_title="Original -> SWT -> Pruned Letters")

>>> # (A plot will be displayed as well) + Save the prepared plot
>>> localized_letter = swtImgObj.localizeLetters(display=False)
>>> swtImgObj.showImage(image_codes=[IMAGE_ORIGINAL,
>>>                                  IMAGE_SWT_TRANSFORMED,
>>>                                  IMAGE_PRUNED_3C_LETTER_LOCALIZATIONS],
>>>                     plot_title="Process Flow",
>>>                     plot_sup_title="Original -> SWT -> Pruned Letters",
>>>                     save_dir='../', save_fig=True, dpi=130)
transformImage(text_mode: Optional[str] = 'lb_df', engine: Optional[str] = 'numba', gaussian_blurr: Optional[bool] = True, gaussian_blurr_kernel: Optional[Tuple] = (5, 5), edge_function: Optional[Union[str, Callable]] = 'ac', auto_canny_sigma: Optional[float] = 0.33, minimum_stroke_width: Optional[int] = 3, maximum_stroke_width: Optional[int] = 200, check_angle_deviation: Optional[bool] = True, maximum_angle_deviation: Optional[float] = 0.5235987755982988, include_edges_in_swt: Optional[bool] = True, display: Optional[bool] = True) → numpy.ndarray[source]

Transform the input image into its Stroke Width Transform. The entire transformation follows the following flow

  • Step-1 : Convert To Gray-Scale

  • Step-2 : Apply Gaussian Blurr

  • Step-3 : Find Edge of the Image

  • Step-4 : Calculate the Image Gradient Theta Angle

  • Step-5 : Calculate the Step Matrices

  • Step-6 : Apply Stroke Width Transformation

This function also stores the time taken to complete all the above mentioned stages in the class attribute transform_time

Parameters

  • text_mode (Optional[str]) –

    Contrast of the text present in the image, which needs to be transformed. Two possible values :

    1. ”db_lf” :> Dark Background Light Foreground i.e Light color text on Dark color background

    2. ”lb_df” :> Light Background Dark Foreground i.e Dark color text on Light color background

    This parameters affect how the gradient vectors (the direction) are calculated, since gradient vectors of db_lf are in −𝑣𝑒 direction to that of lb_df gradient vectors. [default = ‘lb_df’]

  • engine (Optional[str]) – Which engine to use for applying the Stroke Width Transform. [default = ‘numba’] 1) “python” : Use Python for running the findStrokes function 2) “numba” : Use numba for running the findStrokes function

  • gaussian_blurr (Optional[bool]) – Whether to apply gaussian blurr or not. [default = True]

  • gaussian_blurr_kernel (Optional[Tuple]) – Kernel to use for gaussian blurr. [default = (5, 5)]

  • edge_function (Optional[str, Callable]) –

    Finding the Edge of the image is a tricky part, this is pertaining to the fact that in most of the cases the images we deal with are not of standard that applying just a opencv Canny operator would result in the desired Edge Image. Sometimes (In most cases) there is some custom processing required before edging, for that reason alone this parameter accepts one of the following two values :-

    1.) ‘ac’ :> Auto-Canny function, an in-built function which will

    generate the Canny Image from the original image, internally calculating the threshold parameters, although, to tune it even further ‘ac_sigma : float, default(0.33)’ parameter is provided which can take any value between 0.0 <–> 1.0.

    2.) A custom function : This function should have its signature as mentioned below :

    >>> def custom_edge_func(gray_image):
>>>     # Your Function Logic...
>>>     edge_image =
>>>     return edge_image

  • auto_canny_sigma – (Optional[float]) : Value of the sigma to be used in the edging function, if edge_function parameter is given the value “ac”. [default = 0.33]

  • minimum_stroke_width (Optional[int]) – Maximum permissible stroke width. [default = 0.33]

  • maximum_stroke_width (Optional[int]) – Minimum permissible stroke width. [default = 0.33]

  • check_angle_deviation (Optional[bool]) – Whether to check the angle deviation to terminate the ray. [default = 0.33]

  • maximum_angle_deviation (Optional[float]) – Maximum Angle Deviation which would be permissible. [default = 0.33]

  • include_edges_in_swt (Optional[bool]) – Whether to include edges (those edges, from which no stroke was able to be determined) in the final swt transform

  • display (Optional[bool]) –

    If set to True, the images corresponding to following image codes will be displayed . [default = True]

    IMAGE_ORIGINAL = b’01’ -> Original Image IMAGE_GRAYSCALE = b’02’ -> Gray Sclaed Image IMAGE_EDGED = b’03’ -> Edged Image IMAGE_SWT_TRANSFORMED = b’04’ -> SWT Transformed image converted to three channels .. note :

    IMAGE_SWT_TRANSFORMED is not the same as the image array returned from this function.

Returns

Stroke Width Transform of the image.

Return type

(np.ndarray)

Raises

SWTValueError, SWTTypeError –

Example:

>>> # Transform the image using the default engine [default : engine='numba']
>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=True)
>>> # (A plot will be displayed as well)
>>> print('Time Taken', swtImgObj.transform_time)
Time Taken 0.193 sec

>>> # Python engine been used for `transformImage` for engine = 'python'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, engine='python')
>>> # (A plot will be displayed as well)
>>> print('Time Taken', swtImgObj.transform_time)
Time Taken 3.822 sec

>>> # Wrong Input given -> SWTValueError/SWTTypeError will be raised
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='asc', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5.1, maximum_stroke_width=50)
SWTTypeError: `minimum_stroke_width` value should be one of these types : [<class 'int'>]. Not mixed either.

>>># Custom edge function been given to the `transformImage`
>>> def custom_edge_func(gray_image):
>>>     gauss_image = cv2.GaussianBlur(gray_image, (5,5), 1)
>>>     laplacian_conv = cv2.Laplacian(gauss_image, -1, (5,5))
>>>     canny_edge = cv2.Canny(laplacian_conv, 20, 90)
>>>     return canny_edge
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function=custom_edge_func, gaussian_blurr_kernel=(3,3),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50)
wordIterator(localize_by: Optional[str] = 'bubble', display: Optional[bool] = True)[source]

Note

This function can run only after localizeWords has been run with parameter localize_type parameter.

Get a particular word being housed in words attribute

Parameters

  • localize_by (Optional[str]) – Which localization to apply - bubble - Bubble Boundary - bbox - Bounding Box - polygon - Contour Boundary

  • display (Optional[bool]) – If set to True, this will show [default = True] IMAGE_INDIVIDUAL_WORD_LOCALIZATION = b’19’ -> Individual word localized over Pruned RGB Image IMAGE_ORIGINAL_INDIVIDUAL_WORD_LOCALIZATION = b’20’ -> Individual word localized over Original Image

Returns

Individual Word which was queried (np.ndarray) : Localization on Edge and SWT Image (np.ndarray) : Localization on Original Image

Return type

(Word)

Raises

SWTImageProcessError, SWTValueError, SWTTypeError –

Example:

>>> from swtloc import SWTLocalizer
>>> root_path = 'examples/images/'
>>> swtl = SWTLocalizer(image_paths=root_path+'test_image_1/test_img1.jpg')
>>> swtImgObj = swtl.swtimages[0]
>>> swt_image = swtImgObj.transformImage(text_mode='db_lf', maximum_angle_deviation=np.pi/2,
>>>                                      edge_function='ac', gaussian_blurr_kernel=(11, 11),
>>>                                      minimum_stroke_width=5, maximum_stroke_width=50, display=False)
>>> localized_letter = swtImgObj.localizeLetters(minimum_pixels_per_cc=950,
>>>                                              maximum_pixels_per_cc=5200,
>>>                                              localize_by='min_bbox', display=False)
>>> localized_words = swtImgObj.localizeWords(localize_by='polygon', display=False, polygon_dilate_iterations=3)
>>> # Creating a generator for a specific localize_by
>>> word_iterator = swtImgObj.wordIterator(localize_by='polygon', display=True)

>>> _word, _edgeswt_word, _orig_image_word = next(word_iterator)