🚀 Introduction
Welcome to the JSON2YOLO repository! This toolkit is designed to help you convert datasets in JSON format, particularly those following the COCO (Common Objects in Context) standards, into the YOLO format. The YOLO format is widely recognized for its efficiency in real-time object detection tasks.
This conversion process is essential for machine learning practitioners looking to train object detection models using frameworks compatible with the YOLO format, such as Ultralytics YOLO. Our code is flexible and designed to run across various platforms including Linux, macOS, and Windows.
📢 Important Update: The JSON2YOLO project is now integrated into the main Ultralytics package at https://github.com/ultralytics/ultralytics. The standalone scripts in this repository are no longer being actively updated. For the latest functionality, please use the new convert_coco() method described in our updated data converter documentation.
⚙️ Requirements
To get started with JSON2YOLO, you'll need a Python environment running version 3.8 or later. Additionally, you'll need to install all the necessary dependencies listed in the requirements.txt file. You can install these dependencies using the following pip command in your terminal:
pip install -r requirements.txt # Installs all the required packages
💡 Usage
JSON2YOLO functionality is now part of the main ultralytics Python package. For new projects, install ultralytics and use the maintained converter:
pip install ultralytics
from ultralytics.data.converter import convert_coco
convert_coco(
labels_dir="path/to/annotations",
save_dir="path/to/output_dir",
use_segments=False,
use_keypoints=True,
)
This method processes COCO detection, segmentation, and keypoint annotations and saves YOLO labels in the specified directory. For more details, refer to the dataset format documentation.
Legacy standalone script usage is still available for existing workflows:
python general_json2yolo.py --source COCO --json-dir path/to/annotations --save-dir yolo_out
python general_json2yolo.py --source COCO --json-dir path/to/annotations --use-segments --save-dir yolo_seg
python general_json2yolo.py --source COCO --json-dir path/to/annotations --use-keypoints --save-dir yolo_pose
The standalone converter also supports LabelMe polygon, rectangle, circle, linestrip, and mask annotations:
python general_json2yolo.py --source LabelMe --json-dir path/to/labelme_jsons --use-segments --save-dir yolo_labelme
Notes:
- COCO input should be a directory containing
*.json files with standard images, annotations, and categories keys.
- LabelMe input should be a directory containing one JSON file per image.
--save-dir controls the output directory and is deleted/recreated on each run.- Image files are copied for LabelMe when
imagePath points to an existing local file next to the JSON.
- Labelbox exports can be JSON lists or newline-delimited JSON. Bounding-box objects are converted; mask-only objects are skipped with a warning.
The output follows the Ultralytics YOLO dataset layout:
yolo_out/
├── data.yaml
├── images/
└── labels/
📚 Citation
If you find our tool useful for your research or development, please consider citing it:
🤝 Contribute
We welcome contributions from the community! Whether you're fixing bugs, adding new features, or improving documentation, your input is invaluable. Take a look at our Contributing Guide to get started. Also, we'd love to hear about your experience with Ultralytics products. Please consider filling out our Survey. A huge 🙏 and thank you to all of our contributors!
©️ License
Ultralytics offers two licensing options to accommodate diverse needs:
- AGPL-3.0 License: Ideal for students and enthusiasts, this OSI-approved open-source license promotes collaboration and knowledge sharing. See the LICENSE file for details.
- Enterprise License: Designed for commercial use, this license permits seamless integration of Ultralytics software and AI models into commercial products and services, bypassing the open-source requirements of AGPL-3.0. For commercial inquiries, please contact us through Ultralytics Licensing.
📬 Contact Us
For bug reports, feature requests, and contributions, please visit GitHub Issues. For broader questions and discussions about this project and other Ultralytics initiatives, join our vibrant community on Discord!
