Types

The types module provides data models for CVAT annotations and related objects. These classes are used to represent various annotation types and their attributes.

Annotation Types

Box

A bounding box annotation in CVAT.

Boxes are used to define rectangular regions in images using top-left and bottom-right coordinates. They can be converted to polygons and segmentation masks.

ATTRIBUTE	DESCRIPTION
label	The label/class name for this box TYPE: str
xtl	X-coordinate of the top-left corner TYPE: float
ytl	Y-coordinate of the top-left corner TYPE: float
xbr	X-coordinate of the bottom-right corner TYPE: float
ybr	Y-coordinate of the bottom-right corner TYPE: float
occluded	Whether this box is occluded (0 for no, 1 for yes) TYPE: int
z_order	The z-order/layer of this box TYPE: int
source	The source of this annotation (e.g. "manual", "automatic") TYPE: str
attributes	List of additional attributes for this box TYPE: List[Attribute]

Polygon

A polygon annotation in CVAT.

Polygons are used to define regions in images using a series of connected points. They can be converted to segmentation masks and support various geometric operations.

ATTRIBUTE	DESCRIPTION
label	The label/class name for this polygon TYPE: str
source	The source of this annotation (e.g. "manual", "automatic") TYPE: str
occluded	Whether this polygon is occluded (0 for no, 1 for yes) TYPE: int
points	List of (x,y) coordinates defining the polygon vertices TYPE: List[Tuple[float, float]]
z_order	The z-order/layer of this polygon TYPE: int
attributes	List of additional attributes for this polygon TYPE: List[Attribute]

Mask

A binary mask annotation in CVAT.

Masks are used to store pixel-wise segmentations efficiently using run-length encoding (RLE). They can be created from numpy arrays or PIL Images and support various operations.

ATTRIBUTE	DESCRIPTION
label	The label/class name for this mask TYPE: str
source	The source of this annotation (e.g. "manual", "automatic") TYPE: str
occluded	Whether this mask is occluded (0 for no, 1 for yes) TYPE: int
z_order	The z-order/layer of this mask TYPE: int
rle	Run-length encoded string representing the mask TYPE: str
top	Top coordinate of the mask's bounding box TYPE: int
left	Left coordinate of the mask's bounding box TYPE: int
height	Height of the mask's bounding box TYPE: int
width	Width of the mask's bounding box TYPE: int
attributes	List of additional attributes for this mask TYPE: List[Attribute]

Polyline

Container Types

ImageAnnotation

Annotation data for a single image in CVAT.

Contains all annotation shapes (boxes, polygons, masks, polylines, ellipses) associated with an image.

ATTRIBUTE	DESCRIPTION
id	Unique identifier for the image TYPE: str
name	Filename of the image TYPE: str
subset	Optional subset the image belongs to (e.g., "train", "test") TYPE: Optional[str]
task_id	ID of the task this image belongs to TYPE: Optional[str]
job_id	ID of the job this image belongs to TYPE: Optional[str]
width	Image width in pixels TYPE: int
height	Image height in pixels TYPE: int
boxes	List of bounding box annotations TYPE: List[Box]
polygons	List of polygon annotations TYPE: List[Polygon]
masks	List of mask annotations TYPE: List[Mask]
polylines	List of polyline annotations TYPE: List[Polyline]
ellipses	List of ellipse annotations TYPE: List[Ellipse]

Example

image = ImageAnnotation(
    id="1",
    name="frame_000001.jpg",
    subset="train",
    task_id="906591",
    job_id="1247749",
    width=1920,
    height=1080,
    boxes=[
        Box(label="car", xtl=100, ytl=200, xbr=300, ybr=400)
    ],
    masks=[
        Mask(label="person", points="100,200;300,400", z_order=1)
    ],
    ellipses=[
        Ellipse(label="defect", cx=500, cy=600, rx=50, ry=30)
    ]
)

JobStatus

Status information for a CVAT job.

Jobs are subdivisions of tasks that can be assigned to different annotators. Each job has a stage (e.g., "annotation") and state (e.g., "completed").

ATTRIBUTE	DESCRIPTION
task_id	ID of the task this job belongs to TYPE: str
job_id	Unique identifier for the job TYPE: int
task_name	Name of the parent task TYPE: str
stage	Current stage of the job (e.g., "annotation", "validation") TYPE: str
state	Current state of the job (e.g., "completed", "in_progress") TYPE: str
assignee	Username or details of the person assigned to the job TYPE: Optional[Union[str, Dict[str, Any]]]

Example

# Create from job status data
status = JobStatus(
    task_id="906591",
    job_id=520016,
    task_name="Batch 1",
    stage="annotation",
    state="completed",
    assignee="john.doe"
)

# Create from CVAT SDK job object
status = JobStatus.from_job(job, task_name="Batch 1")
print(status.assignee_email)  # Get assignee's email

Label Types

Label

LabelAttribute

Attribute

Project Types

Project

A CVAT project containing tasks and labels.

ATTRIBUTE	DESCRIPTION
id	Unique identifier for the project TYPE: str
name	Human-readable name of the project TYPE: str
created	Timestamp when the project was created TYPE: str
updated	Timestamp when the project was last updated TYPE: str
labels	List of label definitions for the project TYPE: List[Label]

Example

project = Project(
    id="217969",
    name="My Project",
    created="2024-01-01 12:00:00.000000+00:00",
    updated="2024-01-01 12:00:00.000000+00:00",
    labels=[
        Label(name="car", color="#ff0000", type="any"),
        Label(name="person", color="#00ff00", type="any")
    ]
)

Task

A CVAT task representing a unit of work for annotation.

Tasks are created within projects and contain images to be annotated. Each task can be split into multiple jobs for parallel annotation.

ATTRIBUTE	DESCRIPTION
task_id	Unique identifier for the task TYPE: str
name	Human-readable name of the task TYPE: str
url	Optional URL to access the task's data or API endpoint TYPE: Optional[str]

Example

task = Task(
    task_id="906591",
    name="Batch 1",
    url="https://app.cvat.ai/api/jobs/520016"
)