> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cvat-ai/cvat/llms.txt
> Use this file to discover all available pages before exploring further.

# Key concepts

> Understanding CVAT's core concepts - projects, tasks, jobs, labels, and annotation workflows

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
```

<Info>
  Understanding this hierarchy is key to organizing your annotation projects efficiently.
</Info>

## Organizations

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

<Tabs>
  <Tab title="Overview">
    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.
  </Tab>

  <Tab title="Use cases">
    **When to use organizations:**

    * Multi-team companies
    * Agency serving multiple clients
    * Departments within a company
    * Separating development and production work

    **Personal workspace:**
    For individual users or small teams, organizations are optional. You can work directly in your personal workspace.
  </Tab>
</Tabs>

## 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

<CardGroup cols={2}>
  <Card title="Multiple batches" icon="layer-group">
    When annotating data in multiple batches with consistent labels (e.g., 10 batches of street scene images).
  </Card>

  <Card title="Team collaboration" icon="users">
    When multiple team members work on related tasks and need to share label definitions.
  </Card>

  <Card title="Quality control" icon="chart-line">
    When you need project-level quality reports and metrics across all tasks.
  </Card>

  <Card title="Label management" icon="tags">
    When you want to update labels once and have changes apply to all tasks.
  </Card>
</CardGroup>

### Project attributes

```python theme={null}
# 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'}
    ]
})
```

<Note>
  Projects are optional. You can create standalone tasks if you don't need shared labels or project-level organization.
</Note>

## 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

<Tabs>
  <Tab title="Annotation 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)
  </Tab>

  <Tab title="Interpolation mode">
    For **videos** where objects move across frames:

    * Create tracks that span multiple frames
    * Automatic interpolation between keyframes
    * Objects have consistent IDs across frames

    Use when: Tracking objects over time (surveillance, autonomous driving)
  </Tab>
</Tabs>

### Data types

CVAT supports multiple data types:

<AccordionGroup>
  <Accordion title="Images (2D)">
    * Formats: JPEG, PNG, BMP, TIFF, WebP
    * Best for: Object detection, segmentation, classification
    * Example: Photo datasets, medical images, satellite imagery
  </Accordion>

  <Accordion title="Videos (2D)">
    * Formats: MP4, AVI, MOV, MPEG, WebM
    * Best for: Object tracking, action recognition
    * Example: Surveillance footage, sports analysis, autonomous driving
  </Accordion>

  <Accordion title="Point clouds (3D)">
    * Formats: PCD, PLY, Velodyne format
    * Best for: 3D object detection with cuboids
    * Example: LiDAR data, 3D scanning, robotics
  </Accordion>
</AccordionGroup>

## 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:

<Steps>
  <Step title="Annotation stage">
    **State: New → In Progress → Completed**

    Annotator creates initial labels:

    * Draw shapes around objects
    * Assign labels and attributes
    * Track objects across frames (video)
  </Step>

  <Step title="Validation stage">
    **State: New → In Progress → Completed/Rejected**

    Reviewer checks annotation quality:

    * Verify label accuracy
    * Check for missing annotations
    * Open issues for corrections needed
    * Accept or reject the work
  </Step>

  <Step title="Acceptance stage">
    **State: New → In Progress → Completed/Rejected**

    Final approval:

    * Address validation issues
    * Make final corrections
    * Mark as completed
  </Step>
</Steps>

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

### 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

```bash theme={null}
# Assign a job via CLI
cvat-cli --auth user:password task assign \
  --job-id 123 \
  --assignee username
