Convert Supervisely Annotations in Two Minutes

In this post, we walk through how to download data from Supervise.ly and convert Supervise.ly annotations to YOLO Darknet format specifically, and more generally convert Supervisely JSON to any other object detection annotation format for use in any of your custom computer vision models.

This guide is imperative if you want to use data from Supervise.ly in any application outside of the Supervisely platform.

Annotating Your Images

If you have unlabeled images, you can used Supervisely's annotation tool to label them. You may also want to consider open source labeling tools such as CVAT, LabelImg, VoTT, or LabelMe. We have some great guides on these labeling platforms including:

Downloading Data from Supervisely

After you have annotated your images, you will have an annotated dataset on the Datasets tab of Supervisely. You can export that dataset for use on custom computer vision tasks outside of Supervise.ly. Click the three dots in the lower portion of the image --> Download as --> .json + images :

Downloading data from Supervisely

This will download a .tar file to your computer that contains a folder with all of the images in your dataset as well as an annotation file in Supervisely's custom JSON format. There will be one annotation file for each image. At the top of the annotation file there is some meta data about the image and then there is a list of annotated objects:

{
    "description": "",
    "tags": [],
    "size": {
        "height": 1536,
        "width": 1536
    },
    "objects": [
        {
            "id": 466098957,
            "classId": 1549541,
            "description": "",
            "geometryType": "rectangle",
            "labelerLogin": "jacobsolawetz",
            "createdAt": "2020-06-17T16:56:07.802Z",
            "updatedAt": "2020-06-17T16:59:10.242Z",
            "tags": [],
            "classTitle": "House",
            "points": {
                "exterior": [
                    [
                        294,
                        283
                    ],
                    [
                        398,
                        376
                    ]
                ],
                "interior": []
            }
        },
        {
            "id": 466098975,
            "classId": 1549541,
            "description": "",
            "geometryType": "rectangle",
            "labelerLogin": "jacobsolawetz",
            "createdAt": "2020-06-17T16:56:17.388Z",
            "updatedAt": "2020-06-17T16:59:10.242Z",
            "tags": [],
            "classTitle": "House",
            "points": {
                "exterior": [
                    [
                        456,
                        243
                    ],
                    [
                        561,
                        349
                    ]
                ],
                "interior": []
            }
        },

Supervise.ly Annotation Format

Each object has an ID and a class and some points defining the objects bounds.

How do we use this annotation format in an open source computer vision model?

The YOLO Darknet Format

The YOLO Darknet format is the annotation format used to train YOLOv3, train YOLOv4, or train YOLOv4 tiny. See here for a thorough discussion of the YOLOv4 model.

The YOLO TXT format is a simple annotation format. You have one .txt annotation file for each image, and a .labels file for class labels.

YOLO Darknet file structure

In the _darknet.labels file there will be a class map, mapping integer class outputs to the class name, by the position that they occur in the list.

Acanthuridae (Surgeonfishes)
Balistidae (Triggerfishes)
Carangidae (Jacks)
Ephippidae (Spadefishes)
Labridae (Wrasse)
Lutjanidae (Snappers)
Pomacanthidae (Angelfishes)
Pomacentridae (Damselfishes)
Scaridae (Parrotfishes)
Scombridae (Tunas)
Serranidae (Groupers)
Shark (Selachimorpha)
Zanclidae (Moorish Idol)

Example .labels Class Map for YOLO Darknet

The individual .txt annotations specify the bounding box coordinates for each image.

0 0.4735576923076923 0.4855769230769231 0.2620192307692308 0.171875
0 0.24519230769230768 0.3449519230769231 0.17548076923076922 0.12259615384615384
0 0.6634615384615384 0.22716346153846154 0.2776442307692308 0.18629807692307693
0 0.5456730769230769 0.1045673076923077 0.21754807692307693 0.14182692307692307
0 0.4338942307692308 0.2776442307692308 0.20793269230769232 0.15264423076923078
0 0.8894230769230769 0.17668269230769232 0.21514423076923078 0.15264423076923078
0 0.7800480769230769 0.44350961538461536 0.2644230769230769 0.1935096153846154
0 0.8161057692307693 0.6730769230769231 0.27283653846153844 0.21995192307692307
0 0.7115384615384616 0.8305288461538461 0.23798076923076922 0.16826923076923078
0 0.8870192307692307 0.8353365384615384 0.18509615384615385 0.17908653846153846
0 0.6346153846153846 0.6754807692307693 0.16947115384615385 0.14903846153846154
0 0.5288461538461539 0.6478365384615384 0.23798076923076922 0.17548076923076922
0 0.30288461538461536 0.8485576923076923 0.2403846153846154 0.20552884615384615
0 0.46274038461538464 0.8076923076923077 0.18509615384615385 0.14543269230769232
0 0.12980769230769232 0.4963942307692308 0.19471153846153846 0.171875
0 0.09495192307692307 0.71875 0.18990384615384615 0.15985576923076922
0 0.06490384615384616 0.46033653846153844 0.12980769230769232 0.16826923076923078
0 0.3449519230769231 0.6526442307692307 0.21995192307692307 0.1935096153846154
0 0.7860576923076923 0.05048076923076923 0.24759615384615385 0.10096153846153846

YOLO .txt file specifying bounding box coordinates

The first digit corresponds to the class name mapped in the .labels file. So in this .txt file we have a picture full of Surgeonfishes.

The YOLO Darknet format is a barebones flexible annotation format for training object detectors in the Darknet framework.

Converting from Supervise.ly to YOLO Darknet

We could imagine how we would convert Supervisely annotation to YOLO Darknet TXT by writing a script to parse through the the Supervisely annotations and normalize each box and print it on an annotation line. We would also have to create a class map and store that as a .labels file.

But this is Convert Supervise.ly in two minutes!

We can quickly convert our annotations using Roboflow.

First, load your dataset into Roboflow by creating a free Roboflow account. Then create a new dataset.

Creating a new dataset in Roboflow

And upload your Supervise.ly folder after unzipping it.

Uploading Supervisely Annotations by dragging and dropping

Then on the dataset page, choose the preprocessing and data augmentation steps you would like and hit Generate. After generating, you can click Export to output your dataset. Choose YOLO Darknet format.

Choose YOLO Darknet format

You can receive your export back in a .zip file or with a curl link to import your data into a training setting.

Downloading converted data format

🎉 Congratulations! Now you have your Supervisely dataset in the portable annotation format you need to build your application.

Conclusion

In this guide, we have walked through the Supervisely format, the YOLO Darknet format, and we have shown how you can convert Supervisely annotations to YOLO Darknet in a matter of minutes.

This guide should provide the necessary tools to convert Supervisely to other annotations formats such as:

As a next step, I suggest training a model with your new capabilities. I especially recommend checking out our tutorial on:

Training a YOLOv5 Object Detector