Import CVAT

Use create_project_from_cvat_start() to initiate a CVAT project import into Encord.

The import runs asynchronously and returns an import UUID, that is then passed to create_project_from_cvat_get_result() to poll for the final import status and retrieve the created project information.

Method example

cvat_import_uuid = user_client.create_project_from_cvat_start(
    import_method=LocalImport(file_path=CVAT_EXPORT_DIR),
    dataset_name=DATASET_NAME,
    review_mode=ReviewMode.UNLABELLED,
    transform_bounding_boxes_to_polygons=False,
)

Expected CVAT export structure:

<CVAT_EXPORT_DIR>/
├── annotations.xml
└── images/
    ├── image1.jpg
    ├── image2.jpg
    └── ...

Your Encord Ontology must match the labels and attributes defined in the CVAT export.

Full example

# Import dependencies
from encord import EncordUserClient
from encord.orm.project import ReviewMode
from encord.utilities.client_utilities import LocalImport

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key

# Path to the exported CVAT folder. It must contain:
#   <CVAT_EXPORT_DIR>/annotations.xml   <- the CVAT XML export
#   <CVAT_EXPORT_DIR>/images/           <- referenced image files
#
# Export using:
#   "CVAT for images 1.1"
#
# Ensure:
#   "Save images" is enabled.
CVAT_EXPORT_DIR = "/Users/chris-encord/cvat-exports/b1"

# Name of the Encord dataset/project to create.
DATASET_NAME = "b1"

# Create Encord client using SSH private key authentication.
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use:
    # domain="https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Step 1:
# Start the asynchronous CVAT import.
#
# This uploads the images and submits the CVAT annotations.xml file.
cvat_import_uuid = user_client.create_project_from_cvat_start(
    import_method=LocalImport(file_path=CVAT_EXPORT_DIR),
    dataset_name=DATASET_NAME,
    review_mode=ReviewMode.UNLABELLED,
    transform_bounding_boxes_to_polygons=False,
)

print(f"CVAT import started. import_uuid={cvat_import_uuid}")

# Step 2:
# Poll until the import process completes.
result = user_client.create_project_from_cvat_get_result(cvat_import_uuid)

# Step 3:
# Check whether the import succeeded.
if hasattr(result, "project_hash"):
    print(
        f"Import succeeded. "
        f"project_hash={result.project_hash}, "
        f"dataset_hash={result.dataset_hash}"
    )

    # Optional:
    # Display warnings, errors, or informational messages returned by the import.
    issues = getattr(result, "issues", None)

    if issues and (issues.errors or issues.warnings or issues.info):
        print(f"Import issues: {issues}")

else:
    print(f"Import failed. issues={getattr(result, 'issues', None)}")

<?xml version="1.0" encoding="utf-8"?>
<annotations>
  <version>1.1</version>

  <meta>
    <task>
      <id>1002075</id>
      <name>b1</name>
      <size>6</size>

      <labels>
        <label>
          <name>apple</name>
          <type>rectangle</type>

          <attributes>
            <attribute>
              <name>colour</name>
              <input_type>radio</input_type>
              <default_value>red</default_value>

              <values>
                red
                green
                blue
              </values>
            </attribute>
          </attributes>
        </label>

        <label>
          <name>stuff</name>
          <type>any</type>
        </label>
      </labels>
    </task>
  </meta>

  <image
    id="1"
    name="example.jpg"
    width="600"
    height="360"
  >
    <polygon
      label="stuff"
      points="400.36,108.26;375.89,135.51;380.34,164.42"
    />

    <box
      label="stuff"
      xtl="381.46"
      ytl="111.59"
      xbr="419.82"
      ybr="175.54"
    />

    <mask
      label="apple"
      width="220"
      height="244"
    >
      <attribute name="colour">green</attribute>
    </mask>
  </image>
</annotations>