keygim 1.0.0

A library used to download images from Google.

keygim Package Documentation

---

This library provides various image utilities and a function to download images from Google search.

There are two modules in this package.

1. keygim - used to download Google images
2. imageUtils - image and basic utilities

To install this package, type in command prompt:

pip install keygim

---

[1] Keywind Google Images

(1-A) LinkFormatter - Obtaining the Google Search URLs for each search string:

LinkFormatter(stringList)

argument	optional	default	available
stringList	no		[ list-string type ]

self.fetch_links(self, large = False)

argument	optional	default	available
large	yes	False	True, False

(1-A-1) Example of using LinkFormatter

from keygim.keygim import KeyGoogleImages
LinkFormatter = KeyGoogleImages.LinkFormatter
search_strings = [ "landscape", "galaxies" ]
large = False
link_list = LinkFormatter(search_strings).fetch_links(large = large)
print(link_list[0]) # "https://www.google.com/search?q=landscape&tbm=isch"
print(link_list[1]) # "https://www.google.com/search?q=galaxies&tbm=isch"

(1-B) GoogleImageDownloader - Downloading Google images provided a list of strings:

GoogleImageDownloader(search_strings, mode = 0, driver_path = None)

argument	optional	default	available
search_strings	no		[ list-string type ]
mode	yes	GoogleImageDownloader.MODE_CHROME	GoogleImageDownloader.MODE_CHROME, GoogleImageDownloader.MODE_FIREFOX
driver_path	yes	None	None, [ string type ]

self.configure(**kwargs)

argument	optional	default	available
folder_name	yes	None	None, [ string type ]
hide_window	yes	False	True, False
wait_load	yes	True	True, False
search_large	yes	False	True, False
save_search	yes	False	True, False
item_wait	yes	1	[ integer/float (>=0) type ]
images_per_page	yes	10	[ integer (>0) type ]
verbose	yes	True	True, False
url_timeout	yes	60	[ integer/float (>0) type ]
load_timeout	yes	30	[ integer/float (>0) type ]

If a folder name is provided, all images will be stored in that folder after download. Should the folder not already exist, that folder will be created. By default, each search string will be the name of the folder storing the corresponding images.

To scrape and download images in the background, set hide_window to True.

To search images in large mode, set search_large to True.

To wait between consecutive images, pass a number to item_wait so that two images will be separated by time_wait seconds.

To specify the number of images per search string, pass an integer to the argument images_per_page.

To hide the progress bar, set verbose to False.

To specify the maximum number of seconds to connect to the direct link, pass a number to url_timeout.

To specify the maximum number of seconds to download an image, pass a number to load_timeout.

self.download()

Calling this function will initiate the downloading process.

self.cleanup()

Calling this function after finished downloading to remove corrupted image files in the folder.

(1-B-1) Example of using GoogleImageDownloader

from keygim.keygim import KeyGoogleImages
GoogleImageDownloader = KeyGoogleImages.GoogleImageDownloader
search_strings = [ "scenery", "galaxies" ]
large = True
mode = GoogleImageDownloader.MODE_CHROME
driver_path = "./chromedriver.exe"
folder_name = "./KGM_DEMO/"
downloader = GoogleImageDownloader(search_strings, mode, driver_path)
downloader.configure(
  folder_name = folder_name,
  search_large = large
)
downloader.download()
downloader.cleanup()

---

[2] Image Utilities

(2-A) ImageLoader - Loading images from disk:

ImageLoader(filename, mode = ImageLoader.COLOR_BGR_3D)

argument	optional	default	available
filename	no		[ string type ]
mode	yes	ImageLoader.COLOR_BGR_3D	ImageLoader.COLOR_GRAY_2D, ImageLoader.COLOR_GRAY_3D, ImageLoader.COLOR_BGR_3D, ImageLoader.COLOR_BGRA_3D, ImageLoader.COLOR_RGB_3D, ImageLoader.COLOR_RGBA_3D

self.load()

ImageLoader.load_images(nameList, mode = ImageLoader.COLOR_BGR_3D)

argument	optional	default	available
nameList	no		[ list-string type ]
mode	yes	ImageLoader.COLOR_BGR_3D	ImageLoader.COLOR_GRAY_2D, ImageLoader.COLOR_GRAY_3D, ImageLoader.COLOR_BGR_3D, ImageLoader.COLOR_BGRA_3D, ImageLoader.COLOR_RGB_3D, ImageLoader.COLOR_RGBA_3D

ImageLoader.load_images_from_folder(folderName, quantity = "all", shuffle = False)

