CVAT Format

CVAT XML export format for images

CVAT (Computer Vision Annotation Tool) is a popular open-source annotation tool. Panlabel supports reading and writing CVAT XML exports for object detection.

Overview

• Path type: XML file (.xml) or directory with annotations.xml
• Lossiness: Lossy (see below)
• Bbox format: Pixel-space top-left/bottom-right [xtl, ytl, xbr, ybr]
• Use case: CVAT integration, annotation workflows

Key Features

✓ Supports “for images” task exports
✓ Box annotations only (<box> elements)
✓ Preserves occluded, z_order, source attributes
✓ Preserves custom <attribute> elements
✓ Validates labels against metadata (if present)
✓ Writes minimal XML with referenced categories only
⚠️ Project exports not supported (task exports only)
⚠️ Non-box shapes (<polygon>, <polyline>, etc.) cause errors

Structure

CVAT uses a single XML file with <annotations> root:

<?xml version="1.0" encoding="utf-8"?>
<annotations>
  <version>1.1</version>
  <meta>
    <task>
      <name>My Task</name>
      <size>2</size>
      <mode>annotation</mode>
      <labels>
        <label>
          <name>person</name>
          <type>bbox</type>
        </label>
        <label>
          <name>car</name>
          <type>bbox</type>
        </label>
      </labels>
    </task>
  </meta>
  <image id="0" name="img1.jpg" width="640" height="480">
    <box label="person" occluded="0" xtl="100.0" ytl="150.0" xbr="300.0" ybr="400.0" z_order="0" source="manual">
      <attribute name="gender">male</attribute>
    </box>
  </image>
  <image id="1" name="img2.jpg" width="800" height="600"></image>
</annotations>

Bounding Box Format

CVAT uses pixel-space top-left/bottom-right coordinates:

<box xtl="100.0" ytl="150.0" xbr="300.0" ybr="400.0" />

• xtl: Top-left X (xmin)
• ytl: Top-left Y (ymin)
• xbr: Bottom-right X (xmax)
• ybr: Bottom-right Y (ymax)

This maps 1:1 to IR XYXY (no conversion needed).

Box Attributes

CVAT supports several standard attributes:

Standard Attributes

• label: Category name (required)
• occluded: 0 or 1 (default: 0)
• z_order: Integer stacking order (default: 0)
• source: Annotation source (e.g., "manual", "auto")

Custom Attributes

CVAT allows custom <attribute> elements:

<box label="car" ...>
  <attribute name="color">red</attribute>
  <attribute name="make">Honda</attribute>
</box>

Panlabel stores these as Annotation.attributes["cvat_attr_<name>"].

Attribute Mapping

Reading:

<box occluded="1" z_order="2" source="auto" ...>
  <attribute name="color">red</attribute>
</box>

IR attributes:

{
  "occluded": "1",
  "z_order": "2",
  "source": "auto",
  "cvat_attr_color": "red"
}

Writing:

• Retrieves occluded from attributes (normalizes to 0 or 1)
• Retrieves z_order from attributes (default: 0)
• Retrieves source from attributes (default: "manual")
• Writes custom attributes with cvat_attr_ prefix

Metadata Labels

CVAT XML may include label metadata in <meta><task><labels>:

<labels>
  <label>
    <name>person</name>
    <type>bbox</type>
  </label>
  <label>
    <name>background</name>
    <type>polygon</type>
  </label>
</labels>

Reader Behavior

If metadata labels are present:

• Keeps labels with <type>bbox</type> or no <type> (default: bbox)
• Verifies every <box label="..."> exists in metadata labels
• Ignores non-bbox labels (e.g., polygon)

If metadata labels are missing:

• Infers categories from <box label="..."> attributes

Reader Behavior

Input Path

Accepts:

• XML file (.xml)
• Directory containing annotations.xml

Reading Process

1. Parse XML and validate <annotations> root
2. Extract metadata labels (if present)
3. Parse each <image> element:
   • Extract id, name, width, height
   • Parse all <box> elements
   • Reject unsupported shapes (<polygon>, <polyline>, etc.)
4. Assign deterministic IDs:
   • Image IDs: by <image name> (lexicographic)
   • Category IDs: by label name (lexicographic)
   • Annotation IDs: by image order then <box> order

Validation

• Rejects project exports (only task exports supported)
• Rejects non-box shapes with hard error
• Validates box labels against metadata (if present)
• Requires unique image names

Image ID Preservation

Stores CVAT’s <image id> as Image.attributes["cvat_image_id"].

Writer Behavior

Output Structure

• If path ends with .xml: writes directly to that file
• Otherwise: creates annotations.xml inside directory

Writing Process

1. Create minimal <meta><task> with name='panlabel export'
2. Write labels only for referenced categories (not all categories)
3. Write all images (including unannotated images)
4. Write boxes sorted by annotation ID per image
5. Normalize occluded values (true/yes/1 → 1, false/no/0 → 0, else → 0)

Task Metadata

Writes minimal task metadata:

<meta>
  <task>
    <name>panlabel export</name>
    <size>10</size>
    <mode>annotation</mode>
    <labels>
      <!-- Only labels referenced by annotations -->
    </labels>
  </task>
</meta>

Empty Images

Writes image entries without boxes:

<image id="5" name="img6.jpg" width="800" height="600"></image>

Lossiness

CVAT format is lossy:

Preserved ✓

• Image names and dimensions
• CVAT image IDs (as attribute)
• Category names
• Bounding boxes (pixel XYXY)
• occluded, z_order, source attributes
• Custom <attribute> elements (as cvat_attr_*)

Not Preserved ✗

• Dataset-level metadata/licenses
• Annotation confidence
• Category supercategory
• Custom image attributes (except cvat_image_id)
• Custom annotation attributes (except standard CVAT attrs)

CVAT does not support annotation confidence scores. IR confidence values are dropped during conversion.

Usage

Read CVAT

panlabel convert annotations.xml output.json --input-format cvat --output-format ir-json

or from directory:

panlabel convert dataset/ output.json --input-format cvat --output-format ir-json

Aliases: cvat-xml

Write CVAT

panlabel convert input.json output.xml --input-format ir-json --output-format cvat

or to directory:

panlabel convert input.json output/ --input-format ir-json --output-format cvat
# Creates output/annotations.xml

Unsupported Shapes

Panlabel only supports <box> elements. Other shapes cause errors:

<polygon points="1,1;2,2;3,3" />  <!-- ERROR -->
<polyline points="1,1;2,2" />     <!-- ERROR -->
<points points="1,1" />           <!-- ERROR -->

Error message:

image 'img.jpg' contains unsupported annotation type <polygon>; only <box> is supported

Boolean Normalization

Writes normalized occluded values:

Input	Output
true, yes, 1	1
false, no, 0	0
Other or missing	0

See Also

Label Studio

Another annotation tool format

Format Overview

Compare all supported formats