Key concepts

This guide explains the fundamental concepts and architecture of CVAT to help you structure your annotation projects effectively.

Hierarchy overview

CVAT uses a hierarchical structure to organize annotation work:

Organization (optional)
  └── Project
      ├── Labels (shared across tasks)
      └── Task
          ├── Data (images/videos)
          └── Job (work assignment)
              └── Annotations

Understanding this hierarchy is key to organizing your annotation projects efficiently.

Organizations

Organizations are the top-level entity for managing teams and resources.

Overview
Use cases

Organizations allow you to:

Group projects and tasks
Manage team members and permissions
Share resources across teams
Isolate data between different organizations

Each user can belong to multiple organizations or work in their personal workspace.

Projects

Projects group related tasks and define shared label schemas.

What is a project?

A project represents a collection of related annotation tasks that share:

Common labels: Label definitions with attributes
Team members: Assigned annotators and reviewers
Configuration: Bug tracker, storage settings
Quality control: Validation rules and quality targets

When to use projects

Multiple batches

When annotating data in multiple batches with consistent labels (e.g., 10 batches of street scene images).

Team collaboration

When multiple team members work on related tasks and need to share label definitions.

Quality control

When you need project-level quality reports and metrics across all tasks.

Label management

When you want to update labels once and have changes apply to all tasks.

Project attributes

# Creating a project via SDK
project = client.projects.create({
    'name': 'Autonomous Driving Dataset',
    'labels': [
        {
            'name': 'car',
            'color': '#ff0000',
            'attributes': [
                {
                    'name': 'occluded',
                    'mutable': True,
                    'input_type': 'checkbox',
                    'default_value': 'false'
                },
                {
                    'name': 'vehicle_type',
                    'mutable': False,
                    'input_type': 'select',
                    'values': ['sedan', 'suv', 'truck', 'van']
                }
            ]
        },
        {'name': 'pedestrian', 'color': '#00ff00'},
        {'name': 'traffic_light', 'color': '#0000ff'}
    ]
})

Projects are optional. You can create standalone tasks if you don’t need shared labels or project-level organization.

Tasks

Tasks contain the actual data to be annotated.

What is a task?

A task represents a single annotation unit that includes:

Data: Images, video, or 3D point clouds
Jobs: Subdivisions of the task for parallel work
Metadata: Name, owner, status, creation date
Settings: Overlap, segment size, chunk size

Task properties

Property	Description	Example
Name	Descriptive identifier	”Street scenes - batch 1”
Data	Media files to annotate	1000 images or 1 video
Dimension	2D or 3D data	`2d`, `3d`
Mode	Annotation or interpolation	Images vs video
Overlap	Frames shared between jobs	5 frames
Segment size	Frames per job	100 frames
Chunk size	Frames per cached chunk	72 frames
Status	Workflow status	annotation, validation, completed

Task modes

Annotation mode
Interpolation mode

For image sequences where each frame is independent:

Annotate each image separately
No temporal tracking
Suitable for classification, detection, segmentation

Use when: Frames are unrelated (photo collections, medical images)

Data types

CVAT supports multiple data types:

Images (2D)

Formats: JPEG, PNG, BMP, TIFF, WebP
Best for: Object detection, segmentation, classification
Example: Photo datasets, medical images, satellite imagery

Videos (2D)

Formats: MP4, AVI, MOV, MPEG, WebM
Best for: Object tracking, action recognition
Example: Surveillance footage, sports analysis, autonomous driving

Point clouds (3D)

Formats: PCD, PLY, Velodyne format
Best for: 3D object detection with cuboids
Example: LiDAR data, 3D scanning, robotics

Jobs

Jobs are the fundamental unit of work assignment in CVAT.

What is a job?

When a task is created, it’s automatically divided into jobs based on the segment size setting. Each job:

Contains a subset of frames from the task
Can be assigned to one team member
Has its own status (new, in progress, completed, rejected)
Tracks progress independently

Job workflow stages

Jobs move through different stages and states:

Annotation stage

State: New → In Progress → CompletedAnnotator creates initial labels:

Draw shapes around objects
Assign labels and attributes
Track objects across frames (video)

Validation stage

State: New → In Progress → Completed/RejectedReviewer checks annotation quality:

Verify label accuracy
Check for missing annotations
Open issues for corrections needed
Accept or reject the work

Acceptance stage

State: New → In Progress → Completed/RejectedFinal approval:

Address validation issues
Make final corrections
Mark as completed

Stages are managed by supervisors, while states can be updated by the assignee. This separation ensures proper workflow control.

Job types

CVAT supports different job types for quality control:

Job Type	Purpose	Description
Annotation	Standard annotation work	Regular jobs for annotators
Ground truth	Quality reference	Gold standard annotations for validation
Consensus replica	Inter-annotator agreement	Multiple annotators label the same frames

Job assignment

# Assign a job via CLI
cvat-cli --auth user:password task assign \
  --job-id 123 \
  --assignee username

Use the overlap setting to have frames appear in multiple jobs. This helps maintain annotation consistency at job boundaries.

Labels and attributes

Labels define what you’re annotating, and attributes add detailed properties.

Labels

A label represents a class or category of objects:

{
  "name": "car",
  "color": "#ff0000",
  "type": "any"
}

