{"id":18812194,"url":"https://github.com/lightly-ai/labelformat","last_synced_at":"2025-04-05T04:15:07.213Z","repository":{"id":201246042,"uuid":"706648119","full_name":"lightly-ai/labelformat","owner":"lightly-ai","description":"A tool for converting computer vision label formats.","archived":false,"fork":false,"pushed_at":"2025-03-20T15:07:37.000Z","size":1722,"stargazers_count":61,"open_issues_count":5,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T03:08:46.299Z","etag":null,"topics":["annotation","bounding-boxes","kitti","labels","mscoco","object-detection","pascal-voc","yolo","yolov8"],"latest_commit_sha":null,"homepage":"https://labelformat.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lightly-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-18T11:08:06.000Z","updated_at":"2025-03-24T17:57:10.000Z","dependencies_parsed_at":"2025-03-12T15:22:14.445Z","dependency_job_id":"93024025-2b87-40a5-b3c2-b81db0d04b67","html_url":"https://github.com/lightly-ai/labelformat","commit_stats":null,"previous_names":["lightly-ai/labelformat"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightly-ai%2Flabelformat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightly-ai%2Flabelformat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightly-ai%2Flabelformat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightly-ai%2Flabelformat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lightly-ai","download_url":"https://codeload.github.com/lightly-ai/labelformat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284954,"owners_count":20913704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation","bounding-boxes","kitti","labels","mscoco","object-detection","pascal-voc","yolo","yolov8"],"created_at":"2024-11-07T23:30:29.938Z","updated_at":"2025-04-05T04:15:07.185Z","avatar_url":"https://github.com/lightly-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Labelformat - Label Conversion, Simplified](docs/assets/labelformat_banner.png?raw=true \"Labelformat\")\n\n# Labelformat - Label Conversion, Simplified\n\n![GitHub](https://img.shields.io/github/license/lightly-ai/labelformat)\n![Unit Tests](https://github.com/lightly-ai/labelformat/workflows/Run%20Tests/badge.svg)\n[![PyPI](https://img.shields.io/pypi/v/labelformat)](https://pypi.org/project/labelformat/)\n[![Documentation](https://img.shields.io/badge/docs-labelformat.com-blue)](https://labelformat.com)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nAn open-source tool to seamlessly convert between popular computer vision label formats.\n\n#### Why Labelformat\n\nPopular label formats are sparsely documented and store different\ninformation. Understanding them and dealing with the differences is tedious\nand time-consuming. Labelformat aims to solve this pain.\n\n#### Supported Tasks and Formats\n\n- object-detection\n    - [COCO](https://labelformat.com/formats/object-detection/coco/)\n    - [KITTI](https://labelformat.com/formats/object-detection/kitti/)\n    - [Labelbox](https://labelformat.com/formats/object-detection/labelbox/) (input only)\n    - [Lightly](https://labelformat.com/formats/object-detection/lightly/)\n    - [PascalVOC](https://labelformat.com/formats/object-detection/pascalvoc/)\n    - [YOLOv5](https://labelformat.com/formats/object-detection/yolov5/)\n    - [YOLOv6](https://labelformat.com/formats/object-detection/yolov6/)\n    - [YOLOv7](https://labelformat.com/formats/object-detection/yolov7/)\n    - [YOLOv8](https://labelformat.com/formats/object-detection/yolov8/)\n    - [YOLOv9](https://labelformat.com/formats/object-detection/yolov9/)\n    - [YOLOv10](https://labelformat.com/formats/object-detection/yolov10/)\n    - [YOLOv11](https://labelformat.com/formats/object-detection/yolov11/)\n- instance-segmentation\n    - COCO\n    - YOLOv8\n\n#### Features\n\n- Support for common dataset label formats (more coming soon)\n- Support for common tool formats (more coming soon)\n- Minimal dependencies, targets python 3.8 or higher\n- Memory concious - datasets are processed file-by-file instead of loading everything\n  in memory (when possible)\n- Typed\n- Tested with round trip tests to ensure consistency\n- MIT license\n\n#### Supported Platforms\n\nThis package is compatible with the following platforms:\n\n- Windows\n- macOS\n- Linux\n\n\u003e **Note**\n\u003e Labelformat is a young project, contributions and bug reports are welcome. Please see [Contributing](#contributing) section below.\n\n## Installation\n\n```shell\npip install labelformat\n```\n\n## Usage\n\n### CLI\n\n#### Examples\n\nConvert instance segmentation labels from COCO to YOLOv8:\n```shell\nlabelformat convert \\\n    --task instance-segmentation \\\n    --input-format coco \\\n    --input-file coco-labels/train.json \\\n    --output-format yolov8 \\\n    --output-file yolo-labels/data.yaml \\\n    --output-split train\n```\n\nConvert object detection labels from KITTI to PascalVOC:\n```shell\nlabelformat convert \\\n    --task object-detection \\\n    --input-format kitti \\\n    --input-folder kitti-labels/labels \\\n    --category-names cat,dog,fish \\\n    --images-rel-path ../images \\\n    --output-format pascalvoc \\\n    --output-folder pascalvoc-labels\n```\n\nConvert object detection labels from Labelbox to Lightly:\n```shell\nlabelformat convert \\\n    --task object-detection \\\n    --input-format labelbox \\\n    --input-file labelbox-labels/export-result.ndjson \\\n    --category-names cat,dog,fish \\\n    --output-format lightly \\\n    --output-folder lightly-labels/annotation-task\n```\n\n#### Command Arguments\n\nList the available tasks with:\n```console\n$ labelformat convert --help\nusage: labelformat convert [-h] --task\n                           {instance-segmentation,object-detection}\n\nConvert labels from one format to another.\n\noptional arguments:\n  -h, --help\n  --task {instance-segmentation,object-detection}\n```\n\nList the available formats for a given task with:\n```console\n$ labelformat convert --task object-detection --help\nusage: labelformat convert [-h] --task\n                           {instance-segmentation,object-detection}\n                           --input-format\n                           {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}\n                           --output-format\n                           {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}\n\nConvert labels from one format to another.\n\noptional arguments:\n  -h, --help\n  --task {instance-segmentation,object-detection}\n  --input-format {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}\n                        Input format\n  --output-format {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}\n                        Output format\n```\n\nSpecify the input and output format to get required options for specific formats:\n```console\n$ labelformat convert \\\n          --task object-detection \\\n          --input-format coco \\\n          --output-format yolov8 \\\n          --help\nusage: labelformat convert [-h] --task\n                           {instance-segmentation,object-detection}\n                           --input-format\n                           {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}\n                           --output-format\n                           {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}\n                           --input-file INPUT_FILE --output-file OUTPUT_FILE\n                           [--output-split OUTPUT_SPLIT]\n\nConvert labels from one format to another.\n\noptional arguments:\n  -h, --help\n  --task {instance-segmentation,object-detection}\n  --input-format {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}\n                        Input format\n  --output-format {coco,kitti,labelbox,lightly,pascalvoc,yolov5,yolov6,yolov7,yolov8}\n                        Output format\n\n'coco' input arguments:\n  --input-file INPUT_FILE\n                        Path to input COCO JSON file\n\n'yolov8' output arguments:\n  --output-file OUTPUT_FILE\n                        Output data.yaml file\n  --output-split OUTPUT_SPLIT\n                        Split to use\n```\n\n### Code\n\nPlease refer to the code for a full list of available classes.\n\n```python\nfrom pathlib import Path\nfrom labelformat.formats import COCOObjectDetectionInput, YOLOv8ObjectDetectionOutput\n\n# Load the input labels\nlabel_input = COCOObjectDetectionInput(\n    input_file=Path(\"coco-labels/train.json\")\n)\n# Convert to output format and save\nYOLOv8ObjectDetectionOutput(\n    output_file=Path(\"yolo-labels/data.yaml\"),\n    output_split=\"train\",\n).save(label_input=label_input)\n```\n\n### Tutorial\n\nWe will walk through in detail how to convert object detection labels from COCO format\nto YOLOv8 format and the other way around.\n\n#### Convert Object Detections from COCO to YOLOv8\n\nLet's assume we have `coco.json` in the `coco-labels` directory with following contents:\n\n```json\n{\n  \"info\": {\n    \"description\": \"COCO 2017 Dataset\",\n    \"url\": \"http://cocodataset.org\",\n    \"version\": \"1.0\",\n    \"year\": 2017,\n    \"contributor\": \"COCO Consortium\",\n    \"date_created\": \"2017/09/01\"\n  },\n  \"licenses\": [\n    {\n      \"url\": \"http://creativecommons.org/licenses/by/2.0/\",\n      \"id\": 4,\n      \"name\": \"Attribution License\"\n    }\n  ],\n  \"images\": [\n    {\n      \"file_name\": \"image1.jpg\",\n      \"height\": 416,\n      \"width\": 640,\n      \"id\": 0,\n      \"date_captured\": \"2013-11-18 02:53:27\"\n    },\n    {\n      \"file_name\": \"image2.jpg\",\n      \"height\": 428,\n      \"width\": 640,\n      \"id\": 1,\n      \"date_captured\": \"2016-01-23 13:56:27\"\n    }\n  ],\n  \"annotations\": [\n    {\n      \"area\": 421,\n      \"iscrowd\": 0,\n      \"image_id\": 0,\n      \"bbox\": [540, 295, 23, 18],\n      \"category_id\": 2,\n      \"id\": 1\n    },\n    {\n      \"area\": 695.1853359360001,\n      \"iscrowd\": 0,\n      \"image_id\": 0,\n      \"bbox\": [513, 271, 21, 33],\n      \"category_id\": 0,\n      \"id\": 2\n    },\n    {\n      \"area\": 27826,\n      \"iscrowd\": 0,\n      \"image_id\": 1,\n      \"bbox\": [268, 63, 94, 295],\n      \"category_id\": 2,\n      \"id\": 16\n    }\n  ],\n  \"categories\": [\n    {\n      \"supercategory\": \"animal\",\n      \"id\": 0,\n      \"name\": \"cat\"\n    },\n    {\n      \"supercategory\": \"animal\",\n      \"id\": 1,\n      \"name\": \"dog\"\n    },\n    {\n      \"supercategory\": \"animal\",\n      \"id\": 2,\n      \"name\": \"fish\"\n    }\n  ]\n}\n```\n\nConvert it to YOLOv8 format with the following command:\n\n```console\nlabelformat convert \\\n  --task object-detection \\\n  --input-format coco \\\n  --input-file coco-labels/coco.json \\\n  --output-format yolov8 \\\n  --output-file yolo-from-coco-labels/data.yaml \\\n  --output-split train\n```\n\nThis creates the following data structure with YOLOv8 labels:\n\n```\nyolo-from-coco-labels/\n├── data.yaml\n└── labels/\n    ├── image1.txt\n    └── image2.txt\n```\n\nThe contents of the created files will be:\n\n```\n# data.yaml\nnames:\n  0: cat\n  1: dog\n  2: fish\nnc: 3\npath: .\ntrain: images\n\n# image1.txt\n2 0.86171875 0.7307692307692307 0.0359375 0.04326923076923077\n0 0.81796875 0.6911057692307693 0.0328125 0.07932692307692307\n\n# image2.txt\n2 0.4921875 0.49182242990654207 0.146875 0.6892523364485982\n```\n\n#### Convert Object Detections from YOLOv8 to COCO\n\nUnlike COCO format, YOLO uses relative image coordinates. To convert from YOLO to COCO\nwe therefore have to provide also input images. We prepare the following folder structure:\n\n```\nyolo-labels/\n├── data.yaml\n├── images/\n|   ├── image1.jpg\n|   └── image2.jpg\n└── labels/\n    ├── image1.txt\n    └── image2.txt\n```\n\nThe file contents will be as above. The location of the image folder\nis defined in `data.yaml` with the `path` (root path) and `train` field.\nNote that YOLO format allows specifying different data folders for\n`train`, `val` and `test` data splits, we chose to use `train` for our example.\n\nTo convert to COCO run the command below. Note that we specify `--input-split train`:\n\n```console\nlabelformat convert \\\n  --task object-detection \\\n  --input-format yolov8 \\\n  --input-file yolo-labels/data.yaml \\\n  --input-split train \\\n  --output-format coco \\\n  --output-file coco-from-yolo-labels/coco.json\n```\n\nThe command will produce `coco-from-yolo-labels/coco.json` with the following contents:\n\n```json\n{\n  \"images\": [\n    {\n      \"id\": 0,\n      \"file_name\": \"image1.jpg\",\n      \"width\": 640,\n      \"height\": 416\n    },\n    {\n      \"id\": 1,\n      \"file_name\": \"image2.jpg\",\n      \"width\": 640,\n      \"height\": 428\n    }\n  ],\n  \"categories\": [\n    {\n      \"id\": 0,\n      \"name\": \"cat\"\n    },\n    {\n      \"id\": 1,\n      \"name\": \"dog\"\n    },\n    {\n      \"id\": 2,\n      \"name\": \"fish\"\n    }\n  ],\n  \"annotations\": [\n    {\n      \"image_id\": 0,\n      \"category_id\": 2,\n      \"bbox\": [540.0, 295.0, 23.0, 18.0]\n    },\n    {\n      \"image_id\": 0,\n      \"category_id\": 0,\n      \"bbox\": [513.0, 271.0, 21.0, 33.0]\n    },\n    {\n      \"image_id\": 1,\n      \"category_id\": 2,\n      \"bbox\": [268.0, 63.0, 94.0, 295.0]\n    }\n  ]\n}\n```\n\nNote that converting from COCO to YOLO and back loses some information since\nthe intermediate format does not store all the fields.\n\n## Contributing\n\nIf you encounter a bug or have a feature suggestion we will be happy if you file a GitHub issue.\n\nWe also welcome contributions, please submit a PR.\n\n### Development\n\nThe library targets python 3.8 and higher. We use poetry to manage the development environment.\n\nHere is an example development workflow:\n\n```bash\n# Create a virtual environment with development dependencies\npoetry env use python3.8\npoetry install\n\n# Make changes\n...\n\n# Autoformat the code\npoetry run make format\n\n# Run tests\npoetry run make all-checks\n```\n\n## Maintained By\n[Lightly](https://www.lightly.ai) is a spin-off from ETH Zurich that helps companies \nbuild efficient active learning pipelines to select the most relevant data for their models.\n\nYou can find out more about the company and it's services by following the links below:\n\n- [Homepage](https://www.lightly.ai)\n- [Web-App](https://app.lightly.ai)\n- [Lightly Solution Documentation (Lightly Worker \u0026 API)](https://docs.lightly.ai/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightly-ai%2Flabelformat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flightly-ai%2Flabelformat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightly-ai%2Flabelformat/lists"}