Skip to content

Latest commit

 

History

History
176 lines (144 loc) · 6.2 KB

README.md

File metadata and controls

176 lines (144 loc) · 6.2 KB

Dataset Framework (Datumaro)

A framework to build, transform, and analyze datasets.

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

Contents

Documentation

Features

  • Dataset format conversions:
  • Dataset building operations:
    • Merging multiple datasets into one
    • Dataset filtering with custom conditions, for instance:
      • remove all annotations except polygons of a certain class
      • remove images without 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
      • remap dataset labels
  • Dataset comparison
  • Model integration:
    • Inference (OpenVINO and custom models)
    • Explainable AI (RISE algorithm)

Check the design document for a full list of features

Installation

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/opencv/cvat#egg=datumaro&subdirectory=datumaro'

Usage

There are several options available:

Standalone tool

    User
        |
        v
+------------------+
|       CVAT       |
+--------v---------+       +------------------+       +--------------+
| Datumaro module  | ----> | Datumaro project | <---> | Datumaro CLI | <--- User
+------------------+       +------------------+       +--------------+
datum --help
python -m datumaro --help

Python module

Datumaro can be used in custom scripts as a library in the following way:

from datumaro.components.project import Project # project-related things
import datumaro.components.extractor # annotations and high-level interfaces
# etc.
project = Project.load('directory')

Examples

  • Convert PASCAL VOC to COCO, 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 project import --format voc --input-path <path/to/voc>
    datum project export --format coco --filter '/item[annotation/label="cat"]'
  • Convert only non-occluded annotations from a CVAT-annotated project to TFrecord:

    # export Datumaro dataset in CVAT UI, extract somewhere, go to the project dir
    datum project extract --filter '/item/annotation[occluded="False"]' \
      --mode items+anno --output-dir not_occluded
    datum project export --project not_occluded \
      --format tf_detection_api -- --save-images
  • Annotate COCO, 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 project import --format cvat --input-path <path/to/cvat.xml>
    datum project export --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

Contributing

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