Convert Command

Convert annotation datasets between different formats

The convert command transforms annotation datasets from one format to another using Panlabel’s intermediate representation (IR) as a conversion hub.

Usage

panlabel convert --from <FORMAT> --to <FORMAT> -i <INPUT> -o <OUTPUT> [OPTIONS]

Parameters

--from · string · required

Source format. Use auto for automatic detection.

Supported values: auto, ir-json, coco, cvat, label-studio, tfod, yolo, voc

Aliases: coco-json, cvat-xml, label-studio-json, ls, tfod-csv, ultralytics, yolov8, yolov5, pascal-voc, voc-xml

--to · string · required

Target format.

Supported values: ir-json, coco, cvat, label-studio, tfod, yolo, voc

Aliases: Same as --from (except auto is not available)

--input · path · required

Input path to the source dataset. Can be a file or directory depending on the format.

Short form: -i

--output · path · required

Output path for the converted dataset.

Short form: -o

--strict · flag · default: "false"

Treat validation warnings as errors. If enabled, conversion will fail if the input dataset has any warnings.

--no-validate · flag · default: "false"

Skip input validation entirely. Use this for faster conversions when you’re confident the input is valid.

Warning: Skipping validation may result in unexpected output if the input has issues.

--allow-lossy · flag · default: "false"

Allow conversions that drop information (e.g., metadata, images without annotations).

By default, Panlabel blocks lossy conversions and shows a report of what would be lost. Use this flag to proceed anyway.

--report · string · default: "text"

Output format for the conversion report.

Options:

• text - Human-readable report
• json - Machine-readable JSON (prints only JSON to stdout)

Auto-Detection Behavior

When using --from auto, Panlabel detects the input format based on file extension and content:

Directory-based Detection

• YOLO: Directory contains labels/ subdirectory with .txt files, or the path itself is named labels/
• VOC: Directory contains Annotations/ with .xml files and JPEGImages/ subdirectory
• CVAT: Directory contains annotations.xml at the root

File-based Detection

• .csv files: Detected as tfod (TensorFlow Object Detection)
• .xml files: Root element <annotations> indicates cvat format
• .json files:
  • Array-root with Label Studio task structure → label-studio
  • Object-root with annotations[0].bbox as array → coco
  • Object-root with annotations[0].bbox as object → ir-json

If multiple format markers match (ambiguous), auto-detection fails. Use --from to specify the format explicitly.

Examples

Basic Conversion with Auto-Detection

panlabel convert --from auto --to coco -i /data/my_yolo -o out.json

Automatically detects the YOLO format from the directory structure and converts to COCO.

COCO to YOLO Conversion

panlabel convert -f coco -t yolo -i annotations.json -o ./yolo_output/

Strict Validation During Conversion

panlabel convert --from coco --to ir-json \
  -i input.json -o output.json \
  --strict

Fails if the input has any validation warnings.

Allow Lossy Conversion

panlabel convert -f coco -t tfod -i input.json -o output.csv --allow-lossy

Proceeds with the conversion even if some information (like metadata) will be lost.

Skip Validation for Speed

panlabel convert -f ir-json -t coco \
  -i large_dataset.json -o output.json \
  --no-validate

Skips validation to speed up conversion on large, trusted datasets.

JSON Report Output

panlabel convert -f coco -t yolo \
  -i input.json -o ./yolo_dir/ \
  --report json > report.json

Outputs a machine-readable JSON report for programmatic processing.

Convert Label Studio to CVAT

panlabel convert --from label-studio --to cvat \
  -i tasks.json -o annotations.xml

Conversion Report

After conversion, Panlabel prints a report showing:

• Number of images, annotations, and categories converted
• Any information that was lost or transformed
• Lossiness warnings (if applicable)
• Conversion issues or edge cases

Text Report Example

Converted input.json (coco) -> output.json (ir-json)

Conversion Report:
  ✓ Lossless conversion
  Images: 150
  Annotations: 1,234
  Categories: 8

Lossy Conversion Example

Conversion blocked: coco -> tfod is lossy

Would lose:
  - 15 images without annotations
  - Dataset-level metadata
  
Use --allow-lossy to proceed anyway.

Format-Specific Notes

YOLO Conversions

• YOLO is directory-based: output path should be a directory
• Requires classes.txt and data.yaml for category information
• Bounding boxes are stored in normalized coordinates (0-1)

VOC Conversions

• VOC is directory-based with Annotations/ and JPEGImages/ subdirectories
• Each image has a separate XML annotation file
• Output path should be the parent directory containing both subdirectories

TFOD Conversions

• TFOD uses a single CSV file with all annotations
• May lose information like metadata or segmentation masks
• Images without annotations are dropped by default

CVAT Conversions

• Can be a single XML file or a directory export
• Preserves annotation attributes and metadata
• Supports both file and directory-based formats

Exit Codes

• 0 - Conversion successful
• 1 - Validation failed (with --strict or on errors)
• 1 - Lossy conversion blocked (without --allow-lossy)
• 1 - Format detection failed
• 1 - I/O or parsing errors

See Also

Supported Formats

Learn about all supported annotation formats

Validate Command

Validate datasets before conversion

Sample Command

Sample and convert in one step