Labelformat - Label Conversion, Simplified

An open-source tool to seamlessly convert between popular computer vision label formats.

[!TIP] Check out our LightlyStudio open source project that builds on top of Labelformat to visualize and edit your annotation labels.

Why Labelformat

Popular label formats are sparsely documented and store different information. Understanding them and dealing with the differences is tedious and time-consuming. Labelformat aims to solve this pain.

Supported Tasks and Formats

• object-detection
  • COCO
  • KITTI
  • Labelbox (input only)
  • Lightly
  • PascalVOC
  • RT-DETR
  • RT-DETRv2
  • YOLOv5
  • YOLOv6
  • YOLOv7
  • YOLOv8
  • YOLOv9
  • YOLOv10
  • YOLOv11
  • YOLOv12
  • YOLOv26
• instance-segmentation
  • COCO
  • YOLOv8
  • MaskPair (image/mask pairs)

Features

• Support for common dataset label formats (more coming soon)
• Support for common tool formats (more coming soon)
• Minimal dependencies, supports Python 3.8 through 3.14
• Memory concious - datasets are processed file-by-file instead of loading everything in memory (when possible)
• Typed
• Tested with round trip tests to ensure consistency
• MIT license

Supported Platforms

This package is compatible with the following platforms:

• Windows
• macOS
• Linux

Note Labelformat is a young project, contributions and bug reports are welcome. Please see Contributing section below.

Installation

pip install labelformat

☁️ Using Cloud Storage

To work with annotations stored in cloud storage (like AWS S3, GCS, or Azure), install the cloud storage dependencies:

pip install "labelformat[cloud-storage]"

This installs the required libraries: s3fs (for S3), gcsfs (for GCS), and adlfs (for Azure).

Labelformat uses fsspec, which also supports other file systems. If you need a different provider (for example FTP or SSH), check the fsspec documentation and install the matching implementation manually (for example pip install sftpfs).

Current Support Limitations:

• Input format: Cloud URIs are currently supported only for COCO input (--input-format coco).

Usage

CLI

Examples

Convert image/mask pairs to COCO instance segmentation:

labelformat convert \
    --task instance-segmentation \
    --input-format maskpair \
    --image-glob "images/**/*.jpg" \
    --mask-glob "masks/**/*.png" \
    --category-names crack,defect \
    --pairing-mode stem \
    --threshold -1 \
    --min-area 50 \
    --output-format coco \
    --output-file coco-labels/annotations.json

Convert instance segmentation labels from COCO to YOLOv8:

labelformat convert \
    --task instance-segmentation \
    --input-format coco \
    --input-file coco-labels/train.json \
    --output-format yolov8 \
    --output-file yolo-labels/data.yaml \
    --output-split train

Convert object detection labels from KITTI to PascalVOC:

labelformat convert \
    --task object-detection \
    --input-format kitti \
    --input-folder kitti-labels/labels \
    --category-names cat,dog,fish \
    --images-rel-path ../images \
    --output-format pascalvoc \
    --output-folder pascalvoc-labels

Convert object detection labels from Labelbox to Lightly:

labelformat convert \
    --task object-detection \
    --input-format labelbox \
    --input-file labelbox-labels/export-result.ndjson \
    --category-names cat,dog,fish \
    --output-format lightly \
    --output-folder lightly-labels/annotation-task

Command Arguments

List the available tasks with:

$ labelformat convert --help
usage: labelformat convert [-h] --task
                           {instance-segmentation,object-detection}

Convert labels from one format to another.

optional arguments:
  -h, --help
  --task {instance-segmentation,object-detection}

List the available formats for a given task with:

$ labelformat convert --task object-detection --help
usage: labelformat convert [-h] --task
                           {instance-segmentation,object-detection}
                           --input-format
                           {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}
                           --output-format
                           {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}

Convert labels from one format to another.

optional arguments:
  -h, --help
  --task {instance-segmentation,object-detection}
  --input-format {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}
                        Input format
  --output-format {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}
                        Output format

Specify the input and output format to get required options for specific formats:

$ labelformat convert \
          --task object-detection \
          --input-format coco \
          --output-format yolov8 \
          --help
usage: labelformat convert [-h] --task
                           {instance-segmentation,object-detection}
                           --input-format
                           {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}
                           --output-format
                           {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}
                           --input-file INPUT_FILE --output-file OUTPUT_FILE
                           [--output-split OUTPUT_SPLIT]

Convert labels from one format to another.

optional arguments:
  -h, --help
  --task {instance-segmentation,object-detection}
  --input-format {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}
                        Input format
  --output-format {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}
                        Output format

'coco' input arguments:
  --input-file INPUT_FILE
                        Path to input COCO JSON file

'yolov8' output arguments:
  --output-file OUTPUT_FILE
                        Output data.yaml file
  --output-split OUTPUT_SPLIT
                        Split to use

Code

Please refer to the code for a full list of available classes.

Object detection example:

from pathlib import Path
from labelformat.formats import COCOObjectDetectionInput, YOLOv8ObjectDetectionOutput

# Load the input labels
label_input = COCOObjectDetectionInput(
    input_file=Path("coco-labels/train.json")
)
# Convert to output format and save
YOLOv8ObjectDetectionOutput(
    output_file=Path("yolo-labels/data.yaml"),
    output_split="train",
).save(label_input=label_input)

Instance segmentation from image/mask pairs example:

from pathlib import Path
from labelformat.formats import MaskPairInstanceSegmentationInput, COCOInstanceSegmentationOutput

# Load image/mask pairs
label_input = MaskPairInstanceSegmentationInput(
    image_glob="images/*.jpg",
    mask_glob="masks/*.png",
    base_path=Path("dataset"),
    pairing_mode="stem",
    category_names="crack,defect",
    threshold=128,
    min_area=100.0,
    segmentation_type="polygon"
)
# Convert to COCO format
COCOInstanceSegmentationOutput(
    output_file=Path("output/annotations.json")
).save(label_input=label_input)

Tutorial

We will walk through in detail how to convert object detection labels from COCO format to YOLOv8 format and the other way around.

Convert Object Detections from COCO to YOLOv8

Let's assume we have coco.json in the coco-labels directory with following contents:

{
  "info": {
    "description": "COCO 2017 Dataset",
    "url": "http://cocodataset.org",
    "version": "1.0",
    "year": 2017,
    "contributor": "COCO Consortium",
    "date_created": "2017/09/01"
  },
  "licenses": [
    {
      "url": "http://creativecommons.org/licenses/by/2.0/",
      "id": 4,
      "name": "Attribution License"
    }
  ],
  "images": [
    {
      "file_name": "image1.jpg",
      "height": 416,
      "width": 640,
      "id": 0,
      "date_captured": "2013-11-18 02:53:27"
    }