Introducing Hocrox: An image preprocessing and augmentation library with Keras like interface
Image preprocessing and augmentation is one of the most important steps for preparing data for Machine Learning models. In this blog, I’ll introduce my library Hocrox. Hocrox is a simple library that provides Keras like simple interface to preprocess and augment images.
Preprocessing images
Image preprocessing is a process of formatting images before they are consumed by some Machine Learning algorithms. The process of image preprocessing includes image resizing, cropping, making corrections, etc.
Augmenting images
On the other hand, image augmentation is a process of artificially increasing the images by making several manipulations to the original images and making multiple versions of them.
Let’s say we have an image of a cat. If we rotate the image to some certain angle and/or flip the image randomly, then we can make multiple versions of the same image.
By making these augmentations, we can make the final model more robust, as now the model can handle images of different types. One thing to note is that image augmentation is only applicable on the training dataset, not on the test/dev dataset.
Introducing Hocrox
The word “Hocrox”
If you watched the movie or read the book Harry Potter, you must know what Horcrux is. According to Fandom
A Horcrux was an object in which a Dark Wizard or Witch had hidden a fragment of his or her soul in order to become immortal. Horcruxes could only be created after committing murder, the supreme act of evil. The process for the creation of a Horcrux involved a spell and a horrific act was performed soon after the murder had been committed.
I’m a big Potterhead, and I read the books several times. Unfortuanlity at the same time, I’m also stupid 😅 and made a mistake in naming the library.
Instead of Horcrux, I called it Hocrox.
If you’re thinking why I haven't changed the library name after knowing my mistake, then, in that case, let me tell you that I’m lazy.
The Keras interface
I’m a big fan of the Keras interface. I really like the simplicity of it. If you used Keras before, then you must know the high-level APIs provided by Keras to make models. I’m pasting an example code below.
model = keras.Sequential()
model.add(layers.Dense(2, activation="relu"))
model.add(layers.Dense(3, activation="relu"))
model.add(layers.Dense(4))The code above creates a simple model with 3 Dense layers.
Hocrox provides an interface that is similar to Keras for making models.
The Hocrox models
Just the way we make models in Keras to define the architecture of the model, in Hocrox, we also make models. A model is like a pipeline, where we define the entire process for preprocessing/augmenting images.
Layers
In Hocrox, each model contains several layers, where each layer is basically a function that will be performed on the images to preprocess and/or augment images.
Hocrox mainly supports two types of layers, Preprocessing and Augmentation. For the complete list of supported layers, please check the documentation.
Along with that, Hocrox also supports Read and Save layers to read and save images.
Getting started with Hocrox
Setting up the environment
Before we start writing some code, first we need some images. I’m pasting a google drive link to a folder containing some images, please download the folder.
Once you have the images, please install Hocrox. Check the install page for installation instructions.
Importing the module
Let’s start writing some code by importing the necessary dependencies.
Here the Model class is used for making the model, Read and Save layer for reading and saving images, and the rest of the layers for augmenting and/or preprocessing images.
from hocrox.model import Modelfrom hocrox.layer import Read, Savefrom hocrox.layer.preprocessing.transformation import Resize
from hocrox.layer.augmentation.flip import RandomFlip
from hocrox.layer.augmentation.transformation import RandomRotate
Making the model
Once we imported the dependencies, we can start the next process of making the model(pipeline).
- The first step in making a model is to initialize the Model class. The Model class does not take any arguments.
# Initalizing the model
model = Model()2. Once the model is initialized, we can start adding layers. In a model, the first layer is always a Read layer to read images.
# Reading the images
model.add(Read(path="./images", name="Read images"))3. Once we add the layer, we can add the other preprocessing/augmentation layers.
# Resizing the images to 224x224
model.add(Resize((224, 244), interpolation="INTER_LINEAR", name="Resize images"))
# Augmentating the images
model.add(
RandomRotate(
start_angle=-10.0, end_angle=10.0, probability=0.7, number_of_outputs=5, name="Randomly rotates the image"
)
)
model.add(RandomFlip(probability=0.7, name="Randomly flips the image"))Note: Here in the RandomRotate layer, the “number_of_outputs” parameter has a value of 5. This means, if originally we had 5 images then now after this layer, we’ll have 25 (5 x number_of_outputs=5x5=25) images. The parameter “probability” with the value of 0.7 means there is a 70% chance of applying this layer on each of the 25 images.
4. And finally we have the Save layer that saves images to the filesystem.
# Saving the images
model.add(Save("./preprocessed_images", format="img", name="Save the image"))5. Once we defined the model, we can generate a summary of the model using the summary function.
# Printing the summary of the model
print(model.summary())Transforming the images
As we already have the model ready, we can start transforming the images (applying the layers to each image). To do that, we have the transform function.
# Apply transform to the images
model.transform()Conclusion
Hocrox is a simple yet powerful image preprocessing and augmentation library. It provides Keras like interface so it should seem very familiar to developers.
Currently, Hocrox is limited in features and may not be very stable. It is at a very early stage of development. I’m constantly working on this project to add more features. If you’re interested to contribute to this project, please feel free to reach me.
Important Links
- Github: https://github.com/imdeepmind/hocrox
- Documentation: https://hocrox.imdeepmind.com/
- My Twitter: https://twitter.com/imdeepmind