argument	optional	default	available
folderName	no		[ string type ]
quantity	yes	"all"	"all", [ integer (>0) type ]
shuffle	yes	False	True, False

(2-B) ImageSaver - Saving images to disk:

ImageSaver(filename, mode = ImageLoader.COLOR_BGR_3D)

argument	optional	default	available
filename	no		[ string type ]
mode	yes	ImageSaver.COLOR_BGR_3D	ImageSaver.COLOR_GRAY_2D, ImageSaver.COLOR_GRAY_3D, ImageSaver.COLOR_BGR_3D, ImageSaver.COLOR_BGRA_3D, ImageSaver.COLOR_RGB_3D, ImageSaver.COLOR_RGBA_3D

self.save_image(image, overwrite = True)

argument	optional	default	available
image	no		[ numpy-uint8 type ]
overwrite	yes	True	True, False

self.save_images(imageList, overwrite = True)

argument	optional	default	available
imageList	no		[ list-numpy-uint8 type ], [ numpy-uint8 type ]
overwrite	yes	True	True, False

(2-C) ImageDisplayer - Displaying images in a window:

ImageDisplayer(image, windowName = "Image Preview")

argument	optional	default	available
image	no		[ numpy-uint8 type ]
windowName	yes	"Image Preview"	[ string type ]

self.start()

self.stop()

self.display_for(interval = 5)

argument	optional	default	available
interval	yes	5	[ integer/float (>0) type ]

ImageDisplayer.display_multiple_for(imageList, windowName = "Image Preview", interval = 1)

argument	optional	default	available
imageList	no		[ list-numpy-uint8 type ], [ numpy-uint8 type ]
windowName	yes	"Image Preview"	[ string type ]
interval	yes	1	[ integer/float (>0) type ]

(2-D) SnapshotTaker - Taking a screenshot:

SnapshotTaker(mode = SnapshotTaker.COLOR_BGR_3D)

argument	optional	default	available
mode	yes	SnapshotTaker.COLOR_BGR_3D	SnapshotTaker.COLOR_GRAY_2D, SnapshotTaker.COLOR_GRAY_3D, SnapshotTaker.COLOR_BGR_3D, SnapshotTaker.COLOR_BGRA_3D, SnapshotTaker.COLOR_RGB_3D, SnapshotTaker.COLOR_RGBA_3D

self.take_screenshot(key = None, message = None)

argument	optional	default	available
key	yes	None	None, [ pynput-key type ]
message	yes	None	None, [ string type ]

self.take_screenshots(key = None, quantity = 1, message = None)

argument	optional	default	available
key	yes	None	None, [ pynput-key type ]
quantity	yes	1	[ integer (>0) type ]
message	yes	None	None, [ string type ]

(2-D-1) Example of using SnapshotTaker & ImageDisplayer

from keygim.imageUtils import ImageUtils
from pynput.keyboard import Key
SnapshotTaker = ImageUtils.SnapshotTaker
ImageDisplayer = ImageUtils.ImageDisplayer
key = Key.esc
message = "Press Esc to take screenshot."
mode = SnapshotTaker.COLOR_BGR_3D
image = SnapshotTaker(mode = mode).take_screenshot(
  key = key, message = message
)
ImageDisplayer(image).display_for(interval = 3)

(2-E) BoundaryBoxSelector - Selecting boundary box from background image:

BoundaryBoxSelector(image, windowName = "Boundary Box Selector", boxColor = (255, 0, 0), boxWidth = 5)

argument	optional	default	available
image	no		[ numpy-uint8 type ]
windowName	yes	"Boundary Box Selector"	[ string type ]
boxColor	yes	(255, 0, 0)	[ tuple-BGR type ]
boxWidth	yes	5	[ integer (>0) type ]

self.draw()

self.draw_multiple(quantity = 1)

argument	optional	default	available
quantity	yes	1	[ integer (>0) type]

self.place(width, height)

argument	optional	default	available
width	no		[ integer (>0) type ]
height	no		[ integer (>0) type]

self.place_multiple(width, height, quantity = 1)

argument	optional	default	available
width	no		[ integer (>0) type ]
height	no		[ integer (>0) type ]
quantity	yes	1	[ integer (>0) type ]

BoundaryBoxSelector.crop_partial(image, bbox)

argument	optional	default	available
image	no		[ numpy-uint8 type ]
bbox	no		[ BoundaryBoxSelector.BoundaryBox type ]

BoundaryBoxSelector.crop_multiple(image, bboxes)

