This tutorial provides an introduction to using the ImageDataset class, which is central to handling collections of images within the gwel package.
Before you get started, you’ll need to install the package in a Python environment. To do so, follow the installation instructions provided in the README.md. After installation, activate your Python environment and open your preferred IDE or however you may choose to write python scipts. If you’re looking for recommendations, Spyder or VScode are good options for data science and image processing tasks.
To check the installation import the ImageDataset class:
from gwel import ImageDataset
If the import fails, ensure that you have activated the correct Python environment. If the import still fails, try reinstalling the package by following the installation instructions in the README.md file.
Now that the import has been successful, you can instantiate an ImageDataset object by providing the path to your directory of images. You may have a collection of images to follow this tutorial with. However, if not, you are invited to use the example images provided in the project repository to get started. The collection of images should take the form of a single directory with the collection of image files inside.
dataset = ImageDataset('path/to/directory/of/images')
Access the list of image names with the images attribute:
images_list = dataset.images
If you would like to check that each of the images is readable (not corrupt) use the following method. This will print a warning message to the terminal indicting the names of any images which can not be be opened and are likely corrupted.
dataset.check_images()
To view the images use:
from gwel.viewer import Viewer
viewer = Viewer(dataset,max_pixels=1500) # optional max_pixels argument
viewer.open()
#to navigate to the next or previous images use the 'n' and 'p' keys respectively.
#press the 'q' key to quit.
#pressing the 'f' key will flag images, more on this later.
When working with high resolution images it often is more practical to work with resized images of a lower resolution. Use the following method to create resized copies of the images saved in to the hidden ‘.gwel’ directory.
dataset.resize()
Use the following method to view the status of dataset. This will print text to the terminal summarizing the attributes of the object dataset If you have previously used the resize_images method this will be noted in the printed text.
dataset.status()
When viewing images, it is possible to flag images by pressing the ‘f’ key. Use the flagged attribute to access the list of images which have been flagged.
flagged_images = dataset.flagged
To sample a random subset of the image collection and copy the images to another directory, use the sample method. To include the set of flagged images in the sample set the optional argument flagged = True by default it is set to False.
sample_size = N # an integer
sample_dir = 'path/where/sample/images/will/be/copied/into'
dataset.sample(dir = sample_dir, N = sample_size, flagged=True)
Sometimes it is required to flip images by 180°. To do this first view the images and flag images that are require flipping. Then use the flip method to flip them. Warning: the flipped image will be rewritten over the non flipped image file, having a backup of raw image data is recommended.
dataset.flip()
If you have finished this tutorial and would like to continue, the next tutorial is on handling image datasets with factors.