Label properties:

Name: Unique identifier (e.g., “car”, “person”, “road”)
Color: Display color in the UI (hex format)
Type: Allowed annotation shapes (see below)

Label types

Labels can be restricted to specific annotation shapes:

Can be used with any shape type (default).

Attributes

Attributes add additional properties to annotations:

{
  "name": "occluded",
  "mutable": true,
  "input_type": "checkbox",
  "default_value": "false"
}

Attribute types:

Checkbox

Boolean true/false valueExample: occluded, truncated

Select (dropdown)

Choose from predefined optionsExample: vehicle_type: [sedan, suv, truck]

Radio

Single choice from optionsExample: weather: [sunny, cloudy, rainy]

Number

Numeric valueExample: confidence: 0-100

Text

Free-form text inputExample: license_plate, notes

Mutable vs Immutable:

Mutable: Value can change between frames (e.g., occluded in video)
Immutable: Value is constant for the entire track (e.g., vehicle_type)

Sublabels (skeleton structure)

For skeleton annotation, labels can have sublabels representing keypoints:

{
  "name": "person",
  "type": "skeleton",
  "sublabels": [
    {"name": "head"},
    {"name": "left_shoulder"},
    {"name": "right_shoulder"},
    {"name": "left_elbow"},
    {"name": "right_elbow"}
  ],
  "svg": "<line x1='head' y1='left_shoulder' ... />"
}

Annotation shapes

CVAT supports multiple shape types for different annotation needs.

Shape types

Bounding box - Most common shape

Axis-aligned rectangles
Rotated rectangles (for oriented objects)
Use: Object detection, general-purpose labeling

Shapes vs tracks

Shapes
Tracks

Static annotations on single frames:

Created in annotation mode
Each frame has independent annotations
No temporal relationship

Use for: Image datasets, independent frames

User roles and permissions

CVAT has a flexible role-based access control system.

Roles

Admin

Full system access

Manage all users and organizations
Access all projects and tasks
Configure system settings
Manage cloud storage connections

Owner

Resource creator

Full control over created resources
Assign tasks to team members
Manage project/task settings
Delete resources

Assignee

Assigned worker

Annotate assigned jobs
Update job state
View task details
Submit annotations

Worker

Team member

Access assigned jobs
Create annotations
Report issues
Basic permissions

Permission levels

Permissions are hierarchical:

Organization scope
  └── Project scope
      └── Task scope
          └── Job scope

Organization member: Can view organization resources
Project member: Can access project tasks
Task assignee: Can annotate specific tasks
Job assignee: Can work on specific jobs

Permissions are enforced at the API level. Users can only access resources they have explicit permissions for through organization membership, project assignment, or ownership.

Quality control concepts

CVAT includes built-in quality control features.

Ground truth jobs

Ground truth jobs serve as gold standard reference annotations:

One per task
Used to measure annotation quality
Compare against other jobs for quality metrics

Quality reports

Generate quality reports to measure:

Accuracy: Overall annotation correctness
Precision: False positive rate
Recall: False negative rate

Reports can be generated at:

Job level
Task level
Project level

Conflict types

Quality reports identify conflicts:

Conflict Type	Description
Missing annotation	Object not labeled
Extra annotation	Incorrect label added
Mismatching label	Wrong label assigned
Low overlap	Bounding box misalignment
Mismatching attributes	Incorrect attribute values

Honeypot frames

Validation frames distributed across jobs:

Pre-annotated frames
Used to verify annotator quality
Automatically checked against ground truth

Learn more about quality control in the Quality Control guide.

Next steps

Now that you understand CVAT’s core concepts:

Annotation guide

Learn annotation tools and techniques

Project management

Best practices for organizing projects

Quality control

Set up collaborative annotation workflows

API documentation

Automate with Python SDK or CLI

Get Started

Annotation

Projects & Tasks

Dataset Management

Integrations

Account & Organization

​Hierarchy overview

​Organizations

​Projects

​What is a project?

​When to use projects

Multiple batches

Team collaboration

Quality control

Label management

​Project attributes

​Tasks

​What is a task?

​Task properties

​Task modes

​Data types

​Jobs

​What is a job?

​Job workflow stages

​Job types

​Job assignment

​Labels and attributes

​Labels

​Label types

​Attributes

Checkbox

Select (dropdown)

Radio

Number

Text

​Sublabels (skeleton structure)

​Annotation shapes

​Shape types

​Shapes vs tracks

​User roles and permissions

​Roles

Admin

Owner

Assignee

Worker

​Permission levels

​Quality control concepts

​Ground truth jobs

​Quality reports

​Conflict types

​Honeypot frames

​Next steps

Annotation guide

Project management

Quality control

API documentation

Build docs developers (and LLMs) love

Hierarchy overview

Organizations

Projects

What is a project?

When to use projects

Project attributes

Tasks

What is a task?

Task properties

Task modes

Data types

Jobs

What is a job?

Job workflow stages

Job types

Job assignment

Labels and attributes

Labels

Label types

Attributes

Sublabels (skeleton structure)

Annotation shapes

Shape types

Shapes vs tracks

User roles and permissions

Roles

Permission levels

Quality control concepts

Ground truth jobs

Quality reports

Conflict types

Honeypot frames

Next steps