argument	optional	default	available
image	no		[ numpy-uint8 type ]
bboxes	no		[ list-BoundaryBoxSelector.BoundaryBox type ]

(2-E-1) Example of using SnapshotTaker & BoundaryBoxSelector & ImageDisplayer

from keygim.imageUtils import ImageUtils
from pynput.keyboard import Key
ImageDisplayer = ImageUtils.ImageDisplayer
BoundaryBoxSelector = ImageUtils.BoundaryBoxSelector
SnapshotTaker = ImageUtils.SnapshotTaker
key = Key.esc
message = "Press Esc to take screenshot."
image = SnapshotTaker().take_screenshot(key, message)
bbox = BoundaryBoxSelector(image).draw()
image = BoundaryBoxSelector.crop_partial(image, bbox)
ImageDisplayer(image).display_for(interval = 4)

(2-E-A) BoundaryBoxSelector.BoundaryBox - Creating a boundary box object:

BoundaryBoxSelector.BoundaryBox(SX, SY, EX, EY)

argument	optional	default	available
SX	no		[ integer (>=0) type ]
SY	no		[ integer (>=0) type ]
EX	no		[ integer (>=0) type ]
EY	no		[ integer (>=0) type ]

self.__getitem__(key)

argument	optional	default	available
key	no		"sx", "sy", "ex", "ey", "dx", "dy", "cx", "cy", "tuple"

self.sort()

(2-F) ImageRandomCropper - Cropping a random region from an image:

ImageRandomCropper(image)

argument	optional	default	available
image	no		[ numpy-uint8 type ]

self.crop(width, height, overflow = True)

argument	optional	default	available
width	no		[ integer (>0) type ]
height	no		[ integer (>0) type ]
overflow	yes	True	True, False

self.crop_multiple(width, height, quantity = 1, overflow = True)

argument	optional	default	available
width	no		[ integer (>0) type ]
height	no		[ integer (>0) type ]
quantity	yes	1	[ integer (>0) type ]
overflow	yes	True	True, False

(2-G) ImageOverLayer - Adding a background to a 4-channel image:

ImageOverLayer(image)

argument	optional	default	available
image	no		[ numpy-uint8 (4 channels) type ]

self.overlay(background)

argument	optional	default	available
background	no		[ numpy-uint8 (>=3 channels) type ]

self.overlay_multiple(backgroundList)

argument	optional	default	available
backgroundList	no		[ list-numpy-uint8 type ], [ numpy-uint8 type ]

(2-H) convert_color - Color conversion for multiple images:

convert_color(imageList, color_code)

argument	optional	default	available
imageList	no		[ list-numpy-uint8 type ], [ numpy-uint8 type ]
color_code	no		[ cv2-cvtColor type ]

(2-I) ScreenshotCropperSaver - Taking a screenshot, cropping it and saving the image:

ScreenshotCropperSaver(filename = "temp.png", draw = True, save = True)

argument	optional	default	available
filename	yes	"temp.png"	[ string type ]
draw	yes	True	True, False
save	yes	True	True, False

self.start(key = None, message = None, overwrite = True, quantity = 1)

argument	optional	default	available
key	yes	None	None, [ pynput-key type ]
message	yes	None	None, [ string type ]
overwrite	yes	True	True, False
quantity	yes	1	[ integer (>0) type ]

(2-J) ImageResizer - Resizing an image while keeping its aspect ratio:

ImageResizer(image)

argument	optional	default	available
image	no		[ numpy-uint8 type ]

self.resize(width, height)

argument	optional	default	available
width	no		[ integer (>0) type ]
height	no		[ integer (>0) type ]

ImageResizer.resize_multiple(imageList, width, height)

argument	optional	default	available
imageList	no		[ numpy-uint8 type ], [ list-numpy-uint8 type ]
width	no		[ integer (>0) type ]
height	no		[ integer (>0) type ]

(2-K) ImageCorruptDisposer - Disposing corrupt images in a folder:

ImageCorruptDisposer(folderName)

argument	optional	default	available
folderName	no		[ string type ]

self.parse(return_quantity = False)

argument	optional	default	available
return_quantity	yes	False	True, False

self.dispose(extensions = "all")

argument	optional	default	available
extensions	yes	"all"	"all", [ list-string type ]

(2-L) PlainImageGenerator - Generating a uni-colored image:

PlainImageGenerator(width, height, channels)

argument	optional	default	available
width	no		[ integer (>0) type ]
height	no		[ integer (>0) type ]
channels	no		[ integer (>0) type ]

self.generate(quantity = 1)

argument	optional	default	available
quantity	yes	1	[ integer (>0) type ]

