Datumaro Dataset Management Framework

Datumaro is a framework and CLI tool designed for building, transforming, and analyzing datasets. It serves as a dataset storage and a debugging tool for computer vision workflows.

Core capabilities include:

• Dataset Management: Creating, maintaining, and version-controlling annotations and images. This includes editing, joining, splitting, and exporting datasets across various formats.
• Dataset Building: Merging multiple datasets, filtering by custom criteria (e.g., removing specific classes, filtering by image orientation, or removing small bounding boxes), and performing annotation conversions (e.g., polygons to masks).
• Dataset Splitting: Creating train, val, and test subsets using either random splits or task-specific splits that preserve label and attribute distributions (e.g., ensuring unique IDs in re-identification tasks).
• Quality & Analysis: Checking for errors, comparing datasets with model inference results, validating annotations based on task type, and calculating dataset statistics (e.g., image mean/std, annotation distributions).

A valid Pascal VOC dataset for Datumaro should follow this structure:

└─ Dataset/
   ├── dataset_meta.json # Optional: list of non-Pascal labels
   ├── labelmap.txt     # Optional: list of non-Pascal labels
   ├── Annotations/
   │   ├── ann1.xml     # Pascal VOC format annotation files
   │   └── ...
   ├── JPEGImages/
   │   ├── img1.jpg     # Image files
   │   └── ...
   ├── SegmentationClass/ # Semantic segmentation masks
   │   ├── img1.png
   │   └── ...
   ├── SegmentationObject/ # Instance segmentation masks
   │   ├── img1.png
   │   └── ...
   └── ImageSets/
        ├── Main/       # Detection/Classification subsets
        │   ├── test.txt
        │   └── train.txt
        ├── Layout/     # Person layout subsets
        ├── Action/     # Action classification subsets
        └── Segmentation/ # Segmentation subsets

Note: ImageSets must contain at least one of Main, Layout, Action, or Segmentation directories. The .txt files inside these directories should contain image names without extensions.

Datumaro provides several tools for manipulating datasets:

Merging and Filtering

• Merging: Combine multiple datasets into a single unified dataset.
• Filtering: Remove data based on custom criteria, such as:
  • Removing polygons of a specific class.
  • Removing images without annotations for a specific class.
  • Removing occluded annotations.
  • Keeping only vertically-oriented images.
  • Removing small-area bounding boxes.

Conversions and Label Management

• Annotation Conversion: Convert between formats like polygons and instance masks (and vice-versa).
• Mask Manipulation: Apply custom colormaps to mask annotations.
• Label Management: Rename or remove dataset labels.

Dataset Splitting

Split datasets into train, val, and test subsets using:

• Random split.
• Task-specific splits: Maintains initial label and attribute distributions.
  • Classification: Based on labels.
  • Detection: Based on bounding boxes (bboxes).
  • Re-identification: Based on labels, ensuring the same IDs do not appear in both training and test splits.

The Cityscapes format supports Masks as annotation types. It includes an optional is_crowd (boolean) attribute; if False, the annotation id field encodes the instance ID.

Expected Directory Structure

A valid Cityscapes dataset directory should follow this structure:

└─ Dataset/
    ├── dataset_meta.json # optional: list of non-Cityscapes labels
    ├── label_colors.txt # optional: list of non-Cityscapes labels in other format
    ├── leftImg8bit/
    │   ├── <split: train,val, ...>
    │   │   ├── {city1}/
    │   │   │   ├── {city1}_{seq}_{frame}_leftImg8bit.png
    │   │   └── ...
    └── gtFine/
        ├── <split: train,val, ...>
        │   ├── {city1}/
        │   │   ├── {city1}_{seq}_{frame}_gtFine_color.png
        │   │   ├── {city1}_{seq}_{frame}_gtFine_instanceIds.png
        │   │   ├── {city1}_{seq}_{frame}_gtFine_labelIds.png
        │   └── ...

Annotated File Types

• *_leftImg8bit.png: Left images in 8-bit LDR format.
• *_color.png: Class labels encoded by color.
• *_labelIds.png: Class labels encoded by index.
• *_instanceIds.png: Class and instance labels encoded by an instance ID. The integer part of ID / 1000 provides the class ID, and the remainder is the instance ID.