Import CVAT

If you are using CVAT for image and video annotations, we have made it easy to import your entire project or single tasks to Encord. Importing into Encord automatically creates the ontology and imports all labels and classifications.

ℹ️

Note

Videos in CVAT projects must be exported as images to ensure successful import into Encord.

Comparing Annotation Shapes: CVAT vs Encord

The following table shows which CVAT shapes are supported in Encord.

Exporting from CVAT

You can either export an entire project or an individual task from CVAT. Keep in mind that every new export creates an entirely new project.

Use the CVAT UI to export your project:

For project exports:

Or for task exports:

Then in the popup, ensure that images are saved too:

ℹ️

Note

Choose the “CVAT for images 1.1” export format for images. Projects containing videos have to be exported as images.

Once downloaded, unzip the file to create a directory that contains all your images, together with an annotations.xml file which contains your CVAT ontology, CVAT labels, and CVAT tags (which are the equivalent of Encord Classifications for entire images/frames).

Importing CVAT videos into Encord

Videos in CVAT projects must be exported as images to ensure successful import into Encord. Images can be added to Encord as Single Images (each image is a separate data unit), or as Image Groups (all images have been combined into a single data unit).

See the Importing a CVAT project section below for information.

Importing a CVAT project

CVAT projects are imported into Encord as Manual QA projects. We recommend converting Manual QA projects into Workflow projects using the following recipe:

To use this recipe, you need to first create a Workflow template in the Encord platform.

ℹ️

Note

we recommend increasing the EncordUserClient request timeouts, as imports can take a significant amount of time.

The following script can be used to import CVAT projects into Encord.

from pathlib import Path

import prettyprinter as pp
from encord import EncordUserClient
from encord.utilities.client_utilities import CvatImporterSuccess, LocalImport

# Authenticate using the path to your private key. Replace <private_key_path> with the path to your key
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")

# Increase networking timeouts for this long running operation.
timeout = 1800
user_client.user_config.read_timeout = timeout
user_client.user_config.write_timeout = timeout
user_client.user_config.connect_timeout = timeout

# We have placed the unzipped Pizza Project directory into a
# `data` folder relative to this script
data_folder = "data/Pizza Project"
dataset_name = "Pizza Images Dataset"
cvat_importer_ret = user_client.create_project_from_cvat(
    LocalImport(file_path=data_folder), dataset_name
)

# Check if the import was a success and inspect the return value
if type(cvat_importer_ret) == CvatImporterSuccess:
    print(f"project_hash = {cvat_importer_ret.project_hash}")
    print(f"dataset_hash = {cvat_importer_ret.dataset_hash}")
    pp.pprint(cvat_importer_ret.issues)

project_hash = "0a5c5a7e-da96-44c1-a355-a53259c0e73e"
dataset_hash = "bd19ef7c-b698-434f-a7cc-d3c01fc5da3e"
encord.utilities.client_utilities.Issues(
    errors=[],
    warnings=[
        encord.utilities.client_utilities.Issue(
            issue_type='In Encord a specific label can only have one possible shape. If '
                'the same label is used for multiple shapes, multiple labels need '
                'to be created.',
            instances=[
                "The label `not_yet_annotated` was used for multiple shapes "
                "`[<CvatShape.POLYGON: 'polygon'>, <CvatShape.TAG: 'tag'>]`. "
                "Each shape which is translatable to Encord will lead to a "
                "distinct editor entry."
            ]
        )
    ],
    infos=[]
)
issues = None

👍

Tip

If image file names in the CVAT export do not exactly correspond to the file names in the annotation .xml file, use the map_filename_to_cvat_name parameter in LocalImport to map image file names to the names in the .xml file. The following example removes image file extensions so that image_0123.jpeg is recognized as image_0123.

Python

cvat_importer_ret = user_client.create_project_from_cvat(
   LocalImport(
       file_path=data_folder, map_filename_to_cvat_name=lambda x: Path(x).stem
   ),
   dataset_name
)

If the return object is a CvatImporterSuccess, open the Encord platform to ensure that the project was added.

For possible import options and return types see the SDK reference.

CVAT to Encord Import Limitations

We encourage you to inspect the returned Issues object closely. This object informs you about possible limitations during the project/task import.

For example, within CVAT the same label in the ontology can be used for different shapes. Within Encord, a label in the ontology is bound to a specific shape. During import, the importer will detect whether the same CVAT label was used for multiple shapes and create different Encord ontology items for each of them.

There are other limitations which are documented in the Issues object. Please reach out to the Encord team if those need clarification.