Dataset Management Framework (Datumaro)

A framework and CLI tool to build, transform, and analyze datasets.

VOC dataset                                  ---> Annotation tool
     +                                     /
COCO dataset -----> Datumaro ---> dataset ------> Model training
     +                                     \
CVAT annotations                             ---> Publication, statistics etc.

Table of Contents

• Examples
• Features
• Installation
• Usage
• User manual
• Contributing

Examples

(Back to top)

• Convert PASCAL VOC dataset to COCO format, keep only images with cat class presented:

  # Download VOC dataset:
  # http://host.robots.ox.ac.uk/pascal/VOC/voc2012/VOCtrainval_11-May-2012.tar
  datum convert --input-format voc --input-path <path/to/voc> \
                --output-format coco \
                --filter '/item[annotation/label="cat"]'

• Convert only non-occluded annotations from a CVAT project to TFrecord:

  # export Datumaro dataset in CVAT UI, extract somewhere, go to the project dir
  datum project filter -e '/item/annotation[occluded="False"]' \
    --mode items+anno --output-dir not_occluded
  datum project export --project not_occluded \
    --format tf_detection_api -- --save-images

• Annotate MS COCO dataset, extract image subset, re-annotate it in CVAT, update old dataset:

  # Download COCO dataset http://cocodataset.org/#download
  # Put images to coco/images/ and annotations to coco/annotations/
  datum project import --format coco --input-path <path/to/coco>
  datum project export --filter '/image[images_I_dont_like]' --format cvat \
    --output-dir reannotation
  # import dataset and images to CVAT, re-annotate
  # export Datumaro project, extract to 'reannotation-upd'
  datum project project merge reannotation-upd
  datum project export --format coco

• Annotate instance polygons in CVAT, export as masks in COCO:

  datum convert --input-format cvat --input-path <path/to/cvat.xml> \
                --output-format coco -- --segmentation-mode masks

• Apply an OpenVINO detection model to some COCO-like dataset, then compare annotations with ground truth and visualize in TensorBoard:

  datum project import --format coco --input-path <path/to/coco>
  # create model results interpretation script
  datum model add mymodel openvino \
    --weights model.bin --description model.xml \
    --interpretation-script parse_results.py
  datum model run --model mymodel --output-dir mymodel_inference/
  datum project diff mymodel_inference/ --format tensorboard --output-dir diff

• Change colors in PASCAL VOC-like .png masks:

  datum project import --format voc --input-path <path/to/voc/dataset>
  
  # Create a color map file with desired colors:
  #
  # label : color_rgb : parts : actions
  # cat:0,0,255::
  # dog:255,0,0::
  #
  # Save as mycolormap.txt
  
  datum project export --format voc_segmentation -- --label-map mycolormap.txt
  # add "--apply-colormap=0" to save grayscale (indexed) masks
  # check "--help" option for more info
  # use "datum --loglevel debug" for extra conversion info

Features

(Back to top)

• Dataset reading, writing, conversion in any direction. Supported formats:
  • COCO (image_info, instances, person_keypoints, captions, labels*)
  • PASCAL VOC (classification, detection, segmentation, action_classification, person_layout)
  • YOLO (bboxes)
  • TF Detection API (bboxes, masks)
  • MOT sequences
  • MOTS PNG
  • ImageNet
  • CVAT
  • LabelMe
• Dataset building
  • Merging multiple datasets into one
  • Dataset filtering by a custom criteria:
    • remove polygons of a certain class
    • remove images without annotations of a specific class
    • remove occluded annotations from images
    • keep only vertically-oriented images
    • remove small area bounding boxes from annotations
  • Annotation conversions, for instance:
    • polygons to instance masks and vise-versa
    • apply a custom colormap for mask annotations
    • rename or remove dataset labels
• Dataset quality checking
  • Simple checking for errors
  • Comparison with model infernece
  • Merging and comparison of multiple datasets
• Dataset comparison
• Dataset statistics (image mean and std, annotation statistics)
• Model integration
  • Inference (OpenVINO, Caffe, PyTorch, TensorFlow, MxNet, etc.)
  • Explainable AI (RISE algorithm)

Check the design document for a full list of features. Check the user manual for usage instructions.

Installation

(Back to top)

Dependencies

• Python (3.6+)
• Optional: OpenVINO, TensforFlow, PyTorch, MxNet, Caffe, Accuracy Checker

Optionally, create a virtual environment:

python -m pip install virtualenv
python -m virtualenv venv
. venv/bin/activate

Install Datumaro package:

pip install 'git+https://github.com/openvinotoolkit/datumaro'

Usage

(Back to top)

There are several options available:

• A standalone command-line tool
• A python module

Standalone tool

Datuaro as a standalone tool allows to do various dataset operations from the command line interface:

datum --help
python -m datumaro --help

Python module

Datumaro can be used in custom scripts as a Python module. Used this way, it allows to use its features from an existing codebase, enabling dataset reading, exporting and iteration capabilities, simplifying integration of custom formats and providing high performance operations:

from datumaro.components.project import Project # project-related things
import datumaro.components.extractor # annotations and high-level interfaces

# load a Datumaro project
project = Project.load('directory')

# create a dataset
dataset = project.make_dataset()

# keep only annotated images
dataset = dataset.select(lambda item: len(item.annotations) != 0)

# change dataset labels
dataset = dataset.transform(project.env.transforms.get('remap_labels'),
  {'cat': 'dog', # rename cat to dog
    'truck': 'car', # rename truck to car
    'person': '', # remove this label
  }, default='delete')

for item in dataset:
  print(item.id, item.annotations)

# export the resulting dataset in COCO format
project.env.converters.get('coco').convert(dataset, save_dir='dst/dir')

Check our developer guide for additional information.

Contributing

(Back to top)

Feel free to open an Issue, if you think something needs to be changed. You are welcome to participate in development, instructions are available in our contribution guide.