{"id":13861878,"url":"https://github.com/HumanSignal/label-studio-converter","last_synced_at":"2025-07-14T09:34:13.812Z","repository":{"id":37089205,"uuid":"219014916","full_name":"HumanSignal/label-studio-converter","owner":"HumanSignal","description":"Tools for converting Label Studio annotations into common dataset formats","archived":true,"fork":false,"pushed_at":"2024-08-19T14:24:15.000Z","size":3265,"stargazers_count":261,"open_issues_count":60,"forks_count":130,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-11-14T12:56:21.843Z","etag":null,"topics":["coco","coco-image-dataset","coco-ssd","conll","conll-2003","pascal-voc","pascal-voc2012"],"latest_commit_sha":null,"homepage":"https://labelstud.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HumanSignal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-01T15:43:12.000Z","updated_at":"2024-11-08T05:04:40.000Z","dependencies_parsed_at":"2023-07-24T05:45:51.550Z","dependency_job_id":"57383d78-35b6-4b39-bb82-0b4d90307584","html_url":"https://github.com/HumanSignal/label-studio-converter","commit_stats":null,"previous_names":["humansignal/label-studio-converter","heartexlabs/label-studio-converter"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanSignal%2Flabel-studio-converter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanSignal%2Flabel-studio-converter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanSignal%2Flabel-studio-converter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanSignal%2Flabel-studio-converter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HumanSignal","download_url":"https://codeload.github.com/HumanSignal/label-studio-converter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225968892,"owners_count":17553157,"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":["coco","coco-image-dataset","coco-ssd","conll","conll-2003","pascal-voc","pascal-voc2012"],"created_at":"2024-08-05T06:01:32.098Z","updated_at":"2024-11-22T21:31:18.943Z","avatar_url":"https://github.com/HumanSignal.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Warning\n\nThis repository has been archived and merged into the Label Studio SDK:\nhttps://github.com/HumanSignal/label-studio-sdk/tree/master/src/label_studio_sdk/converter\n\n# Label Studio Converter\n\n[Website](https://labelstud.io/) • [Docs](https://labelstud.io/guide) • [Twitter](https://twitter.com/heartexlabs) • [Join Slack Community \u003cimg src=\"https://app.heartex.ai/docs/images/slack-mini.png\" width=\"18px\"/\u003e](https://slack.labelstud.io)\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Examples](#examples)\n    - [JSON](#json)\n    - [CSV](#csv)\n    - [CoNLL 2003](#conll-2003)\n    - [COCO](#coco)\n    - [Pascal VOC XML](#pascal-voc-xml)\n- [YOLO to Label Studio Converter](#yolo-to-label-studio-converter)\n  - [Usage](#usage)\n  - [Tutorial: Importing YOLO Pre-Annotated Images to Label Studio using Local Storage](#tutorial-importing-yolo-pre-annotated-images-to-label-studio-using-local-storage)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Introduction\n\nLabel Studio Format Converter helps you to encode labels into the format of your favorite machine learning library.\n\n## Examples\n\n#### JSON\n**Running from the command line:**\n\n```bash\npip install -U label-studio-converter\npython label-studio-converter export -i exported_tasks.json -c examples/sentiment_analysis/config.xml -o output_dir -f CSV\n```\n\n**Running from python:**\n```python\nfrom label_studio_converter import Converter\n\nc = Converter('examples/sentiment_analysis/config.xml')\nc.convert_to_json('examples/sentiment_analysis/completions/', 'tmp/output.json')\n```\n\nGetting output file: `tmp/output.json`\n```json\n[\n  {\n    \"reviewText\": \"Good case, Excellent value.\",\n    \"sentiment\": \"Positive\"\n  },\n  {\n    \"reviewText\": \"What a waste of money and time!\",\n    \"sentiment\": \"Negative\"\n  },\n  {\n    \"reviewText\": \"The goose neck needs a little coaxing\",\n    \"sentiment\": \"Neutral\"\n  }\n]\n```\n\nUse cases: any tasks\n\n\n#### CSV\nRunning from the command line:\n```bash\npython label_studio_converter/cli.py --input examples/sentiment_analysis/completions/ --config examples/sentiment_analysis/config.xml --output output_dir --format CSV --csv-separator $'\\t'\n```\n\nRunning from python:\n```python\nfrom label_studio_converter import Converter\n\nc = Converter('examples/sentiment_analysis/config.xml')\nc.convert_to_csv('examples/sentiment_analysis/completions/', 'output_dir', sep='\\t', header=True)\n```\n\nGetting output file `tmp/output.tsv`:\n```tsv\nreviewText\tsentiment\nGood case, Excellent value.\tPositive\nWhat a waste of money and time!\tNegative\nThe goose neck needs a little coaxing\tNeutral\n```\n\nUse cases: any tasks\n\n#### CoNLL 2003\n\nRunning from the command line:\n```bash\npython label_studio_converter/cli.py --input examples/named_entity/completions/ --config examples/named_entity/config.xml --output tmp/output.conll --format CONLL2003\n```\n\nRunning from python:\n```python\nfrom label_studio_converter import Converter\n\nc = Converter('examples/named_entity/config.xml')\nc.convert_to_conll2003('examples/named_entity/completions/', 'tmp/output.conll')\n```\n\nGetting output file `tmp/output.conll`\n```text\n-DOCSTART- -X- O\nShowers -X- _ O\ncontinued -X- _ O\nthroughout -X- _ O\nthe -X- _ O\nweek -X- _ O\nin -X- _ O\nthe -X- _ O\nBahia -X- _ B-Location\ncocoa -X- _ O\nzone, -X- _ O\n...\n```\n\nUse cases: text tagging\n\n\n#### COCO\nRunning from the command line:\n```bash\npython label_studio_converter/cli.py --input examples/image_bbox/completions/ --config examples/image_bbox/config.xml --output tmp/output.json --format COCO --image-dir tmp/images\n```\n\nRunning from python:\n```python\nfrom label_studio_converter import Converter\n\nc = Converter('examples/image_bbox/config.xml')\nc.convert_to_coco('examples/image_bbox/completions/', 'tmp/output.conll', output_image_dir='tmp/images')\n```\n\nOutput images could be found in `tmp/images`\n\nGetting output file `tmp/output.json`\n```json\n{\n  \"images\": [\n    {\n      \"width\": 800,\n      \"height\": 501,\n      \"id\": 0,\n      \"file_name\": \"tmp/images/62a623a0d3cef27a51d3689865e7b08a\"\n    }\n  ],\n  \"categories\": [\n    {\n      \"id\": 0,\n      \"name\": \"Planet\"\n    },\n    {\n      \"id\": 1,\n      \"name\": \"Moonwalker\"\n    }\n  ],\n  \"annotations\": [\n    {\n      \"id\": 0,\n      \"image_id\": 0,\n      \"category_id\": 0,\n      \"segmentation\": [],\n      \"bbox\": [\n        299,\n        6,\n        377,\n        260\n      ],\n      \"ignore\": 0,\n      \"iscrowd\": 0,\n      \"area\": 98020\n    },\n    {\n      \"id\": 1,\n      \"image_id\": 0,\n      \"category_id\": 1,\n      \"segmentation\": [],\n      \"bbox\": [\n        288,\n        300,\n        132,\n        90\n      ],\n      \"ignore\": 0,\n      \"iscrowd\": 0,\n      \"area\": 11880\n    }\n  ],\n  \"info\": {\n    \"year\": 2019,\n    \"version\": \"1.0\",\n    \"contributor\": \"Label Studio\"\n  }\n}\n```\n\nUse cases: image object detection\n\n#### Pascal VOC XML\nRunning from the command line:\n```bash\npython label_studio_converter/cli.py --input examples/image_bbox/completions/ --config examples/image_bbox/config.xml --output tmp/voc-annotations --format VOC --image-dir tmp/images\n```\n\nRunning from python:\n```python\nfrom label_studio_converter import Converter\n\nc = Converter('examples/image_bbox/config.xml')\nc.convert_to_voc('examples/image_bbox/completions/', 'tmp/output.conll', output_image_dir='tmp/images')\n```\n\nOutput images can be found in `tmp/images`\n\nCorresponding annotations could be found in `tmp/voc-annotations/*.xml`:\n```xml\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\n\u003cannotation\u003e\n\u003cfolder\u003etmp/images\u003c/folder\u003e\n\u003cfilename\u003e62a623a0d3cef27a51d3689865e7b08a\u003c/filename\u003e\n\u003csource\u003e\n\u003cdatabase\u003eMyDatabase\u003c/database\u003e\n\u003cannotation\u003eCOCO2017\u003c/annotation\u003e\n\u003cimage\u003eflickr\u003c/image\u003e\n\u003cflickrid\u003eNULL\u003c/flickrid\u003e\n\u003c/source\u003e\n\u003cowner\u003e\n\u003cflickrid\u003eNULL\u003c/flickrid\u003e\n\u003cname\u003eLabel Studio\u003c/name\u003e\n\u003c/owner\u003e\n\u003csize\u003e\n\u003cwidth\u003e800\u003c/width\u003e\n\u003cheight\u003e501\u003c/height\u003e\n\u003cdepth\u003e3\u003c/depth\u003e\n\u003c/size\u003e\n\u003csegmented\u003e0\u003c/segmented\u003e\n\u003cobject\u003e\n\u003cname\u003ePlanet\u003c/name\u003e\n\u003cpose\u003eUnspecified\u003c/pose\u003e\n\u003ctruncated\u003e0\u003c/truncated\u003e\n\u003cdifficult\u003e0\u003c/difficult\u003e\n\u003cbndbox\u003e\n\u003cxmin\u003e299\u003c/xmin\u003e\n\u003cymin\u003e6\u003c/ymin\u003e\n\u003cxmax\u003e676\u003c/xmax\u003e\n\u003cymax\u003e266\u003c/ymax\u003e\n\u003c/bndbox\u003e\n\u003c/object\u003e\n\u003cobject\u003e\n\u003cname\u003eMoonwalker\u003c/name\u003e\n\u003cpose\u003eUnspecified\u003c/pose\u003e\n\u003ctruncated\u003e0\u003c/truncated\u003e\n\u003cdifficult\u003e0\u003c/difficult\u003e\n\u003cbndbox\u003e\n\u003cxmin\u003e288\u003c/xmin\u003e\n\u003cymin\u003e300\u003c/ymin\u003e\n\u003cxmax\u003e420\u003c/xmax\u003e\n\u003cymax\u003e390\u003c/ymax\u003e\n\u003c/bndbox\u003e\n\u003c/object\u003e\n\u003c/annotation\u003e\n```\n\nUse cases: image object detection\n\n--------\n\n# YOLO to Label Studio Converter \n\n### YOLO directory structure\n\nCheck the structure of YOLO folder first, keep in mind that the root is `/yolo/datasets/one`. \n\n```\n/yolo/datasets/one\n  images\n   - 1.jpg\n   - 2.jpg\n   - ...\n  labels\n   - 1.txt\n   - 2.txt\n\n  classes.txt\n```\n\n*classes.txt example*\n\n```\nAirplane\nCar\n```\n\n### Usage\n\n```\nlabel-studio-converter import yolo -i /yolo/datasets/one -o ls-tasks.json --image-root-url \"/data/local-files/?d=one/images\"\n```\nWhere the URL path from `?d=` is relative to the path you set in `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT`.\n\n**Note for Local Storages** \n  * It's very important to set `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/yolo/datasets` (**not** to `/yolo/datasets/one`, but **`/yolo/datasets`**) for Label Studio to run.\n  * [Add a new Local Storage](https://labelstud.io/guide/storage#Local-storage) in the project settings and set **Absolute local path** to `/yolo/datasets/one/images` (or `c:\\yolo\\datasets\\one\\images` for Windows). \n\n**Note for Cloud Storages**\n  * Use `--image-root-url` to make correct prefixes for task URLs, e.g. `--image-root-url s3://my-bucket/yolo/datasets/one`.\n  * [Add a new Cloud Storage](https://labelstud.io/guide/storage) in the project settings with the corresponding bucket and prefix.\n\n**Help command**\n\n```\nlabel-studio-converter import yolo -h\n\nusage: label-studio-converter import yolo [-h] -i INPUT [-o OUTPUT]\n                                          [--to-name TO_NAME]\n                                          [--from-name FROM_NAME]\n                                          [--out-type OUT_TYPE]\n                                          [--image-root-url IMAGE_ROOT_URL]\n                                          [--image-ext IMAGE_EXT]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -i INPUT, --input INPUT\n                        directory with YOLO where images, labels, notes.json\n                        are located\n  -o OUTPUT, --output OUTPUT\n                        output file with Label Studio JSON tasks\n  --to-name TO_NAME     object name from Label Studio labeling config\n  --from-name FROM_NAME\n                        control tag name from Label Studio labeling config\n  --out-type OUT_TYPE   annotation type - \"annotations\" or \"predictions\"\n  --image-root-url IMAGE_ROOT_URL\n                        root URL path where images will be hosted, e.g.:\n                        http://example.com/images or s3://my-bucket\n  --image-ext IMAGE_EXT\n                        image extension to search: .jpg, .png\n```\n\n\n## Tutorial: Importing YOLO Pre-Annotated Images to Label Studio using Local Storage\n\nThis tutorial will guide you through the process of importing a folder with YOLO annotations into Label Studio for further annotation. \nWe'll cover setting up your environment, converting YOLO annotations to Label Studio's format, and importing them into your project.\n\n\n### Prerequisites\n- Label Studio installed locally\n- YOLO annotated images and corresponding .txt label files in the directory `/yolo/datasets/one`.\n- label-studio-converter installed (available via `pip install label-studio-converter`)\n\n### Step 1: Set Up Your Environment and Run Label Studio\nBefore starting Label Studio, set the following environment variables to enable Local Storage file serving:\n\nUnix systems: \n```\nexport LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true\nexport LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/yolo/datasets\nlabel-studio\n```\n\nWindows: \n```\nset LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true\nset LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=C:\\\\yolo\\\\datasets\nlabel-studio\n```\n\nReplace `/yolo/datasets` with the actual path to your YOLO datasets directory.\n\n### Step 2: Setup Local Storage\n1. Create a new project.\n2. Go to the project settings and select **Cloud Storage**. \n3. Click **Add Source Storage** and select **Local files** from the **Storage Type** options.  \n3. Set the **Absolute local path** to `/yolo/datasets/one/images` or `c:\\yolo\\datasets\\one\\images` on Windows.\n4. Click `Add storage`.\n\nCheck more details about Local Storages [in the documentation](https://labelstud.io/guide/storage.html#Local-storage).\n\n### Step 3: Verify Image Access\nBefore importing the converted annotations from YOLO, verify that you can access an image from your Local storage via Label Studio. Open a new browser tab and enter the following URL:\n\n```\nhttp://localhost:8080/data/local-files/?d=one/images/\u003cyour_image\u003e.jpg\n```\n\nReplace `one/images/\u003cyour_image\u003e.jpg` with the path to one of your images. The image should display **in the new tab of the browser**.\nIf you can't open an image, the Local Storage configuration is incorrect. The most likely reason is that you made a mistake when specifying your `Path` in Local Storage settings or in `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT`. \n\n**Note:** The URL path from `?d=` should be relative to `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/yolo/datasets`, \nit means that the real path will be `/yolo/datasets/one/images/\u003cyour_image\u003e.jpg` and this image should exist on your hard drive.\n\n### Step 4: Convert YOLO Annotations\nUse the label-studio-converter to convert your YOLO annotations to a format that Label Studio can understand:\n\n```\nlabel-studio-converter import yolo -i /yolo/datasets/one -o output.json --image-root-url \"/data/local-files/?d=one/images\"\n```\n\n### Step 5: Import Converted Annotations\nNow import the `output.json` file into Label Studio:\n1. Go to your Label Studio project.\n2. From the Data Manager, click **Import**.\n3. Select the `output.json` file and import it.\n\n### Step 6: Verify Annotations\nAfter importing, you should see your images with the pre-annotated bounding boxes in Label Studio. Verify that the annotations are correct and make any necessary adjustments.\n\n### Troubleshooting\nIf you encounter issues with paths or image access, ensure that:\n- The LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT is set correctly.\n- The `--image-root-url` in the conversion command matches the relative path:\n```\n`Absolute local path from Local Storage Settings` - `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT` = `path for --image_root_url`\n```\ne.g.:\n```\n/yolo/datasets/one/images - /yolo/datasets/ = one/images\n```\n- The Local Storage in Label Studio is set up correctly with the Absolute local path to your images (`/yolo/datasets/one/images`)\n- For more details, refer to the documentation on [importing pre-annotated data](https://labelstud.io/guide/predictions.html) and [setting up Cloud Storages](https://labelstud.io/guide/storage).\n\n------------\n\n# Contributing\n\nWe would love to get your help for creating converters to other models. Please feel free to create pull requests.\n\n- [Contributing Guideline](https://github.com/heartexlabs/label-studio/blob/develop/CONTRIBUTING.md)\n- [Code Of Conduct](https://github.com/heartexlabs/label-studio/blob/develop/CODE_OF_CONDUCT.md)\n\n# License\n\nThis software is licensed under the [Apache 2.0 LICENSE](/LICENSE) © [Heartex](https://www.heartex.com/). 2020\n\n\u003cimg src=\"https://github.com/heartexlabs/label-studio/blob/master/images/opossum_looking.png?raw=true\" title=\"Hey everyone!\" height=\"140\" width=\"140\" /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHumanSignal%2Flabel-studio-converter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHumanSignal%2Flabel-studio-converter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHumanSignal%2Flabel-studio-converter/lists"}