adbedada/imageprep

ImagePrep is a tool for preparing image labels in different formats, primarily for object detection tasks.

Deep Learning frameworks expect datasets to be prepared in a structure, style or format that fits into their workflow. With ImagePrep, you can easily organize labels according to these requirements. Currently, the tool simplifies the process of preparing labels with COCO, Pascal VOC and YOLO label formats. Conversion to one from another is also supported.

Installation

A stable version:

pip install imageprep

The latest:

# clone repo
git clone https://github.com/adbeda/imageprep    

# install
cd imageprep && pip install -e .

# or simply with:
python -m pip install 'git+https://github.com/adbeda/imageprep.git'

Usage

Example 1: Organize images and labels in COCO style

from imageprep import coco

"""
Folder Structure of a sample dataset

data
├── images
│ ├── 145_28.jpg
│ ├── 79_38.jpg
│ ├── 79_45.jpg
│ └── 80_7.jpg
└── labels
 ├── 145_28.txt
 ├── 79_38.txt
 ├── 79_45.txt
 └── 80_7.txt
"""

# folder containing images
image_path = "data/images/"
label_path = "data/labels/"

# run task
coco_dict = coco.coco_format_folder(image_path, label_path)

print(coco_dict)

Output:

[ {
   "image":[{
         "file_name":"data/images/145_28.jpg",
         "height":416,
         "width":416
      }],
   "annotations":[{
         "bbox":[336, 398, 416, 416],
         "id":1,
         "segmentation":[],
         "area":1440,
         "category_id":0
      },
      {
         "bbox":[3, 91, 105, 163],
         "id":2,
         "segmentation":[],
         "area":7344,
         "category_id":0
      },
      {
         "bbox":[134, 31, 196, 95],
         "id":3,
         "segmentation":[],
         "area":3968,
         "category_id":0
      }
   ],
   "image_id":0
},
{
   "image":[{
         "file_name":"data/images/79_38.jpg",
         "height":416,
         "width":416
      }],
   "annotations":[{
         "bbox":[257, 306, 325, 370],
         "id":1,
         "segmentation":[],
         "area":4352,
         "category_id":0
      }],
   "image_id":1}

]

Example 2: Convert absolute bounding box values to YOLO style formats

X_minY_minX_maxY_max -----> X_centerY_center Width Height

from imageprep import yolo

"""
# Input BBOX in absolute format (Xmin, Ymin, Xmax, Ymax)

├── labels
 ├── 145_28.txt
 │   ├── 336 398 416 416
 │   ├──   3  91 105 163
 │   ├── 134  31 196  95
 ├── 79_38.txt
 │   ├── 257 306 325 370   
 ├── 79_45.txt
 │   ├──   0 399 133 416
 │   ├── 161 255 239 343
 │   ├── 336  32 416 108      
 └── 80_7.txt
     ├── 267 223 391 319

"""

# folder containing images
image_path = "data/images/"
label_path = "data/labels/" 
output_path = "data/yolo_labels/"

# run task and save text 
yolo.convert_to_yolo(image_path, label_path, output_path)

Output:

# Output BBOX in relative format (Xcenter, Ycenter, Width, Height)

├── yolo_labels
    ├── 145_28.txt
    │   ├── 0.9038461538461539 0.9783653846153847 0.19230769230769232 0.04326923076923077
    │   ├── 0.12980769230769232 0.30528846153846156 0.2451923076923077 0.17307692307692307
    │   ├── 0.3966346153846154 0.1514423076923077 0.14903846153846154 0.15384615384615385
    ├── 79_38.txt
    │   ├── 0.6995192307692308 0.8125 0.16346153846153846 0.15384615384615385   
    ├── 79_45.txt
    │   ├── 0.15985576923076925 0.9795673076923077 0.3197115384615385 0.040865384615384616
    │   ├── 0.4807692307692308 0.71875 0.1875 0.21153846153846156
    │   ├── 0.9038461538461539 0.16826923076923078 0.19230769230769232 0.1826923076923077
    └── 80_7.txt
        ├── 0.7908653846153847 0.6514423076923077 0.2980769230769231 0.23076923076923078

Command Line

Usage: imageprep [OPTIONS] COMMAND [ARGS]...

  Dataset Preparation Helper

Options:
  -h, --help  Show this message and exit.

Commands:
  convert-to-yolo   Converts absolute bbox values to relative ones
  create-path-file  Writes out the path to images in a folder as a list
  get-image-name    Prints out the names of images in a folder
  resize-images     Resizes Image dimension to a size provided by user

The CLI is still in early stage of development.

Use case:

The above output can easily be integrated with data registration steps requried to train a Mask-RCNN model using Detectron2. Check out the example here.

Other functionalities included in the library:

Create a list of all bounding boxes
Stack and save images as numpy array
Dump labels as JSON objects to a file
Resize images within a single or multiple folders
Convert relative (YOLO style) values to absolute ones
Customize a python dictionary of labels to a Detectron2 format and more ...

TODO: current and future work

Improve the CLI
Add workflow for VOC style
Test against RCNN families
Create a documentation
Improve integration for Detectron2 and YOLO

adbedada / imageprep