Skip to content

convert: Convert Between Annotation Formats

The convert command group converts annotations between Pascal VOC, YOLO, and JSON formats.

m3-download convert [voc-yolo|yolo-voc|yolo-json] [OPTIONS]

convert voc-yolo

Converts Pascal VOC annotation XMLs to YOLO format, which is commonly used for training object detection models like YOLOv3, YOLOv4, and YOLOv5.

Usage

m3-download convert voc-yolo INPUT_DIR [INPUT_DIR...] [--output-dir OUTPUT_DIR] [--yolo-names YOLO_NAMES]

Parameters

  • INPUT_DIR: One or more directories containing Pascal VOC XML files
  • --output-dir: (Optional) Output directory for YOLO annotations (default: "yolo_localizations")
  • --yolo-names: (Optional) Path to an existing yolo.names file to use for class name mapping

Output

  • OUTPUT_DIR/labels/: Directory containing YOLO annotation files (one .txt file per input XML)
  • OUTPUT_DIR/yolo.names: File containing all class names sorted alphabetically (unless provided via --yolo-names)

Directory Structure

The command creates a YOLO-friendly directory structure with all annotation files in a 'labels' subdirectory and a 'yolo.names' file at the root level. If you provide a yolo.names file, its mapping will be used for class IDs.

YOLO Format Explanation

YOLO annotations are simple text files with one line per object:

<class_id> <x_center> <y_center> <width> <height>
  • <class_id>: Integer ID of the object class (starting from 0)
  • <x_center>: X-coordinate of the object center, relative to image width (0 to 1)
  • <y_center>: Y-coordinate of the object center, relative to image height (0 to 1)
  • <width>: Width of the object bounding box, relative to image width (0 to 1)
  • <height>: Height of the object bounding box, relative to image height (0 to 1)

Examples

Convert VOC XMLs using an existing class mapping: 

m3-download convert voc-yolo --output-dir Sebastes_yolo/ --yolo-names my_yolo.names Sebastes_voc_1/ Sebastes_voc_2/

Convert VOC XMLs and auto-generate the class mapping: 

m3-download convert voc-yolo --output-dir Sebastes_yolo/ Sebastes_voc_1/ Sebastes_voc_2/

convert yolo-voc

Converts YOLO format annotations (text files) to Pascal VOC XML format. Since YOLO annotations don't include image dimensions, corresponding images must be provided to extract this information.

Usage

m3-download convert yolo-voc YOLO_DIR IMAGE_DIR NAMES_FILE OUTPUT_DIR [--verbose]

Parameters

  • YOLO_DIR: Directory containing YOLO annotation text files
  • IMAGE_DIR: Directory containing corresponding images (PNG or JPG)
  • NAMES_FILE: File containing class names, one per line
  • OUTPUT_DIR: Directory where VOC XML files will be saved
  • --verbose, -v: (Optional) Display additional information about file matching

How It Works

  1. The command matches annotation files with image files by their filename stems
  2. For each matched pair, it:
    • Reads the image dimensions using the imagesize library
    • Converts YOLO's normalized coordinates to absolute pixel coordinates
    • Creates a Pascal VOC XML using the pascal_voc_writer library
    • Saves the XML to the output directory

File Requirements

  • YOLO annotations must have the .txt file extension
  • Image files must have .png or .jpg file extensions
  • Files are matched based on filename stem (name without extension)

Missing Matches

If an annotation file has no matching image file or vice versa, a warning will be displayed and those files will be skipped.

Examples

Basic conversion:

m3-download convert yolo-voc yolo_annotations/ images/ yolo.names voc_annotations/

Verbose output to debug file matching issues:

m3-download convert yolo-voc yolo_annotations/ images/ yolo.names voc_annotations/ --verbose

convert yolo-json

Converts YOLO format annotations to a more readable and portable JSON format. This can be useful for data examination, sharing, or as an intermediate format for further processing.

Usage

m3-download convert yolo-json INPUT_DIR NAMES_FILE WIDTH HEIGHT OUTPUT_FILE [--round]

Parameters

  • INPUT_DIR: Directory containing YOLO annotation text files
  • NAMES_FILE: File containing class names, one per line
  • WIDTH: Image width (for scaling normalized YOLO coordinates)
  • HEIGHT: Image height (for scaling normalized YOLO coordinates)
  • OUTPUT_FILE: Path to save the output JSON file
  • --round: (Optional) Round the scaled coordinates to the nearest whole number

Output Format

The JSON output follows this structure:

{
  "/absolute/path/to/annotation1.txt": [
    {
      "concept": "class_name",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 40
    },
    ...
  ],
  "/absolute/path/to/annotation2.txt": [
    ...
  ]
}

How It Works

  1. The command reads all YOLO annotation files (.txt) in the input directory
  2. For each annotation, it converts:
    • Class indices to human-readable class names using the provided names file
    • Normalized coordinates to absolute pixel coordinates using the provided dimensions
    • Center-based coordinates (YOLO) to top-left coordinates (traditional)
  3. All annotations are compiled into a single JSON file

Coordinate Precision

Use the --round flag when you need integer coordinates (e.g., for displaying in pixel-based applications). Omit it when you need to preserve the exact floating-point precision (e.g., for mathematical analysis).

Examples

Basic conversion with integer coordinates: 

m3-download convert yolo-json yolo_annotations/ yolo.names 1920 1080 localizations.json --round

Preserving floating point precision: 

m3-download convert yolo-json yolo_annotations/ yolo.names 1920 1080 localizations.json