```

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

## Labels and attributes

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

### Labels

A label represents a class or category of objects:

```json theme={null}
{
  "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:

<Tabs>
  <Tab title="Any">
    Can be used with any shape type (default).
  </Tab>

  <Tab title="Rectangle">
    Bounding box only (axis-aligned or rotated).
  </Tab>

  <Tab title="Polygon">
    Closed polygon shapes only.
  </Tab>

  <Tab title="Polyline">
    Open polyline shapes only.
  </Tab>

  <Tab title="Points">
    Individual points only.
  </Tab>

  <Tab title="Ellipse">
    Ellipse shapes only.
  </Tab>

  <Tab title="Cuboid">
    3D cuboids only (for 3D tasks).
  </Tab>

  <Tab title="Skeleton">
    Skeleton with predefined keypoints (for pose estimation).
  </Tab>

  <Tab title="Mask">
    Segmentation masks only.
  </Tab>

  <Tab title="Tag">
    Image-level labels (no shape).
  </Tab>
</Tabs>

### Attributes

Attributes add additional properties to annotations:

```json theme={null}
{
  "name": "occluded",
  "mutable": true,
  "input_type": "checkbox",
  "default_value": "false"
}
```

**Attribute types:**

<CardGroup cols={2}>
  <Card title="Checkbox" icon="square-check">
    Boolean true/false value

    Example: `occluded`, `truncated`
  </Card>

  <Card title="Select (dropdown)" icon="list">
    Choose from predefined options

    Example: `vehicle_type: [sedan, suv, truck]`
  </Card>

  <Card title="Radio" icon="circle-dot">
    Single choice from options

    Example: `weather: [sunny, cloudy, rainy]`
  </Card>

  <Card title="Number" icon="hashtag">
    Numeric value

    Example: `confidence: 0-100`
  </Card>

  <Card title="Text" icon="text">
    Free-form text input

    Example: `license_plate`, `notes`
  </Card>
</CardGroup>

**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:

```json theme={null}
{
  "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

<Tabs>
  <Tab title="Rectangle">
    **Bounding box** - Most common shape

    * Axis-aligned rectangles
    * Rotated rectangles (for oriented objects)
    * Use: Object detection, general-purpose labeling
  </Tab>

  <Tab title="Polygon">
    **Closed polygon** - Precise boundaries

    * Variable number of points
    * Follows object contours exactly
    * Use: Instance segmentation, precise object boundaries
  </Tab>

  <Tab title="Polyline">
    **Open line** - Linear features

    * Connected line segments
    * Not closed
    * Use: Roads, boundaries, paths
  </Tab>

  <Tab title="Points">
    **Individual points** - Landmarks

    * Single or multiple points
    * Use: Keypoint detection, landmarks, small objects
  </Tab>

  <Tab title="Cuboid">
    **3D bounding box** - 3D objects

    * 8 vertices in 3D space
    * Use: 3D object detection, LiDAR data
  </Tab>

  <Tab title="Ellipse">
    **Oval shape**

    * Center point with two radii
    * Use: Circular or oval objects
  </Tab>

  <Tab title="Mask">
    **Pixel-wise segmentation**

    * Bitmap mask
    * Use: Semantic segmentation, fine-grained boundaries
  </Tab>

  <Tab title="Skeleton">
    **Pose structure** - Keypoints with connections

    * Predefined keypoints
    * Edges connecting keypoints
    * Use: Pose estimation, human/animal poses
  </Tab>

  <Tab title="Tag">
    **Image label** - No spatial information

    * Entire image classification
    * Use: Image classification, scene categorization
  </Tab>
</Tabs>

### Shapes vs tracks

<Tabs>
  <Tab title="Shapes">
    **Static annotations** on single frames:

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

    Use for: Image datasets, independent frames
  </Tab>

  <Tab title="Tracks">
    **Temporal annotations** across multiple frames:

    * Created in interpolation mode (video)
    * Objects have consistent IDs
    * Automatic interpolation between keyframes
    * Can have per-frame mutable attributes

    Use for: Video annotation, object tracking
  </Tab>
</Tabs>

## User roles and permissions

CVAT has a flexible role-based access control system.

### Roles

<CardGroup cols={2}>
  <Card title="Admin" icon="user-shield">
    **Full system access**

    * Manage all users and organizations
    * Access all projects and tasks
    * Configure system settings
    * Manage cloud storage connections
  </Card>

  <Card title="Owner" icon="crown">
    **Resource creator**

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

  <Card title="Assignee" icon="user-check">
    **Assigned worker**

    * Annotate assigned jobs
    * Update job state
    * View task details
    * Submit annotations
  </Card>

  <Card title="Worker" icon="user">
    **Team member**

    * Access assigned jobs
    * Create annotations
    * Report issues
    * Basic permissions
  </Card>
</CardGroup>

### 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

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

## 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

<Info>
  Learn more about quality control in the [Quality Control guide](/projects/quality-control).
</Info>

## Next steps

Now that you understand CVAT's core concepts:

<CardGroup cols={2}>
  <Card title="Annotation guide" icon="pen" href="/annotation/editor-overview">
    Learn annotation tools and techniques
  </Card>

  <Card title="Project management" icon="folder" href="/projects/creating-projects">
    Best practices for organizing projects
  </Card>

  <Card title="Quality control" icon="shield-check" href="/projects/quality-control">
    Set up collaborative annotation workflows
  </Card>

  <Card title="API documentation" icon="code" href="/api/overview">
    Automate with Python SDK or CLI
  </Card>
</CardGroup>