ImageAuGomentationCLI
ImageAuGomentationCLI is a simple command-line tool that allows users to conveniently analyze and augment annotated and not-annotated images. It's written in Go (Golang), and leverages its beautiful concurrency model to speed up computations.
Setup
DISCLAIMER: this utility has only been tested on GNU/Linux and macOS. If you're running Windows, it's strongly recommended that you install Windows Subsystem for Linux.
Below are the steps to get the CLI.
1) Get the Go SDK
On Debian-based systems:
$> sudo apt-get install golang
On macOs:
$> brew install go
If you're running some other GNU/Linux distribution check out https://golang.ir/doc/install.
2) Clone this repository and setup environment vars
Enter the folder where you intend to clone the code and run
$> git clone https://github.com/lootag/ImageAuGomentationCLI.git
Then:
$> export GOPATH=${HOME}/go
$> export GOBIN=${GOPATH}bin
$> export PATH=${PATH}:${GOBIN}
$> go env
[...]
3) Make the utility
Prepare test environment:
$> make build_test
Run test:
$> make test
4) Install
Option 1: Install augoment in /usr/local/bin.
Fix build target in Makefile, in order to set your preferred location based on your $PATH env
$> make build
Option 2: Install augoment in $GOBIN
$> make install
At this point the utility should have been installed successfully. Try out your installation by running $> augoment -h
. If you get a list with the utility's command-line arguments, the process was successful.
Usage
The augoment command needs to be run in a directory that has two subdirectories:
Images
, containing all your images;
Annotations
, containing all your annotations.
By default, the command will run in the current directory, that is .
. If you wish to run it in a directory other than .
you'll need to specify a value for the -folder
argument.
1) Scan your dataset
The first thing you might want to do is get a picture of your dataset. You can do this by running
$> augoment -scan -folder="/path/to/folder/"
.
This will print a list of all the classes in your dataset, with their corresponding number of instances.
It's important to note that at the moment the utility only supports PASCAL_VOC. However, implementing readers and writers for your own custom format is pretty straightforward.
- Add an annotation type in entities/AnnotationType.go;
- In the annotationReaders folder, create a structure for your custom reader;
- Implement the
Read
method for the structure (check out PascalVocReader.go for an example);
- Implement the
ReadSync
method for the structure (check out PascalVocReader.go for an example);
- Add the structure to annotationReaders/AnnotationReadersFactory.go;
- In the annotationWriters folder, create a structure for your custom writer;
- Implement the
Write
method for the structure (check out PascalVocWriter.go for an example);
- Add the structure to annotationWriters/AnnotationWritersFactory.go;
- Now add your command-line argument to converStringToAnnotationType.go.
Now you can use the utility with your custom annotation format by simply specifying the arguments -in_annotationtype
and -out_annotationtype
.
2) Augment your dataset
The first thing to understand, is that augoment splits up the data into batches, and processes them in parallel. In order to specify a batch size, you need to assign a value to the -batch_size
command-line argument (the default value is 50).
As of right now, the utility will allow you to:
- rotate your images 90 degrees left and right;
- rotate your images 180 degrees;
- blur your images.
It's important to note that all images will also be resized. You can specify the size through the -size
command-line-argument (height and width will be the equal). The default value is 464.
These actions are controlled by the -rotate
and -blur
command-line arguments. If you don't specify any value for these arguments, all augmentations will be performed.
By setting the -exlusion_threshold
argument, you can exclude from your augmented dataset the images which contain classes whose number of instances is less than a certain threshold.
If you want to manually exclude some classes from the augmented dataset, you can specify the -user_defined_exclusions
argument (Ex. - user_defined_exclusions="class1;class2;"
).
By default, the utility will assume that your dataset is annotated, and will therefore augment your annotations too. If you only wish to augment your images, you can simply set -annotations=false
.