(2-L-1) Example of PlainImageGenerator & ImageDisplayer

from keygim.imageUtils import ImageUtils, ImageAugmentor
PlainImageGenerator = ImageAugmentor.PlainImageGenerator
ImageDisplayer = ImageUtils.ImageDisplayer
width, height, channels = 250, 400, 3
image = PlainImageGenerator(width, height, channels).generate()
ImageDisplayer(image).display_for(interval = 4)

(2-M) NoiseImageGenerator - Generating a static/noise image:

NoiseImageGenerator(width, height, channels)

argument	optional	default	available
width	no		[ integer (>0) type ]
height	no		[ integer (>0) type ]
channels	no		[ integer (>0) type ]

self.generate(quantity = 1)

argument	optional	default	available
quantity	yes	1	[ integer (>0) type ]

(2-M-1) Example of NoiseImageGenerator & ImageDisplayer

from keygim.imageUtils import ImageUtils, ImageAugmentor
NoiseImageGenerator = ImageAugmentor.NoiseImageGenerator
ImageDisplayer = ImageUtils.ImageDisplayer
width, height, channels = 250, 400, 3
image = NoiseImageGenerator(width, height, channels).generate()
ImageDisplayer(image).display_for(interval = 4)

(2-N) MapGenerator - Generating a map image from two images:

MapGenerator(image1, image2)

argument	optional	default	available
image1	no		[ numpy-uint8 type ]
image2	no		[ numpy-uint8 type ]

self.get()

(2-O) PositionShifter - Shifting an image to the side:

PositionShifter(image, safeMode = True)

argument	optional	default	available
image	no		[ numpy-uint8 type ]
safeMode	yes	True	True, False

self.shift(width_offset_range, height_offset_range, quantity = 1, rate = 1)

argument	optional	default	available
width_offset_range	no		[ tuple-integer type ]
height_offset_range	no		[ tuple-integer type ]
quantity	yes	1	[ integer (>0) type ]
rate	yes	1	[ integer/float [0, 1] type ]

(2-P) BrightnessShifter - Changing an image's brightness level:

BrightnessShifter(image, safeMode = True)

argument	optional	default	available
image	no		[ numpy-uint8 type ]
safeMode	yes	True	True, False

self.shift(brightness_shift_range, quantity = 1, rate = 1)

argument	optional	default	available
brightness_shift_range	no		[ tuple-float [0, 1] type ]
quantity	yes	1	[ integer (>0) type ]
rate	yes	1	[ integer/float [0, 1] type ]

(2-Q) ImageZoomer - Zooming in and out from an image:

ImageZoomer(image, safeMode = True)

argument	optional	default	available
image	no		[ numpy-uint8 type ]
safeMode	yes	True	True, False

self.zoom(zoom_value)

argument	optional	default	available
zoom_value	no		[ integer/float (>0) type ]

self.random_zoom(zoom_range, quantity = 1, rate = 1)

argument	optional	default	available
zoom_range	no		[ tuple-float (>0) type ]
quantity	yes	1	[ integer (>0) type ]
rate	yes	1	[ integer/float [0, 1] type ]

(2-R) ImageGenerator - Generating training data to recognize a pattern:

ImageGenerator(image1, image2)

argument	optional	default	available
image1	no		[ numpy-uint8 type ]
image2	no		[ numpy-uint8 type ]

self.configure(verbose = True, **kwargs)

argument	optional	default	available
verbose	yes	True	True, False
position_shift_range	yes	((-1, 1), (-1, 1))	[ tuple-tuple-integer type ]
zoom_range	yes	(1.0, 1.0)	[ tuple-integer/float (>0) type ]
brightness_range	yes	(1.0, 1.0)	[ tuple-integer/float [0, 1] type ]
position_shift_rate	yes	1	[ integer/float (>=0) type ]
brightness_rate	yes	1	[ integer/float (>=0) type ]
zoom_rate	yes	1	[ integer/float (>=0) type ]
plain_quantity	yes	1	[ integer (>=0) type ]
noise_quantity	yes	0	[ integer (>=0) type ]
background_quantity	yes	1	[ integer (>=0) type ]
region_quantity	yes	0	[ integer (>=0) type ]
background_folder	yes	None	None, [ string type ]

self.summary()

self.generate(return_backgrounds = False, verbose = True)

argument	optional	default	available
return_backgrounds	yes	False	True, False
verbose	yes	True	True, False

self.generate_backgrounds(verbose = True)

argument	optional	default	available
verbose	yes	True	True, False