# How to Use Annotations
Source: https://docs.labellerr.com/actions/annotations-guide

Everything you need to know about image annotation types in Labellerr, including Bounding Box, Polygon, Line, Segmentation, Landmark/Keypoint, and Ellipse.

## Everything you Need to Know About Image Annotation

***

### These are the annotation types that you can use on Labellerr.

1. **Bounding Box**

2. **Polygon**

3. **Polyline**

4. **Keypoint**

5. **Dot**

Once on the Labelling Screen, the tools appear on the left.

<Info>
  Only the Objects selected while making a project would be visible. More can be added from the settings
</Info>

<Frame>
  <img alt="Labelling Screen Tools" />
</Frame>

### Bounding Box

A bounding box is a rectangular frame used to mark the location of an object in an image. It is one of the most common annotation methods, typically used for object detection and localization. Use M for manual bounding box and A for AI-assisted bounding box.

<Frame>
  <img alt="Bounding Box manual Example" />
</Frame>

<Frame>
  <img alt="Bounding Box ai mode Example" />
</Frame>

<Tip>
  For more, check out this video tutorial
</Tip>

<iframe title="Bounding Box Tutorial" />

### Polygon

Polygon annotation is a computer vision technique that outlines objects by connecting a series of points to form a polygon. This accurately captures the true shape and boundaries of objects, making it ideal for handling complex or irregular shapes.

Additionally, you can place a single point to run SAM or use a box prompt to draw a bounding box around the object, enabling faster and more accurate polygon generation.

<Frame>
  <img alt="Polygon Annotation dot Example" />
</Frame>

<Frame>
  <img alt="Polygon Annotation box Example" />
</Frame>

<Tip>
  For more, check out this video tutorial
</Tip>

<iframe title="Polygon Tutorial" />

#### Drag Polygon

User can drag the cursor to draw the pixel perfect annotation on an object. Press 'Shift' key and then drag the cursor towards the boundaries of an object.

<Frame>
  <img alt="Drag Polygon" />
</Frame>

<Tip>
  Press 'N' to close the polygon or simply drag the cursor to starting point.
</Tip>

### Polyline

Line annotation is mainly used to create lines across the image.

<Frame>
  <img alt="Line Annotation Example" />
</Frame>

### Keypoint

Landmark and Key-point annotation is used in shape variation and small object detection. It works by creating dots across an image, usually used for the detection of facial features, gestures, emotions, poses and body part distinction.

<Frame>
  <img alt="Landmark/Keypoint Example" />
</Frame>

### Dot Annotation

Dot annotation is used to mark specific points in an image by placing single dots. It is commonly used for object counting, small object detection, and identifying points of interest.

<Frame>
  <img alt="Dot Annotation Example" />
</Frame>

To predict the description/brief/keywords about the image using Generative AI, visit the [Image Captioning Using Generative AI](/features/image-captioning) guide.

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Client Review
Source: https://docs.labellerr.com/actions/client-review

A guide to effectively reviewing annotated images, offering suggestions, and providing feedback on potential errors within Labellerr.

This guide provides step-by-step instructions for effectively reviewing annotated images, offering suggestions, and providing feedback on potential errors. Follow these guidelines to participate in the annotation review process seamlessly.

### 1. Access the Client Reviewer Platform

* Log in to the Labellerr platform using your credentials.
* Navigate to the "Client Review" tab on the dashboard.

<Frame>
  <img alt="Client Review Dashboard" />
</Frame>

The review screen is designed just like the labeling page, giving you access to all the same tools. This ensures you have full control over the quality and accuracy of the annotations. You can easily edit, add, or remove annotations as needed to meet your specific requirements.

<Frame>
  <img alt="Client Review Screen" />
</Frame>

### 2. Review Annotations and Provide Feedback

The bottom-left part of the screen shows a list of all annotated object names. To provide feedback on a specific annotation:

* Scroll through the list of annotated object names.
* As you hover over a specific name, the corresponding object in the image will be highlighted.

While reviewing, you can provide remarks for each annotated object. If there is a mistake in the annotation, specify the mistake, or give suggestions for improvement.

<Frame>
  <img alt="Review Feedback" />
</Frame>

### 3. Add Remarks or Suggestions

* To give remarks, click the comment icon next to the annotated object's name and type your feedback. Select "Mistake" if the annotation is incorrect, or "Suggestion" to propose improvements. Then, click the "Add Remark" button to submit your feedback.

<Frame>
  <img alt="Add Remark" />
</Frame>

### 4. Hide Annotated Objects

To hide an annotated object, click the eye icon located to the right of the annotated object's name, just after the comment icon.

<Frame>
  <img alt="Hide Object" />
</Frame>

To hide all the annotations, click on the eye icon located next to the "Annotations" heading, which groups all the annotated objects.

**Why It’s Important:**

This feature helps you focus on specific areas of the image by temporarily hiding other annotated objects. It can reduce visual clutter, making it easier to review and analyze individual annotations or their placement in detail.

### 5. Skip, Reject or Accept a file

Once the file screening is complete, you have three options:

1. To accept the file, click the "Accept" button, and the file will be ready for export.
2. If there are mistakes or suggestions, click the "Reject" button, and the file will be sent for corrections.
3. To skip the file and have another client review it, click the "Skip" button.

The "Reject" and "Accept" buttons are located at the top-right corner of the screen. To the left of the "Reject" button, click the three dots to open a dropdown menu, then select the "Skip" option.

<Frame>
  <img alt="Review Actions" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Client Review Using Grid View
Source: https://docs.labellerr.com/actions/client-review-grid

Learn how clients can efficiently review and manage annotated files in Labellerr using the grid view, with quick accept or reject options.

This feature allows clients to view files in a grid view, enabling users to quickly accept or reject files with just one click. Below, we provide step-by-step guidance on how to use this functionality.

### 1. Access the Annotated file

* Labeling must be completed within the **Label** section.
* Once labeling is done, files should be submitted.
* Files must be accepted by a reviewer. All reviewer-accepted files will then appear in the **In Client Review** section.
* Next, navigate to the **Files** section by clicking on it.

<Frame>
  <img alt="Access Files Section" />
</Frame>

* At the top of the page, in the **File Filters** section, you'll find the File status bar. Select the File status than select the '**Ready for Client Review**' filter to display relevant files. You may also apply other filters as needed to narrow down your search and click on the **Apply Filters**.

<Frame>
  <img alt="Apply Filters" />
</Frame>

Once the filter is applied, all your submitted files will be visible in the list, allowing you to view them easily in one place.

<Frame>
  <img alt="Filtered Files List" />
</Frame>

### 2. Review files in Grid View

Once the files appear, hover over the icon on the top right bar to reveal the '**Grid View**' option, then click it to switch to grid view.

<Frame>
  <img alt="Switch to Grid View" />
</Frame>

You can now zoom in and out of the image using the slider, making it easier to view your annotated file clearly and in detail, so users can confidently accept or reject the file.

### 3. Reject a file by adding relevant remarks

This feature adds remarks before rejection, ensuring clarity, transparency, and constructive feedback for better communication.

<Frame>
  <img alt="Add Remarks for Rejection" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# How to Create an Export in Labellerr
Source: https://docs.labellerr.com/actions/create-export

A guide for Supervisors, Admins, and Super Admins on creating exports of annotated data, including filtering, scheduling, and selecting formats.

<Note>
  This Guide is for Supervisors, Admins, and Super admins of a project who wish to create an export of the annotated data. In this guide, you would find filtering data for exports, setting up automated scheduled exports, and export destination and format.
</Note>

<Info>
  An export can only be created by **Supervisors, Admins, and Super admins**. In order to export, make sure that you are on the same project/workspace on which the export has to be made.
</Info>

## Creating an Export

### 1. Select Export Option

Select the **Export** option from the Taskbar.

<Frame>
  <img alt="Export Option" />
</Frame>

After which, the following screen would appear. Click on **Create export** to get started.

<Frame>
  <img alt="Create Export" />
</Frame>

Here in the redirected page, click on the File Status filters to make changes to the filter settings.

<Frame>
  <img alt="Status Filters" />
</Frame>

***

### 2. Change the Default Status Selection

Select desired filters among the dropdown option of filters. For example, if you need files for "Final export" then choose a status "**Ready for Export**". Then click the button **Apply Filters**.

<Frame>
  <img alt="Select Status Filter" />
</Frame>

On the resulting screen, you can choose All Files to export everything, or select specific files if you only want to export certain ones. Then Click on the Export Button

<Frame>
  <img alt="Export All Files" />
</Frame>

A popup window appears in which you have to fill in the essential details and then click on the **'Create'** button.

<Frame>
  <img alt="Export Details Popup" />
</Frame>

***

Here, the Export Name is compulsory.

The File Activity Log button present under `**Apply Filters**` section includes activity logs into the export generated. Enabling it includes the log of all the activities done by people having access to the project.

In the Select Questions dropdown, select the questions for which you want to create an export.

### Download Format Options

There are multiple download formats available:

1. **CSV** - Select 'CSV' from the export format list. It's a plain text format used to store tabular data, where each line represents a data record, and each field within a record is separated by a comma.

   <CardGroup>
     <Card>
       <Frame>
         <img alt="CSV Export Example 1" />
       </Frame>
     </Card>

     <Card>
       <Frame>
         <img alt="CSV Export Example 2" />
       </Frame>
     </Card>
   </CardGroup>

2. **JSON** - Select 'JSON' from the export format list. It's a lightweight data interchange format that is easy for humans to read and write and easy for machines to parse and generate. It uses key-value pairs.

3. **COCO JSON** - Select 'COCO JSON' from the export format list. COCO (Common Objects in Context) JSON format is a widely used standard for annotating and sharing object detection, segmentation, and captioning datasets. It consists of annotations that describe the locations and categories of objects in images, along with metadata about the images themselves.

4. **YOLO V5** - Select 'YOLO V5' from the export format list. This is a popular object detection algorithm that stands for "You Only Look Once version 5". It's an evolution of the YOLO (You Only Look Once) series of object detection models. YOLOv5 offers improved performance and accuracy compared to its predecessors by leveraging various architectural improvements and training strategies.

If you need another format, you can convert our exports using tools like [Datumaro](https://open-edge-platform.github.io/datumaro/latest/docs/data-formats/formats/coco.html), [FiftyOne](https://docs.voxel51.com/recipes/convert_datasets.html), or [JSON2YOLO](https://github.com/ultralytics/JSON2YOLO).

You will again be taken to the exports screen, where the new export process starts.

<Frame>
  <img alt="Exports Screen" />
</Frame>

Upon export completion click on the **Three-dot icon** of the new export.

Select the **Download** button from the dropdown to download the export created.

<Frame>
  <img alt="Download Export" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Delete, Hide, and Unhide Annotations
Source: https://docs.labellerr.com/actions/delete-hide-unhide

Learn how to efficiently manage annotations by deleting, hiding, and unhiding them in Labellerr for a clearer view and better accuracy.

An annotation can also be edited based on classification, **Deleted** and **Hidden** easily.

<Info>
  **Delete** can be used instead of **clear all answers** option if a single annotation is to be removed.
</Info>

<iframe title="[VIDEO_TITLE]" />

<Info>
  Hidden is used when there is overlapping of different annotations. To avoid mistakes, some annotations can be hidden.
</Info>

<iframe title="[VIDEO_TITLE]" />


# Image Editing Icons Guide (Actions)
Source: https://docs.labellerr.com/actions/image-editing-icons

A comprehensive guide to the image editing tools available within Labellerr's action-oriented interface for enhanced labeling.

Labellerr provides additional tools to edit image samples for a better labelling experience.

## Available Tools

### Move/Drag Tool

**Move/Drag** icon lets you move the Image after selecting it. This is useful when you want a certain edge of the image or in complex images where detailed annotating is required.

<Frame>
  <img alt="Move/Drag Tool" />
</Frame>

### Display Settings

**Display** icon lets you change the brightness, contrast, hue, saturation and luminance. It is especially useful for details that are often missed in a very dark/bright picture or for the detection of an object that blends with the environment.

<Frame>
  <img alt="Display Settings" />
</Frame>

### Radius Tool

**Radius** icon allows edge reduction or anchor radius editing in different type of annotations like bounding box/polygon/line/segmentation.

<Frame>
  <img alt="Radius Tool" />
</Frame>

### Zoom Tool

**Zoom** icon as the name suggests lets you zoom in and zoom out. This can be useful when the image pixels are huge and specific pixels have to be highlighted with precision. It also serves as useful while using dot annotation in high pixel images.

<Frame>
  <img alt="Zoom Tool" />
</Frame>

### Selection Tool (Lasso)

**Selection Tool (Lasso)** lets you freely select regions by drawing around the object. This is useful for capturing Multiple annotation to perform operation on multiple annotation at once like grouping,deleting etc.

<Frame>
  <img alt="Selection Tool Lasso" />
</Frame>


# Labelling Screen Elements Guide
Source: https://docs.labellerr.com/actions/labelling-screen-elements

A guide to the key elements and functionalities of the Labellerr labelling screen, including tools, questions, auto-label, and navigation.

## This is the Labelling Window

<Frame>
  <img alt="Labelling Window Overview" />
</Frame>

### Key Elements and Functionalities

* On the left there is **objects and classification** questions that were created while making a new project.

<Frame>
  <img alt="Tools and Classifications" />
</Frame>

* **Mandatory questions** must be answered before submission but others can be skipped if not needed.

* To use the **Autolabel** feature, an auto label model first needs to be attached.

* ‘**Clear all answers’** removes the previous entries for a sample if corrections need to be made. Alternatively, you can also delete a single annotation using the delete button against that annotation.

* If the classifications list is long, then a user can also search for the desired question pertaining to the current sample data from the **Search Question** option.

* The **Settings option** can be used to update/change the annotation questions for the project.

<Frame>
  <img alt="Settings Option" />
</Frame>

* If the sample is too distorted, blurry, or irrelevant then, the user can instead **skip** the sample and add a remark stating the reason for skipping.

<Frame>
  <img alt="Skip Option" />
</Frame>

* After each sample is done being marked, click on **SUBMIT** present in the bottom left corner beneath the objects and classifications.

* On the top center, the tool also shows how much time has been spent labelling the particular set and beneath it, the time spent at each session.

<Frame>
  <img alt="Time Spent Tracking" />
</Frame>

* To close the current session, simply press the HOME button on the top left corner.

<Frame>
  <img alt="Exit Button" />
</Frame>

* You also have the Move image, Display image, Radius, Zoom In-Out, Reset icons, selection Tool available on top of each Image file to set the image quality, display and position.

<Frame>
  <img alt="Image Editing Tools" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Review Annotations
Source: https://docs.labellerr.com/actions/review

A guide to effectively reviewing annotated images, offering suggestions, and providing feedback on potential errors within Labellerr.

This guide provides step-by-step instructions for effectively reviewing annotated images, offering suggestions, and providing feedback on potential errors. Follow these guidelines to participate in the annotation review process seamlessly.

### 1. Access the Reviewer Platform

* Log in to the Labellerr platform using your credentials.
* Navigate to the "Review" tab on the dashboard.

The review screen is designed just like the labeling page, giving you access to all the same tools. This ensures you have full control over the quality and accuracy of the annotations. You can easily edit, add, or remove annotations as needed to meet your specific requirements.

<Frame>
  <img alt="Review Screen" />
</Frame>

### 2. Review Annotations and Provide Feedback

The bottom-left part of the screen shows a list of all annotated object names. To provide feedback on a specific annotation:

* Scroll through the list of annotated object names.
* As you hover over a specific name, the corresponding object in the image will be highlighted.

While reviewing, you can provide remarks for each annotated object. If there is a mistake in the annotation, specify the mistake, or give suggestions for improvement.

<Frame>
  <img alt="Review Feedback" />
</Frame>

### 3. Add Remarks or Suggestions

* To give remarks, click the comment icon next to the annotated object's name and type your feedback. Select "Mistake" if the annotation is incorrect, or "Suggestion" to propose improvements. Then, click the "Add Remark" button to submit your feedback.

<Frame>
  <img alt="Add Remarks" />
</Frame>

### 4. Hide Annotated Objects

To hide an annotated object, click the eye icon located to the right of the annotated object's name, just after the comment icon.

To hide all the annotations, click on the eye icon located next to the "Annotations" heading, which groups all the annotated objects.

**Why It’s Important:**

This feature helps you focus on specific areas of the image by temporarily hiding other annotated objects. It can reduce visual clutter, making it easier to review and analyze individual annotations or their placement in detail.

### 5. Skip, Reject or Accept a file

Once the file screening is complete, you have three options:

1. To accept the file, click the "Accept" button, and the file will be ready for export.
2. If there are mistakes or suggestions, click the "Reject" button, and the file will be sent for corrections.
3. To skip the file and have another review it, click the "Skip" button.

The "Reject" and "Accept" buttons are located at the top-right corner of the screen. To the left of the "Reject" button, click the three dots to open a dropdown menu, then select the "Skip" option.

<Frame>
  <img alt="Review Actions" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Review via Files
Source: https://docs.labellerr.com/actions/review-via-files

Learn how to accept, reject, and edit files directly from the Files view based on your review role.

The Files view allows reviewers and client reviewers to take review actions directly from the file list. Instead of opening the regular review queue first, you can filter the files you need, open the available file actions, and Accept, Reject, or Edit based on your role.

### 1. Access Files View

* Log in to the Labellerr platform using your credentials.
* Open the required project from the dashboard.
* Navigate to the **Files** section.
* Apply file status filters such as review-ready or client-review-ready files to find the files that need action.

<Frame>
  <img alt="Files View Actions" />
</Frame>

Once the filtered files appear, use the available action options from the Files view. The actions shown depend on your project role and the current status of each file and then click on any file link to open.

### 2. Role-Based Review Options

**Super Admin**

Super Admin users can view files across the project and perform all available review actions, including **Accept**, **Reject**, and **Edit**, wherever their permissions allow.

**Client Reviewer**

Client Reviewers can review files that are in the client review section or client-review-ready status. From the Files view, they can **Accept** files that meet the required quality standard or **Reject** files that need correction.

**Reviewer**

Reviewers can review files assigned to the review section or review-ready status. From the Files view, they can **Accept**, **Reject**, or **Edit** files before taking the final review action.

### 3. Available Actions

**Accept**

Use **Accept** when the file and its annotations meet the required quality standard. Accepting a file moves it forward in the workflow.

**Reject**

Use **Reject** when the file needs correction. Add relevant remarks or correction feedback so the next user understands what must be fixed.

**Edit**

Use **Edit** to open the file and update annotations before completing the review action. This is useful when a reviewer or Super Admin needs to make changes directly instead of sending the file back.

<Frame>
  <img alt="Accept Reject Edit Actions" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Start Labelling
Source: https://docs.labellerr.com/actions/start-labelling

A guide for both new and experienced users to understand the labelling process, annotation tools, sample editing, and screen elements in Labellerr.

<Note>
  For those new to Labellerr, this guide would assist in understanding the Labelling process with annotations and for experienced annotators, this guide would help them get familiarized with Labellerr. The guide also covers sample editing tools such as brightness, crop etc and detailed explanations of how each of the annotations is used.
</Note>

<Card title="Topics Covered" icon="play">
  This guide covers the complete labelling workflow in Labellerr:

  * **Accessing the Labelling Screen** - Getting started with annotation interface
  * **Basics of Labelling** - Fundamental concepts and processes
  * **Annotation Tools** - How to use different annotation types effectively
  * **Delete, Hide and Unhide** - Managing annotations during workflow
  * **Labelling Screen Elements** - Understanding the interface components
  * **Image Editing Icons** - Tools for image manipulation and enhancement
</Card>

## How to access the Labelling screen?

This is how the Dashboard screen appears. “A” is where you select the project that needs labelling. “B” is the Status Bar and “C” Is where you can start labelling.

<Info>
  For more on the Status bar, check out the [Status Bar Elements](/getting-started/status-bar-elements) guide.
</Info>

<Frame>
  <img alt="Dashboard Screen" />
</Frame>

To start labelling simply click on “C”, **Start Labelling** OR select the ‘**Label**’ tab from the **Task Bar**

### Labelling Screen

This is the screen that will appear once labelling is commenced. The Labelling Screen displays Annotations, Questions, Sample editing tools along with some basic elements.

<Frame>
  <img alt="Labelling Screen" />
</Frame>

<Info>
  For More on labelling Screen Elements, Check out the [Labelling Screen Elements Guide](/actions/labelling-screen-elements).
</Info>

### Annotations

There are six main annotations that you can use on Labellerr

1. **Bounding Box**

2. **Polygon**

3. **Dot**

4. **Polyline**

5. **Keypoint**

<Info>
  For more on how to use annotations, check out the [How to Use Annotations](/actions/annotations-guide) guide.
</Info>

An annotation can also be edited based on classification, **Deleted** and **Hidden** easily. **Delete** can be used instead of **clear all answers** option if a single annotation is to be removed. **Hidden** is used when there is overlapping of different annotations. To avoid mistakes, some annotations can be hidden.

<Info>
  For more on deleting and hiding annotations, check out the [Delete, Hide and Unhide annotations](/actions/delete-hide-unhide) guide.
</Info>

Additionally, some editing tools for the samples are available. Move, Brightness, Crop, Selection tool and Zoom are the available tools. They are present on the upperr-center of the sample.

<Frame>
  <img alt="Image Editing Tools" />
</Frame>

<Info>
  For more on Image editing tools, check out the [Image Editing Icons Guide (Actions)](/actions/image-editing-icons) guide.
</Info>

<Note>
  To predict the description/brief/keywords about the image using Generative AI, visit the [Image Captioning Using Generative AI](/features/image-captioning) guide.
</Note>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# View on Files Page
Source: https://docs.labellerr.com/actions/view-files-page

Explore different viewing options on the Files page in Labellerr, including Files View, Statistics View, Grid View, and Object View.

### Files View

To view the list of files based on the filter applied on the add Filter option.

<Frame>
  <img alt="Files View" />
</Frame>

### Grid View

After applying the filters, the grid view can be enabled by clicking on the grid icon in the top right section of the page.

This view enables the users to easily see the annotation present within the filtered files at a glance.

<Frame>
  <img alt="Grid View" />
</Frame>

### Object View

With object view, you can access each annotated object individually and can change the 'label' name to correct one while reviewing.

<Frame>
  <img alt="Object View" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Changelog
Source: https://docs.labellerr.com/changelog

Version history and release notes for the Labellerr annotation tool

This page documents notable changes to the Labellerr annotation platform. The latest releases appear first.

## About Versioning

This changelog follows Semantic Versioning principles:

* **MAJOR** (`X.0.0`): Significant platform or workflow changes that can materially alter how the product is used.
* **MINOR** (`X.Y.0`): New customer-facing capabilities and substantial backwards-compatible improvements.
* **PATCH** (`X.Y.Z`): Focused bug fixes, reliability fixes, and small backwards-compatible improvements.

Major versions are intentionally rare.

## Changelog Categories

* **Added**: New features and capabilities
* **Changed**: Improvements or behavior changes to existing functionality
* **Fixed**: Bug fixes and reliability improvements
* **Security**: Security, authentication, access-control, or policy changes

***

## \[2.1.0] - 2026-09-30

### Added

* **Faster Pre‑Annotation Indexing** — Pre‑annotation uploads are now queued for indexing, so users see their data indexed quickly without upload interruptions, improving workflow speed and reliability.
* **On‑Demand Project Reindexing** — Teams can trigger a reindex for any project via a new API, instantly refreshing search results and ensuring data stays up‑to‑date without manual database work.
* **Instance Metrics Analytics Screen** — Users can view detailed instance usage metrics on a new analytics screen, helping them monitor performance and optimize resource allocation.

### Fixed

* **Accurate Video Processing Status** — Video dataset cards now correctly display processing, success, incomplete, or failure states, preventing missing information and allowing annotators to act on the right datasets.
* **Reliable Dataset Completion & Lower Memory Use** — Datasets now finish only after all videos are processed and segment uploads stream from disk, preventing premature completion and out‑of‑memory errors, which improves data quality and system stability.
* **Reduced Elasticsearch Retry Load** — Retry logic has been tightened to stop excess retries, lowering load on the search service and keeping the platform responsive during indexing.

***

## \[2.0.2] - 2026-08-27

### Fixed

* **Deterministic file IDs for dataset creation** — Generate consistent and deterministic `file_ids` to make dataset creation idempotent.
* **Reconcile file count after ingestion** — Reconcile file count for the dataset once file ingestion is complete.
* **Duplicate fields error in Firestore query** — Fix duplicate fields error in the Firestore query for flexible sorting and pagination.
* **Delete docs from ES when dataset detached** — Delete the docs from ElasticSearch when a dataset is detached from a project.

***

## \[2.0.1] - 2026-08-20

### Fixed

* **Export-service singleton and connection-reset** — Fixed export-service singleton and connection-reset issues affecting coordinate normalization, pagination, and service reinitialization.
* **Export processing reliability** — Improved export processing reliability for data-type handling and aggregation preferences.
* **Populate updated\_at alongside created\_at** — Populate `updated_at` along with `created_at` in Firestore documents.

***

## \[2.0.0] - 2026-08-18

### Added

* **Workspace management and access controls** — Added workspace settings, workspace-level user management, SSO enforcement, and IP allowlisting.
* **WebCodecs/CMAF video playback** — Added client-side WebCodecs/CMAF playback with JPEG fallback, audio controls, enhanced timeline navigation, and frame-based mark-out controls.
* **SAM2 tracking for segmented video** — Added frame acquisition and tracking support for videos stored as CMAF/HLS segments.

### Changed

* **Video playback and frame acquisition** — Improved video playback, frame acquisition, buffering, caching, and recovery across segmented and JPEG-backed video (CMAF decode tier, JPEG fallback, density-gated frame ranges).
* **Video annotation draft handling** — Improved video annotation draft handling with accumulated changes and undo/redo support.
* **Workspace access and error handling** — Improved workspace access and error handling.

### Fixed

* **Delta handling for video** — Improved delta handling for video annotation saves and made aggregation strategy a user preference (LABIMP-8894 — Actions #121, ExportsCore #69, labellingTool #1433).

### Security

* **Workspace-level SSO and IP** — Added workspace-level SSO and IP allowlist enforcement.
* **Gateway-level CORS validation** — Improved gateway-level CORS validation and API-key handling.

***

## \[1.21.0] - 2026-07-28

### Added

* **SAM3 text-prompt support** — Added SAM3 text-prompt support for annotation workflows.
* **SAM3 support for bounding-box prompts** — Added SAM3 support for bounding-box prompts in the annotation tool.
* **SAM3 cross-image similarity search** — Added SAM3 cross-image similarity search using reference regions or text prompts.
* **Batch similarity-search processing across project images** — Added batch similarity-search processing across project images.
* **Batch processing for saving inference answers** — Added batch processing for saving inference answers across multiple files.
* **Per-file success and error reporting** — Added per-file success and error reporting for batch inference-answer operations.
* **Activity associations and background indexing** — Added activity associations and background indexing support for inference saves.

### Changed

* **SAM3 prediction performance via cached instances** — Improved SAM3 prediction performance by reusing cached model instances.
* **COCO pre-annotation exports with attributes** — Improved COCO pre-annotation exports to preserve annotation attributes as structured metadata.
* **SAM3 validation and prediction filtering** — Improved SAM3 validation and prediction filtering.

***

## \[1.20.0] - 2026-06-17

### Added

* **Active Events overlay** — Added an Active Events overlay for quickly identifying events present at a specific point in a video.
* **Change Label action** — Added a Change Label action for event-tagging annotations in the video player.
* **Display controls in toolbar** — Added display controls in the video annotation toolbar.
* **Manual start/end frame controls** — Added manual controls for changing event start and end frames.
* **Prefetching of upcoming video frames** — Added prefetching of upcoming video frames to improve playback responsiveness.
* **AWS S3 support for video** — Added AWS S3 support for video frame retrieval.
* **Background prefetch of next-video frames** — Added background prefetch of next-video frames using IDB store as cache for faster cold-start and transitions.

### Changed

* **Video playback buffering** — Improved video playback buffering, caching, and frame availability handling (tiered memory + persistent cache, scheduled signed URLs, stall/miss tolerance).
* **Video-player controls and playback state** — Improved video-player controls and playback state management.
* **Export handling for audio and multimodal** — Improved export handling for audio and multimodal data types.

### Fixed

* **Date filtering for files** — Fixed date filtering for files updated on the same day.
* **User edit flow** — Fixed user edit flow in existing projects — project list readiness and filtering now update reliably without background polling.
* **Modal layering** — Fixed modal layering that blocked S3 connection setup.

***

## \[1.19.0] - 2026-05-28

### Added

* **MediaPipe landmark detection** — Added MediaPipe landmark detection for hand and pose keypoints, including egocentric video tracking.
* **Per-keypoint attributes** — Added per-keypoint attributes for keypoint skeleton annotations.
* **SAM2 tracking for polygons** — Added SAM2 tracking for polygons using bounding-box prompts.
* **Attribute filtering for annotations** — Added attribute filtering for annotations.
* **Improved keypoint guidelines based on MediaPipe** — Added improved keypoint guidelines based on MediaPipe landmarks.
* **Per-keypoint attribute export in COCO** — Added per-keypoint attribute export in COCO JSON.
* **Finish-on-N for polygon drawing** — Added finish-on-N for polygon drawing with ordered timeline tracks and improved tracking reliability.

### Changed

* **Video tracking frame-range handling** — Improved video tracking frame-range handling for landmark models.
* **Annotation filtering** — Improved annotation filtering in image and video players.
* **Export support for multiple data types** — Improved export support for multiple data types and video manifests (including per-file sharding).
* **Connection handling and CORS** — Improved connection handling and optional CORS configuration for data connections, with warnings and test result panels.
* **Decoupled CORS policy check** — Decouple CORS policy check for connectors from data connection permissions — CORS issues now surface as soft-warnings with auto-fix.

### Fixed

* **Pixel-level polygon accuracy** — Fixed pixel-level polygon accuracy on scaled/zoomed canvases and improved anchor targeting.
* **Timeline min/max length** — Fixed timeline min/max length and narrow single-frame visibility; improved dashboard layout and resize controls.
* **Delete-project InProgress handling** — Fixed delete-project & InProgress handling for projects exceeding 24h threshold and refined polling.
* **Export delete-button error** — Fixed export delete-button error and indexing chip display when indexing is active.

***

## \[1.18.0] - 2026-04-24

### Added

* **Event-annotation attributes** — Added event-annotation attributes in the video player.
* **Editing support in Gallery** — Added editing support in Gallery View and View Mode.
* **Auto-Bordering for polygon** — Added Auto-Bordering for polygon annotations (Alt+click boundary-following, batch-aware undo/redo).
* **Direct accept/reject actions** — Added direct accept/reject actions from View Mode.
* **View-only annotation mode** — Added view-only annotation mode with permission-based controls and expanded domain for accept/reject across statuses.

### Changed

* **Attribute dialog UX** — Improved attribute dialog UX and visual context (short IDs, bulk editing, draggable headers).
* **Audio annotation state** — Improved audio annotation state management and draft saving via ngRx store.
* **Expanded workflow-state handling** — Expanded workflow-state handling for accept/reject actions.

### Fixed

* **Guideline creation navigation** — Fixed guideline creation navigation, pixel-level polygon issues, and UI stacking behavior.
* **Attribute validation for required** — Fixed attribute validation for required attributes (including video-data skip and per-keypoint level checks).

***

## \[1.17.0] - 2026-03-30

### Added

* **Keypoint annotation export** — Added keypoint annotation export to COCO JSON, including skeleton information.
* **COCO pre-annotation support** — Added COCO pre-annotation support for keypoints.
* **Edit-mode save API integration** — Added edit-mode save API integration.
* **Transactional file assignment** — Added transactional file assignment to reduce conflicts when assigning files to users.
* **DLQ handling for dataset operations** — Added Dead Letter Queue endpoint to capture failed message data with complete context.

### Changed

* **Refactored image annotation** — Refactored image annotation workflows.
* **Keypoint export validation** — Improved keypoint export validation and annotation retrieval.

### Fixed

* **Inline export error** — Improved inline export error handling and edit-mode reliability.

***

## \[1.16.0] - 2026-02-16

### Added

* **More reliable export** — Added more reliable export processing through a Cloud Run Job and Apache Beam pipeline.
* **S3 export support** — Added S3 export support.

### Changed

* **SAM request handling** — Improved SAM request handling by removing the deprecated image-link dependency.
* **SAM3 prediction behavior** — Improved SAM3 prediction behavior so annotation attributes can be carried forward.
* **GRPC connection reliability** — Improved gRPC connection reliability and retry handling (safer channel recreation, recoverable-error handling).

***

## \[1.15.0] - 2026-01-31

### Added

* **Annotation activity logs** — Added annotation activity logs and fixed preservation of labelling transition time.
* **SAM+ for Magic Wand** — Added SAM+ for Magic Wand and polygon refinement workflows (persistent model option, batch refinement, parallel warmup).
* **SegRefiner/SAMPlus-based annotation refinement** — Added SegRefiner/SAMPlus-based annotation refinement.
* **Projects delete API** — Added project deletion capability with bulk storage-class updates and search-index cleanup.

### Changed

* **Video annotation attributes** — Improved video annotation attributes in the player (frame-aware dialogs, prior-frame retrieval).
* **Project deletion and user-interface** — Improved project deletion and user-interface flows (typed confirmation, selected-project indicator).
* **Annotation label-main architecture** — Improved annotation label-main architecture and activity tracking (centralized store-driven workflow, autosave, activity preview).

***

## \[1.14.0] - 2025-12-26

### Added

* **Configurable API rate** — Added configurable API rate limiting (global per-client, 429 + Retry-After).
* **Rate-limits per client API** — Added API to update rate limits per client id.
* **Short video previews** — Added short video previews.
* **Support for streaming** — Added support for streaming TS video content through the video data pipeline (HLS playlist + TS segment proxy, adapter-based storage).
* **Selective project-based user** — Added selective project-based user import (guided two-step flow with per-step search and validation).
* **Error messaging for failed video processing** — Added error messaging for failed video processing jobs to surface dataset error state.

### Changed

* **Video-player stability when** — Improved video-player stability when switching videos (resource cleanup, preloading fixes).
* **Annotation pagination and similar-file** — Improved annotation pagination and similar-file search pagination (consistent footers, improved control).
* **Handling of missing** — Improved handling of missing video end-frame values with FPS/start-end fallbacks and manual annotation consistency.
* **Visibility of bounding-box** — Improved visibility of bounding-box corners and annotation-setting previews.
* **Project creation polling for dataset readiness** — Added validations and polling for project creation to wait till attached datasets are ready.
* **Bulk sync and selected file indexing** — Added bulk project-file sync and support for indexing selected file ids of a project.
* **ES multimodal indexing status** — Handled status update for ES multimodal indexing with transactional state.

### Fixed

* **Video-player pagination and search-navigation** — Fixed video-player, pagination, and search-navigation issues including rescaling/UI distortion on export↔files switching and pagination when searching similar files.

***

## \[1.13.0] - 2025-11-29

### Added

* **File-queue thumbnails to make** — Added file-queue thumbnails to make navigation easier in full-page annotation view.
* **Files Management milestone** — Added Files Management milestone 2 capabilities (table/grid/object views, virtualized grid, search/filter/sort, bulk select, export).
* **Superset dashboarding support** — Added Superset dashboarding support (guest-token viewer).
* **SAM3 exemplar-prompt support** — Added SAM3 exemplar-prompt support (dedicated prediction + warmup endpoints, runtime mode selection).
* **Video pre-annotation processing** — Added video pre-annotation processing improvements (COCO-for-video, unified media pre-annotations with Pub/Sub).
* **Dataset sync for S3/GCS** — Added dataset sync endpoint to trigger synchronization across S3 and GCS.
* **File links flags in search results** — Added flags to return file links along with search results.
* **Client ID request support** — Added client ID request support for tracking access requests.

### Changed

* **Grouping selection and polygon** — Improved grouping selection and polygon clipping workflows (precise containment, multi-piece clipping, G-shortcut).
* **Annotation bounds handling** — Improved annotation bounds handling by keeping polygons and points within image boundaries (clamping/normalization).
* **File switching stability** — Improved file switching stability and prevented annotations from carrying over between files (virtual scroll buffering, batched tree expansion).

### Fixed

* **Race conditions when** — Fixed race conditions when switching files quickly in the annotation gallery and when fetching file data via gallery strip.

***

## \[1.12.0] - 2025-10-24

### Added

* **File-management capabilities** — Added file-management capabilities as an initial milestone of the Files Management module.
* **File tagging support** — Added file tagging support and tagging APIs (single & batch, per-file success/failure, gRPC services, reserved-tag validation).
* **Keyboard shortcuts for changing** — Added keyboard shortcuts for changing annotation labels (L for label, N for complete polygon).
* **Polyline occlusion handling** — Added polyline occlusion handling with right-click interactions (gray dashed styling, persistence).
* **Dedicated gRPC services** — Added dedicated gRPC services for file tagging and exports (with context propagation, background tasks, centralized error handling).
* **Tags mapping to ES** — Added tags mapping to ElasticSearch for project-file search filtering.
* **Pub/Sub observability** — Added observability for pub/sub with correlation IDs.

### Changed

* **Bulk inference handling** — Improved bulk inference handling for pre-label and review-ready predictions (cloud-bucket support, dual storage paths).
* **Polygon editing and annotation** — Improved polygon editing and annotation workflows (including eraser transparency to 100% for target polygon).
* **gRPC client logging** — Added logging for gRPC clients with request context propagation.

### Security

* **Security fixes across** — Applied security fixes across export and gateway services.

***

## \[1.11.0] - 2025-09-30

### Added

* **Project indexing progress** — Added project indexing progress tracking with ETA information.
* **SAM2.1 support and updated** — Added SAM2.1 support and updated frame-loading behavior (removed old SAM dependency).
* **Structured tracing and correlation** — Added structured tracing and correlation information for improved diagnostics (GCP logging spans).

### Changed

* **Annotation rendering after** — Improved annotation rendering after video load and handling of deleted/dangling video events.
* **Logging and error reporting** — Improved logging and error reporting across core services (centralized error handling, context-based logging).
* **Project indexing and file-processing** — Improved project indexing and file-processing visibility.

### Fixed

* **UUID compulsory enforcement** — Fixed UUID compulsory enforcement in requests and made error handling more robust.
* **In-progress dataset selection** — Fixed in-progress dataset selection handling.
* **Validation and cleanup for datasets** — Added validation, cleanup, generic error handling and pagination improvements for datasets.

### Security

* **Access-control and gateway** — Addressed access-control and gateway security considerations alongside logging improvements.

***

## \[1.10.0] - 2025-08-30

### Added

* **Search experience** — Added a search experience for the file listing page, including support for legacy and newer query patterns (reusable search components, textarea mode, date-range guards).
* **Multi-object tracking support** — Added multi-object tracking support (simultaneous tracking, multi-object API).
* **Video keyframe and marker** — Added video keyframe and marker retrieval capabilities (keyframe/marker APIs, DataCore frame fetch).
* **Richer SAM2 logging** — Added richer SAM2 logging and annotation history tracking for image and video workflows (GCS structure, session/history).
* **Ability to see similar** — Added ability to see similar files already annotated on the labeling screen.
* **Video dataset upload** — Added video dataset upload improvements with quality checks and new status chips.
* **Video dataset permission handling** — Added permission handling for video-based datasets.

### Changed

* **Delta-delete handling when** — Added delta-delete handling when saving annotations across supported data modalities (GCS + Firestore delta logic).
* **Video dataset upload** — Improved video dataset upload states and playback-related workflows.
* **File-list filtering pagination** — Improved file-list filtering, pagination, status indicators, and annotation navigation (pagination fixes, status chip normalization).
* **Image adjustment controls** — Improved image adjustment controls (brightness/contrast) and similar-file search behavior.
* **Pagination and annotation-count** — Improved pagination and annotation-count filtering (including annotation count filters and file-listing page fixes).
* **GCS file name preservation** — Refactored GCSConnectorService to preserve file names via `os.path.basename` for local uploads.
* **ES indexing via Cloud Run** — Moved ES indexing from gRPC call to Cloud Run job.

### Fixed

* **SAM2 frame coverage** — Fixed SAM2 frame coverage for last few frames, annotation counts, pagination, status display, and file transitions.
* **Pagination on file listing** — Fixed pagination on file listing page (second-page reload, filter reset) and dataset page API params.
* **Irregular status chips** — Fixed irregular status chips on file listing page.
* **User-added refresh new** — Fixed user-added refresh — new users now appear via optimistic update without manual refresh.
* **Dialog-box tests and stale** — Fixed dialog-box tests and stale SAM temp-state when deselecting questions.
* **Bounding-box creation when** — Fixed bounding-box creation when release point is outside the Konva stage.
* **Video annotation delta** — Fixed video annotation delta handling edge cases and in-progress dataset selection.
* **GCP auth retries** — Added retries to authenticate with GCP.
* **Duplicate projects listed** — Fix duplicate projects getting listed in the project listing API.
* **ES jobs and multimodal jobs** — Added ES jobs and size-based multimodal job handling.

***

## \[1.9.0] - 2025-07-27

### Added

* **Delta-based saving for video** — Added delta-based saving for video annotations (firestore + caching optimization).
* **Polyline annotation support** — Added polyline annotation support for satellite imagery.
* **Similar-file discovery for previously** — Added similar-file discovery for previously annotated files.
* **Project failure status** — Added project failure status visibility (red "Failed" pill for status\_code 501).
* **Annotation indexing improvements** — Added annotation indexing improvements for search (ES multimodal index flag, search bar suggestions).
* **Template search and improved** — Added template search and improved project-creation validation (search reset on close, padding, name validation).
* **Bounding-box validation for empty** — Added bounding-box validation for empty submissions and out-of-bounds handling.

### Changed

* **Video annotation change** — Improved video annotation change tracking and diff handling (diff updates for video annotation).
* **File-list and project** — Improved file-list and project responsiveness and pagination (table-responsive, media queries, dataset pagination).
* **Annotation validation and erased-region** — Improved annotation validation and erased-region handling (polygon validator for erased regions).
* **SAM2 processing including** — Improved SAM2 processing, including support for multiple input points and concurrent processing (torch).

### Fixed

* **Responsive issues in project** — Fixed responsive issues in project table and dataset page not updating when more files available.
* **Sentry issues on /files** — Fixed Sentry issues on /files and /dashboard routes and guideline page visibility.
* **Export notification trigger** — Fixed export notification trigger inconsistency.
* **Attribute filtering for pubsub** — Fixed attribute filtering for pubsub aggregate job and export pre-processor for erased regions.
* **Latency for answer submission** — Fixed latency for answer submission by not waiting for pubsub (10–15s → 2–5s).
* **Email normalization to lowercase** — Normalize email IDs to lowercase in user registration and update endpoints.
* **Image orientations handling** — Handle image orientations while storing image dimensions (height, width).

***

## \[1.8.0] - 2025-06-19

### Added

* **Anonymous dataset search** — Added anonymous dataset search so users can explore datasets without logging in.
* **Direct accept/reject actions** — Added direct accept/reject actions for review-stage files from grid view.
* **File status information** — Added file status information to exports.
* **Support for exporting** — Added support for exporting files across workflow statuses.
* **Store activity data on ES** — Added code to store activity data on ElasticSearch server.
* **Auth0 gRPC for user details** — Added auth0 gRPC to get user details.

### Changed

* **Bounding-box validation and coordinate** — Added bounding-box validation and coordinate normalization to keep annotations within image boundaries.
* **Validation behavior for submissions** — Improved validation behavior for submissions without annotations.
* **The project dataset** — Improved the project, dataset, guideline, and export interfaces.
* **Handling of failed file** — Improved handling of failed file references and reference errors in export controllers.
* **Prevent deletion of attached datasets** — Updated code to prevent deletion of datasets which are attached to a project.
* **Annotated and reviewed query** — Updated query to get annotated and reviewed files and added migration script.
* **ES server default timeout** — Updated default timeout of ES server.

***

## \[1.7.0] - 2025-05-13

### Added

* **Gemini-powered LLM API** — Added a Gemini-powered LLM API route.
* **Fallback handling when** — Added fallback handling when file update timestamps are unavailable.
* **Improved error reporting** — Added improved error reporting for cloud-storage operations.
* **Validation for invalid** — Added validation for invalid polygon and bounding-box annotations (ignore invalid annotations).
* **Richer activity information** — Added richer activity information for annotation and review workflows.
* **Retry mechanism for importing users** — Added retry mechanism while importing users.
* **Connectors v2 for dataset creation** — Added Connectors v2 for new dataset creation process.

### Changed

* **Dataset and sample-file** — Improved dataset and sample-file retrieval APIs (including getting sample file from dataset id).
* **Error reporting for cloud-storage** — Improved error reporting for cloud-storage operations.
* **Rejected-file handling reassigned** — Improved rejected-file handling — reassigned to last annotator/reviewer who updated it and preserved annotator/reviewer email.
* **Separated development and production** — Separated development and production export workflows and made workflow builds distinct per environment.
* **Annotation-save latency for image** — Improved annotation-save latency for image workflows via cache service.
* **Project creation polling after dataset** — Project creation will only start after dataset has been successfully created, else will poll.

### Fixed

* **UUID handling issues** — Fixed UUID handling issues affecting request processing.
* **Add-remark endpoint removal** — Fixed add-remark endpoint removal and fetching logic cleanup.

***

## \[1.6.0] - 2025-03-28

### Added

* **Support for using fine-tuned** — Added support for using fine-tuned SAM models when available.
* **Dedicated inference handling** — Added dedicated inference handling for fine-tuned SAM workflows.

### Changed

* **The Actions service** — Migrated the Actions service from Flask to FastAPI.
* **Export processing to use** — Updated export processing to use YOLO11 instead of YOLOv5.
* **SAM usage tracking** — Added SAM usage tracking.

***

## \[1.5.0] - 2025-02-20

### Added

* **Label-based file filtering** — Added label-based file filtering.
* **Export email notifications** — Added export email notifications and ordering support.
* **Atomic project create/delete operations** — Added atomic project create and delete operations.
* **New create project flow** — Added new create project flow.

### Changed

* **Bulk file movement across** — Improved bulk file movement across workflow stages.
* **Session management token** — Improved session management, token authentication, and cross-workspace session restrictions.
* **Error logging and workflow** — Improved error logging and workflow timing information.

***

## \[1.4.0] - 2025-01-30

### Added

* **Pre-annotation processing through** — Added pre-annotation processing through Cloud Run jobs.
* **Simultaneous SAM2 tracking** — Added simultaneous SAM2 tracking and the ability to stop long-running SAM2 jobs.
* **Validation hooks for missing** — Added validation hooks for missing or invalid annotations.
* **Support for validating** — Added support for validating and ignoring invalid polygon and bounding-box annotations.
* **Richer activity information** — Added richer activity information for annotation and review workflows.
* **S3 lastModified timestamp** — Extract S3 object last modified timestamp and add in pubsub packet as created\_at.
* **Gdrive connector as Cloud Run job** — Added Gdrive connector service as a Cloud Run job.

### Changed

* **Annotation-save latency for image** — Improved annotation-save latency for image workflows.
* **Rejection handling by preserving** — Improved rejection handling by preserving annotator/reviewer information and reassigning rejected files appropriately.
* **Validation messages and attribute** — Improved validation messages and attribute handling.
* **Time-taken tracking in Firestore** — Improved time-taken tracking in Firestore and error logging.
* **Datasets status files\_count** — Updated datasets status API to return `files_count`.

### Security

* **Reported API security** — Addressed reported API security vulnerabilities and tightened allowed origins.

***

## \[1.3.0] - 2024-12-17

### Added

* **SAM2 support for bounding-box-driven** — Added SAM2 support for bounding-box-driven video annotation.
* **Support for storing** — Added support for storing and retrieving image and auto-label annotations through the updated annotation flow.
* **Annotation storage in managed** — Added annotation storage in managed object storage with compatibility for existing annotation data.
* **Annotator identity information** — Added annotator identity information to activity records.
* **Concurrent uploadToLocal** — Updated `uploadToLocal` method to upload files concurrently.

### Changed

* **Annotation persistence and retrieval** — Improved annotation persistence and retrieval across image and video workflows.

***

## \[1.2.0] - 2024-11-25

### Added

* **SAM2-based inference capabilities** — Integrated SAM2-based inference capabilities.
* **Support for SAM inputs** — Added support for SAM inputs encoded as base64 images.
* **File-detail and frame-aware** — Added file-detail and frame-aware data retrieval APIs.
* **Handling of video frame** — Improved handling of video frame answers when annotation IDs are unavailable.
* **Altair integration** — Added Altair integration with updated flow as per Labellerr pricing plan.
* **Delete Users API** — Added Delete Users API and Altair License integration.

***

## \[1.1.0] - 2024-10-14

### Added

* **Decoding support for mask** — Added decoding support for mask annotations stored in base64 form.
* **Inference responses for compact/binary** — Improved inference responses for compact/binary mask data.

***

## \[1.0.0] - 2024-09-24

### Added

* **File retrieval ordering** — Improved file retrieval ordering and foundational data APIs.

***

## Staying Updated

To stay informed about new releases:

* Watch the [Labellerr GitHub](https://github.com/labellerr) for release notifications
* Visit the [Labellerr website](https://labellerr.com) for product announcements
* Check the [Product Updates](/product-releases/2026) section for monthly feature roundups

## Release Schedule

Future Labellerr releases can continue using the same Semantic Versioning convention:

* **Minor versions**: New features and substantial backwards-compatible improvements
* **Patch versions**: Focused fixes and small improvements
* **Major versions**: Significant or potentially breaking product/workflow changes

## Support

<CardGroup>
  <Card title="Documentation" icon="book" href="/getting-started/introduction">
    Guides and reference for the Labellerr annotation tool
  </Card>

  <Card title="Product Updates" icon="calendar" href="/product-releases/2026">
    Monthly feature updates and announcements
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:support@tensormatics.com">
    Get help from our team
  </Card>
</CardGroup>


# Automobile
Source: https://docs.labellerr.com/cookbooks/automobile



<CardGroup>
  <Card title="Fine-tune YOLO for Emergency Vehicle Detection" icon="ambulance" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Automobile/fine-tune-yolo-for-Emergency-vehicle-detection.ipynb" />

  <Card title="Fine-Tune YOLO for Traffic Flow Counting" icon="traffic-light" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Automobile/Fine-Tune-YOLO-for-Traffic-Flow-Counting.ipynb" />
</CardGroup>


# Build your AI Agents
Source: https://docs.labellerr.com/cookbooks/build-ai-agents



<CardGroup>
  <Card title="RAG with Gemini" icon="sparkles" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Build%20your%20AI%20Agents/RAG_with_gemini.ipynb" />

  <Card title="Research Multi Agent AI" icon="robot" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Build%20your%20AI%20Agents/Research_Multi_Agent_AI.ipynb" />
</CardGroup>


# Fine-tune YOLO for various use cases
Source: https://docs.labellerr.com/cookbooks/fine-tune-yolo



<CardGroup>
  <Card title="Cell Segmentation using YOLO" icon="microscope" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Cell_Segmentation_using_YOLO.ipynb" />

  <Card title="Fine-tune YOLO for Emergency Vehicle Detection" icon="truck-medical" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/fine-tune-yolo-for-Emergency-vehicle-detection.ipynb" />

  <Card title="Fine-Tune YOLO For Fruits Counting" icon="apple-whole" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Fine-Tune-YOLO-For-Fruits-Counting.ipynb" />

  <Card title="Fine-Tune YOLO for Threat Detection" icon="shield-halved" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Fine-Tune-YOLO-for-Threat-Detection.ipynb" />

  <Card title="Fine-Tune YOLO for Traffic Flow Counting" icon="car" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Fine-Tune-YOLO-for-Traffic-Flow-Counting.ipynb" />

  <Card title="Fine-Tune YOLO Production Line Counting" icon="industry" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Fine-Tune-YOLO-Production-Line-Counting.ipynb" />

  <Card title="Fine-Tune YOLO for Product Recognition for Price Verification" icon="barcode" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Fine-Tune_YOLO_for_Product_Recognition_for_Price_Verification.ipynb" />

  <Card title="Fine Tune YOLO for Football Analytics" icon="futbol" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Fine_tune_yolo_for_football_analytics.ipynb" />

  <Card title="Pill Counting Using YOLOv12" icon="pills" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Pill_Counting_Using_YOLOv12.ipynb" />

  <Card title="Using YOLO for 3D Cuboid Detection" icon="cube" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Using-YOLO-for-3D-Cuboid_detection.ipynb" />

  <Card title="YOLO Model Comparison" icon="chart-bar" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/YOLO_Model_Comparison.ipynb" />

  <Card title="YOLO vs RT-DETR" icon="code-compare" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/yolo_vs_rt-detr.ipynb" />
</CardGroup>


# Healthcare
Source: https://docs.labellerr.com/cookbooks/healthcare



<CardGroup>
  <Card title="Breast Cancer Detection CNN" icon="ribbon" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Healthcare/Breast%20Cancer%20Detection%20CNN%20Priyanka.ipynb" />

  <Card title="Heart Disease Detection" icon="heart-pulse" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Healthcare/Heart%20disease%20detection.ipynb" />

  <Card title="PCOS Ovary Detection" icon="notes-medical" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Healthcare/PCOS%20Ovary%20Detection%20CV%20Priyanka.ipynb" />

  <Card title="Parkinson's Disease Detection" icon="brain" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Healthcare/Parkinson%27s_disease_detection.ipynb" />

  <Card title="Skin Cancer Detection" icon="user-doctor" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Healthcare/Skin%20Cancer%20Detection%20CV%20Priyanka.ipynb" />

  <Card title="Alzheimer Disease Stage Prediction Model" icon="head-side-virus" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Healthcare/alzhemier-disease-stage-prediction-model-cv-priyanka%20(1).ipynb" />

  <Card title="Cell Segmentation using YOLO" icon="microscope" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Cell_Segmentation_using_YOLO.ipynb" />

  <Card title="Pill Counting Using YOLOv12" icon="pills" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Pill_Counting_Using_YOLOv12.ipynb" />
</CardGroup>


# Manufacturing
Source: https://docs.labellerr.com/cookbooks/manufacturing



<CardGroup>
  <Card title="Fine-tune YOLO PPE Detection" icon="hard-hat" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Manufacturing/fine-tune-yolo-PPE-detection.ipynb" />

  <Card title="Fine-Tune YOLO Production Line Counting" icon="conveyor-belt" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Manufacturing/Fine-Tune-YOLO-Production-Line-Counting.ipynb.ipynb" />
</CardGroup>


# Model Notebooks
Source: https://docs.labellerr.com/cookbooks/model-notebooks



## Vision-Language Models

<CardGroup>
  <Card title="BLIP" icon="image" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Model%20Notebooks/BLIP/blip.ipynb" />

  <Card title="KOSMOS-2" icon="language" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Model%20Notebooks/KOSMOS-2/kosmos_2.ipynb" />

  <Card title="Vision Agent using Segment Anything" icon="wand-magic-sparkles" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Model%20Notebooks/Vision%20Agent/Vision_Agent_using_Segment_Anything.ipynb" />
</CardGroup>

***

## Tracking Algorithms

<CardGroup>
  <Card title="ByteTrack" icon="location-arrow" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Model%20Notebooks/ByteTrack/bytetrack.ipynb" />

  <Card title="DeepSORT" icon="route" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Model%20Notebooks/DeepSORT/deepsort.ipynb" />

  <Card title="OC-SORT" icon="timeline" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Model%20Notebooks/OC-SORT/ocsort.ipynb" />
</CardGroup>

***

## Segmentation

<CardGroup>
  <Card title="SAM2" icon="scissors" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Model%20Notebooks/SAM2/SAM2_inference_notebook.ipynb" />

  <Card title="Mask2Former" icon="layer-group" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Model%20Notebooks/Mask2Former/Mask2Former_experiment_notebook.ipynb" />
</CardGroup>

***

## Model Comparisons

<CardGroup>
  <Card title="YOLO Model Comparison" icon="chart-bar" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/YOLO_Model_Comparison.ipynb" />

  <Card title="YOLO vs RT-DETR" icon="code-compare" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/yolo_vs_rt-detr.ipynb" />
</CardGroup>


# Retail
Source: https://docs.labellerr.com/cookbooks/retail



<CardGroup>
  <Card title="Fine-Tune YOLO for Product Recognition for Price Verification" icon="barcode" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Retail/Fine-Tune_YOLO_for_Product_Recognition_for_Price_Verification.ipynb" />

  <Card title="Fine-Tune YOLO For Fruits Counting" icon="apple-whole" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/fine-tune%20YOLO%20for%20various%20use%20cases/Fine-Tune-YOLO-For-Fruits-Counting.ipynb" />
</CardGroup>


# Robotics
Source: https://docs.labellerr.com/cookbooks/robotics



<CardGroup>
  <Card title="Using YOLO for 3D Cuboid Detection" icon="robot" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Robotics/Using-YOLO-for-3D-Cuboid_detection.ipynb" />
</CardGroup>


# Security
Source: https://docs.labellerr.com/cookbooks/security



<CardGroup>
  <Card title="Fine-Tune YOLO for Threat Detection" icon="shield" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Security/Fine-Tune-YOLO-for-Threat-Detection.ipynb" />
</CardGroup>


# Sports
Source: https://docs.labellerr.com/cookbooks/sports



<CardGroup>
  <Card title="Fine Tune YOLO for Football Analytics" icon="futbol" href="https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/Sports/Fine_tune_yolo_for_football_analytics.ipynb" />
</CardGroup>


# IP Allowlisting
Source: https://docs.labellerr.com/enterprise-security/ip-allowlisting

Restrict access to your Labellerr workspace by allowing only specific IP addresses.

## Overview

IP Allowlisting restricts access to your Labellerr workspace to a set of allowed IP ranges. Once enabled, only users connecting from the listed IPs can access your data — such as images, videos, and annotations.

<iframe title="IP Allowlisting" />

<Info>
  Only users with **workspace admin** privileges can enable IP Allowlisting, add IP ranges, and remove them.
</Info>

## Enabling IP Allowlisting

<Steps>
  <Step title="Go to Workspace Settings">
    Open the **Workspace Settings** option from the left sidebar.

    <Frame>
      <img alt="Workspace Settings in the left sidebar" />
    </Frame>
  </Step>

  <Step title="Toggle On IP Allowlisting">
    Toggle on **IP Range Allowlist**.

    <Frame>
      <img alt="IP Range Allowlist toggle" />
    </Frame>
  </Step>

  <Step title="Add Allowed IP Ranges">
    Enter the IP ranges in **CIDR notation**. Multiple IPs are supported, for example:

    * `192.168.1.100/32` (IPv4)
    * `2001:db8::/32` (IPv6)
  </Step>

  <Step title="Save">
    Save your changes to apply the allowlist.
  </Step>
</Steps>

## How It Works

Once IP Allowlisting is enabled, only users connecting from the listed IP ranges can work in the tool — accessing data such as videos or images and performing annotations. Users connecting from unlisted IPs are blocked, including the **workspace admin** — after enabling the allowlist, even the workspace admin can only access the workspace from the listed IPs. Only a **workspace admin** can enable the allowlist, add IP ranges, and remove them.

<Warning>
  Add your **current IP address** to the allowlist. If your own IP is not listed, you will also be locked out of the workspace.
</Warning>

## Removing IPs and Disabling

Only a **workspace admin** can manage the allowlist from the same **Workspace Settings** screen:

* **Remove IP ranges** — delete entries from the list to revoke access for those IPs.
* **Disable IP Allowlisting** — toggle off **IP Range Allowlist** to restore access for all users.

To disable the allowlist, the workspace admin must first connect from a listed IP — the allowlist applies to the workspace admin as well.

<Note>
  For further assistance contact <a href="mailto:support@tensormatics.com">[support@tensormatics.com](mailto:support@tensormatics.com)</a>
</Note>


# Single Sign-On (SSO) Enforcement
Source: https://docs.labellerr.com/enterprise-security/sso-enforcement

Enforce Single Sign-On (SSO) authentication for all members of your Labellerr workspace.

## Overview

Single Sign-On (SSO) Enforcement lets you enforce sign-in through a designated identity provider — **Google Workspace** or **Okta** — for all members of your workspace. Once enabled, every user must authenticate through the selected provider.

<iframe title="SSO Enforcement" />

<Info>
  Only users with **workspace admin** privileges can enable or disable SSO Enforcement for a workspace.
</Info>

## Enabling SSO Enforcement

<Steps>
  <Step title="Go to Workspace Settings">
    Open the **Workspace Settings** option from the left sidebar.

    <Frame>
      <img alt="Workspace Settings in the left sidebar" />
    </Frame>
  </Step>

  <Step title="Toggle On SSO Enforcement">
    Toggle on **Single Sign-on (SSO) Enforcement**.

    <Frame>
      <img alt="Single Sign-on (SSO) Enforcement toggle" />
    </Frame>
  </Step>

  <Step title="Select the SSO Identity Provider">
    Check the box for the SSO identity provider you want to enforce: **Google Workspace** or **Okta**.
  </Step>
</Steps>

## How It Works

Once SSO Enforcement is enabled, all users must sign in through the designated identity provider. Users are forced to re-authenticate with the provider on login, and there is no alternative login path.

<Warning>
  Keep your login credentials safe and remembered. After SSO Enforcement is enabled, a user can only log in using the designated provider.
</Warning>

## Disabling SSO

Only a **workspace admin** can disable SSO Enforcement from the same **Workspace Settings** screen by toggling it off. To disable it, the workspace admin must first sign in through the designated SSO provider — SSO applies to the workspace admin as well.

<Note>
  For further assistance contact <a href="mailto:support@tensormatics.com">[support@tensormatics.com](mailto:support@tensormatics.com)</a>
</Note>


# Audio Segmentation
Source: https://docs.labellerr.com/features/audio-segmentation

Learn about audio segmentation in Labellerr, a feature that divides audio signals into segments and classifies them for various applications like speech recognition or music.

Audio segmentation divides the digital audio signal into a sequence of segments or frames and then classifies these into various classes such as speech recognition, music, or noise.

<Info>
  The template configuration setup is located in the 'Label Configuration' section on the project creation page.

  [How to Create an Audio Annotation Project?](/getting-started/create-audio-project)
</Info>

Set object type to ‘Audio segmentation’and add attributes to write the transcription in the input box.

Select the portion of the audio that needs transcription. This selection will generate a parallel attribute section on the right side.

<Frame>
  <img alt="Audio Segmentation Interface" />
</Frame>

Similarly, select objects and add transcriptions alongside the corresponding attributes in the attributes section.

<Note>
  Similar screens are available in the review stage, where reviewers can also edit transcriptions as needed.
</Note>

<iframe title="YouTube video player" />


# Audio Transcription Using Generative AI
Source: https://docs.labellerr.com/features/audio-transcription

Learn how Labellerr's audio analyzer, powered by Gemini API, provides accurate transcriptions and insights from audio recordings.

Labellerr's **audio analyser** would help the AI scientist obtain an accurate transcription of the audio recording. Also, the AI scientist can obtain the essence of the conversation, the next steps after the conversation, and things like that.

**Gemini API**, configured to send responses to the UI of the platform, sends measured analysis of data that has been integrated with Labellerr. (The user has to enter the right question in the prompt window).

Below is a sample audio file analysed by **Labellerr's Audio analyser.**

<Info>
  The template configuration setup is located in the 'Label Configuration' section on the project creation page.

  [How to Create an Audio Project?](/getting-started/create-audio-project)
</Info>

After setting up classification questions and creating the project, you will be directed to the dashboard. Click on the '**Label**' tab to open the labeling screen.

<Frame>
  <img alt="Audio Labelling Screen" />
</Frame>

Next, click '**LLM Powered Transcript**.' A small popup will appear where you can enter prompts or questions, such as how many people are in the audio, full transcription, highlighted keywords, summary of the audio, and more.

<Frame>
  <img alt="LLM Powered Transcript Prompt" />
</Frame>

Click "**Proceed**" after entering your prompt. The generative AI will then provide a transcription/details based on your input.

<Frame>
  <img alt="Generative AI Transcription Output" />
</Frame>

You can review and edit this output as needed.

<Tip>
  **Further Prompts**: You can provide additional prompts to obtain more specific details about the audio, such as the transcription of a particular person (male/female/first person, etc.).
</Tip>

Once satisfied with the description/transcription, click the "**Submit**" button to submit the file.

The file will be sent to a reviewer, who can also view the audio file and edit the output if necessary.

Reviewers can access files for review by navigating to the "Review" page from the dashboard.


# Auto Bordering
Source: https://docs.labellerr.com/features/auto-bordering

Learn how to use Auto Bordering in Labellerr to reuse common polygon edges while annotating adjacent objects.

Auto Bordering helps you create polygons that share the same boundary without manually redrawing the common side. It is useful when two objects are touching each other and need clean, accurate borders between them.

## What is Auto Bordering?

When you have already created one polygon, Auto Bordering lets you use part of that polygon's border while drawing another polygon. This keeps the shared side consistent and avoids gaps or overlaps between adjacent annotations.

## How to Use Auto Bordering

<iframe title="Auto Bordering - Your Solution to Faster Annotation" />

1. **Draw the first polygon** around the object as usual.
2. **Start drawing the next polygon** that shares a boundary with the first one.
3. **Press and hold the Alt key** when you reach the side that should be common.
4. **Select the points** on the existing polygon border that you want to reuse.
5. **Continue drawing the remaining polygon** and close the shape.
6. **Review the shared border** to make sure both polygons are aligned correctly.

## Example Use Case

If you are annotating two adjacent land parcels, road lanes, buildings, or touching object segments, draw the first polygon completely. For the second polygon, use Auto Bordering on the side already created by the first polygon, then draw only the remaining outer boundary.

## Benefits

* Reduces repeated manual drawing.
* Keeps common polygon borders clean and consistent.
* Helps avoid small gaps or overlaps between touching objects.
* Speeds up segmentation work for adjacent objects.

## Best Practices

* Create the first polygon carefully because its border will be reused.
* Use Auto Bordering only for the side that is actually common between polygons.
* Zoom in while selecting border points for better accuracy.
* Review the final polygon before submitting the annotation.


# Auto Label Jobs by Active Learning
Source: https://docs.labellerr.com/features/auto-label-jobs

Learn how to use active learning and zero-shot learning in Labellerr to autolabel datasets efficiently, select informative samples, and manage auto label jobs.

In Labellerr, we have implemented active learning to autolabel datasets by selecting the most informative samples for labeling, complemented by zero-shot learning. The results in the datasets are excellent. Here's how to perform auto label jobs on Labellerr:

### To create a new job or view the status and details of past jobs, including attached model details and predictions, follow these steps:

1. Go to '**Settings**' on the dashboard and select '**Autolabel Jobs**'.

<Frame>
  <img alt="Autolabel Jobs Settings" />
</Frame>

2. You will see previously created jobs and their details. To create a new job, select '**Create New Job**'.

<Frame>
  <img alt="Create New Job Button" />
</Frame>

3. First, select the **use case**, such as the type of annotation like bounding box, image segmentation, etc.

<Frame>
  <img alt="Select Use Case" />
</Frame>

<Frame>
  <img alt="Use Case Options" />
</Frame>

4. Next, you can select current and previous batches/projects with labeled data.

Options on the right side include 'accept', 'review', and 'client\_review'—these indicate the statuses of annotated files in current or past projects that can be used as labeled data for labeling new data. Select '**Select labels to train**' to choose the labels needed for the current project. After selecting the required options, click '**Next**'.

<Frame>
  <img alt="Select Labels to Train" />
</Frame>

5. Review the job details, enter the Job name and description, and specify the number of training hyperparameters (epochs) required to execute the job.

<Info>
  An epoch is when all the training data is used at once and is defined as the total number of iterations of all the training data in one cycle for training the machine learning model.
</Info>

Click '**Start Job**'. The job will begin, and the details will be displayed on your autolabel screen while the job is in progress.

<Frame>
  <img alt="Autolabel Job in Progress" />
</Frame>

6. Attach a model to the completed job in the '**Models**' section to run autolabeling. You can view job details, metrics, and model attachment status here.

<Frame>
  <img alt="Attach Model" />
</Frame>

7. Additional options are available by clicking the three-dot button. You have the option to detach the model from the job.

<Frame>
  <img alt="Detach Model Option" />
</Frame>

### To run Autolabel and see the results on a set of files, follow these steps:

After completing this process, you can run autolabeling on individual files or on the entire dataset at once.

1. Go to the labeling screen by clicking '**Label**' on the dashboard and select '**Use Autolabel**'.

<Frame>
  <img alt="Use Autolabel" />
</Frame>

2. The autolabel model details will be displayed in a popup. Click '**Get Predictions**'.

<Frame>
  <img alt="Get Predictions" />
</Frame>

3. Fetching labels will start, showing 'fetching labels' while in progress.

<Frame>
  <img alt="Fetching Labels" />
</Frame>

4. After fetching, the results will be displayed on your screen, showing the labeled objects.

<Frame>
  <img alt="Labeled Objects" />
</Frame>

<Note>
  See the video tutorial.

  <iframe title="Boost Data Annotation Accuracy and Efficiency with Labellerr's Active Learning Feature" />
</Note>


# Classification Agent
Source: https://docs.labellerr.com/features/classification-agent

Labellerr’s Classification Agent automates classification tasks for various data types using AI, enhancing speed and accuracy.

Labellerr’s **Classification Agent** introduces a fully automated, agentic (AI-driven) workflow designed to make classification tasks for images—and beyond—**faster, smarter, and more accurate**. By leveraging the power of AI agents and batch processing, Labellerr replaces time-consuming manual workflows, minimizing errors and dramatically boosting annotation productivity for images, videos, audio, and text.

## Key Features

* **Batch classification:** Processes many images (or files) at once, not one by one.
* **Automatic answers:** AI agent analyzes each image and completes multiple classification questions automatically.
* **Template saving:** Save and reuse classification setups for future projects.
* **Multi-domain support:** Works for images, videos, audio, and text data.
* **Easy review:** Annotators simply verify or correct AI suggestions, speeding up final approval.

## How Does the Classification Agent Work?

<iframe title="Introducing Classification Agent | Labellerr's New Automated Annotation Workflow" />

### 1. Set Up Your Project

* **Select your dataset** (e.g., a set of vehicle scene images).
* **Define your classification questions:**
  * *Radio button*: Traffic volume (High, Low, Clear Road).
  * *Dropdown*: Weather condition (Sunny, Cloudy, Rainy, Fog, Snowy).
  * *Multi-select*: Objects present (Pedestrian, Car, Truck, Bike, Bus).
* **Select your AI agent** (e.g., Gemini 2 flash) as the engine for classification.

### 2. Save Templates for Reuse

* Save this classification setup as a template.
* Instantly reuse it in any current or future project, ensuring consistency and efficiency.

### 3. Batch Process with the Agent

* **Initiate the AI agent workflow:** The Classification Agent automatically analyzes all images in your dataset.
* All questions are answered in bulk, not per image.

### 4. Review and Verify

* The review screen shows each image with its AI-generated classification answers.
* Your only job: **accept or correct** outputs. No more repetitive manual selections.

### 5. Apply to Any Data Type

* The agentic classification workflow can be adapted for videos, audio, text, and more—making it a universal tool for large datasets across domains.

## Real-World Example

Previously, annotators would view each image, manually judge factors such as traffic volume and weather, mark every item present, and possibly make mistakes or omissions. Now, Labellerr’s Classification Agent performs all this in bulk using AI, so human reviewers simply verify each result. Work that used to take hours or a full day can now be finished in minutes.

## Benefits

* **Faster annotation:** Drastically cuts manual effort and completion time.
* **Higher accuracy:** Consistent labeling, fewer human mistakes.
* **Effortless review:** Focus on quality verification, not repetitive input.
* **Scalable:** Suitable for datasets with thousands (or more) files.
* **Versatile:** Extendable across modalities (images, videos, audio, text).

## Best Practices

* Save templates for standard classification flows to reuse across projects.
* Use the review step to quickly catch and correct outlier results or edge cases.
* Regularly update your classification questions and AI agent selection as your project’s needs evolve.


# CLIP Mode and Gap Filler
Source: https://docs.labellerr.com/features/clip-mode-gap-filler

Explore Labellerr’s advanced CLIP Mode and Gap Filler features for precise image segmentation, refining annotation edges, and seamlessly filling unlabeled spaces.

## Introduction

Labellerr’s **CLIP Mode** and **Gap Filler** are advanced annotation features built to save time, boost accuracy, and streamline the process of precise image segmentation—especially when traditional keypoint dragging and manual corrections fall short. These tools are ideal for handling overlapping, missing, or messy annotation borders encountered in real-world datasets across fields like medical imaging, autonomous driving, retail, and agriculture.

## What is CLIP Mode?

**CLIP Mode** is a smart boundary editing tool that automates the process of refinivng annotation edges and clearing overlaps in a single step. Instead of laboriously stretching keypoints or editing polygons to fix borders, users can quickly:

* Sharpen and correct polygon edges.
* Instantly resolve overlapping segments between adjacent objects.
* Achieve precise, pixel-level correction—no manual shape manipulation required.

CLIP Mode works seamlessly with annotations generated from automatic tools like SAM (Segment Anything Model), where artifacts such as missing pixels or overlapping masks are common.

## Gap Filler

**Gap Filler** is designed to effortlessly fill unlabeled spaces—“gaps”—that are often left between objects after auto-annotation or manual masking. Combining Gap Filler and CLIP Mode allows for ultra-fast, accurate segmentation by letting users:

* Auto-complete annotation masks in a single step.
* Repair incomplete labeling between objects (e.g., between people in a group photo).
* Perfect common borders between objects for clean, contiguous masks.

## How to Use CLIP Mode

<iframe title="Boost AI Image Annotation 10X with Labellerr’s CLIP Mode" />

1. **Identify a Problem Area:**
   * Look for jagged edges, overlaps, or unlabeled gaps between two annotated objects.

2. **Activate the Proper Polygon:**
   * Select the object (polygon) you wish to refine.

3. **Enable CLIP Mode:**
   * Turn on the **CLIP Mode** button in the annotation panel.

4. **Adjust Boundaries:**
   * With CLIP Mode active, the software will automatically correct and align the selected polygon's border along the shared edge with the neighboring object.
   * For overlapping segments, the correct object keeps ownership of the pixels.

5. **Review and Fine-Tune:**
   * Instantly see the corrected, sharp boundary.
   * Inspect for any remaining irregularities; use **Magic Filler** or manual edits for further refinement.

## How to Use Gap Filler

<iframe title="Gap Filler - Your Solution to Faster Gap Filling" />

1. **Detect Gaps:**
   * After labeling with SAM or another method, examine the image for spaces between labels.

2. **Activate Gap Filler (Magic Filler):**
   * Fill in the empty region between polygons by selecting the area or using shortcut keys as per the interface.

3. **Combine With CLIP Mode:**
   * For adjoining objects, after filling gaps, use CLIP Mode to align borders and ensure a seamless, overlap-free mask.

## Example Use Cases

* **Medical Imaging:** Segment organs, tumors, and tissue boundaries with extreme precision, eliminating errors from overlapping or incomplete mask borders.
* **Autonomous Driving:** Cleanly separate objects like pedestrians, vehicles, and road signs for robust training data.
* **Retail & Agriculture:** Accurately outline products on shelves or distinguish between healthy/diseased crops, even against cluttered backgrounds.

## Key Benefits

* **Fast:** Up to 10x quicker than manual keypoint editing.
* **Accurate:** Ensures crisp, correct segmentation along shared object borders.
* **Flexible:** Works across industries and annotation types, from people and animals to complex industrial scenes.
* **Seamless Workflow:** Easily integrates with other Labellerr features like SAM, Magic Editor, and Auto-Label for end-to-end annotation efficiency.

## Best Practices

* Use CLIP Mode after initial annotation (especially after SAM or Magic Filler) to finalize object boundaries.
* Use Gap Filler to catch missing pixels between adjacent masks before activating CLIP Mode.
* Always review the adjustment, especially in cases with complex object overlaps.

CLIP Mode and Gap Filler together represent a major upgrade in Labellerr’s image annotation toolkit, making precise segmentation fast for any annotation project.


# Copy From Similar Images
Source: https://docs.labellerr.com/features/copy-similar-images

Learn how Labellerr's 'Copy from' feature reduces annotation time by up to 70% by leveraging past annotations from similar images.

<CardGroup>
  <Card title="What is the “Copy from” feature?">
    To save labeling time, [Labellerr](https://www.linkedin.com/company/labellerr/) has introduced copy the label feature which reduces the time spent on each image by up to 70%.
  </Card>

  <Card title="Benefits of Copy from">
    The average time spent by annotators on labeling classifications with an average of 60-70 labels per image is around 10000 hrs. In most of the projects, up to 70% of labels are the same, it's just 30% of labels that changes with every image/video. If it's a video project, the time would go up by 150%. Now, the annotators can leverage their past annotations and copy all the labels with just a click.
  </Card>

  <Card title="How it works">
    For large and diverse datasets, our system sorts the annotated image based on the similarity with the highest chance of similar labels. This additionally saves annotators time to look for the right image to copy, because it will always be at the top.
  </Card>
</CardGroup>

<iframe title="Labellerr Feature demo 4: Copy Previous file to speed up classification annotation" />


# Event/Action Tagging
Source: https://docs.labellerr.com/features/event-tagging

Learn how Labellerr's Event Tagging feature transforms raw video into structured, searchable data by marking and labeling specific segments in a video timeline.

**Event/Action Tagging** is the process of marking specific segments or moments in a video timeline that correspond to important or noteworthy events. Each tag typically includes:

* The **start time** of the event.
* The **end time** (adjustable).
* A **name or label** describing the event (e.g., "Goran Dragic’s clutch 2-pointer" or "Foul on LeBron").
* Custom **attributes** to capture additional details and metadata (e.g., player names, game situation, or action intensity).

This transforms raw video into structured, searchable data that can be accessed instantly.

## How to Use Labellerr’s Event/Action Tagging Tool

<iframe title="Master Event Tagging with Labellerr: Effortlessly Organize & Analyze Video Content" />

### Step 1: Create a Video Annotation Project

* Create a video annotation project in Labellerr designed for event tagging.

<Frame>
  <img alt="Create a Video Annotation Project" />
</Frame>

### Step 2: Create an Annotation Template

* Create an annotations template configured with the "event" criteria object.

<Frame>
  <img alt="Create an Annotation Template" />
</Frame>

### Step 3: Add Event on the Timeline

* While performing the video annotation, add the event annotation directly on the video timeline.

<Frame>
  <img alt="Add Event on the Timeline" />
</Frame>

### Step 4: Double-Click the Event to Set Its Last Frame

* Double-click on the event on the timeline to set its last frame.

<Frame>
  <img alt="Double-Click the Event to Set Its Last Frame" />
</Frame>

### Step 5: Click the "Set End Frame" Button

* Reach the last frame of the event and then click the **Set End Frame** button.

<Frame>
  <img alt="Reach the Last Frame of Event and Click Set End Frame" />
</Frame>

### Step 6: Event Gets Set on the Timeline

* After clicking the button, the event will be set on the timeline.

<Frame>
  <img alt="After Clicking the Button Event Will Set on Timeline" />
</Frame>

### Step 7: Repeat for All Events

* Keep doing this for all the events to tag them.

<Frame>
  <img alt="Repeat for All Events" />
</Frame>

***

## Event/Action Tag Attributes

Event tagging in Labellerr supports adding **attributes** directly to event annotations. With this capability, you can attach additional context, metadata, or specific details to any tagged event (e.g., player names, action intensity, success/failure states, or game quarters).

<iframe title="Event/Action Tagging with Attributes" />

### How to Add Attributes to Event/Action Tags

1. **Enable Attributes in Annotation Settings:** When creating your project annotation guidelines, click **Edit** on your annotation class and click on **Add Attribute**.

<Frame>
  <img alt="Enable Attributes in Annotation Settings" />
</Frame>

2. **Add Attributes:** Configure the various attributes that you want to associate with your annotation class.

<Frame>
  <img alt="Add Attributes" />
</Frame>

3. **Fill Attributes During Annotation:** While annotating, once you select your event annotation class, an attribute filling box will appear on the screen automatically. Alternatively, you can press **E** on your keyboard to bring the attribute box onto the screen, and then fill in the attributes.

<Frame>
  <img alt="Fill Attributes During Annotation" />
</Frame>

## Benefits of Event/Action Tagging with Labellerr

* **Instant Access to Highlights:** Skip long videos to jump directly to key moments.
* **Structured Data for ML:** Tagged moments become datasets for machine learning, enabling recognition of patterns and automated video understanding.
* **Multi-Industry Application:** Useful for sports, security monitoring, education, content creation, marketing, and more.
* **Saves Time:** No more manual scrubbing through hours of footage to find specific events.
* **Customizable:** Tags can be named, timed, edited, and organized to suit your project needs.

## Use Cases

* **Sports Analytics:** Tag game highlights such as dunks, fouls, goals, or plays—ideal for broadcasters and coaching staff.
* **Security & Surveillance:** Mark suspicious activities for fast review and incident documentation.
* **Education & Content Creation:** Highlight key concepts, demos, or tutorial sections for streamlined video content.
* **Media & Entertainment:** Quickly generate clips for social media, marketing, or highlight reels.

## Best Practices

* Tag events precisely at their start time for easy navigation.
* Use descriptive, consistent naming conventions to organize tags efficiently.
* Adjust the length of tags to cover entire events but keep them concise.
* Regularly review and update tags for accuracy as video content is refined.
* Combine event tagging with other Labellerr annotation tools for enriched datasets.


# Labellerr Grouping Tool Feature
Source: https://docs.labellerr.com/features/grouping-tool

Discover Labellerr's grouping tool, which allows you to group labels for a single object into one unit, enhancing AI model understanding and improving annotation consistency.

Labellerr has introduced a **grouping tool feature** that enables grouping all labels for a single object into one unit. This helps the AI model better understand the relationship between different parts of an object.

### Steps to Implement the Grouping Tool

1. **Annotate** all parts of the object.
2. **Enable** the grouping icon button at the top.
3. **Draw an area** that covers all annotations of the object.
4. A **unique ID** will be automatically assigned to all parts of that object.

<Note>
  The ID can be changed if any part of the object is mistakenly grouped with another object.
</Note>

<iframe title="[VIDEO_TITLE]" />

### How to Identify Incorrect IDs?

Labellerr has introduced a **Filter Annotations** icon in front of the annotated objects list.

1. **Apply the ‘Group’ filter** to check:
   * If any ID is missing from a group, it will appear under the **‘Ungrouped’** section.
   * The **‘Grouped’** section will show grouped objects. Hover over them to review.

2. **Switch to the ‘Question’ option** to see the objects list in their original view.

3. **Click the ‘Filters’ icon** to:
   * View grouped and ungrouped objects.
   * Check objects with remarks left by annotators or reviewers. Users can apply this filter to view remarked annotations, and the count will be displayed in the left panel.
   * Identify issues like:
     * ID mismatches between parts of a single object.
     * Missing attributes where mandatory.
     * Missing IDs for any annotated object.

4. **Review a specific object’s annotations.**

This feature improves annotation consistency, reduces errors, and ensures better AI model performance.

<iframe title="[VIDEO_TITLE]" />


# Hand Keypoint Tracking
Source: https://docs.labellerr.com/features/hand-keypoint-tracking

Learn how Labellerr's Hand Keypoint Tracking supports up to 21 points for precise hand and finger gesture annotation on images and videos.

<iframe title="Hand Keypoint Tracking on Image and Video" />

# Hand Keypoint Tracking

Precise hand annotation is a critical requirement for many computer vision applications, especially in scenarios involving gesture interpretation, hand-object interaction, and egocentric understanding.

Labellerr supports **Hand Keypoint Tracking** across both images and videos with up to **21 keypoints per hand**, enabling teams to create detailed and structured annotations for hand movement and articulation. This enhancement allows annotation teams to define fine-grained hand positions with greater consistency, making it easier to build high-quality datasets for motion-centric AI workflows.

***

## Key Features

* **21-Point Skeletal Mapping:** Captures the complete skeletal structure of the hand, including the wrist and five fingers with all joint articulations.
* **Image & Video Compatibility:** Supports tracking across both static images and video timelines, maintaining temporal consistency.
* **Preset Support:** Redesigned template setups allow teams to use standard hand presets without manual layout configuration.
* **Egocentric Video Optimization:** Built specifically to support first-person views and handle complex rotations, occlusions, and hand-object interactions.

***

## Step-by-Step Guide: Using Hand Keypoint Tracking

### 1. Configure the Hand Keypoint Template

* Navigate to the **Label Configuration** section in your project setup.
* Click on **Add Object**, enter a label name (e.g., `hand`), and select the **Keypoint** type.
* Choose the **Hand Preset (21 Points)** from the template presets. This automatically generates the skeletal structure with predefined wrist and finger joint landmarks.
* Click **Save** to apply the template to your project.

### 2. Positioning the Keypoints

* Open the labeling screen and select the `hand` label.
* Click on the canvas to place the hand keypoint skeleton.
* Adjust individual keypoints (e.g., finger tips, knuckles, wrist joint) to precisely align with the subject's hand structure.

### 3. Tracking Across Video Frames

* For video projects, select the hand annotation on the canvas.
* Right-click and choose **Hand Tracking** (or use the keypoint tracking controls) to automatically propagate the skeleton across subsequent frames.
* Review the tracked frames and manually adjust keypoints if there are minor drift issues caused by fast movements or severe occlusions.

***

## Use Cases

* **Gesture Recognition:** Training models to interpret hand signs, gestures, and user interface controls.
* **Human-Computer Interaction (HCI):** Capturing interactions in AR/VR and smart devices.
* **Robotics:** Annotating hand movements for robotic manipulation and training.
* **Egocentric Workflows:** Annotating tasks filmed from a first-person perspective, such as assembly lines, medical surgeries, or cooking tutorials.
* **Sign Language Interpretation:** Capturing fine-grained finger spelling and movements for translation systems.


# Image Captioning Using Generative AI
Source: https://docs.labellerr.com/features/image-captioning

Learn how to generate detailed image captions, descriptions, and keywords using generative AI in Labellerr, enhancing your annotation projects.

Start by creating a project following the steps outlined in the link provided below. [How to Create a New Project?](/getting-started/create-project)

### Setting Up Object/Classification template:

<Info>
  You can refer to the link mentioned above for guidance on how to create a template for objects/questions within a project.
</Info>

Select a classification question and specify its type as '**captioning**' from the dropdown menu. Here, I've created a project and labeled a classification question as 'caption' with the question type set to 'captioning'.

<Frame>
  <img alt="Captioning Classification Setup" />
</Frame>

<Note>
  You have the option to create a new project or modify an existing project template according to your needs. Additionally, multiple questions can be set up to gather various types of details. You can choose to obtain all details at once or gather them one by one by providing different prompts.
</Note>

After setting the template, Go to Dashboard. Click on "**Start Labelling**" button on the dashboard. This will redirect you to the annotation canvas.

<Frame>
  <img alt="Start Labelling Button" />
</Frame>

### Predict Button:

Below the displayed image, you will see the "**Predict**" button. Click on the "**Predict**" button to open a prompt box where you can input a prompt for the generative AI. Example prompt: "Write a detailed description about this image".

<Frame>
  <img alt="Predict Button and Prompt Box" />
</Frame>

### Generating Descriptions:

Click "**Proceed**" after entering your prompt. The generative AI will then provide a description based on your input.

<Frame>
  <img alt="Generative AI Description Output" />
</Frame>

You can review and edit this output as needed.

<Tip>
  **Further Prompts:** You can give additional prompts to get more details about the image, such as relevant keywords or a brief description.

  If the API is available, the **meta description** can be displayed in the info icon. Click on the info icon to view the meta description, which includes keywords and descriptions related to the image provided by the API.
</Tip>

Once satisfied with the description, click the "**Submit**" button to submit the file.

The file will be sent to a reviewer, who can also view the image and edit the output if necessary.

Reviewers can access files for review by navigating to the "Review" page from the dashboard.


# Image Similarity
Source: https://docs.labellerr.com/features/image-similarity

Understand Image Similarity in Labellerr, a capability used to automate repetitive data preparation tasks for faster, more efficient, and accurate pipelines.

<Note>
  This guide is meant for users to understand the concept of Image Similarity, how can we use this capability to automate the repetitive tasks to make the data-preparation pipeline more faster, efficient, accurate & convenient .
</Note>

<Card title="Topics Covered" icon="images">
  This guide covers image similarity capabilities in Labellerr:

  * **What is Image Similarity** - Understanding the concept and measurements
  * **Image Similarity at Labellerr** - How the feature works in our platform
  * **Use Cases in Data Preparation** - Real-world applications and benefits
  * **Data Preparation Automation** - How to streamline annotation workflows
  * **Practical Implementation** - Step-by-step usage guide
</Card>

Image similarity is the measure of how similar two images are. In other words, It quantifies the degree of similarity between intensity patterns in two images.

#### Similar Images

<Frame>
  <img alt="Similar Images Example" />
</Frame>

### IMAGE SIMILARITY & DATA PREPARATION

**Data preparation** is the process of transforming raw data so that data scientists and analysts can run it through machine learning models to uncover insights or make predictions. There are different steps in data preparation like, **Data-Collection**, **Data-Curation** & **Data-Annotations**. These steps are **very time-consuming and requires a lots to resources and cost for doing them on scale**, which can be automate or reduced by the capability of **IMAGE SIMILARITY**. Following is some use-cases where we can use the capability of **IMAGE SIMILARITY** to automate the tasks and make the process faster .

<Frame>
  <img alt="Image Similarity Data Prep" />
</Frame>

<Steps>
  <Step title="Data-Collection:">
    <p>**Data-Collection:** Collecting data for training the ML model is the basic step in the machine learning pipeline. The predictions made by ML systems can only be as good as the data on which they have been trained.</p>

    <Frame>
      <img alt="Data Collection" />
    </Frame>

    <p>Following are some of the **problems** that can arise in **data collection**:-</p>

    <ul>
      <li>**Inaccurate data**. The collected datasets could have some data/files that are **unrelated to the problem statement**. After finding one such file that is inaccurate as per the problem statement we can find out all similar files and remove them from datasets .</li>
      <li>**Data imbalance**. Some classes or categories in the data may have a disproportionately high or low number of corresponding samples. As a result, they risk being under-represented in the model. We can use the **IMAGE SIMILARITY** capability to find out the disproportion via finding out the similar images and then accordingly collect more data or remove data to ensure the proportion .</li>
    </ul>

    <Frame>
      <img alt="Data Imbalance" />
    </Frame>
  </Step>

  <Step title="Data-Curation :">
    **Data-Curation :** Data curation is a critical part of model development as Computer Vision models are derived by learning from the data they see. We define data curation as the process of **selecting**, **preparing** and **organising** a collection of data such that the value of the data can be maintained over time.

    **DUPLICATION :-** When the **same datasets are available at different sources**, challenges such as **duplication occurs**. Transformation of data may alter one source leaving the other source and result in incorrect data usage. **IMAGE SIMILARITY** can be used to find out the similar datasets or files .

    <Frame>
      <img alt="Data Curation" />
    </Frame>
  </Step>

  <Step title="Data-Annotation:-">
    Data annotation is the process of Labelling data in various formats such as video, images, or text so that machines can understand it. So, as you now know, Image Annotation is vital in modules that involve facial recognition, computer vision, robotic vision, and more.

    <Frame>
      <img alt="Data Annotation" />
    </Frame>
  </Step>
</Steps>

**Efficiency**, **Quality** and **time** are some of the **key challenges** of **data-annotation**. We can use the capability of **IMAGE SIMILARITY** to build a annotation pipeline which is better in terms of quality & efficiency & time-consumption .

### IMAGE SIMILARITY AT LABELLERR

We have used the capability of **IMAGE SIMILARITY** to build a feature called **COPY PREVIOUS** in our annotation pipeline. This feature **enables a user to copy answers from the similar files in the pipeline which have been already annotated.**

<Note>
  Before going forward, please ensure that you are familiar with the Annotation Projects, Datasets and Annotation Pipelines at Labellerr. If not please visit the below links :-

  1. [How to create a datasets at workspace level?](/tutorials/datasets)
  2. [How to create a new project](/getting-started/create-project)?
  3. [Start Labelling](/actions/start-labelling)
</Note>

Suppose you are doing annotation. While annotating **for any specific image you feel that such image (similar-image) has been already annotated**. Now your **wish will be to just copy the labels of the similar previous file**. Following examples demonstrate the same functionality.

<Card title="Image Currently Under Annotation Process">
  <Frame>
    <img alt="Image under annotation" />
  </Frame>
</Card>

Now if you feel that a similar image is already annotated. Then click on the Button **Copy previous.** After this similar images(Make sure that **“sort by”** filter is set to **similarity** as shown in image) in the annotation pipeline will be rendered as follow :-

<Info>
  **Note-1:** When the **“sort by”** filter is set to **similarity.** The images are render in order of similarity. Means the **First image is the most similar** & **Last Image is least similar image.**

  **Note-2:** When the **“sort by”** filter is set to **Recently Annotated.** The images are rendered on the basis of time of annotation. Means the **First image is the most recently annotated** & **Last Image is least recently annotated.**
</Info>

<Frame>
  <img alt="Similar Images Rendered" />
</Frame>

Now one can view any specific image via **hovering on image** & clicking on **view** button as follow.

<Frame>
  <img alt="View Image Button" />
</Frame>

<Frame>
  <img alt="Image View" />
</Frame>

To copy the answers from the compatible similar image. Click on **Copy Button** and then click the **Submit** button.

<Frame>
  <img alt="Copy Button" />
</Frame>

<Frame>
  <img alt="Submit Button" />
</Frame>

<Note>
  This feature can be use efficiently in annotation projects where the annotation questions are only the classification questions .
</Note>

### TRY IMAGE SIMILARITY AT LABELLERR

1. [**Create a new project**](/getting-started/create-project) along **with datasets**. Annotate some files in the pipeline and for any specific images that feels similar to any previous image, Try out the “Copy Previous”.

2. [**Create datasets**](/tutorials/datasets) at workspace level. Now **create a new project and link the same datasets** with the project. Annotate some files in the pipeline and for any specific images that feels similar to any previous image. Try out the “Copy Previous” .

3. **Create a project with multiple datasets**. Annotate some files in the pipeline and for any specific images that feels similar to any previous image. Try out the “Copy Previous” . **Observe that if the similar files are rendering from multiple datasets**.

4. **Add more data to a existing datasets**. Annotate some files in the pipeline and for any specific images that feels similar to any previous image. Try out the “Copy Previous” . **Observe that if the similar files are rendering from the added files**.

<Note>
  **Note:** After creating any project or linking any datasets with project, Please contact the back-end team. There is some work which is going on, till then after linking projects & datasets we need to invoke some APIs manually from back-end. This requires the project\_id & datasets\_id that are linked. This can be done anytime after linking project & datasets.
</Note>


# Interpolation Feature
Source: https://docs.labellerr.com/features/interpolation

Learn about Labellerr's interpolation feature for video annotation, which automates bounding box tracking across multiple frames to save time and ensure consistency.

<Card title="Introduction to Video Annotation">
  Labellerr provides a user-friendly platform to annotate videos with bounding boxes, making it easy to track and mark moving objects, such as cars, throughout the entire frame sequence. This process ensures accurate and efficient video annotation for various computer vision and AI projects.
</Card>

## What is Bounding Box Interpolation?

Interpolation in Labellerr is a feature that automates the process of marking object movement across multiple video frames. After annotating key frames (i.e., manually marking bounding boxes on certain frames), the platform intelligently fills in (interpolates) the object's bounding boxes between those frames. This saves time, reduces manual work, and maintains labeling consistency.

## Using the Interpolation Feature

<Steps>
  <Step title="Start Bounding Box Annotation">
    * Begin by uploading your video to the Labellerr platform.
    * Select the bounding box annotation tool from the interface.
  </Step>

  <Step title="Mark Key Frames">
    * Play the video and pause at the first frame where the object (e.g., a car) appears.
    * Draw a bounding box around the object.
    * Advance the video to another significant frame where the object's position has changed (key frame).
    * Adjust or redraw the bounding box to fit the object in its new position.
  </Step>

  <Step title="Adjust the Bounding Boxes">
    * For frames in between these key frames, you may adjust the bounding boxes as needed, especially if the object changes shape or direction.
  </Step>

  <Step title="Apply Interpolation">
    * Once bounding boxes are marked on multiple key frames, use the Interpolation feature.
    * Labellerr will automatically generate bounding boxes for all intermediate frames by calculating how the object moves from one key frame to the next.
    * This process “fills the gaps” so you don’t have to annotate every single frame manually.
  </Step>

  <Step title="Review & Edit">
    * Review the interpolated bounding boxes across the video sequence.
    * Make any necessary adjustments if the automatically generated boxes need refinement.
  </Step>
</Steps>

For a detailed guide, watch the video.

<iframe title="Annotate Video Objects with Labellerr’s Bounding Box Tool Easily" />


# Magic Editor
Source: https://docs.labellerr.com/features/magic-editor

Discover Labellerr's Magic Editor, a precision tool for refining image annotations by smoothing edges, merging missing labels, and correcting irregular boundaries.

Labellerr's **Magic Editor** is a precision tool designed for effortlessly refining image annotations. It is especially useful for fixing sharp edges, merging missing labels, and smoothing annotation boundaries, making it an ideal solution for projects in retail, medical imaging, and any domain where annotation quality directly impacts AI model performance.

## What Does Magic Editor Do?

Magic Editor allows users to:

* **Smooth and adjust boundaries** for annotations, eliminating jagged edges.
* **Merge unlabeled or missed regions** (such as hair, loose clothing, or partially detected objects) into existing annotations with a few clicks.
* Instantly correct irregular or imprecise annotation areas without disrupting the overall shape.
* *Quickly touch up* one-dot labels generated by automated methods like SAM.

## How to Use Magic Editor

<iframe title="Faster precised Image Annotation using Labellerr's Magic Editor" />

### Step 1: Identify Annotation Irregularities

* Review your annotation. Look for sharp or jagged edges, or spots where the label doesn’t fully cover the target object.

### Step 2: Activate Magic Editor

* Access Magic Editor within the annotation panel. The feature can be used in conjunction with normal annotation tools or after automated methods like SAM’s one-dot labeling.

### Step 3: Refine with Key Points or Merge Areas

* **For edge smoothing:** Drag individual key points to gently curve and improve boundary lines. This helps fix sharp or unnatural corners.
* **To merge unlabeled regions:**
  * Hold `Shift` and select the starting key point on the object boundary.
  * Move your cursor across the unlabeled area, right-clicking to cover missed regions.
  * End by selecting another boundary key point while holding `Shift` again.
  * For continuous adjustments, hold `Ctrl` and guide the pointer along the desired boundary.

### Step 4: Review the Correction

* Inspect the updated segmentation mask or bounding polygon to ensure the modification looks natural and the target object is properly enclosed.

### Step 5: Apply and Continue

* Confirm the adjustment. Continue editing other areas as needed or proceed with your annotation workflow.

## Benefits

* **Saves Time:** No need to redraw entire masks or shapes—fix only what’s needed.
* **Increases Accuracy:** Ensures pixel-perfect, label-consistent masks, critical for AI training tasks.
* **Non-Destructive Workflow:** Edit without disrupting the overall annotation shape or label hierarchy.
* **Keyboard Shortcuts:** Rapid boundary manipulation with Shift and Control keys for faster, smoother work.

## Use Cases

* **Retail:** Refine product outlines for catalog and inventory automation.
* **Medical Imaging:** Precisely segment organs, tumors, or anatomical structures where label accuracy affects diagnostic models.
* **General AI Applications:** Clean up complex shape outlines in people, vehicles, industrial settings, and more.

## Best Practices

* Use Magic Editor especially after initial automated or SAM-based annotations to catch missed pixels and perfect edges.
* For highly complex boundaries (e.g., hair or textile frays), employ multiple short refinement actions rather than one large adjustment.
* Save iterations of your work in case you need to step back or compare edits.


# Natural Language Search
Source: https://docs.labellerr.com/features/natural-language-search

Discover Labellerr’s Natural Language Search, an AI-powered feature that allows you to instantly find files, images, or datasets by simply typing a descriptive phrase.

Labellerr’s **Natural Language Search** feature lets you find files, images, or complete datasets instantly—even if you don’t remember exact names or filenames. Powered by AI, you simply type a phrase (just like Google search), and Labellerr scans your workspace, datasets, or images for the content that matches your description. No more endless scrolling or manual checking—just fast, intuitive searching across your data.

## How to Use Natural Language Search

<iframe title="Search Images Instantly Using Natural Language | Labellerr’s Natural Language Search Explained" />

### 1. Enable Natural Language Search

* **Where to Find It:**
  * Go to the **settings section** in your Labellerr workspace to see all your datasets, or open a specific dataset to get started.
* **Activation:**
  * Look for the **natural language search** option in your dataset or workspace view.

### 2. Enter Your Search Prompt

* In the search bar, type a plain language description of what you’re looking for.
* Examples:
  * “Dataset with a gray car”
  * “Cake photo”
  * “Birthday celebration image”
  * “Red truck on highway”
* The system supports complex queries (e.g., “sunny beach with family”, “person with dog at park”).

### 3. Refine Your Results

* **Adjust Confidence Level:**
  * If your prompt is ambiguous or returns too many results, use the confidence slider to make the search stricter or more relaxed.
* **Show Matching Datasets/Images:**
  * Click on “Show Datasets” or “Show Images” to view and explore all files matching your prompt.

### 4. Browse and Organize

* **Preview Results:**
  * Click on a result to see images and all related metadata and details.
* **Organize:**
  * Use the search to help organize, label, or manage files and datasets as needed.

## Key Benefits

* **Super-Fast Search:** Locates files and datasets in seconds—even with thousands of images or unorganized folders.
* **More Than Filename Search:** Works on image content, associated text, and metadata using AI.
* **No Memory Burden:** Don’t remember the file or dataset name? Just describe what you want.
* **Powerful for Teams:** Allows creators, businesses, and organizations to manage massive datasets or archives, regardless of storage backend (including Google Drive, cloud platforms, or local storage).
* **Flexible Use Cases:**
  * Find specific photos, objects, or scenes
  * Organize content for projects
  * Accelerate annotation or content review

## Best Practices

* Use descriptive and specific prompts for faster, more accurate results.
* Employ the confidence level adjustment to fine-tune searches.
* Organize search results into new datasets, or export relevant files for further use.
* Try natural language search for both images and non-image data (where supported).


# Notification Bar
Source: https://docs.labellerr.com/features/notification-bar

Labellerr’s Notification Bar is a collaboration feature designed to streamline team communication, enable instant tag-based messaging, and resolve complex labeling queries quickly.

Labellerr's **Notification Bar** is a dedicated collaboration feature designed to streamline communication and boost productivity in annotation teams. It enables instant tag-based messaging, keeps everyone in the loop, and ensures complex labeling queries are resolved quickly—without disrupting your workflow.

## Key Features

* **Tag Team Members Directly:** Seek second opinions or escalate queries by tagging any colleague (including annotators and reviewers) right within the platform.
* **Visual Alerts:**
  * **Red Dot:** Appears on the dashboard for the tagged recipient, indicating an action or response is needed.
  * **Blue Dot:** Shows which messages remain unread in a user’s notification inbox.
* **One-Click Navigation:** Click any notification to immediately jump to the relevant labeling window—saving time and reducing confusion.
* **Inbox Filtering:** Organize notifications with filtering options, making it easy to keep track of pending, read, or resolved issues.
* **External Integration:** The notification inbox can be linked to Slack for real-time, cross-platform collaboration.

## Step-by-Step Workflow

<iframe title="Enhance Team Collaboration with Labellerr’s Notification Bar" />

1. **Identify an Annotation Query:** While annotating (e.g., unsure whether to label a jacket under the "man" class), highlight the relevant area using the tool’s remark or comment function.

2. **Tag a Team Member:** Tag any team member, reviewer, or stakeholder—whether they’re on your team or the client side—directly in the tool.

3. **Notification Delivery:** The tagged person sees a **red dot** on their dashboard, signaling that a response is needed.

4. **Message Status Tracking:** A **blue dot** appears for any notification that remains unread by the recipient.

5. **Jump to Task:** The team member can click the notification to open the corresponding labeling instance and respond immediately.

6. **Update Read Status:** Marking a notification as read will automatically update its status, helping the entire team track what’s been addressed.

7. **Keep Inbox Tidy:** Use the filtering options to sort, organize, and manage messages (by status, type, project, etc.).

## Benefits

* **Faster Resolution:** Speeds up decision-making by instantly alerting the right people for feedback or validation.
* **Seamless Integration:** Notification inboxes can link to Slack, ensuring communication flows across platforms teams already use.
* **Clear Accountability:** Red and blue dots visually track what needs attention and what’s been handled.
* **Boosts Productivity:** Prevents annotation delays, so the workflow continues smoothly without searching for or waiting on responses.

## Best Practices

* Tag only relevant team members to keep communication focused.
* Regularly check your notification bar for updates—respond promptly to keep projects moving.
* Use inbox filters to locate unresolved issues or specific categories of queries quickly.
* Integrate with Slack if your team relies on external messaging for broader visibility.


# Polygon Eraser
Source: https://docs.labellerr.com/features/polygon-eraser

Master Labellerr's Polygon Eraser and CLIP Mode for effortless image annotation refinement, selective erasing, and precise boundary adjustments in complex scenarios.

## Introduction

Labellerr’s latest features—**Polygon Eraser** and **CLIP Mode**—make tackling complex image annotation challenges effortless. When used alongside tools like SAM (Segment Anything Model), these features enable users to refine, adjust, and perfect masks in fewer steps, ensuring both accuracy and flexibility in their labeling workflow.

## What is Polygon Eraser?

The **Polygon Eraser** lets users selectively erase parts of an existing annotation polygon. It is designed to:

* Remove mislabeled or unwanted regions from a polygon mask with precision.
* Instantly correct labeling mistakes or refine the shape of the annotation, especially in crowded or overlapping scenarios.

### How to Use Polygon Eraser

1. **Select the Polygon:** Click on the annotated object you wish to modify.
2. **Activate Polygon Eraser:** Enable the Polygon Eraser tool from the annotation panel.
3. **Erase the Area:** Sketch over the area you want to remove from the annotation. This region will be instantly removed from the label.
4. **Refine Borders:** Drag polygon keypoints to further adjust and perfect the shape as needed for accuracy.

## What is CLIP Mode?

**CLIP Mode** streamlines the process of re-annotating complex regions and aligning borders between objects. It is ideal when:

* Multiple objects overlap or share complex boundaries.
* You want to quickly reassign regions from one label to another without laborious manual work.

### How to Use CLIP Mode

1. **Select the Object:** Choose the object you wish to adjust.
2. **Activate CLIP Mode:** Toggle the CLIP Mode switch in the annotation panel.
3. **Sketch the Desired Area:** Draw the region that should now belong to the selected object. The tool automatically creates a void in the adjacent annotation and reassigns the selected area.
4. **Delete with Polygon Eraser:** You can even delete parts of the annotation created by Polygon Eraser if needed, for even more flexibility.

## Example Workflow

1. **Annotate with SAM:** Annotate multiple objects (e.g., a person and the ocean).
2. **Spot a Problem Area:** Notice parts of the scene mislabeled (e.g., ocean incorrectly labeled as the person).
3. **Erase & Refine:** Use Polygon Eraser to remove the region from the incorrect object.
4. **Reassign with CLIP Mode:** Select the correct object, activate CLIP Mode, and sketch the region to add it to the correct label. The boundary between the objects is instantly resolved to avoid overlap or confusion.
5. **Adjust Keypoints:** If needed, fine-tune the polygons for pixel-perfect segmentation.

## Benefits

* **Speeds Up Work:** Reduces multi-step corrections to just a few clicks.
* **Improves Accuracy:** Ensures each labeled region belongs to the correct object with no overlap or ambiguity.
* **Highly Flexible:** Suits complicated scenes and integrates perfectly with semi-automated methods like SAM.
* **Non-destructive:** Erased parts and CLIP corrections can be further adjusted, preserving editing flexibility.

## Best Practices

* Use Polygon Eraser to clean up annotated areas before reassigning regions with CLIP Mode.
* Rely on keypoint adjustments for perfecting boundaries after using the eraser or CLIP.
* Review the final label assignments, especially when multiple objects are close together.

Polygon Eraser and CLIP Mode together make Labellerr’s platform one of the most versatile and efficient tools for image annotation, handling both routine and highly intricate labeling tasks with ease.


# Body Pose Keypoint Tracking
Source: https://docs.labellerr.com/features/pose-keypoint-tracking

Learn how Labellerr's Body Pose Keypoint Tracking supports up to 33 points to create detailed skeletal annotations for full-body pose estimation.

<iframe title="Body Pose Keypoint Tracking" />

# Body Pose Keypoint Tracking

Human pose estimation is a fundamental building block for modern computer vision systems. Labellerr introduces **Body Pose Keypoint Tracking** with support for up to **33 body keypoints**, helping teams create richer skeletal annotations for full-body understanding tasks.

This enables more structured human pose labeling and better representation of body movement, alignment, posture, and positional relationships.

***

## Key Features

* **33-Point Pose Annotation:** Maps all critical body joints, including shoulders, elbows, wrists, hips, knees, ankles, and facial landmarks (eyes, nose, ears).
* **Connected Skeleton Structure:** Visualizes spatial and anatomical relationships directly on the labeling canvas.
* **Pose Presets:** Quickly start labeling with pre-configured skeletal structures tailored for pose estimation workflows.
* **Enhanced Precision:** Designed to handle complex human body movements, varied camera angles, and distance variations.

***

## Step-by-Step Guide: Using Body Pose Keypoint Tracking

### 1. Set Up the Pose Template

* Go to the **Label Configuration** settings of your project.
* Click **Add Object**, name the label (e.g., `person` or `pose`), and select **Keypoint** as the tool type.
* Choose the **Body Pose Preset (33 Points)** to instantly load the standardized skeleton layout.
* Click **Save** to confirm.

### 2. Placing the Pose Skeleton

* Select the `pose` label from the annotation sidebar.
* Click on the person in the image/frame to overlay the skeleton.
* Drag and place individual keypoint nodes (such as the elbows, knees, or shoulders) onto their corresponding anatomical landmarks.

### 3. Verification & Fine-Tuning

* Toggle connecting lines to verify that limbs and joints are connected correctly.
* Use **Attribute Filtering** to isolate and audit pose annotations across large datasets, ensuring metadata consistency.

***

## Use Cases

* **Pose Estimation Training:** Building datasets to train deep learning models on human joint detection.
* **Fitness & Movement Analysis:** Analyzing body alignment, squats, or yoga poses in fitness coaching apps.
* **Sports Performance Tracking:** Tracking athlete movements, posture, and techniques for analytics.
* **Safety Monitoring:** Detecting falls or unsafe postures in industrial and healthcare environments.
* **Human Behavior Analysis:** Enhancing security and retail analytics through posture and movement interpretation.


# Quality Metrics
Source: https://docs.labellerr.com/features/quality-metrics

Monitor and improve annotation team performance with Labellerr’s Quality Metrics Dashboard, offering insights into productivity, review accuracy, and client rejections.

Labellerr’s **Quality Metrics Dashboard** is a dedicated feature for monitoring and improving the performance of annotation teams. It equips managers, reviewers, and clients with detailed, actionable insights into annotator and reviewer productivity, review accuracy, and quality control in the data labeling process. The dashboard also makes it easy to **track client rejections** and identify areas for improvement—ensuring higher data quality and operational efficiency.

## Accessing the Quality Metrics Dashboard

<iframe title="Track Annotation Quality with Ease! ✅ Introducing Labellerr’s Quality Metrics Dashboard" />

* Open any recent project in Labellerr.
* Navigate to the **Quality Metrics** option from the project interface.
* Set your desired date range to filter results for a relevant time period.

## Dashboard Sections and Key Features

The dashboard consists of **three main tabs**:

### 1. Annotator Tab

Monitors the individual performance of each annotator:

* **User Name & Email:** Identify who performed the annotation.
* **Total Files Annotated:** The number of files each annotator worked on during the selected period.
* **Accepted Files:** Count of files accepted by reviewers with no changes needed.
* **Reviewer Rejections:** Files rejected by reviewers due to quality issues.
* **Client Rejections:** Files rejected by clients even after review.
* **Files Skipped:** How many files were skipped by the annotator.
* **Acceptance Rate:** Percentage of files accepted out of total annotated—a direct measure of accuracy and reliability.

### 2. Reviewer Tab

Tracks the performance of each reviewer:

* **Reviewer Name & Email:** Who reviewed the files.
* **Total Files Reviewed:** Volume of work checked within the time range.
* **Accepted During Review:** Number of files accepted as is.
* **Marked as Rejected:** Files that the reviewer flagged for changes.
* **Client Rejections:** After the reviewer acceptance, files that clients still rejected.
* **Files Skipped:** Count of files skipped or not reviewed.
* **Review Accuracy:** Calculated based on reviews ultimately accepted by the client, helping identify consistency and stringency in reviews.

### 3. Client Rejected Tab

Provides detailed insights into files rejected by clients:

* **Unique File ID:** Traceability to the particular file rejected.
* **Annotator Name:** Who originally annotated the file.
* **Reviewer Name:** Who performed the review.
* **Rejection Reason/Feedback:** Client’s exact reason for rejection (if provided), helping teams learn and adjust.
* **Rejection Date:** When the rejection occurred for record-keeping and trend analysis.

## Additional Features

* **CSV Download:** Export all metrics as a CSV for external analysis or reporting.
* **Date Range Selection:** Custom time frames for granular performance tracking.
* **Full Traceability:** Every status (from annotation to review to client acceptance/rejection) is traceable by user and file.

## Benefits

* **Spot Performance Trends:** Quickly identify top performers and those needing support.
* **Enhance Quality Control:** Pinpoint where errors occur—during annotation, review, or client acceptance.
* **Data-Driven Management:** Use concrete metrics for team improvement, feedback, and project reporting.
* **Audit-Ready:** Maintain an auditable record of all actions and decisions.

## Best Practices

* Regularly review the dashboard to catch issues early.
* Use client feedback to retrain annotators and reviewers.
* Export and share CSVs for collaborative analysis and quality meetings.


# Quick Edit while Reviewing
Source: https://docs.labellerr.com/features/quick-edit-while-reviewing

Learn how Labellerr's View Mode supports direct editing and annotation, allowing reviewers to make instant corrections without leaving the review interface.

<iframe title="Edit Files in View Mode" />

# Quick Edit while Reviewing (Edit Files in View Mode)

In large-scale data annotation pipelines, quality assurance (QA) and review cycles are critical for model accuracy. However, switching back and forth between the review interface and the labeling screen to fix minor errors creates significant workflow friction.

To solve this, Labellerr supports **direct editing and annotation within View Mode**. Reviewers and admins can make instant corrections, modify existing boundaries, or add missing annotations directly from the review interface.

This reduces interruptions during QA, streamlines the correction loop, and speeds up overall dataset refinement.

***

## Key Benefits

* **Faster Annotation Corrections:** Modify labels, adjust bounding boxes, or refine polygons instantly as you spot errors.
* **Reduced Workflow Switching:** No need to bounce between separate labeling and QA screens.
* **Improved Reviewer Productivity:** Allows reviewers to maintain focus and execute corrections in one place.
* **Better Collaboration:** Minimizes back-and-forth loops between annotation teams and QA managers by enabling direct overrides.

***

## Step-by-Step Guide: Editing Files in View Mode

### 1. Enter View Mode

* Navigate to your project dashboard and open the **Files** section.
* Select a file to view its annotations, or open the file directly in the **Review** / **Client Review** interface.

### 2. Click the Edit Button

* To edit files while in view mode, you must click the **Edit** button present in the view mode interface. This activates the annotation tools (such as bounding boxes, polygons, or keypoints).
* Select the appropriate tool or existing annotation that needs adjustment.

### 3. Make Direct Corrections

* **Modify Existing Annotations:** Click on an existing bounding box, polygon, or keypoint skeleton to reposition, resize, or edit it.
* **Draw New Annotations:** Select a label from your configured list and draw new bounding boxes or polygons directly onto the canvas.
* **Update Attributes:** Edit annotation-level attributes (e.g., class labels, visibility tags) directly in the attributes panel.

### 4. Save and Update

* Once corrections are made, save your changes. The updated annotations are applied immediately, ensuring the dataset reflects the correct status.


# SAM 2 Object Tracking
Source: https://docs.labellerr.com/features/sam-2-object-tracking

Learn how Labellerr's Segment Anything Model 2 (SAM 2) enables 10x faster video object tracking for annotating moving objects across frames with minimal manual effort.

<iframe title="Speed Up AI Training with SAM 2 for Quick Video Annotation | Sports, Robotics & Security" />

# Labellerr: Segment Anything Model 2 (SAM 2) Video Object Tracking Documentation

## Introduction

Labellerr's SAM 2 enables **10x faster video object tracking** compared to manual annotation, making it ideal for annotating moving objects—such as players and balls in sports videos—across frames with minimal effort. This AI-powered tool streamlines the process, saving significant time and ensuring high-accuracy results in sports analytics, robotics, retail, and agriculture.

## Key Features

* **AI-driven, frame-by-frame object tracking**
* Compatible with multiple label types (player, ball, etc.)
* Combines manual annotation, point prompts, and automated tracking
* Efficiently handles occlusions and out-of-frame moments

## Step-by-Step Guide: Using SAM 2 for Video Object Tracking

### 1. Preparing the Video and Labels

* **Upload your video** to the Labellerr platform.
* Play the video briefly to familiarize yourself with its content.
* **Create labels** for each object you want to track (e.g., `player`, `ball`).

### 2. Annotating Key Frames with SAM 2

#### a. Select Object and Annotation Tool

* Select the relevant label (e.g., `ball`).
* Click the **Magic Brush** and choose **Segment Anything Model 2 (SAM 2)** from the dropdown menu.

#### b. Add Point Prompts

* Click the *interact* icon to begin.
* Place point prompts on the object to help the model segment it accurately.
* Confirm the segmentation by clicking the tick icon.

#### c. Track Object Across Video

* Right-click on the object and select **SAM 2 Tracking**.
* SAM 2 automatically tracks and segments the object across the entire video timeline.
* **Repeat for additional objects** (e.g., select `player` and follow the same steps).

### 3. Reviewing and Adjusting Tracks

#### a. Timeline Visualization

* Tracked objects appear on a colored timeline.
* Colored dots indicate **present**, **absent**, or **segmentation error**.
* Gaps in the timeline indicate occlusion or the object moving out of frame.

#### b. Handling Occlusions & Errors

* If SAM 2 misses a frame:
  * Right-click and select **Mark Out of View** (if object is absent).
  * Right-click and select **Mark in View** (if object is present).

#### c. Seamless Results

* Play the labeled video to preview accurate object tracking across all frames.

### 4. Customizing Annotations (Optional)

* Use **bounding boxes** for simple shapes (e.g., players).
* Use **polygons** for small or irregular objects (e.g., balls).
* Add **attributes** (e.g., player activity, jersey color) and **video-wide classifications** for detailed datasets.

### 5. Firing Multiple Annotation Jobs

Labellerr supports running **multiple annotation jobs simultaneously**, speeding up large-scale video annotation.

#### How It Works

1. Upload your videos and create object labels.
2. Select objects to annotate.
3. Click the **SAM 2 button** in the object header.
4. Choose the object for this job.
5. Click **Run** to automatically track and segment the object across all frames.

<iframe title="SAM 2 Multi-Object Tracking Demo" />

### 6. Running SAM 2 on a Single Timeline

You can track multiple objects continuously in a single workflow.

#### How It Works

* Upload your video and create labels for all objects.
* Select each object to include in the timeline job.
* Right-click on the timeline, choose **SAM 2 Tracking**, and select **Run SAM 2**.
* Monitor progress in the **Timeline** section, where colored dots indicate object presence, absence, or segmentation errors.

***

## Benefits

* **Dramatically faster:** Reduces hours of manual tracking to just a few clicks.
* **High accuracy:** AI leverages previous frame information to minimize drift and errors.
* **Flexible:** Suitable for any moving object in videos—sports, robotics, animals, retail, etc.
* **Easy error correction:** Quick manual fixes via right-click if predictions are off.


# SAM 3 Multi-Instance Auto-Labeling
Source: https://docs.labellerr.com/features/sam-3-multi-instance-auto-labeling

Learn how Labellerr's SAM 3 Multi-Instance Auto-Labeling allows you to label all similar objects in an image with a single visual prompt to speed up annotation workflows.

<iframe title="SAM3 Integration - Label Similar Objects" />

## Visual Prompt based Multi-Labeling

<iframe title="Visual Prompt based Multi-Labeling" />

## Text Prompt based Multi-Labeling

<iframe title="Text Prompt based Multi-Labeling" />

Labeling multiple instances of the same object class in a single image (e.g., vehicles in a parking lot, players on a field, or products on a shelf) can be extremely repetitive and time-consuming.

With **SAM 3 Multi-Instance Auto-Labeling** (powered by Meta AI's Segment Anything Model 3), Labellerr allows you to label all similar objects in an image using just a **single visual prompt**. SAM 3 intelligently identifies and labels all matching instances across the entire image canvas, dramatically reducing manual effort and accelerating your annotation pipeline.

***

## Key Features

* **Single-Prompt Auto-Labeling:** Draw a single bounding box or polygon outline, and the system automatically segment-labels all other similar objects in the image.
* **Advanced Segmentation Power:** Powered by SAM 3's high-precision, zero-shot segmentation capabilities.
* **Consistency:** Maintains uniform labeling standards and boundary shapes across all detected object instances.
* **Multi-Instance Speedup:** Annotate dozens or hundreds of similar objects in seconds rather than hours.

***

## Step-by-Step Guide: Using SAM 3 Multi-Instance Auto-Labeling

### 1. Initialize the Prompt

* Open your image annotation project and choose the appropriate target label.
* Draw a bounding box or polygon (using SAM) annotation on your object to serve as the visual prompt.

### 2. Activate Similar Object Detection

* Select the created annotation on the canvas.
* Press **I** on your keyboard to trigger SAM 3 auto-annotation.
* The model will process the visual signature and automatically annotate all similar objects across the image.

### 3. Review and Save

* Inspect the generated annotations.
* Manually refine any boundaries if necessary, and click save to apply the updates.

***

## Future Roadmap

* **Negative & Incremental Prompting:** Add support to exclude specific false-positives or add refined suggestions to improve detection accuracy.
* **Granular Controls:** Introduce individual accept/reject controls for each detected instance (e.g., "accept all", "reject all").
* **Latency Optimization:** Reduce inference and processing times for faster annotation cycles.
* **Video Support:** Extend similar object tracking to video sequences for automated frame-by-frame propagation.


# Segment Anything (SAM)
Source: https://docs.labellerr.com/features/segment-anything

Discover how Labellerr integrates Meta AI's Segment Anything Model (SAM) to enable fast and accurate object segmentation with a single click, enhancing your annotation pipeline.

**A new AI model from Meta AI that can "cut out" any object, in any image, with a single click.**

SAM is a promptable segmentation system with zero-shot generalization to unfamiliar objects and images, without the need for additional training.

We have used the capability of **SAM** to build a more accurate and fast annotation pipeline. This feature **enables a user to draw segmentation around an object via only a single click on that object.**

<Note>
  Before going forward, please ensure that you are familiar with the Annotation Projects, Datasets and Annotation Pipelines at Labellerr. If not please visit the below links :-

  1. [How to create a datasets at workspace level?](/tutorials/datasets)
  2. [How to create a new project](/getting-started/create-project)?
  3. [Start Labelling](/actions/start-labelling)
</Note>

First we need to create a polygon type annotation question with the name of object that we want to auto-segment. Select that polygon object. An auto segment icon in the icons list above the file will appear. Click on the auto segment icon , Select ‘**Interact**’.

<Frame>
  <img alt="Auto Segment Icon" />
</Frame>

Click on the required object to auto label in the image. Wait for a few seconds, the object will be segmented.

<Frame>
  <img alt="Segmented Object" />
</Frame>

Check the video tutorial to implement this feature.

<iframe title="YouTube video player" />

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Smart File Filtering
Source: https://docs.labellerr.com/features/smart-file-filtering

Revolutionize how you manage and navigate image datasets with Labellerr’s Smart File Filtering, allowing you to find exactly what you need in seconds using multiple advanced filters.

Labellerr's new **Smart File Filtering** feature revolutionizes how you manage and navigate your image datasets. It lets you find exactly what you need **in seconds**, saving hours spent manually searching for images. This powerful tool allows users to apply **multiple advanced filters simultaneously** across their dataset, providing laser-precise results with just a few clicks.

## What Can You Filter By?

* **Last Updated User:** Find files updated by specific users to track contributions or assignments.
* **Objects Present in Images:** Filter images containing specific objects such as cars, bikes, people, etc.
* **Classifications:** Narrow results using classification labels like weather conditions, traffic density, etc.
* **Custom Attributes:** Use your project-specific attributes for further granularity (e.g., number of cars in an image).
* **Combination Filters:** Apply multiple filter conditions simultaneously for incredibly precise search.

## Real-Life Example: Filtering Traffic Images

Imagine you want to find images meeting these conditions:

* Sunny weather
* Less than 10 cars
* Presence of bikes
* More than or equal to 2 large vehicles
* High traffic condition

### How to Apply Filters Step-by-Step

#### Filter by Object:

Select images containing *bikes* and *large vehicles* (≥ 2).

#### Filter by Classification:

Choose *high traffic* and *sunny weather* classifications.

#### Filter by Attribute:

Add an attribute filter to exclude images with exactly 10 cars (e.g., "cars \< 10").

#### Result:

The system instantly returns seven images matching all these combined filters.

## Key Benefits

* ⚡ **Dramatically Faster Search:** Find specific images in seconds, not hours.
* 🎯 **Highly Precise Filtering:** Combine multiple filters on objects, classifications, and attributes to get exactly what you need.
* 📊 **Instant Review & Actions:** Review filtered images quickly, assign tasks, or prepare exports without leaving the filter interface.
* 🚀 **Boost Workflow Efficiency:** Speeds up the entire annotation process by streamlining data organization and retrieval.

## How to Use Smart File Filtering

<iframe title="Stop Wasting Hours Searching Images - This Filter Feature Does It in Seconds!" />

1. Open the **File Section** in your Labellerr project.
2. Choose the **filter icon** to open filter options.
3. Select filters based on:
   * **User:** Filter files by the last person who updated them.
   * **Objects:** Check the boxes next to objects that should be present.
   * **Classifications:** Pick classification labels relevant to your search.
   * **Attributes:** Set attribute conditions like numeric values or categorical options.
4. Combine multiple filter types as needed for a refined search.
5. View your filtered results instantly.
6. Use the options to:
   * **Review images.**
   * **Assign files** to team members or yourself.
   * **Export filtered datasets** for use in training or analysis.

## Best Practices

* **Use Combination Filters for Complex Queries:** Filter by objects, classifications, and attributes together to narrow your dataset effectively.
* **Validate Filter Results:** Confirm that the filtered files meet the criteria by spot-checking a few samples.
* **Assign Tasks Efficiently:** Use the filtering results to assign relevant files to proper team members based on content type or annotation progress.
* **Export Relevant Data:** Prepare datasets tailored to project needs by exporting the filtered subset directly from the tool.


# Text Captioning Using Generative AI
Source: https://docs.labellerr.com/features/text-captioning

Learn how to use generative AI in Labellerr for text captioning, enabling you to generate detailed descriptions and keywords for your text annotation projects.

Start by creating a project following the steps outlined in the link provided below.

[How to Create a Text Project?](/getting-started/create-text-project)

### Setting Up Object/Classification template:

<Info>
  You can refer to the link mentioned above for guidance on how to create a template for objects/questions within a project.
</Info>

Select a classification question and specify its type as '**captioning**' from the dropdown menu. Here, I've created a project and labeled a classification question as 'caption' with the question type set to 'captioning'.

<Frame>
  <img alt="Text Captioning Classification Setup" />
</Frame>

<Note>
  You have the option to create a new project or modify an existing project template according to your needs. Additionally, multiple questions can be set up to gather various types of details. You can choose to obtain all details at once or gather them one by one by providing different prompts.
</Note>

After setting the template, Go to Dashboard. Click on "**Start Labelling**" button on the dashboard. This will redirect you to the annotation canvas.

<Frame>
  <img alt="Start Labelling Button" />
</Frame>

### Predict Button:

Below the displayed image, you will see the "**Predict**" button. Click on the "**Predict**" button to open a prompt box where you can input a prompt for the generative AI.

**Example prompt**: "Write a detailed description about this image".

<Frame>
  <img alt="Predict Button and Prompt Box" />
</Frame>

### Generating Descriptions:

Click "**Proceed**" after entering your prompt. The generative AI will then provide a description based on your input.

<Frame>
  <img alt="Generative AI Description Output" />
</Frame>

You can review and edit this output as needed.

<Tip>
  **Further Prompts:** You can give additional prompts to get more details about the image, such as relevant keywords or a brief description.

  If the API is available, the **meta description** can be displayed in the info icon. Click on the info icon to view the meta description, which includes keywords and descriptions related to the image provided by the API.
</Tip>

Once satisfied with the description, click the "**Submit**" button to submit the file.

The file will be sent to a reviewer, who can also view the image and edit the output if necessary.

Reviewers can access files for review by navigating to the "Review" page from the dashboard.


# User Settings Guide
Source: https://docs.labellerr.com/features/user-settings

Learn how to manage users in Labellerr, including adding, deleting, editing credentials, and assigning roles and projects to annotators.

### Managing Users

<Info>
  User settings allows you to add or delete new users and assign new roles and projects to existing annotator
</Info>

<Steps>
  <Step title="Access User Settings">
    To access the user settings, click on the user icon from the settings list on the left.

    <Frame>
      <img alt="User Icon in Settings" />
    </Frame>
  </Step>

  <Step title="Click on Users Option">
    Click on Users Option.

    <Frame>
      <img alt="Users Option" />
    </Frame>
  </Step>

  <Step title="User Settings Screen">
    The User settings screen should appear which lets you manage users. The following screen shows the list of all users working on a domain. Display on-screen also shows the role and the last date of work for each user. Multiple actions can be taken henceforth.

    <Frame>
      <img alt="User Settings Screen" />
    </Frame>
  </Step>

  <Step title="Search and Edit Users">
    The **search option** allows you to search for a user by name. The **Edit option** lets you edit user credentials, profile and assign or delete roles.

    <Frame>
      <img alt="Search and Edit Options" />
    </Frame>
  </Step>

  <Step title="Add a New User">
    To add a new user, simply click on the create user option located on the top right corner.

    <Frame>
      <img alt="Create User Option" />
    </Frame>

    The following create user screen would appear.

    <Frame>
      <img alt="Create User Screen" />
    </Frame>

    <ol>
      <li>On the left, basic user credentials are to be added. Email, First Name and Last name are mandatory fields.</li>
      <li>On the right, click on ‘+’ icon and then projects and roles can be assigned.</li>
    </ol>
  </Step>
</Steps>

Once the input has been made, the new user profile would be made by clicking on save at the bottom right.


# AWS S3 Data Flow Architecture
Source: https://docs.labellerr.com/few-additional-features/few-additional-features-1/aws-s3-data-flow

Detailed architecture and security reference diagram illustrating data flow between AWS S3 and Labellerr.

## Data Flow Diagram: AWS S3 to Annotator

Detailed architecture and security reference diagram illustrating how data travels from your Amazon S3 bucket, through the Labellerr annotation platform, to an annotator's browser — and back on export.

<Card title="Download / View Architecture PDF" icon="file-pdf" href="https://storage.googleapis.com/labellerr-cdn/%20%201%20EMMA/Labellerr-DataFlow-S3-to-Annotator.pdf">
  Click to open or download the complete AWS S3 to Labellerr Data Flow Reference PDF.
</Card>

<iframe />

<Note>
  For further assistance contact <a href="mailto:support@tensormatics.com">[support@tensormatics.com](mailto:support@tensormatics.com)</a>
</Note>


# Labellerr Workflow Diagram
Source: https://docs.labellerr.com/few-additional-features/few-additional-features-1/labellerr-workflow-diagram

Understand the complete annotation workflow from labeling to approval with our comprehensive diagram.

## Labellerr Workflow Diagram

We've designed a structured, multi-stage workflow that helps your team label, review, and approve data to guarantee accuracy before exporting.

<Frame>
  <img alt="Labellerr Workflow Diagram" />
</Frame>

***

## Workflow Breakdown

The Labellerr lifecycle consists of three structured review phases leading to export readiness:

### 1. Annotation Phase

The primary stage where raw data is labeled by assigned annotators.

* **Unlabeled Files**: Freshly ingested files enter the pipeline ready for annotation.
* **User Visits Label Section**: Annotators access their assigned tasks in the **Label** tab.
* **Annotator Assigned Files**: Files are allocated to annotators based on project assignments or batch distribution.
* **Annotator Actions**:
  * **Submit File**: Annotations are completed and submitted, moving the file forward into the **Review Phase**.
  * **Skip File**: If an asset is corrupted, unclear, or out-of-scope, annotators can skip it, moving it to **Skipped by Annotator Files**.

***

### 2. Review Phase

Internal quality assurance where designated reviewers validate and audit annotator submissions.

* **Review Files Queue**: Holds all submitted files awaiting inspection.
* **Reviewer Visits Review Section**: Reviewers navigate to the **Review** tab to inspect completed annotations.
* **Review Assigned Files**: Reviewers evaluate labels against annotation guidelines.
* **Reviewer Actions**:
  * **Accept File**:
    * If **Client Review is NOT enabled**, the file transitions directly to **Ready for Export**.
    * If **Client Review IS enabled**, the file advances to the **Client Review Phase**.
  * **Reject File**: File is rejected and sent back to **Unlabeled Files** (or re-assigned to annotators) with remarks for correction.
  * **Skip File**: File is set aside in **Skipped by Reviewer Files** and can be re-queued into **Review Files** if needed.

***

### 3. Client Review Phase (CR)

An optional external or client-level audit layer for final customer sign-off.

* **Client Review Files**: Files approved by internal reviewers enter this queue.
* **User Visits CR Section**: External reviewers or client managers access the **Client Review** section.
* **Client Review Assigned Files**: Client auditors evaluate annotations against enterprise quality standards.
* **Client Reviewer Actions**:
  * **Accept File**: File is fully approved and marked as **Ready for Export**.
  * **Reject File**: Sent back with file-level feedback to internal **Review Files** for rework.
  * **Skip File**: Placed into **Skipped by CR** and can return to the client review queue.

***

### 4. Ready for Export

Once files pass all active review gates (internal review and optional client review), they are placed into the **Ready for Export** state. These finalized datasets can then be exported in formats such as JSON, COCO JSON, CSV, or synced directly back to your cloud storage (e.g., AWS S3 / GCS).

<Note>
  For further assistance contact <a href="mailto:support@tensormatics.com">[support@tensormatics.com](mailto:support@tensormatics.com)</a>
</Note>


# File Remarks & Client Feedback
Source: https://docs.labellerr.com/few-additional-features/few-additional-features-1/reviewing-file-level-remarks-by-annotators-reviewers

Learn how annotators and reviewers can view and handle remarks from clients at the file level.

## File Remarks & Client Feedback

### How can the annotator review the remarks given by the client reviewer at file level?

After a file is rejected by the client, it will be reassigned to the reviewer. The reviewer can then view the remarks made during the rejection.

To check remarks from the client on a rejected file:

1. Navigate to the **Label** tab on the dashboard to view the file.

2. Click the timer icon on the right side of the screen to check the file's remarks and activity.

3. Details such as the email ID of the person who gave the remark, the label, the time of the remark, and the feedback will be displayed.

4. To view feedback from the client, look for the label **"rejected by client"**. For reviewer feedback, look for the label **"rejected by reviewer"**.

5. The client's feedback will appear next to the corresponding label.

### To check comments from the client when a file is rejected:

1. Click on the timer icon on the right side of the screen, which shows file activity.

2. This will display the label and the feedback provided.

3. Look for the label **"rejected by client"**.

4. The client's feedback will be shown on the right.

<Note>
  For further assistance contact <a href="mailto:support@tensormatics.com">[support@tensormatics.com](mailto:support@tensormatics.com)</a>
</Note>


# How to Connect AWS S3 with Labellerr
Source: https://docs.labellerr.com/getting-started/connect-aws-s3

Learn how to establish a secure connection between your Amazon S3 bucket and Labellerr using IAM User Access for data import and export.

Welcome to the User Guide for connecting an Amazon S3 bucket with LABELLERR, a powerful SaaS product for data annotation and labeling. In this guide, we will walk you through the process of establishing a connection between your S3 bucket and Labellerr, leveraging IAM User Access within the same AWS account.

To establish the connection between your S3 bucket and Labellerr, we will utilize IAM User Access. IAM (Identity and Access Management) is an AWS service that enables you to manage access to your AWS resources securely. By creating an IAM user with appropriate permissions, you can grant Labellerr the necessary access to your S3 bucket while ensuring the security of your data.

Throughout this guide, we will provide step-by-step instructions, along with detailed explanations, to help you successfully configure the connection. It is assumed that you have a basic understanding of AWS services, including S3 and IAM. If you are new to AWS or require additional information on these services, we recommend referring to the AWS documentation for a more comprehensive understanding.

<Note>
  Please note that the procedures outlined in this guide pertain to connecting an S3 bucket and LABELLERR within the same AWS account.
</Note>

## Prerequisites

* **AWS Account:** You must have an active AWS account to access and utilize the IAM service. If you don't have an account, you can sign up for one at the AWS website.

* **IAM Permissions:** Ensure that you have the necessary permissions to create IAM users and policies. You need to have IAM administrative access or consult with your AWS account administrator to grant you the required permissions.

* **IAM User Creation:** Decide on the user(s) you want to create in IAM. Consider the appropriate naming conventions and the level of access each user should have. Determine the number of users you need to create and the specific roles and permissions they require.

* **User Credentials:** Plan how you will manage the user credentials. Determine whether you will generate initial passwords for the users or require them to set their own passwords upon first login. Alternatively, you can leverage AWS Single Sign-On or other authentication mechanisms.

* **IAM Policies:** Identify the specific permissions and access levels required for each user. You can create custom policies to grant fine-grained permissions or leverage existing AWS managed policies. Define the policies that align with your security and access control requirements.

* **IAM Best Practices:** Familiarize yourself with IAM best practices, such as implementing the principle of least privilege, regularly reviewing and rotating credentials, and enabling multi-factor authentication (MFA) for added security.

Please follow the reference link for more information

## Quick Reference

### S3 URI Format

<Card title="S3 Path Format" icon="link">
  ```
  Format: s3://bucket-name/path/to/folder/
  Example: s3://my-annotation-bucket/images/batch-001/
  ```

  <Warning>
    When entering the path in Labellerr UI, **remove the `s3://` prefix**. Enter only: `bucket-name/path/to/folder/`
  </Warning>
</Card>

### Required Permissions Summary

<Tabs>
  <Tab title="Import (Read)">
    | Permission | Purpose |
    | - | - |
    | `s3:GetObject` | Read files from bucket |
    | `s3:ListBucket` | List bucket contents |
    | `s3:GetBucketCors` (Optional) | Get CORS configuration |
    | `s3:GetBucketLocation` | Get bucket region |
    | `s3:PutBucketCors` (Optional) | Set CORS policy (or configure manually) |
  </Tab>

  <Tab title="Export (Write)">
    | Permission | Purpose |
    | - | - |
    | `s3:PutObject` | Write/upload annotation files |
    | `s3:DeleteObject` | Delete files if needed |
    | `s3:ListBucket` | List bucket contents |

    <Note>Export permissions are required **in addition** to import permissions.</Note>
  </Tab>
</Tabs>

<Tip>
  **Using Google Cloud Storage instead?** See our [GCS Connection Guide](/getting-started/connect-gcs) for Google Cloud Storage setup instructions.
</Tip>

## CREATE IAM USER

<Steps>
  <Step title="Access IAM Users">
    Go to **IAM** ⇒ **Users** and click to **Add users** button

    <Frame>
      <img alt="IAM Users page" />
    </Frame>
  </Step>

  <Step title="Create User">
    Now write a **User name** and click to **Next** button

    <Frame>
      <img alt="Create user form" />
    </Frame>
  </Step>

  <Step title="Set Permissions">
    In the **Set Permissions** section you will see the **Permissions options.** Choose **Attach Policies Directly**

    <Frame>
      <img alt="Set permissions options" />
    </Frame>

    After choosing the above option you can see the list of existing policies

    <Frame>
      <img alt="Existing policies list" />
    </Frame>
  </Step>

  <Step title="Create Custom Policy">
    Create a new policy for the user to access the bucket. Now click on the **Create policy** button. After this you will be redirected to a window **IAM** ⇒ **Policies** ⇒ **Create Policy** as we can see following.

    <Frame>
      <img alt="Create policy page" />
    </Frame>

    Choose the **JSON** option from the **RIGHT-HAND-SIDE** of the window. After choosing the JSON option you will see the window as follow

    <Frame>
      <img alt="JSON policy editor" />
    </Frame>
  </Step>

  <Step title="Configure Policy Permissions">
    Update the JSON as follow and replace the **your-bucket-name** with **bucket-name**

    <Frame>
      <img alt="JSON policy configuration" />
    </Frame>

    <Warning>
      Ensure to include '*' at the end of Resource URL in case of S3:GetObject & S3:PutObject like 'arn:aws:s3:::bucket-name/*'. The '\*' ensures that the required permission is added to the sub-folders also
    </Warning>

    Now, update the JSON policy. We will create two permission sets: one for importing data from S3 and another for exporting data to S3.

    ## A. Policy for Importing Data

    To allow Labellerr to read data from your bucket, paste the following JSON code. Replace `your-bucket-name` with the actual name of your S3 bucket.

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "S3ObjectAccess",
          "Effect": "Allow",
          "Action": [
            "s3:GetObject"
          ],
          "Resource": "arn:aws:s3:::your-bucket-name/*"
        },
        {
          "Sid": "S3BucketReadAccess",
          "Effect": "Allow",
          "Action": [
            "s3:ListBucket",
            "s3:GetBucketCors",
            "s3:GetBucketLocation"
          ],
          "Resource": "arn:aws:s3:::your-bucket-name"
        },
        {
          "Sid": "S3PutCorsAccess",
          "Effect": "Allow",
          "Action": [
            "s3:PutBucketCors"
          ],
          "Resource": "arn:aws:s3:::your-bucket-name"
        }
      ]
    }
    ```

    <Info>
      **Note:** If you prefer not to grant `s3:PutBucketCors` permission, you can set the CORS policy on your S3 bucket manually with the following configuration. For more details, refer to the official AWS documentation on CORS.

      ```json theme={"dark"}
      [
        {
            "AllowedHeaders": ["*.labellerr.com"],
            "AllowedMethods": ["GET", "HEAD"],
            "AllowedOrigins": ["*.labellerr.com"],
            "ExposeHeaders": [],
            "MaxAgeSeconds": 3600
         }
      ]
      ```
    </Info>

    ## B. Policy for Exporting Data

    To allow Labellerr to write (export) annotations back to your S3 bucket, add the following permissions to your policy. These are required **in addition** to the import permissions above.

    ```json theme={"dark"}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "S3ObjectWriteDeleteAccess",
          "Effect": "Allow",
          "Action": [
            "s3:PutObject",
            "s3:DeleteObject"
          ],
          "Resource": "arn:aws:s3:::your-bucket-name/*"
        },
        {
          "Sid": "S3BucketListAccess",
          "Effect": "Allow",
          "Action": [
            "s3:ListBucket"
          ],
          "Resource": "arn:aws:s3:::your-bucket-name"
        }
      ]
    }
    ```
  </Step>

  <Step title="Finalize Policy">
    Click on **Next** button

    <Frame>
      <img alt="Policy review page" />
    </Frame>

    Fill the **Policy name** & **Policy Description** and click on **Create policy** button

    <Frame>
      <img alt="Policy details form" />
    </Frame>

    <Frame>
      <img alt="Create policy button" />
    </Frame>

    After this the policy will be created and listed

    <Frame>
      <img alt="Policy created successfully" />
    </Frame>
  </Step>

  <Step title="Attach Policy to User">
    Now go to the previous **user-creation** window and after reloading and entering the **User Name** and selecting the option **Attach policies directly** we can see the policy that we created. Choose the same policy and click on **Next** button

    <Frame>
      <img alt="Select policy for user" />
    </Frame>

    <Frame>
      <img alt="Policy attached to user" />
    </Frame>

    Now click on Create user button and user will be created

    <Frame>
      <img alt="Create user final step" />
    </Frame>

    <Frame>
      <img alt="User created successfully" />
    </Frame>
  </Step>
</Steps>

## Generate Access Key

<Steps>
  <Step title="Create Access Key">
    Now go to **IAM ⇒ user ⇒ user\_name** and click on **Create access** key button.

    <Frame>
      <img alt="User details page" />
    </Frame>

    <Frame>
      <img alt="Create access key button" />
    </Frame>
  </Step>

  <Step title="Configure Access Key">
    Choose the option **Application running outside AWS** & click on **Next .** Enter a description and click on the **Create access key** button. Now you can copy the **Access keys** & **Secret access key** or download a **CSV** file for the same for future use while connecting with Labellerr

    <Frame>
      <img alt="Access key use case" />
    </Frame>

    <Frame>
      <img alt="Access key description" />
    </Frame>

    <Frame>
      <img alt="Access key generated" />
    </Frame>
  </Step>
</Steps>

## Creating Dataset & Annotation Project at LABELLERR

<Steps>
  <Step title="Select Amazon S3">
    While creating a project dataset **choose Amazon S3** to connect data-source and click on Create new connection button.

    <Frame>
      <img alt="Select Amazon S3 connector" />
    </Frame>
  </Step>

  <Step title="Configure Connection">
    Fill in the details. Fill the **Access key** & **Secret Access Key** generated in previous steps along with **s3 URI.** To find the **s3 URI** go to your bucket and copy the path of the images **folder.** Also remove the **s3:// prefix** from the URL. Now click on **connect** button

    <Frame>
      <img alt="S3 connection configuration" />
    </Frame>

    If you fill in the details correctly you will receive this message.

    <Frame>
      <img alt="Connection successful" />
    </Frame>

    If you messed up somewhere you will get an error.

    <Frame>
      <img alt="Connection error" />
    </Frame>

    After successfully testing the connection you will be required to fill the **Connection Name** and **Connection Description(Optional).**

    <Frame>
      <img alt="Connection name and description" />
    </Frame>
  </Step>
</Steps>

That's it, this is how you can connect AWS S3 with our Labellerr Data Connector. Now you can successfully, Create a Project.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Dataset creation shows status 500 or 'Failed'">
    **Symptom:** Dataset appears to create successfully but then shows "Failed" status or status code 500.

    **Cause:** The IAM user/connection does not have the required permissions to access the S3 bucket.

    **Solution:**

    1. Verify the IAM policy is correctly attached to your user
    2. Ensure the bucket name in the policy matches your actual bucket
    3. Check that the `/*` wildcard is included for object-level permissions
    4. Test the connection before creating datasets:

    ```python theme={"dark"}
    from labellerr.core.connectors import LabellerrConnection
    from labellerr.core.schemas import ConnectionType, DatasetDataType

    connection = LabellerrConnection(client=client, connection_id="your_connection_id")
    test_result = connection.test(
        path="s3://your-bucket/path/to/data/",
        connection_type=ConnectionType._IMPORT,
        data_type=DatasetDataType.image
    )
    ```
  </Accordion>

  <Accordion title="'Dataset has no files' error">
    **Symptom:** Files exist in S3 bucket but dataset shows 0 files.

    **Cause:** The connection lacks read permissions (`s3:GetObject`, `s3:ListBucket`) on the bucket.

    **Solution:**

    1. Verify `s3:GetObject` permission is set on the bucket objects (`arn:aws:s3:::bucket-name/*`)
    2. Verify `s3:ListBucket` permission is set on the bucket (`arn:aws:s3:::bucket-name`)
    3. Check that the path format is correct: `s3://bucket-name/folder/`
  </Accordion>

  <Accordion title="Connection test fails">
    **Symptom:** Connection test returns an error when trying to connect.

    **Cause:** Invalid credentials, wrong path format, or insufficient permissions.

    **Solution:**

    1. Verify your Access Key and Secret Access Key are correct
    2. Check the path format: `s3://bucket-name/path/to/folder/`
    3. Ensure the IAM user has all required permissions listed above
    4. Verify the bucket exists and is in the correct AWS region
  </Accordion>

  <Accordion title="CORS errors in browser">
    **Symptom:** Images don't load in the Labellerr annotation interface due to CORS errors.

    **Cause:** Missing CORS configuration on the S3 bucket.

    **Solution:**
    Either grant `s3:PutBucketCors` permission to allow Labellerr to set CORS automatically, or configure CORS manually on your bucket:

    ```json theme={"dark"}
    [
      {
        "AllowedHeaders": ["*"],
        "AllowedMethods": ["GET", "HEAD"],
        "AllowedOrigins": ["*.labellerr.com"],
        "ExposeHeaders": [],
        "MaxAgeSeconds": 3600
      }
    ]
    ```
  </Accordion>

  <Accordion title="'No files found with status' during export">
    **Symptom:** Export fails with "No files found with the given status" error.

    **Cause:** Files have not been moved to the expected workflow stage (review, client\_review, or accepted).

    **Solution:**

    1. Ensure files have been annotated AND reviewed before exporting
    2. Check the `statuses` parameter in your export configuration
    3. Valid statuses for export: `review`, `client_review`, `accepted`
  </Accordion>

  <Accordion title="Internal server error with tracking ID">
    **Symptom:** An "Internal server error" appears with a tracking ID.

    **Cause:** Usually indicates a server-side issue, often related to permissions.

    **Solution:**

    1. Note the tracking ID for support reference
    2. Check connection permissions are still valid
    3. Verify IAM user credentials haven't been rotated or revoked
    4. Contact [support@tensormatics.com](mailto:support@tensormatics.com) with the tracking ID
  </Accordion>
</AccordionGroup>

## Related Guides

<CardGroup>
  <Card title="Connect Google Cloud Storage" icon="google" href="/getting-started/connect-gcs">
    Set up GCS bucket connection with service account authentication
  </Card>

  <Card title="Create Projects" icon="folder-plus" href="/getting-started/create-project">
    Learn how to create annotation projects with your connected data
  </Card>
</CardGroup>


# How to Connect Google Cloud Storage with Labellerr
Source: https://docs.labellerr.com/getting-started/connect-gcs

Learn how to establish a secure connection between your Google Cloud Storage bucket and Labellerr using IAM Service Account for data access.

Welcome to the User Guide for connecting a Google Cloud Storage (GCS) bucket with Labellerr, a powerful SaaS product for data annotation and labeling. In this guide, we will walk you through the process of establishing a connection between your GCS bucket and Labellerr, leveraging IAM User Access within the same Google Cloud account.

To establish the connection between your GCS bucket and Labellerr, we will utilize IAM (Identity and Access Management). IAM is a Google Cloud service that enables you to manage access to your Google Cloud resources securely.

By creating an IAM user with appropriate permissions, you can grant Labellerr the necessary access to your GCS bucket while ensuring the security of your data.

<Note>
  Please note that the procedures outlined in this guide pertain to connecting a GCS bucket and LABELLERR within the same Google Cloud account.
</Note>

## Quick Reference

### GCS URI Format

<Card title="GCS Path Format" icon="link">
  ```
  Format: gs://bucket-name/path/to/folder/
  Example: gs://my-gcs-bucket/annotations/dataset-001/
  ```
</Card>

### Required Permissions Summary

<Tabs>
  <Tab title="Import (Read)">
    | Permission | Purpose |
    | - | - |
    | `storage.objects.get` | Read files from bucket |
    | `storage.objects.list` | List files in bucket |
    | `storage.buckets.get` | Get bucket metadata |
    | `storage.buckets.update`(Optional) | Update bucket settings (CORS) |
  </Tab>

  <Tab title="Export (Write)">
    | Permission | Purpose |
    | - | - |
    | `storage.objects.create` | Write/upload annotation files |
    | `storage.objects.delete` | Delete files if needed |

    <Note>Export permissions are required **in addition** to import permissions.</Note>
  </Tab>
</Tabs>

### S3 vs GCS Comparison

| Feature | AWS S3 | Google Cloud Storage |
| - | - | - |
| URI Format | `s3://bucket/path/` | `gs://bucket/path/` |
| Authentication | Access Key + Secret Key | Service Account JSON |
| Import Permissions | 5 permissions | 4 permissions |
| Export Permissions | +2 permissions | +2 permissions |
| CORS Setup | Via IAM policy or manual | Via bucket settings |

<Tip>
  **Using AWS S3 instead?** See our [AWS S3 Connection Guide](/getting-started/connect-aws-s3) for S3 setup instructions.
</Tip>

To connect data with GCS in Labellerr:

## Prerequisites

<Steps>
  <Step title="Role Creation">
    **Go to the IAM & Admin Console:**

    * Open the Google Cloud Console
    * Navigate to **IAM & Admin > Roles**

    **Create a Custom Role:**

    * Click on **+ CREATE ROLE**
    * Enter a **Title, ID,** and **Description** for the role
    * Click **CONTINUE**

    <Frame>
      <img alt="Create custom role in GCS" />
    </Frame>

    **Add Permissions:**

    * In the **Permissions** section, add the necessary permissions

    For accessing a GCS bucket, you typically need:

    1. `storage.buckets.get`
    2. `storage.buckets.update`
    3. `storage.objects.get`
    4. `storage.objects.list`

    * Click **CONTINUE**
    * Review the role details
    * Click **CREATE**

    <Frame>
      <img alt="GCS role permissions" />
    </Frame>
  </Step>

  <Step title="Service Account Creation">
    **Go to the Service Accounts Console:**

    * In the Google Cloud Console, navigate to **IAM & Admin** > **Service Accounts**

    <Frame>
      <img alt="GCS service accounts console" />
    </Frame>

    **Create a Service Account:**

    * Click on + CREATE SERVICE ACCOUNT
    * Enter a Service account name and Description
    * Click CREATE AND CONTINUE

    **Grant Access to Project:**

    * In the Grant this service account access to project section, add the role created in the previous step
    * Click **CONTINUE**

    <Frame>
      <img alt="Grant role to service account" />
    </Frame>

    **Grant Users Access to this Service Account (Optional):**

    * If needed, add users who can manage this service account
    * Click DONE
  </Step>

  <Step title="Generate and Download Service Account Key">
    **Select Service Account:**

    * In the Service Accounts console, find the service account you created
    * Click the ⋮ (three vertical dots) next to the service account and select Manage keys

    <Frame>
      <img alt="Manage service account keys" />
    </Frame>

    **Create Key:**

    * Click ADD KEY > Create new key

    <Frame>
      <img alt="Create new key" />
    </Frame>

    <Frame>
      <img alt="Select key type" />
    </Frame>

    <Frame>
      <img alt="Download key file" />
    </Frame>

    * Click CREATE
    * A JSON key file will be downloaded. Keep this file secure as it contains the credentials needed to access the GCS bucket
  </Step>

  <Step title="Assign IAM Policy to GCS Bucket">
    1. **Go to the Cloud Storage Console:** Navigate to Cloud Storage > Buckets in the Google Cloud Console
    2. **Select Your Bucket:** Click on the name of your private bucket. You will see the bucket details, including its Name, Location, and other information
    3. **Open Permissions:** Click on the Permissions tab
    4. **Add Member:**
       * Click ADD
       * In the New members field, enter the service account email
       * Select the role you created earlier
       * Click SAVE
  </Step>

  <Step title="Use the Labellerr tool to Access the GCS Data">
    Click 'Google Cloud Storage' from the sources list and then 'Create New Connection'. There are two options to connect your data through 'Private Bucket' and 'Public Bucket'.

    <Frame>
      <img alt="Labellerr GCS connector" />
    </Frame>

    <Frame>
      <img alt="GCS connection form" />
    </Frame>

    After filling the details successfully, click on **Test Connection**, if the details are correct, you should see this.

    <Frame>
      <img alt="GCS test connection success" />
    </Frame>

    Else you will get this error.

    <Frame>
      <img alt="GCS test connection error" />
    </Frame>

    If successfully tested the connection and your files are recognized, you will need to fill the **Connection name** and **Description(Optional)**.

    <Frame>
      <img alt="GCS connection details" />
    </Frame>
  </Step>
</Steps>

And you're done, this is how you can connect your GCS bucket with Labellerr.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Service account JSON is invalid">
    **Symptom:** Connection test fails with "invalid service account" error.

    **Cause:** The JSON key file is corrupted, expired, or incorrectly formatted.

    **Solution:**

    1. Go to **IAM & Admin > Service Accounts** in Google Cloud Console
    2. Select your service account
    3. Click **Manage keys**
    4. Delete the old key and create a new one
    5. Download the new JSON key file and use it for the connection
  </Accordion>

  <Accordion title="Permission denied error">
    **Symptom:** Connection test fails with "permission denied" or "403 Forbidden" error.

    **Cause:** The service account doesn't have the required role assigned to the bucket.

    **Solution:**

    1. Go to **Cloud Storage > Buckets** in Google Cloud Console
    2. Select your bucket and click **Permissions** tab
    3. Click **ADD** and enter the service account email
    4. Assign the custom role you created with the required permissions
    5. Click **SAVE**
  </Accordion>

  <Accordion title="Bucket not found">
    **Symptom:** Connection test fails with "bucket not found" error.

    **Cause:** The bucket name in the path doesn't match the actual bucket name.

    **Solution:**

    1. Verify the gs\:// path matches your exact bucket name
    2. Check for typos in the bucket name
    3. Ensure the bucket exists in the same Google Cloud project
    4. Path format should be: `gs://exact-bucket-name/folder/`
  </Accordion>

  <Accordion title="Dataset creation shows status 500 or 'Failed'">
    **Symptom:** Dataset appears to create successfully but then shows "Failed" status.

    **Cause:** The service account doesn't have the required permissions to access the GCS bucket.

    **Solution:**

    1. Verify all required permissions are in the custom role
    2. Ensure the role is assigned to the bucket (not just the project)
    3. Test the connection before creating datasets:

    ```python theme={"dark"}
    from labellerr.core.connectors import LabellerrConnection
    from labellerr.core.schemas import ConnectionType, DatasetDataType

    connection = LabellerrConnection(client=client, connection_id="your_connection_id")
    test_result = connection.test(
        path="gs://your-bucket/path/to/data/",
        connection_type=ConnectionType._IMPORT,
        data_type=DatasetDataType.image
    )
    ```
  </Accordion>

  <Accordion title="'No files found with status' during export">
    **Symptom:** Export fails with "No files found with the given status" error.

    **Cause:** Files have not been moved to the expected workflow stage.

    **Solution:**

    1. Ensure files have been annotated AND reviewed before exporting
    2. Check the `statuses` parameter in your export configuration
    3. Valid statuses for export: `review`, `client_review`, `accepted`
  </Accordion>
</AccordionGroup>

## Related Guides

<CardGroup>
  <Card title="Connect AWS S3" icon="aws" href="/getting-started/connect-aws-s3">
    Set up AWS S3 bucket connection with IAM user authentication
  </Card>

  <Card title="Create Projects" icon="folder-plus" href="/getting-started/create-project">
    Learn how to create annotation projects with your connected data
  </Card>
</CardGroup>


# How to Create an Audio Annotation Project
Source: https://docs.labellerr.com/getting-started/create-audio-project

Learn how to create a new audio annotation project in Labellerr with step-by-step instructions.

## Create a New Audio Project

### Step 1: Selecting Data

Once at the **New project** page, To create a new project, first select an existing project name at the top. A popup will open displaying all projects within the workspace, along with a 'Create New Project' button. Click on 'Create New Project' to begin.

Give your project a suitable name and select the **Audio** data type. Then click on **Save and Next.**

<Warning>
  Only one data type can be selected per project
</Warning>

<Frame>
  <img alt="Create audio project" />
</Frame>

***

### Step 2: Upload/Attach existing dataset

If a new dataset is to be created, Click on the "**Create Dataset**" button. The available formats are **Google Drive, Google Cloud, Amazon S3 & Local Upload**.

<Frame>
  <img alt="Audio dataset upload options" />
</Frame>

<CardGroup>
  <Card>
    <Frame>
      <img alt="Audio upload option 1" />
    </Frame>
  </Card>

  <Card>
    <Frame>
      <img alt="Audio upload option 2" />
    </Frame>
  </Card>
</CardGroup>

<Tip>
  For more on how to upload files from different sources, check out this link [datasets](/tutorials/datasets).
</Tip>

Next, fill in the new dataset details: Enter the Name (mandatory) and Description (optional), then click on 'Create Dataset'.

<Frame>
  <img alt="Audio dataset details" />
</Frame>

***

### Step 3: Label Configuration

Here, Objects and Classifications based on the labeling requirements are supposed to be created. You can create a new template from scratch using the various options available or select an existing template from previous work on clicking **'Existing Templates'** button.

There are different 'Object' & 'Classification' types. For objects, in **Objects** tab, Click on '**Add Object**'. Enter Object name and select object type. Click on 💾 button to add it.

<Frame>
  <img alt="Audio label configuration" />
</Frame>

To add attributes of an object or to edit the type/name of object, click on pen icon in parallel to object name. Click on 'Add Attribute'. Enter name of the Attribute and click on 'Add Options' to enter the values of attribute.

**Additional options are also available:**

<Info>
  * **Required** - Indicates that the attribute must be completed
  * **Sort options** - Allows sorting the values of the attribute
  * **Not sure remarks** - Enables adding remarks when unsure about an answer
</Info>

<CardGroup>
  <Card>
    <Frame>
      <img alt="Audio attribute interface 1" />
    </Frame>
  </Card>

  <Card>
    <Frame>
      <img alt="Audio attribute interface 2" />
    </Frame>
  </Card>
</CardGroup>

<Tip>
  Similarly, for classification, navigate to the 'Classifications' tab. Click on 'Add Classification', then enter the classification name/question. Select the classification type from the dropdown options, and click on 'Add option' to enter values for dropdown, radio, or multiselect options.
</Tip>

<Frame>
  <img alt="Audio classification interface" />
</Frame>

After you've finished, click on the "**Next Step**" button. Then, fill your new "**Template Details**" details and click on "**Proceed**" to continue so you can use the same template in future projects.

<Frame>
  <img alt="Audio template details" />
</Frame>

***

### Step 4: Review

Select your review process by setting up the annotation count, review count (if **Review Process** is enabled) & client review count (if **Client Review Process** is enabled).

<Frame>
  <img alt="Audio review settings" />
</Frame>

Click the **'Create Project'** button to create your project. Once created, it will appear in the list along with your previously created projects. To view a project, simply click the '**View button'**.

<Frame>
  <img alt="Audio project created" />
</Frame>

<Info>
  **To find the project ID**, check the URL in the web link of the project's dashboard, labeling, review/client review screens, or files page.
</Info>

<Frame>
  <img alt="Audio project ID location" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# How to Create a New Project
Source: https://docs.labellerr.com/getting-started/create-project

Learn how to create different types of projects including image, text, video, and audio annotation projects in Labellerr.

<Note>
  This tutorial would help address all issues regarding creation of a new project. What are the data types supported? How to Import data? & How to set Labelling parameters?
</Note>

<Card title="Topics Covered" icon="list-check">
  This guide covers creating different types of projects in Labellerr:

  * **Image Projects** - For visual annotation tasks
  * **Text Projects** - For text analysis and labeling
  * **Video Projects** - For temporal annotation workflows
  * **Audio Projects** - For sound analysis and segmentation
</Card>

## How to Create an Image Project?

<Steps>
  <Step title="Selecting Data">
    Once at the **Home** page, To create a new project, click on **'Create Project'** button to begin.

    <Frame>
      <img alt="Create project from home page" />
    </Frame>

    <Warning>
      **Only one data type can be selected per project.**

      For more on **Text, Audio and Video** data types, Check out the following create Text, Video & Audio Guides:

      * [How to create a Text Project?](/getting-started/create-text-project)
      * [How to create a Video Project?](/getting-started/create-video-project)
      * [How to create an Audio Project?](/getting-started/create-audio-project)
    </Warning>
  </Step>

  <Step title="Upload/Attach existing dataset">
    If a new dataset is to be created, Click on the "**Create Dataset**" button or you can select **Public datasets** for testing. To know more about how to test using Public Datasets you can visit the next tutorial.

    <Frame>
      <img alt="Create dataset screen" />
    </Frame>

    Now choose a data modality to work with. The options are **Image, Video, Audio, Text, Document** and then click on **Next**.

    <Frame>
      <img alt="Select data modality" />
    </Frame>

    Now select a Data Connector. The available formats are Google Drive, Google Cloud, Amazon S3 & Local Upload.

    <Frame>
      <img alt="Select data connector" />
    </Frame>

    <Info>
      For more on how to upload files from different sources, check out [Datasets](/tutorials/datasets)
    </Info>

    Next, fill in the new dataset details: Enter the Name (mandatory) and Description (optional), then click on 'Create Dataset'.

    <Frame>
      <img alt="Fill dataset details" />
    </Frame>
  </Step>

  <Step title="Label Configuration">
    Here, Objects and Classifications based on the labeling requirements are supposed to be created. You can create a new template from scratch using the various options available or select an existing template from previous work on clicking **'Existing Templates'** button.

    <Frame>
      <img alt="Label configuration screen" />
    </Frame>

    There are different 'Object' & 'Classification' types. For objects, in **Objects** tab, Click on '**Add Object**'. Enter Object name and select object type. Click on 💾 button to add it.

    <Frame>
      <img alt="Add object interface" />
    </Frame>

    If you are confused to what object should be you can also view a sample image by clicking on show preview.

    <Frame>
      <img alt="Show preview option" />
    </Frame>

    This will show you a preview of a random image from the dataset.

    <Frame>
      <img alt="Image preview" />
    </Frame>

    To add attributes of an object or to edit the type/name of object, click on pen icon in parallel to object name. Click on 'Add Attribute'. Enter name of the Attribute and click on 'Add Options' to enter the values of attribute.

    <Frame>
      <img alt="Add attribute interface" />
    </Frame>

    <Frame>
      <img alt="Attribute options" />
    </Frame>

    <Info>
      **Additional options are also available:**

      * **Required** - Indicates that the attribute must be completed.
      * **Sort options** - Allows sorting the values of the attribute.
      * **Not sure remarks** - Enables adding remarks when unsure about an answer.
    </Info>

    <CardGroup>
      <Card>
        <Frame>
          <img alt="Attribute interface 1" />
        </Frame>
      </Card>

      <Card>
        <Frame>
          <img alt="Attribute interface 2" />
        </Frame>
      </Card>
    </CardGroup>

    <Tip>
      Similarly, for classification, navigate to the 'Classifications' tab. Click on 'Add Classification', then enter the classification name/question. Select the classification type from the dropdown options, and click on 'Add option' to enter values for dropdown, radio, or multiselect options.
    </Tip>

    <Frame>
      <img alt="Classification interface" />
    </Frame>

    For more on Image editing icons, check out the [Image Editing Icons Guide](/tutorials/image-editing-icons).

    After you've finished, click on the "**Next Step**" button. Then, fill your new "**Template Details**" details and click on "**Proceed**" to continue so you can use the same template in future projects.

    <Frame>
      <img alt="Template details" />
    </Frame>
  </Step>

  <Step title="Create Project with AI or Manual Labelling and Review">
    Write the project name.

    Select your review process by enabling or disabling the toggle button, Enable review cycle (if **Review Process** is needed) & Enable client review cycle (if **Client Review Process** is needed).

    <Frame>
      <img alt="Project settings" />
    </Frame>

    Click the **'Create Project with Labellerr AI'** button to create your project with AI Data Labeling and you will have to just review.

    If selected Human Labeling project it will allow you to annotate manually. Once created, it will appear in the list along with your previously created projects. To view a project, simply click the '**View button**'.

    <Frame>
      <img alt="Project created successfully" />
    </Frame>

    To find the project ID, check the URL in the web link of the project's dashboard, labeling, review/client review screens, or navigate to the project's page and find it under that particular project as a column.

    <Frame>
      <img alt="Project ID in URL" />
    </Frame>

    <Frame>
      <img alt="Project ID in column" />
    </Frame>
  </Step>
</Steps>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# How to Create a Text Annotation Project
Source: https://docs.labellerr.com/getting-started/create-text-project

Learn how to create a new text annotation project in Labellerr with step-by-step instructions.

## Create a New Text Project

<Steps>
  <Step title="Selecting Data">
    Once at the **New project** page, To create a new project, first select an existing project name at the top. A popup will open displaying all projects within the workspace, along with a 'Create New Project' button. Click on 'Create New Project' to begin.

    Give your project a suitable name and select the **Text** data type. Then click on **Save and Next**.

    <Warning>
      Only one data type can be selected per project
    </Warning>

    <Frame>
      <img alt="Create text project screen" />
    </Frame>
  </Step>

  <Step title="Upload/Attach existing dataset">
    If a new dataset is to be created, Click on the "Create Dataset" button. The available formats are Google Drive, Google Cloud, Amazon S3 & Local Upload.

    <Frame>
      <img alt="Text dataset upload options" />
    </Frame>

    <CardGroup>
      <Card>
        <Frame>
          <img alt="Upload option 1" />
        </Frame>
      </Card>

      <Card>
        <Frame>
          <img alt="Upload option 2" />
        </Frame>
      </Card>
    </CardGroup>

    Next, fill in the new dataset details: Enter the Name (mandatory) and Description (optional), then click on 'Create Dataset'.

    <Frame>
      <img alt="Text dataset details form" />
    </Frame>
  </Step>

  <Step title="Label Configuration">
    Here, Objects and Classifications based on the labeling requirements are supposed to be created. You can create a new template from scratch using the various options available or select an existing template from previous work on clicking **'Existing Templates'** button.

    There are different 'Object' & 'Classification' types. For objects, in **Objects** tab, Click on '**Add Object**'. Enter Object name and select object type. Click on 💾 button to add it.

    <Frame>
      <img alt="Text label configuration" />
    </Frame>

    To add attributes of an object or to edit the type/name of object, click on pen icon in parallel to object name. Click on 'Add Attribute'. Enter name of the Attribute and click on 'Add Options' to enter the values of attribute.

    <Info>
      **Additional options are also available:**

      * **Required** - Indicates that the attribute must be completed
      * **Sort options** - Allows sorting the values of the attribute
      * **Not sure remarks** - Enables adding remarks when unsure about an answer
    </Info>

    <CardGroup>
      <Card>
        <Frame>
          <img alt="Text attribute interface 1" />
        </Frame>
      </Card>

      <Card>
        <Frame>
          <img alt="Text attribute interface 2" />
        </Frame>
      </Card>
    </CardGroup>

    <Tip>
      Similarly, for classification, navigate to the 'Classifications' tab. Click on 'Add Classification', then enter the classification name/question. Select the classification type from the dropdown options, and click on 'Add Attribute' to enter values for dropdown, radio, or multiselect options.
    </Tip>

    <Frame>
      <img alt="Text classification interface" />
    </Frame>

    After you've finished, click on the "**Next Step**" button. Then, fill your new "**Template Details**" details and click on "**Proceed**" to continue so you can use the same template in future projects.

    <Frame>
      <img alt="Text template details" />
    </Frame>
  </Step>

  <Step title="Review">
    Select your review process by enabling or disabling the toggle button, Enable review cycle (if **Review Process** is needed) & Enable client review cycle (if **Client Review Process** is needed).

    <Frame>
      <img alt="Text review settings" />
    </Frame>

    <Tip>
      Click the 'Create Project' button to create your project. Once created, it will appear in the list along with your previously created projects. To view a project, simply click the 'View button'
    </Tip>

    <Frame>
      <img alt="Text project created" />
    </Frame>

    <Info>
      **To find the project ID**, check the URL in the web link of the project's dashboard, labeling, review/client review screens, or files page.
    </Info>

    <Frame>
      <img alt="Text project ID location" />
    </Frame>
  </Step>
</Steps>


# How to Create a Video Annotation Project
Source: https://docs.labellerr.com/getting-started/create-video-project

Learn how to create a new video annotation project in Labellerr with step-by-step instructions.

## Create a New Video Project

### Step 1: Selecting Data

Once at the **New project** page, To create a new project, first select an existing project name at the top. A popup will open displaying all projects within the workspace, along with a 'Create New Project' button. Click on 'Create New Project' to begin.

Give your project a suitable name and select the **Video** type data that you have. Then click on **Save and Next.**

<Warning>
  Only one data type can be selected per project
</Warning>

<Frame>
  <img alt="Create video project" />
</Frame>

***

### Step 2: Upload/Attach existing dataset

If a new dataset is to be created, Click on the "**Create Dataset**" button. The available formats are **Google Drive, Google Cloud, Amazon S3 & Local Upload**.

<Frame>
  <img alt="Video dataset upload options" />
</Frame>

<CardGroup>
  <Card>
    <Frame>
      <img alt="Video upload option 1" />
    </Frame>
  </Card>

  <Card>
    <Frame>
      <img alt="Video upload option 2" />
    </Frame>
  </Card>
</CardGroup>

<Tip>
  For more on how to upload files from different sources, check out this link [Datasets](/tutorials/datasets)
</Tip>

Next, fill in the new dataset details: Enter the Name (mandatory) and Description (optional), then click on 'Create Dataset'.

***

### Step 3: Label Configuration

Here, Objects and Classifications based on the labeling requirements are supposed to be created. You can create a new template from scratch using the various options available or select an existing template from previous work on clicking **'Existing Templates'** button.

<Frame>
  <img alt="Video label configuration" />
</Frame>

<Tip>
  There are different 'Object' & 'Classification' types. For objects, in **Objects** tab, Click on '**Add Object**'. Enter Object name and select object type. Click on 💾 button to add it.
</Tip>

<Frame>
  <img alt="Add video object" />
</Frame>

To add attributes of an object or to edit the type/name of object, click on pen icon in parallel to object name. Click on 'Add Attribute'. Enter name of the Attribute and click on 'Add Options' to enter the values of attribute.

**Additional options are also available:**

<Info>
  * **Required** - Indicates that the attribute must be completed
  * **Sort options** - Allows sorting the values of the attribute
  * **Not sure remarks** - Enables adding remarks when unsure about an answer
</Info>

<CardGroup>
  <Card>
    <Frame>
      <img alt="Video attribute interface 1" />
    </Frame>
  </Card>

  <Card>
    <Frame>
      <img alt="Video attribute interface 2" />
    </Frame>
  </Card>
</CardGroup>

<Tip>
  Similarly, for classification, navigate to the 'Classifications' tab. Click on 'Add Classification', then enter the classification name/question. Select the classification type from the dropdown options, and click on 'Add option' to enter values for dropdown, radio, or multiselect options.
</Tip>

<Frame>
  <img alt="Video classification interface" />
</Frame>

After you've finished, click on the "**Next Step**" button. Then, fill your new "**Template Details**" details and click on "**Proceed**" to continue so you can use the same template in future projects.

<Frame>
  <img alt="Video template details" />
</Frame>

***

### Step 4: Review

Select your review process by enabling or disabling the toggle button, Enable review cycle (if **Review Process** is needed) & Enable client review cycle (if **Client Review Process** is needed).

<Frame>
  <img alt="Video review settings" />
</Frame>

Click the **'Create Project'** button to create your project. Once created, it will appear in the list along with your previously created projects. To view a project, simply click the '**View button'**.

<Frame>
  <img alt="Video project created" />
</Frame>

<Info>
  **To find the project ID**, check the URL in the web link of the project's dashboard, labeling, review/client review screens, or files page.
</Info>

<Frame>
  <img alt="Video project ID location" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# How to Delete a Dataset
Source: https://docs.labellerr.com/getting-started/delete-dataset

Learn how to permanently delete a dataset in Labellerr using the dataset options menu.

<Warning>
  Deleting a dataset is a **permanent and irreversible action**. All files and data associated with the dataset will be removed. Make sure you no longer need the dataset before proceeding.
</Warning>

<Card title="What This Guide Covers" icon="list-check">
  This guide walks you through the complete process of deleting a dataset in Labellerr:

  * **Navigating** to the Datasets section from the left sidebar
  * **Locating** the dataset you want to delete
  * **Accessing** the dataset options via the three-dot menu
  * **Confirming** the deletion
</Card>

## How to Delete a Dataset?

<Steps>
  <Step title="Navigate to the Datasets Section">
    From the **left sidebar**, click on **Datasets**. This will open the datasets listing page, showing all datasets available within your workspace.

    <Frame>
      <img alt="Navigate to Datasets from left sidebar" />
    </Frame>

    <Info>
      Ensure you are in the correct **workspace** before proceeding, as datasets are workspace-specific.
    </Info>
  </Step>

  <Step title="Click the Three-Dot Menu on the Dataset">
    From the list of datasets, locate the dataset you wish to delete. Click on the **three-dot icon (⋮)** on the right side of that dataset row to open the options menu.

    <Frame>
      <img alt="Three-dot options menu on a dataset" />
    </Frame>
  </Step>

  <Step title="Select 'Delete Dataset'">
    From the dropdown options menu that appears, click on **Delete Dataset**.

    <Warning>
      Only users with **Admin** or **Owner** level permissions can delete a dataset. If the option is not visible, contact your workspace administrator.
    </Warning>
  </Step>

  <Step title="Click Delete to Confirm">
    A confirmation dialog will appear asking you to confirm the deletion. Click the **Delete** button to permanently remove the dataset from your workspace.

    <Frame>
      <img alt="Delete confirmation dialog" />
    </Frame>

    The dataset will be removed and will no longer appear in the datasets list.
  </Step>
</Steps>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# How to Delete a Project
Source: https://docs.labellerr.com/getting-started/delete-project

Learn how to permanently delete a project in Labellerr, including the confirmation steps required to prevent accidental deletion.

<Warning>
  Deleting a project is a **permanent and irreversible action**. All associated data, annotations, and configurations will be lost. Please ensure you have exported any required data before proceeding.
</Warning>

<Card title="What This Guide Covers" icon="list-check">
  This guide walks you through the complete process of safely deleting a project in Labellerr:

  * **Navigating** to the Projects section
  * **Locating** the delete option under project actions
  * **Confirming** the deletion with a typed confirmation
  * **Completing** the deletion
</Card>

## How to Delete a Project?

<Steps>
  <Step title="Navigate to the Projects Section">
    From the **left sidebar**, click on **Projects** to open the projects listing page. This will display all the projects within your workspace.

    <Frame>
      <img alt="Navigate to Projects from left sidebar" />
    </Frame>

    <Info>
      Make sure you are in the correct **workspace** before proceeding, as projects are workspace-specific.
    </Info>
  </Step>

  <Step title="Click the Delete Icon">
    On the **Projects** page, locate the project you want to delete. Under the **Actions** column, click on the **Delete icon** (🗑️) associated with that project.

    <Frame>
      <img alt="Delete icon under Actions column on project page" />
    </Frame>

    <Warning>
      Only users with **Admin** or **Owner** level permissions can delete a project. If you do not see the delete icon, contact your workspace administrator.
    </Warning>
  </Step>

  <Step title="Type DELETE to Confirm">
    A confirmation dialog will appear. To prevent accidental deletion, you are required to type **DELETE** (in all caps) in the confirmation input field.

    <Frame>
      <img alt="Delete confirmation dialog with DELETE text input" />
    </Frame>

    <Info>
      The **Confirm** button will remain disabled until you type `DELETE` exactly as shown. This ensures that project deletions are always intentional.
    </Info>
  </Step>

  <Step title="Click Confirm to Delete the Project">
    Once you have typed **DELETE** in the input field, the **Confirm** button will become active. Click on **Confirm** to permanently delete the project.

    The project will be removed from your workspace and will no longer appear in the projects list.

    <Frame>
      <img alt="Projects list after successful deletion" />
    </Frame>
  </Step>
</Steps>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# How to Get Started with Labellerr
Source: https://docs.labellerr.com/getting-started/getting-started

Learn how to sign up, create a workspace, set up your first domain, and begin your first project in a few simple steps.

<Note>
  The objective of this tutorial is to help New and potential clients/users get started with labellerr. The tutorial covers all login procedures for convenience in the case of any issues faced by a new user with the signup process.
</Note>

## Labellerr Signup

<Steps>
  <Step title="Accessing The Platform">
    Once on our webpage, on the home screen, a floating toolbar with a few options is visible on the top. Click on the **Login Button**.

    <Frame>
      <img alt="Labellerr Homepage" />
    </Frame>
  </Step>

  <Step title="Fill Up The Credentials">
    This would redirect you to the Login/Sign Up screen. Here, you can choose either to click on the **Sign Up** option or the **Continue with Google** option.

    <Frame>
      <img alt="Sign up screen" />
    </Frame>

    <Info>
      **If the 'Sign Up' option is selected:**

      * A confirmation email would be sent to the registered email address
      * Be sure to check the Socials/Promotion page if the email is not visible on your Primary list
      * Click on the Verification link to proceed

      **If the 'Continue with Google' option is selected:**

      * Choose one of the active emails to proceed
    </Info>
  </Step>

  <Step title="Domain Creation">
    Give your account a domain name that suits your preference. In case the suggested name is not accepted, try using a different name.

    <Frame>
      <img alt="Domain creation screen" />
    </Frame>
  </Step>

  <Step title="Project Creation and Dashboard">
    Once domain is created, you would be redirected to create project page. Give a suitable name to your project and you can get started right away!

    <Frame>
      <img alt="Project creation screen" />
    </Frame>

    For more, check out the video tutorial.
  </Step>
</Steps>

<iframe title="Getting Started with Labellerr 🚀 | Sign Up, Upload Data & Add Users in Minutes!" />

<Note>
  For further assistance contact **[support@tensormatics.com](mailto:support@tensormatics.com)**
</Note>


# Getting Started with Labellerr
Source: https://docs.labellerr.com/getting-started/introduction

Learn how to get started with Labellerr - a simple and powerful platform for labeling data for AI and machine learning.

Labellerr is a simple and powerful platform for labeling data for AI and machine learning. It helps you annotate images, videos, text, PDFs, and audio quickly and accurately. You can use AI-assisted tools, automated workflows, and a smart feedback loop to get high-quality training data fast.

This section shows you fast, easy steps to begin using Labellerr. You'll learn how to sign up, create a project, and use the dashboard to manage your labeling work with confidence.

***

<CardGroup>
  <Card title="How to Get Started with Labellerr?" icon="play" href="/getting-started/getting-started">
    Learn how to sign up, create a workspace, set up your first domain, and begin your first project in a few simple steps.
  </Card>

  <Card title="How to Create a New Project?" icon="plus" href="/getting-started/create-project">
    Covers selecting data type (image, text, audio, video), uploading datasets, and setting up labeling templates and attributes.
  </Card>

  <Card title="How to Navigate Dashboard?" icon="chart-line" href="/getting-started/navigate-dashboard">
    Explains the dashboard layout, status bar, progress indicators, and built-in analytics to track your labeling work.
  </Card>
</CardGroup>


# How to Navigate Dashboard
Source: https://docs.labellerr.com/getting-started/navigate-dashboard

This tutorial helps new users get accustomed to the Dashboard and its elements, covering dashboard elements and self-generated graphs for activity tracking.

<Note>
  This tutorial is to help new users get accustomed to the Dashboard and its elements. It would cover the elements on the dashboard and self-generated graphs for activity tracking. Navigating the dashboard is swift and easy.
</Note>

<Card title="Topics Covered" icon="navigation">
  This guide covers navigating the Labellerr dashboard:

  * **Dashboard Overview** - Your home screen and main navigation hub
  * **Status Bar Elements** - Real-time annotation progress tracking
  * **Self-Generated Graphs** - Activity tracking and progress visualization
  * **Quick Actions** - Accessing projects and tasks efficiently
</Card>

The dashboard is your home screen. All tasks can be accessed through the dashboard. Every time the user logs in, the dashboard displays all the actions and progress (which changes in real-time). The Dashboard Shows the Status Bar and some self-generated statistics used for tracking progress.

## Status bar Elements

The Status bar displays Annotation progress in real-time and helps keep track of the user activity. The most important elements are the Total files, Accepted, remaining, and Percentage completion. This automatically updates itself when new files are added to the project.

<Frame>
  <img alt="Status bar elements" />
</Frame>

To learn more about the status bar, check out the [Status Bar Elements guide](/getting-started/status-bar-elements).

## Self Generated Graphs

These are the four self-generated graphs:

<Steps>
  <Step title="Labelling Trends">
    **Labelling Trends**: Shows the trends of a specific time period and status

    <Frame>
      <img alt="Labelling trends graph" />
    </Frame>

    <br />

    <br />

    <iframe title="YouTube video player" />
  </Step>

  <Step title="Label Distribution">
    **Label Distribution**: Here the labelling trends are seen. Individual objects can also be selected for screening

    <Frame>
      <img alt="Label distribution graph" />
    </Frame>

    <br />

    <br />

    <iframe title="YouTube video player" />
  </Step>

  <Step title="User Level Velocity Tracking">
    **User Level Velocity Tracking**: It is a graphical representation of average Data annotated and average Working time for a specific annotator.

    <Frame>
      <img alt="User level velocity tracking graph" />
    </Frame>

    <br />

    <br />

    <iframe title="YouTube video player" />
  </Step>

  <Step title="User Level Velocity Tracking">
    **User Level Velocity Tracking**: It is a graphical representation of average Data annotated and average Working time for a specific annotator.

    <Frame>
      <img alt="User level velocity tracking graph" />
    </Frame>

    <br />

    <br />

    <iframe title="YouTube video player" />
  </Step>
</Steps>

<Note>
  For further assistance contact **[support@tensormatics.com](mailto:support@tensormatics.com)**
</Note>


# Status Bar Elements Guide
Source: https://docs.labellerr.com/getting-started/status-bar-elements

Learn about the different elements in the status bar that track annotation progress and file states in real-time.

The status bar displays the status of the samples at all times.

<Frame>
  <img alt="Status bar overview" />
</Frame>

**Total** shows the total number of samples for labelling in the current set.

<Card title="Status Bar Elements Overview" icon="chart-bar">
  The status bar provides real-time tracking of annotation progress across different file states:
</Card>

<Card title="📊 Total" icon="hashtag">
  Shows the total number of samples active in the current dataset for annotation
</Card>

<Card title="✅ Accepted" icon="check-circle">
  Shows the annotated files that are accepted by client and are ready for export
</Card>

<Card title="⏳ Remaining" icon="clock">
  Shows the number of files unlabelled in the project
</Card>

<Card title="👤 Assigned" icon="user-check">
  Shows the total number of files that have already been assigned to annotators for annotation
</Card>

<Card title="🔄 Partial Annotation" icon="arrows-rotate">
  Shows partially annotated files completed by a single annotator (used when multiple rounds of annotations are needed for a single file)
</Card>

<Card title="👁️ In Review" icon="eye">
  Shows the no. of files sent for review
</Card>

<Card title="👨‍💼 In Client Review" icon="user-tie">
  Shows the no. of files sent for client review
</Card>

<Card title="❌ Client Rejected" icon="xmark-circle">
  Shows the no. of files rejected by the client
</Card>

<Card title="⏭️ Skipped" icon="forward">
  Shows the number of files that were not annotated and were skipped by annotators due to complexity or questions. These files are shown one by one at the end, after all unlabeled files have been annotated
</Card>

<Card title="🔍 Review Skipped" icon="magnifying-glass">
  Shows the number of files currently skipped by the reviewer during the internal review process due to specific queries or issues. These files will reappear one by one at the end of the review process, after all other files have completed one full round of review. This ensures that each file is revisited for resolution once initial reviews are complete.
</Card>

<Card title="👀 Client Review Skipped" icon="user-magnifying-glass">
  Shows the number of files skipped by the client while reviewing due to specific queries or issues. These files will reappear one by one at the end of the review process, after all other files have completed one full round of review.
</Card>

<Card title="🚫 Rejected" icon="ban">
  Shows the number of annotated files that were rejected by reviewers during the internal review process
</Card>

<Card title="📈 Completed" icon="chart-line">
  Tracks the completion percentage based on the number of accepted files compared to the total number of files
</Card>


# Template Versioning
Source: https://docs.labellerr.com/getting-started/template-versioning

Learn how to create, manage, and roll back annotation template versions in Labellerr to maintain consistency across your projects.

<Note>
  Template versioning gives teams full control over their annotation templates across projects. You can track changes, manage versions, and roll back when needed — without disrupting active workflows.
</Note>

<Card title="What This Guide Covers" icon="list-check">
  This guide covers everything you need to know about Template Versioning in Labellerr:

  * **Creating and saving** multiple versions of annotation templates
  * **Tracking changes** across project timelines
  * **Reverting** to previous versions with ease
  * **Viewing** version history with creator name and timestamp
  * **Applying** a specific version to a project from annotation settings
</Card>

## What is Template Versioning?

Template versioning allows teams to manage the lifecycle of annotation templates across different projects. Every time a template is modified, a new version can be saved — preserving the history of changes while keeping active projects unaffected.

This is especially useful for large-scale annotation workflows where templates evolve over time and multiple projects share the same label configuration.

<iframe title="Template Versioning" />

***

## Key Features

<CardGroup>
  <Card title="Version History" icon="clock-rotate-left">
    View a full history of all saved template versions, including the creator's name and the timestamp of each change.
  </Card>

  <Card title="Create New Versions" icon="floppy-disk">
    Save any modification to a template as a new version, keeping previous versions intact and accessible.
  </Card>

  <Card title="Rollback Support" icon="rotate-left">
    Revert to any previous version of a template instantly without disrupting other active projects using a different version.
  </Card>

  <Card title="Project-Level Application" icon="layer-group">
    Apply any specific template version to a project independently through the annotation settings — changes won't impact other linked projects.
  </Card>
</CardGroup>

***

## How to Use Template Versioning

<Steps>
  <Step title="Open the Template in Annotation Settings">
    Navigate to your project and go to the **Annotation Settings** (or Label Configuration). Here you will find the template associated with your project and the option to manage its versions.

    <Frame>
      <img alt="Annotation settings showing template version options" />
    </Frame>
  </Step>

  <Step title="Create a New Version">
    After making changes to the template (adding/editing objects or classifications), save it as a **new version**. This preserves the existing version history and does not affect projects still using older versions.

    <Frame>
      <img alt="Save new template version interface" />
    </Frame>

    <Info>
      Each saved version is independent, updating a template to a new version in one project does **not** automatically update other projects using the same template.
    </Info>
  </Step>

  <Step title="Apply a Specific Version to a Project">
    From the annotation settings, you can browse all available versions and apply any specific version to the current project. This allows different projects to run on different template versions simultaneously.

    <Frame>
      <img alt="Apply a specific template version to a project" />
    </Frame>
  </Step>
</Steps>

***

## FAQs

**Q. What is the difference between Template Versioning and Workspace Level Guidelines?**

Template Versioning allows teams to track, manage, and roll back changes to annotation templates across different versions, ensuring no work is lost during updates. Workspace Level Guidelines, on the other hand, provide a centralized place to define and share annotation standards that apply across all projects in a workspace, ensuring consistency without requiring per-project setup.

**Q. Can I apply a specific template version to an existing project without affecting other projects?**

Yes. Template versioning is managed at the project level through the annotation settings. You can view all available versions and apply any specific version to a project independently, without impacting other linked projects.

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Client Review
Source: https://docs.labellerr.com/labellerr/documentation-labellerr/actions/actions/client-review

A guide to effectively reviewing annotated images, offering suggestions, and providing feedback on potential errors within Labellerr.

<Warning>This page has been moved! Please visit the updated version at: **[Client Review](/actions/client-review)**</Warning>

This guide provides step-by-step instructions for effectively reviewing annotated images, offering suggestions, and providing feedback on potential errors. Follow these guidelines to participate in the annotation review process seamlessly.

### 1. Access the Client Reviewer Platform

* Log in to the Labellerr platform using your credentials.
* Navigate to the "Client Review" tab on the dashboard.

<Frame>
  <img alt="Client Review Dashboard" />
</Frame>

The review screen is designed just like the labeling page, giving you access to all the same tools. This ensures you have full control over the quality and accuracy of the annotations. You can easily edit, add, or remove annotations as needed to meet your specific requirements.

<Frame>
  <img alt="Client Review Screen" />
</Frame>

### 2. Review Annotations and Provide Feedback

The bottom-left part of the screen shows a list of all annotated object names. To provide feedback on a specific annotation:

* Scroll through the list of annotated object names.
* As you hover over a specific name, the corresponding object in the image will be highlighted.

While reviewing, you can provide remarks for each annotated object. If there is a mistake in the annotation, specify the mistake, or give suggestions for improvement.

<Frame>
  <img alt="Review Feedback" />
</Frame>

### 3. Add Remarks or Suggestions

* To give remarks, click the comment icon next to the annotated object's name and type your feedback. Select "Mistake" if the annotation is incorrect, or "Suggestion" to propose improvements. Then, click the "Add Remark" button to submit your feedback.

<Frame>
  <img alt="Add Remark" />
</Frame>

### 4. Hide Annotated Objects

To hide an annotated object, click the eye icon located to the right of the annotated object's name, just after the comment icon.

<Frame>
  <img alt="Hide Object" />
</Frame>

To hide all the annotations, click on the eye icon located next to the "Annotations" heading, which groups all the annotated objects.

**Why It’s Important:**

This feature helps you focus on specific areas of the image by temporarily hiding other annotated objects. It can reduce visual clutter, making it easier to review and analyze individual annotations or their placement in detail.

### 5. Skip, Reject or Accept a file

Once the file screening is complete, you have three options:

1. To accept the file, click the "Accept" button, and the file will be ready for export.
2. If there are mistakes or suggestions, click the "Reject" button, and the file will be sent for corrections.
3. To skip the file and have another client review it, click the "Skip" button.

The "Reject" and "Accept" buttons are located at the bottom left of the screen. To the left of the "Reject" button, you'll find a small arrow.

<Frame>
  <img alt="Review Actions" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Client Review Using Grid View
Source: https://docs.labellerr.com/labellerr/documentation-labellerr/actions/actions/client-review-using-grid-view

Learn how clients can efficiently review and manage annotated files in Labellerr using the grid view, with quick accept or reject options.

<Warning>This page has been moved! Please visit the updated version at: **[Client Review Using Grid View](/actions/client-review-grid)**</Warning>

This feature allows clients to view files in a grid view, enabling users to quickly accept or reject files with just one click. Below, we provide step-by-step guidance on how to use this functionality.

### 1. Access the Annotated file

* Labeling must be completed within the **Label** section.
* Once labeling is done, files should be submitted.
* Files must be accepted by a reviewer. All reviewer-accepted files will then appear in the **In Client Review** section.
* Next, navigate to the **Files** section by clicking on it.

<Frame>
  <img alt="Access Files Section" />
</Frame>

* At the top of the page, in the **File Filters** section, you'll find the status bar. Use the dropdown menu to select the '**Ready for Client Review**' filter to display relevant files. You may also apply other filters as needed to narrow down your search and click on the **Apply Filters**.

<Frame>
  <img alt="Apply Filters" />
</Frame>

Once the filter is applied, all your submitted files will be visible in the list, allowing you to view them easily in one place.

<Frame>
  <img alt="Filtered Files List" />
</Frame>

### 2. Review files in Grid View

Once the files appear, hover over the icon on the top right bar to reveal the '**Grid View**' option, then click it to switch to grid view.

<Frame>
  <img alt="Switch to Grid View" />
</Frame>

You can now zoom in and out of the image using the slider, making it easier to view your annotated file clearly and in detail, so users can confidently accept or reject the file.

### 3. Reject a file by adding relevant remarks.

This feature adds remarks before rejection, ensuring clarity, transparency, and constructive feedback for better communication.

<Frame>
  <img alt="Add Remarks for Rejection" />
</Frame>

<Note>
  For further assistance contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Copy From Similar Images
Source: https://docs.labellerr.com/labellerr/documentation-labellerr/feature-demos/feature-demos/copy-from-similar-images

Learn how Labellerr's 'Copy from' feature reduces annotation time by up to 70% by leveraging past annotations from similar images.

<Warning>This page has been moved! Please visit the updated version at: **[Copy From Similar Images](/features/copy-similar-images)**</Warning>

<CardGroup>
  <Card title="What is the “Copy from” feature?">
    To save labeling time, [Labellerr](https://www.linkedin.com/company/labellerr/) has introduced copy the label feature which reduces the time spent on each image by up to 70%.
  </Card>

  <Card title="Benefits of Copy from">
    The average time spent by annotators on labeling classifications with an average of 60-70 labels per image is around 10000 hrs. In most of the projects, up to 70% of labels are the same, it's just 30% of labels that changes with every image/video. If it's a video project, the time would go up by 150%. Now, the annotators can leverage their past annotations and copy all the labels with just a click.
  </Card>

  <Card title="How it works">
    For large and diverse datasets, our system sorts the annotated image based on the similarity with the highest chance of similar labels. This additionally saves annotators time to look for the right image to copy, because it will always be at the top.
  </Card>
</CardGroup>

Watch the demo video to see it in action.

<Video />


# User Settings Guide
Source: https://docs.labellerr.com/labellerr/documentation-labellerr/feature-demos/feature-demos/user-settings-guide

Learn how to manage users in Labellerr, including adding, deleting, editing credentials, and assigning roles and projects to annotators.

<Warning>This page has been moved! Please visit the updated version at: **[User Settings Guide](/features/user-settings)**</Warning>

### Managing Users

<Info>
  User settings allows you to add or delete new users and assign new roles and projects to existing annotator
</Info>

<Steps>
  <Step title="Access User Settings">
    To access the user settings, click on the user icon from the settings list on the left.

    <Frame>
      <img alt="User Icon in Settings" />
    </Frame>
  </Step>

  <Step title="Click on Users Option">
    Click on Users Option.

    <Frame>
      <img alt="Users Option" />
    </Frame>
  </Step>

  <Step title="User Settings Screen">
    The User settings screen should appear which lets you manage users. The following screen shows the list of all users working on a domain. Display on-screen also shows the role and the last date of work for each user. Multiple actions can be taken henceforth.

    <Frame>
      <img alt="User Settings Screen" />
    </Frame>
  </Step>

  <Step title="Search and Edit Users">
    The **search option** allows you to search for a user by name. The **Edit option** lets you edit user credentials, profile and assign or delete roles.

    <Frame>
      <img alt="Search and Edit Options" />
    </Frame>
  </Step>

  <Step title="Add a New User">
    To add a new user, simply click on the create user option located on the top right corner.

    <Frame>
      <img alt="Create User Option" />
    </Frame>

    The following create user screen would appear.

    <Frame>
      <img alt="Create User Screen" />
    </Frame>

    <ol>
      <li>On the left, basic user credentials are to be added. Email, First Name and Last name are mandatory fields.</li>
      <li>On the right, click on ‘+’ icon and then projects and roles can be assigned.</li>
    </ol>
  </Step>
</Steps>

Once the input has been made, the new user profile would be made by clicking on save at the bottom right.


# Importing users from one project to another in the same workspace
Source: https://docs.labellerr.com/labellerr/documentation-labellerr/frequently-accessed-tutorials/frequently-accessed-tutorials-1/importing-users-from-one-project-to-another-in-the-same-workspace



***

title: "Importing Users from One Project to Another"
description: "Learn how to import users from one project to another within the same workspace in Labellerr."
icon: user-plus
---------------

<Warning>This page has been moved! Please visit the updated version at: **[Importing Users from One Project to Another](/tutorials/importing-users)**</Warning>

## Overview

This guide provides step-by-step instructions on how to import users from a selected project into the required project within the same workspace.

## Prerequisites

* You must have the necessary permissions to import users
* Ensure that both the source and target projects exist within the same workspace
* Check this to learn about [Workspace](/tutorials/workspace)

## Steps to Import Users

<Steps>
  <Step title="Navigate to the Settings section">
    1. Log in to your workspace
    2. Go to the Settings section from the main dashboard of the current project

    <Frame>
      <img alt="Navigate to Settings" />
    </Frame>
  </Step>

  <Step title="Access the Users option">
    1. Click on the **Users** option within the **Settings** section

    <Frame>
      <img alt="Access Users option" />
    </Frame>

    2. Locate and click on the **Import Users** button

    <Frame>
      <img alt="Import Users button" />
    </Frame>
  </Step>

  <Step title="Select the Source project">
    <Frame>
      <img alt="Select source project" />
    </Frame>

    1. A dialog box will open, prompting you to select the project from which you want to import users
    2. Choose the desired project from the drop-down list
    3. Once the project is selected, the **Import** button will be enabled
    4. Click on the **Import** button to finalize the import process
  </Step>

  <Step title="Verification">
    <Frame>
      <img alt="Verify imported users" />
    </Frame>

    1. Verify that all the users are successfully imported to the project
    2. All the imported users will be shown along with the current users list
  </Step>
</Steps>

## Additional Notes

<Info>
  * If a user already exists in the target project, they will not be duplicated
  * Users will retain their roles and permissions as assigned in the source project
</Info>

<Note>
  For further assistance, please contact [support@tensormatics.com](mailto:support@tensormatics.com).
</Note>


# How to Get Started with Labellerr
Source: https://docs.labellerr.com/labellerr/documentation-labellerr/getting-started/get-started-with-labellerr

Learn how to sign up, create a workspace, set up your first domain, and begin your first project in a few simple steps.

<Warning>This page has been moved! Please visit the updated version at: **[How to Get Started with Labellerr](/getting-started/getting-started)**</Warning>

<Note>
  The objective of this tutorial is to help New and potential clients/users get started with labellerr. The tutorial covers all login procedures for convenience in the case of any issues faced by a new user with the signup process.
</Note>

## Labellerr Signup

<Steps>
  <Step title="Accessing The Platform">
    Once on our webpage, on the home screen, a floating toolbar with a few options is visible on the top. Click on the **Login Button**.

    <Frame>
      <img alt="Labellerr Homepage" />
    </Frame>
  </Step>

  <Step title="Fill Up The Credentials">
    This would redirect you to the Login/Sign Up screen. Here, you can choose either to click on the **Sign Up** option or the **Continue with Google** option.

    <Frame>
      <img alt="Sign up screen" />
    </Frame>

    <Info>
      **If the 'Sign Up' option is selected:**

      * A confirmation email would be sent to the registered email address
      * Be sure to check the Socials/Promotion page if the email is not visible on your Primary list
      * Click on the Verification link to proceed

      **If the 'Continue with Google' option is selected:**

      * Choose one of the active emails to proceed
    </Info>
  </Step>

  <Step title="Domain Creation">
    Give your account a domain name that suits your preference. In case the suggested name is not accepted, try using a different name.

    <Frame>
      <img alt="Domain creation screen" />
    </Frame>
  </Step>

  <Step title="Project Creation and Dashboard">
    Once domain is created, you would be redirected to create project page. Give a suitable name to your project and you can get started right away!

    <Frame>
      <img alt="Project creation screen" />
    </Frame>

    For more, check out the video tutorial.
  </Step>
</Steps>

<Note>
  For further assistance contact **[support@tensormatics.com](mailto:support@tensormatics.com)**
</Note>


# Getting Started with SDK
Source: https://docs.labellerr.com/labellerr/documentation-labellerr/sdk/sdk-documentation

Learn how to install and initialize the Labellerr SDK, a Python library for seamless interaction with the Labellerr platform to manage data annotations, projects, and exports.

<Warning>This page has been moved! Please visit the updated version at: **[Getting Started with SDK](/sdk/getting-started)**</Warning>

## Introduction

The **Labellerr SDK** is a Python library designed to make interaction with the Labellerr platform simple and efficient. With this SDK, you can manage data annotations, projects, and exports seamlessly in your applications.

This documentation will guide you through installing the SDK, understanding its core functionalities, and handling common errors.

Prefer a runnable notebook with sample data and ready-made cells? [Open the end-to-end SDK cookbook in Google Colab](https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/SDK%20Tutorials/Labellerr_SDK_End_to_End_Annotation_Pipeline.ipynb)

***

## Installation

To install the Labellerr SDK, use the following command:

<CodeBlock lang="bash" title="Install Labellerr SDK">
  pip install git+[https://github.com/Labellerr/SDKPython.git](https://github.com/Labellerr/SDKPython.git)
</CodeBlock>

***

## Getting Started

#### Obtaining `api_keys` and `client_id`:

**To obtain your api\_keys and client\_id, Pro and Enterprise plan users can contact Labellerr support. If you are on a free plan, you can request them by emailing** `**support@tensormatics.com**`**.**

Once installed, you can start by importing and initializing the `LabellerrClient` and `LabellerrError`. This client will handle all communication with the Labellerr platform.

### Example Client initiation:

<CodeBlock lang="python" title="Client Initialization">
  from labellerr.client import LabellerrClient
  from labellerr.exceptions import LabellerrError

  # Initialize the client with your API credentials

  api\_key = "your-api-key"
  api\_secret = "your-api-secret"
  client\_id = "your-client-id"
  project\_id = 'your-project-id'

  # choose scope from SCOPE\_LIST=\['project','client','public']

  scope = 'client'
  email = "your-email-id"

  client = LabellerrClient(api\_key, api\_secret)
</CodeBlock>

Replace `'your_api_key', 'your-email-id', 'client_id', 'project_id'` and `'your-api-secret'` with your actual credentials provided by Labellerr.


# Product Updates 2025
Source: https://docs.labellerr.com/product-releases/2025

Stay up to date with the latest Labellerr product releases and feature updates

Welcome to Labellerr's 2025 Product Updates! This year has been transformative for our platform, with major releases focused on AI-powered automation, precision editing tools, and enhanced collaboration features.

<CardGroup>
  <Card title="March 2025" icon="wand-magic-sparkles" href="/product-releases/march-2025">
    Advanced precision editing tools and SAM 2 integration for video object tracking
  </Card>

  <Card title="April 2025" icon="robot" href="/product-releases/april-2025">
    GenAI Classification Agent, Natural Language Search, and Multi-Modal AI support
  </Card>

  <Card title="May 2025" icon="rocket" href="/product-releases/may-2025">
    Redesigned workflow with new landing page, datasets section, and API keys management
  </Card>

  <Card title="June-July 2025" icon="filter" href="/product-releases/june-july-2025">
    Advanced file search, polyline annotations, and file similarity detection
  </Card>

  <Card title="August 2025" icon="video" href="/product-releases/august-2025">
    Frame-by-frame precision in video annotation and enhanced SAM2 tracking
  </Card>

  <Card title="September 2025" icon="bolt" href="/product-releases/september-2025">
    Smarter project indexing, polyline grouping, and required object annotations
  </Card>

  <Card title="October 2025" icon="layer-group" href="/product-releases/october-2025">
    File tagging, full-screen view mode, SDK automation, and canvas shortcuts
  </Card>

  <Card title="November 2025" icon="sparkles" href="/product-releases/november-2025">
    SAM3 integration for similar object labeling, file preview strips, polygon splitting, and SDK model training
  </Card>

  <Card title="December 2025" icon="comments" href="/product-releases/december-2025">
    MCP Server for conversational AI control, local SAM3 pipeline, selective user import, and video pre-annotations
  </Card>
</CardGroup>


# Product Updates 2026
Source: https://docs.labellerr.com/product-releases/2026

Stay up to date with the latest Labellerr product releases and feature updates

Welcome to Labellerr's 2026 Product Updates! This year has been transformative for our platform, with major releases focused on AI-powered automation, smarter annotation workflows, and enhanced collaboration features.

<CardGroup>
  <Card title="August 2026" icon="calendar-plus" href="/product-releases/aug-2026">
    Workspace-level user management, hear audio while annotating, SSO enforcement & IP allowlisting
  </Card>

  <Card title="June 2026" icon="calendar-plus" href="/product-releases/june-2026">
    Event tagging master control panel and SAM 3 visual, click, and text-based segmentation
  </Card>

  <Card title="May 2026" icon="calendar-days" href="/product-releases/may-2026">
    Hand & pose tracking, attribute filtering, and template redesign
  </Card>

  <Card title="April 2026" icon="calendar-check" href="/product-releases/april-2026">
    Auto-bordering, view mode actions, improved UI/UX, and larger video support
  </Card>

  <Card title="March 2026" icon="wand-magic-sparkles" href="/product-releases/march-2026">
    UI/UX updates, keypoint skeletons, template versioning & workspace guidelines
  </Card>
</CardGroup>


# April 2025 - Product Updates
Source: https://docs.labellerr.com/product-releases/april-2025

AI-powered automation and intelligent workflow optimization with GenAI

This April, we are excited to introduce major updates that focus on AI-powered automation and intelligent workflow optimization. Our latest release brings powerful Generative AI (GenAI) capabilities to all data types on our platform. We also added new features to improve team collaboration and communication. These updates help you work faster, smarter, and more efficiently.

## Major Feature Releases

### Classification Agent (GenAI Integration)

<iframe title="Classification Agent" />

We are thrilled to launch our new Classification Agent, an AI assistant that automates classification tasks across all supported question types. This powerful tool helps you handle large-scale projects with ease.

**Key Features:**

* **Batch Processing**: Automatically classify large batches of images (e.g., thousands of vehicle photos) in just a few clicks
* **Save Templates**: Save classification settings as templates to quickly replicate projects
* **Human-in-the-Loop Review**: Built-in review step to verify AI classifications and ensure top quality
* **Seamless Integration**: Works perfectly with existing Labellerr workflows
* **Enterprise-Ready**: Designed to handle enterprise-level classification tasks at any scale

***

### Natural Language Search

<iframe title="Natural Language Search" />

We have implemented a new, AI-powered way to find your datasets. You no longer need to remember exact file names to find what you are looking for.

**Key Features:**

* **Prompt-Based Search**: Type what you need in plain English (e.g., "find all images of cars at night")
* **Intelligent Recommendations**: AI recommends datasets you might find useful based on your query
* **Enhanced Experience**: Natural language processing makes finding and discovering datasets faster and more intuitive

***

### GenAI Multi-Modal Support

<iframe title="GenAI Multi-Modal Support" />

We have expanded our GenAI capabilities to support all major data types. Now, you can handle all your AI tasks on a single platform without switching between different tools.

**Supported Data Types:**

* **Audio**: Fast and accurate audio transcription and translation services
* **Image**: Classify images using contextual prompts for more precise results
* **Video**: Automatically generate video summaries and relevant tags
* **Text**: Summarize long documents and identify key entities and information

***

## Collaboration and Communication Enhancements

<iframe title="Collaboration Enhancements" />

We also improved our tools for team collaboration to make communication faster and more organized.

### Enhanced Notification System

Our new notification system helps your team stay connected and resolve issues quickly.

**Core Features:**

* **Direct Tagging**: Tag team members directly within the annotation interface using the @ symbol
* **Real-Time Alerts**: Tagged members receive instant notifications with a visual indicator
* **Organized Messages**: Use filtering options to manage your messages and stay organized
* **Jump to Label**: Click on a notification to jump directly to the specific label being discussed

### Remarks Tags System

We have enhanced our remarks system to provide a more structured way to give feedback.

**Key Features:**

* **Categorized Feedback**: Use predefined tags like "Mistake" or "Suggestion" to categorize your feedback
* **Streamlined Communication**: Creates a clear and organized feedback loop for annotation projects
* **Better Quality Assurance**: Easily identify and track mistakes and suggestions to improve work quality

***

## Conclusion

We are committed to continuously improving Labellerr to meet your evolving needs. These updates bring powerful AI automation, smarter workflows, and better team collaboration to help you label data faster and with higher quality. We invite you to explore these new features and share your feedback so we can build an even better platform together. Stay tuned for more exciting innovations coming soon!


# April 2026 - Product Updates
Source: https://docs.labellerr.com/product-releases/april-2026

Improvements across annotation precision, review workflows, usability, and video handling.

At Labellerr, we continue improving annotation workflows to help AI teams work faster, maintain quality, and scale operations more efficiently. This latest update introduces improvements across annotation precision, review workflows, usability, and video handling.

Here’s what’s new.

## 1. Auto-Bordering for Overlapping Annotations

<iframe title="Auto-Bordering for Overlapping Annotations" />

Handling overlapping objects is a common challenge in computer vision annotation workflows, especially in dense industrial or manufacturing datasets. With this update, overlapping annotations can now share common annotation points during auto-bordering.

Previously, annotators often had to manually create separate bordering points even when objects shared boundaries. The new enhancement reduces repetitive adjustments and helps create cleaner polygon annotations.

**Benefits:**

* Faster polygon annotation workflows
* Better boundary consistency
* Reduced manual correction effort
* Improved accuracy in dense scenes

## 2. Accept or Reject Files Directly from View Mode

<iframe title="Accept or Reject Files Directly from View Mode" />

Admins can now accept or reject files directly from view mode without switching between interfaces. This simplifies the review process and helps teams manage large annotation projects more efficiently.

Instead of navigating across multiple workflow stages, reviewers can now make validation decisions while reviewing the file itself. This enhancement is especially valuable for enterprise annotation operations handling large datasets and rapid review cycles.

**Benefits:**

* Faster QA workflows
* Reduced navigation overhead
* Improved review efficiency
* Smoother project management at scale

## 3. Edit Files in View Mode

<iframe title="Edit Files in View Mode" />

View mode now also supports direct editing and annotation. Users can make corrections or update annotations without leaving the review interface, creating a more seamless workflow experience.

This reduces interruptions during QA and speeds up annotation refinement cycles. This is especially useful for projects involving iterative reviews and precise annotation adjustments.

**Benefits:**

* Faster annotation corrections
* Reduced workflow switching
* Improved reviewer productivity
* Better collaboration between annotation and QA teams

## 4. Improved UI/UX for Annotation Attributes

<iframe title="Improved UI/UX for Annotation Attributes" />

We’ve enhanced the experience of adding attributes to annotations. Users can now continue interacting with the image while selecting attributes, making the workflow smoother and less disruptive.

This helps annotators maintain visual focus during complex labeling tasks. The update is especially useful for multi-attribute and fine-grained annotation workflows.

**Benefits:**

* Better annotation flow
* Reduced interruptions
* Faster attribute assignment
* Improved usability for complex datasets

## 5. Support for Larger Video Files in Annotation Projects

<iframe title="Support for Larger Video Files in Annotation Projects" />

Annotation projects now support video uploads between 100MB and 500MB. This allows teams to work with larger and more realistic video datasets without excessive preprocessing or file splitting.

**Benefits:**

* Support for longer video sequences
* Better context preservation across frames
* Reduced preprocessing effort
* Improved support for enterprise video workflows

## How These Updates Help You

* **Greater Precision:** Auto-bordering for overlapping annotations creates cleaner polygons and improves accuracy in dense scenes.
* **Faster Reviews:** Accepting, rejecting, and editing files directly from view mode speeds up QA and reduces navigation overhead.
* **Cleaner Experience:** Improved UI/UX for attributes allows annotators to maintain visual focus without disruptive interruptions.
* **Better Scalability:** Support for larger video files lets enterprise teams handle longer sequences and preserve context across frames without excessive preprocessing.

## Conclusive Thoughts

These updates are designed to improve efficiency, usability, and scalability across enterprise annotation pipelines. From smarter overlapping annotations and streamlined review actions to improved attribute workflows and expanded video support, each enhancement focuses on reducing operational friction while maintaining annotation quality.

At Labellerr, we’ll continue building tools that help AI teams manage complex data annotation workflows with greater speed and precision.

**The Labellerr Team**

## FAQs

**Q1. How does the new auto-bordering work for overlapping annotations?**

The new auto-bordering feature allows overlapping annotations to share common annotation points. This means annotators no longer have to manually create separate bordering points when objects share boundaries, reducing repetitive adjustments and creating cleaner polygons.

**Q2. Can I edit annotations directly during the review process?**

Yes. With this update, view mode supports both accepting/rejecting files and direct editing. Reviewers can make corrections or update annotations without leaving the review interface, which speeds up the refinement cycle.

**Q3. What is the new file size limit for video uploads?**

Annotation projects now support video uploads between 100MB and 500MB. This allows you to work with longer video sequences and preserve context without needing to split files.


# August 2026 - Product Updates
Source: https://docs.labellerr.com/product-releases/aug-2026

Workspace-level user management, audio support in video annotation, optimized video streaming, SSO enforcement, IP allowlisting, and a unified timeline for annotated objects.

At Labellerr, we continue to streamline data annotation pipelines to help AI teams annotate faster and with greater accuracy. This month, we are excited to release major improvements to workspace management, video annotation workflows, and enterprise security.

Here's what's new.

***

## 1. Workspace-Level User Management

<iframe title="Workspace-Level User Management" />

Previously, users could only be added to a single annotation project at a time. Now you can manage users at the workspace level, where each workspace consists of multiple ongoing annotation projects.

**Key Capabilities:**

* **Workspace-Level Access:** Add and manage users once at the workspace level instead of per project.
* **Project-Wide Coverage:** New users are available across all annotation projects within the workspace.
* **Simplified Onboarding:** Onboard annotators, reviewers, and managers without repeating project-by-project setup.

***

## 2. Enforced SSO Sign-In for Every Workspace Member

<iframe title="Enforced SSO Sign-In for Every Workspace Member" />

Enforce Single Sign-On (SSO) authentication for all members of your Labellerr workspace. Currently supported identity providers are Google Workspace and Okta.

**Key Capabilities:**

* **Forced SSO Login:** All workspace members must authenticate through your identity provider.
* **Supported Providers:** Google Workspace and Okta.
* **Centralized Identity Management:** Align Labellerr access with your organization's SSO policies.

Learn more in our [SSO enforcement guide](/enterprise-security/sso-enforcement).

***

## 3. Restrict Workspace Access to Approved IPs

<iframe title="Restrict Workspace Access to Approved IPs" />

Restrict access to your Labellerr workspace by allowing only specific IP addresses.

**Key Capabilities:**

* **Restricted Access:** Only requests from allowlisted IP addresses can access the workspace.
* **Enhanced Security:** Block unauthorized access from unknown networks.
* **Granular Control:** Define exactly which IPs can reach your workspace.

Learn more in our [IP allowlisting guide](/enterprise-security/ip-allowlisting).

***

## 4. All Object Segments on One Timeline

<iframe title="All Object Segments on One Timeline" />

Previously, each annotated object in a video had its own separate timeline. Now there is a single timeline on which every object is overlaid, making it easy for annotators to see all annotation segments at a glance.

**Key Capabilities:**

* **Single Overlay Timeline:** All annotated objects are displayed on one timeline.
* **Segment Visibility:** See how long each annotation segment is and where it occurs.
* **Easier Video QA:** Compare and review object segments without switching between timelines.

***

## 5. Lag-Free Video Streaming

Video annotation used to suffer from latency and slow playback while streaming frames. Video streaming has been fully optimized, eliminating playback lag when annotating frames.

**Key Capabilities:**

* **Instant Playback:** No more latency when playing videos during annotation.
* **Smooth Frame Scrubbing:** Navigate and annotate frames without buffering delays.
* **Faster Workflows:** Spend time annotating instead of waiting for video to load.

***

## 6. Hear Audio While Annotating Videos

Previously, audio was stripped from videos during dataset creation, leaving annotators with silent footage. Video audio is now retained and can be heard while annotating.

**Key Capabilities:**

* **Audio Retention:** Video files keep their audio track through dataset creation.
* **In-Player Playback:** Listen to audio directly in the annotation player for richer context.
* **Better Annotation Context:** Use audio cues to make more accurate decisions while labeling.

***

## Why It Matters

These updates focus on three key pillars of annotation efficiency:

1. **Streamlined Administration:** Manage users at the workspace level and onboard teams faster across projects.
2. **Better Video Annotation Experience:** Retained audio, latency-free streaming, and a unified timeline make video labeling faster and more accurate.
3. **Enterprise-Grade Security:** SSO enforcement and IP allowlisting give you control over who can access your workspace.

Together, these enhancements help computer vision teams accelerate dataset creation while maintaining the highest quality and security standards.

***

## FAQs

**Q1. Can I still add users to individual projects?**
Yes, project-level user management remains available. Workspace-level management simply adds a faster way to onboard users across multiple projects at once.

**Q2. Which identity providers are supported for SSO enforcement?**
Google Workspace and Okta are currently supported.

**Q3. How does the unified timeline help with video QA?**
All annotated objects are overlaid on a single timeline, so reviewers can instantly see where and how long each annotation segment is, without toggling between multiple per-object timelines.


# August 2025 - Product Updates
Source: https://docs.labellerr.com/product-releases/august-2025

Frame-by-frame precision in video annotation, SAM2 tracking, and enhanced visibility filters

This month's release focuses on improving video annotation workflows, enhancing SAM2 tracking, and adding finer control for editing. These updates are designed to make annotation more accurate, efficient, and user-friendly for both annotators and reviewers.

## 1. Frame-by-Frame Precision in Video Annotation

<iframe title="Frame-by-Frame Precision in Video Annotation" />

The video player has been upgraded to ensure frame-level accuracy and a smoother annotation workflow. This update addresses sync issues caused by time-based playback and provides a more reliable environment for video annotation. No more labels drifting off-sync. With frame-accurate playback, annotations stick exactly where they should, which means cleaner training data and fewer noisy samples downstream.

**Key Improvements:**

* Frame-based rendering powered by a backend streaming API
* Accurate annotation sync with frames during playback and navigation
* Next and Previous frame controls for precise navigation
* Manual frame seeking with exact frame display
* Smooth playback at correct FPS using sequential frames
* Error handling with retry support and fallback display
* Loading indicators to manage network delays

***

## 2. Review Annotations Faster with Timeline Keyframes

<iframe title="Review Annotations Faster with Timeline Keyframes" />

Keyframes can now be created, managed, and reviewed directly on the video timeline. This makes it easier for annotators to label efficiently and for reviewers to validate annotation quality at a glance.

**Key Improvements:**

* Visual pins displayed on the timeline for all keyframes in the active track or layer
* Hover tooltips showing timestamp and frame number for each keyframe
* Click on any pin to instantly jump the player to that frame
* Add keyframes using a dedicated button, context menu, or keyboard shortcut (K)
* Delete keyframes with the Delete key or context menu options
* Popover list provided for overlapping pins to ensure precise selection
* Full API integration for fetching, creating, and deleting keyframes with smooth UI updates
* Keyboard accessibility support with focusable pins and shortcuts
* Optimized rendering for hundreds or thousands of pins without lag

This update reduces cognitive overhead by providing a faster way to navigate annotations and ensures reviewers can easily assess annotation completeness and accuracy.

***

## 3. Track Multiple Objects in One SAM2 Run

<iframe title="Track Multiple Objects in One SAM2 Run" />

Instead of running SAM2 separately for each object, you can now track all selected annotations in a single job. This dramatically speeds up labeling while lowering compute costs.

**Key Improvements:**

* Magic wand beside Objects to select timelines that contain SAM prompts
* Single job execution for all chosen timelines in one run
* In-app and email notifications on completion or failure
* Job detail view with status and progress information
* Option to cancel an active job
* Option to keep or discard partial progress, with discard as the default
* Test coverage for backend and UI flows

***

## 4. Apply SAM2 Reliably to Bounding Box Workflows

We resolved errors that appeared during SAM2 runs on bounding box annotations, ensuring a stable and predictable experience for annotators. With this fix, users can confidently create bounding box labels and run SAM2 without interruptions.

**Key Improvements:**

* Stability fixes for SAM2 execution on bounding box annotations
* Error-free integration between bounding box labeling and SAM2 tracking
* More reliable experience when creating projects from new datasets
* Tested and validated in QA environment with consistent results

This enhancement makes bounding box workflows smoother and ensures SAM2 can be applied seamlessly during annotation.

***

## 5. Enhance Visibility During Annotation with Non-Destructive Filters

Brightness and contrast filters are now built into the labeling interface, helping annotators see details more clearly without altering the source data. This is especially useful for low-light, medical, or noisy datasets.

**Key Improvements:**

* Reliable controls for brightness and contrast across images and video frames
* Non-destructive adjustments that preserve the source asset
* Per-frame and continuous playback rendering with consistent results
* Reset to default and quick compare to view changes instantly
* Persistent settings during a session for smoother multi-frame work
* Keyboard support for fine-step adjustments
* Clear tooltips and accessible labels for each control
* Performance tuning for smooth scrubbing and playback while filters are active

***

## How These Updates Help You

* **Higher Accuracy**: Frame-based video playback keeps annotations in perfect sync
* **Faster Workflows**: Single SAM2 runs save time and resources
* **Better Visibility**: Keyframes, markers, and filters improve clarity
* **Smarter Reviews**: Reviewers can quickly validate annotation quality with fewer clicks

***

## What's Next

We are preparing additional features such as advanced file management, extended automation support, and improved object detection agents.

***

## Wrapping Up

The August 2025 release delivers precise frame rendering, smarter SAM2 tracking, intuitive keyframe management, stable bounding box workflows, and improved annotation filters. These updates create a faster, more reliable, and more productive annotation environment.

We encourage you to explore the new features and share your feedback with us.

**Labellerr Team**


# December 2025 - Product Updates
Source: https://docs.labellerr.com/product-releases/december-2025

MCP Server launch, SAM3 local pipeline, selective user import, incremental exports, and video pre-annotations

## Happy New Year 2026! 🎉

Thank you for your incredible support throughout 2025! We're back to work with renewed energy and excitement to make 2026 even better. As we close out the year, we're thrilled to share December's product updates, featuring groundbreaking conversational AI integrations, local auto-labeling pipelines, and powerful SDK enhancements that put more control in your hands.

Let's dive into what we've built for you this month.

## 1. Labellerr MCP Server: Control Labellerr with Natural Language

We launched the **Labellerr MCP Server**, which enables you to use Labellerr through AI assistants such as Claude Desktop and Cursor using natural language. Built on the **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro)**, it provides a structured way to manage datasets, projects, annotations, and exports through conversational workflows. Instead of manually clicking through UIs or writing API scripts, you can simply ask your AI assistant to create projects, upload datasets, or export annotations, and it happens automatically.

**Example Workflows:**

```
"Create a new image annotation project called 'Traffic Detection' with a dataset from my local folder"

"Export all accepted annotations from project X in COCO JSON format"

"Show me the progress statistics for my current project"

"Upload pre-annotations to project Y from this JSON file"
```

**Key Improvements:**

* Natural language control of Labellerr inside Claude Desktop and Cursor through MCP integration
* Twenty-three tools organized across project management, dataset management, annotation operations, monitoring, and query workflows
* End-to-end project creation through a guided workflow covering dataset creation, template setup, and project linking
* Support for multiple data types including images, videos, audio, documents, and text
* Export support for common formats such as Labellerr JSON, COCO JSON, CSV, and segmentation masks

**Documentation:** [Labellerr MCP Server Guide](https://docs.labellerr.com/sdk/mcp-server)

***

## 2. SAM3 Local Auto-Labeling Pipeline with Labellerr

<iframe title="SAM3 Local Pipeline Demo" />

After the launch of SAM3, there has been a lot of discussion around whether auto-labeling is still relevant. The reality is simpler: **Auto-labeling is not dead**. What matters is **where and how it runs**. We have enabled a **fully local SAM3 auto-labeling pipeline** that runs on your own system, without any paid inference or cloud dependency. You can generate high-quality pre-annotations locally and then bring them into Labellerr for review and refinement. This approach gives teams the best of both worlds: fast, AI-powered pre-labeling without cloud dependencies, combined with Labellerr's powerful review and refinement tools.

**Key Improvements:**

* Run SAM3 locally on your own image folders with zero inference costs
* Use multiple class text prompts in a single run for batch processing
* Generate COCO JSON pre-annotations directly from SAM3
* Upload pre-annotations into Labellerr using the SDK for human review
* Complete data privacy as images never leave your infrastructure

**GitHub Repository:** [SAM3 Batch Inference Pipeline](https://github.com/Labellerr/SAM3_Batch_Inference)

***

## 3. Selective User Import from Projects

<iframe title="Selective User Import Demo" />

Users can now **selectively import specific users** from an existing project instead of importing all members at once. This improvement gives teams finer control over project access and avoids clutter from unwanted users. Instead of inheriting entire project rosters, you can now choose exactly which annotators, reviewers, or managers to add, with their roles and permissions preserved. This feature streamlines team management and ensures that project membership remains intentional and organized.

**Key Improvements:**

* Choose individual users when importing from another project instead of importing all members
* Prevents automatic addition of all users from the source project
* Faster and more controlled project setup for targeted collaboration
* Reduced risk of assigning unintended access or roles
* Improved usability on the User Listing page with clearer selection flow

***

## 4. Incremental File Export via SDK Using Timestamps

Developers can now perform **incremental file exports** through the SDK by specifying a UNIX timestamp. This ensures that only files updated on or after the given timestamp are exported, reducing unnecessary processing and improving efficiency for recurring data pipelines. Instead of exporting entire projects every time, subsequent exports can use the previous export's timestamp for true incremental sync, making it ideal for daily data syncs, continuous integration workflows, and automated backup systems.

**Key Improvements:**

* Timestamp-based export requests using a UNIX timestamp parameter
* Exports return only files updated on or after the specified time
* Improved efficiency by avoiding reprocessing of unchanged files
* SDK integration of the list exports capability to view export history per project
* Better support for scheduled and automated data sync workflows

***

## 5. Video Pre-Annotations Upload via SDK

Users can now **upload pre-annotations for video projects**, enabling faster annotation and review workflows. This extends existing pre-label upload capabilities from image projects to video-based datasets. Instead of manually annotating videos from scratch, teams can now upload predictions from object tracking models, migrate annotations from other platforms, or bootstrap video projects with AI-generated keyframe annotations. This feature unlocks video-first workflows and makes Labellerr a comprehensive solution for both image and video annotation at scale.

**Key Improvements:**

* Support for uploading pre-annotations specifically for video projects via SDK
* Defined and standardized pre-annotation payload structure for video data with frame-by-frame support
* Ability to upload annotations directly into files in the unlabeled state
* Seamless SDK integration to allow programmatic pre-annotation uploads
* Improved review speed by eliminating the need to annotate from scratch

***

## How These Updates Help You

* **Conversational Control**: MCP Server integration lets you manage entire annotation workflows through natural language in Claude or Cursor
* **Cost-Effective Auto-Labeling**: Run SAM3 locally without inference fees while maintaining full data privacy
* **Granular Access Control**: Selective user import ensures clean, intentional project team composition
* **Efficient Data Pipelines**: Incremental exports save bandwidth and compute by processing only changed files
* **Video Workflow Acceleration**: Pre-annotation upload for videos eliminates manual frame-by-frame labeling

***

## What's Next

As we head into 2026, we're working on:

* Enhanced multi-modal annotation support
* Advanced workflow automation features
* Deeper MLOps integrations for training and deployment
* Performance optimizations for large-scale enterprise projects
* Expanded AI-assisted annotation capabilities across all data types

***

## Wrapping Up

December 2025 marks a significant milestone in making Labellerr more accessible, efficient, and powerful. The MCP Server brings conversational AI to annotation workflows, the local SAM3 pipeline democratizes auto-labeling, and our SDK enhancements provide production-grade tools for incremental exports and video pre-annotations.

These updates reflect our commitment to empowering teams with flexible, cost-effective tools that adapt to your infrastructure and workflow requirements. Whether you're a startup building your first dataset or an enterprise managing millions of annotations, Labellerr scales with you.

Thank you for being part of our journey in 2025. Here's to an even more innovative 2026!

**The Labellerr Team**

***

## FAQs

<AccordionGroup>
  <Accordion title="Q1. What AI assistants support the Labellerr MCP Server?">
    Currently, the MCP Server works with **Claude Desktop** and **Cursor**. Both applications support the Model Context Protocol and can interact with Labellerr through natural language commands. We're monitoring the MCP ecosystem and will add support for additional assistants as they adopt the protocol.
  </Accordion>

  <Accordion title="Q2. Do I need a GPU to run the local SAM3 pipeline?">
    While **a CUDA-capable GPU is highly recommended** for faster inference, SAM3 can technically run on CPU. However, processing times will be significantly longer. For production workflows, we recommend using a system with at least an NVIDIA GPU with 8GB+ VRAM for efficient batch processing.
  </Accordion>

  <Accordion title="Q3. Can I use incremental exports with formats other than COCO JSON?">
    Yes, **incremental exports work with all supported formats**: Labellerr JSON, COCO JSON, CSV, and segmentation masks (PNG). The timestamp filtering is applied before export generation, so only files modified after the specified timestamp are included regardless of output format.
  </Accordion>

  <Accordion title="Q4. How does selective user import handle role permissions?">
    When you import users selectively, their **roles and permissions are preserved from the source project**. For example, if User A is an annotator in the source project, they'll be added as an annotator in the destination project. You can modify their role after import if needed through the User Management interface.
  </Accordion>
</AccordionGroup>


# June 2026 - Product Updates
Source: https://docs.labellerr.com/product-releases/june-2026

Introducing Master Control for event tagging and full SAM 3 support with visual, click, and text-based prompting.

At Labellerr, we continue to streamline data annotation pipelines to help AI teams annotate faster and with greater accuracy. This month, we are excited to release major improvements to video event tagging workflows and full integration of the Segment Anything Model 3 (SAM 3).

Here’s what’s new.

***

## 1. Master Control Panel for Event Tagging Annotation

<iframe title="Master Control for Event Tagging" />

Managing event annotations across video timelines can be challenging when events span multiple frames and require precise boundary adjustments. Labellerr’s new **Master Control for Event Tagging** provides a unified control panel at the frame level to simplify this process.

**Key Capabilities:**

* **Centralized Editing:** Update and modify event tagging annotations directly from a single interface.
* **Boundary Precision:** Easily correct event boundaries by adjusting start and end frames.
* **Keyframe Review:** Verify active events present in any selected video keyframe instantly.
* **Reduced Navigation:** Review annotations without toggling between multiple screens.

***

## 2. Visual Prompt Auto-Labeling with SAM 3

<iframe title="Visual Prompt Auto-Labeling with SAM 3" />

With full support for **SAM 3 (Segment Anything Model 3)**, you can now use existing annotations as visual prompts to automatically segment similar objects across the same image.

**How to Use:**

1. Draw a bounding box or polygon annotation on a reference object.
2. Select the annotation and press **I** on your keyboard.
3. SAM 3 automatically identifies similar visual signatures and generates segmentation masks for all matching instances in the canvas.

**Benefits:**

* Saves hours of manual tracing on repetitive items (e.g., vehicles, shelf products, tools).
* Ensures boundary and mask quality consistency.

***

## 3. One-Click Similar Object Annotation

<iframe title="One-Click Similar Object Annotation" />

For even faster workflows, you can annotate all visually similar objects with a single click.

**How to Use:**

1. Select **SAM 3** from the model selection tab.
2. Click directly on a target object in the image.
3. The platform automatically detects, matches, and annotates all similar instances in a single step.

**Benefits:**

* Drastically speeds up dense scene labeling.
* Minimizes annotator fatigue during large-scale instance segmentation.

***

## 4. Text Prompt Segmentation

<iframe title="Text Prompt Segmentation" />

SAM 3 now supports text-driven object annotation inside Labellerr, allowing you to label objects by typing their semantic name.

**How to Use:**

1. Select **SAM 3** and choose the **Text Prompt** option.
2. Enter the name of the object category (e.g., *"dice"*, *"car"*, *"furniture"*).
3. The platform automatically localizes and segments the target objects.

**Benefits:**

* Highly flexible for datasets with clearly defined semantic categories.
* Eliminates manual clicking/drawing by relying on text-to-segmentation models.

***

## Why It Matters

These updates focus on two key pillars of annotation efficiency:

1. **Model-Assisted Speedup:** Leverage state-of-the-art zero-shot segmentation with SAM 3 to label multiple instances in seconds.
2. **Centralized Video Controls:** Streamline temporal QA and event verification directly on the video timeline.

Together, these enhancements help computer vision teams accelerate dataset creation while maintaining the highest quality standards.

***

## FAQs

**Q1. How does the new Master Control help with video QA?**
It displays all active events on a frame-by-frame basis in a centralized panel, allowing reviewers to correct temporal boundaries (start/end frames) and edit metadata without opening multiple side panels.

**Q2. What is the keyboard shortcut to trigger visual prompt labeling?**
Select an existing annotation and press **I** on your keyboard to trigger SAM 3 to find and segment similar objects in the image.

**Q3. Can I use text prompt segmentation for custom objects?**
Yes, SAM 3's zero-shot capabilities allow it to segment a wide variety of common and custom objects based on standard English names.


# June-July 2025 - Product Updates
Source: https://docs.labellerr.com/product-releases/june-july-2025

Advanced file search, polyline annotations, and dataset management improvements

Our June-July 2025 update brings lots of improvements in image and video annotation experience, software latency, and some new features. These changes will help you work faster, stay organized, and get more done.

***

## Advanced File Search & Filtering

We've significantly enhanced our file search capabilities with powerful new filtering options:

<iframe title="Advanced File Search & Filtering" />

**Key Features:**

* **Smart Content Filtering**: Filter files based on objects detected within images (cars, bikes, people, or any other specific objects)
* **User Activity Tracking**: Filter files by the last user who updated them for better visibility into team collaboration
* **Classification & Attribute Filters**: Enhanced filtering by classifications and custom attributes
* **Advanced Combination Logic**: Mix and match multiple filter criteria to create sophisticated search queries

***

## Polyline Annotations (NEW)

![Polyline Annotation](https://storage.googleapis.com/labellerr-cdn/%201%20%20Product%20Update%20May%202025/polyline.webp)

We're excited to introduce polyline annotations - a new annotation type that expands your labeling capabilities.

**Versatile Use Cases:**

Perfect for annotating linear features like:

* Road lanes and traffic paths
* Power lines and cables
* Boundary lines and fences
* Sequential workflows or processes

**Enhanced Functionality:**

* Add custom attributes directly to polyline annotations for richer data capture
* Create smooth curves for more natural and precise representations
* Maintain full compatibility with existing annotation workflows

***

## Annotated File Similarity

![File Similarity](https://storage.googleapis.com/labellerr-cdn/%201%20%20Product%20Update%20May%202025/file-similarity.webp)

**Key Features:**

* **Intelligent Duplicate Detection**: Click the magnifying glass icon in the right panel of the labeling screen to check if your current file is similar to previously annotated files
* **Adjustable Similarity Threshold**: Fine-tune the similarity index from loose similarity detection to precise duplicate identification
* **Workflow Optimization**: Reduce redundant annotation work by leveraging existing labels from similar files

***

## Dataset Management Improvements

Flexible Dataset Operations: We've streamlined dataset deletion and detachment with intelligent workflow awareness:

* **Direct Deletion**: Delete datasets that aren't attached to any projects instantly
* **Smart Detachment**: For datasets attached to projects but with unlabeled files, easily detach and delete through the improved interface
* **Work-in-Progress Handling**: For datasets in progress or review stages, reassign files to "unlabeled" status via the three-dot menu, then detach and delete as needed

***

## Classification Enhancements

**Remarks Support**: Add detailed remarks to classification questions, providing additional context and guidance for your annotation team.

<Note>
  These updates continue our commitment to providing powerful, flexible annotation tools that scale with your project needs. Each feature has been designed to reduce manual work while increasing the precision and efficiency of your labeling workflows.
</Note>

***

## Conclusion

These updates make it easier, faster, and more accurate to work with your datasets. You can now search files with smarter filters, use polyline annotations for more labeling options, and manage datasets with less effort. The new tools help your team find what they need quickly, avoid repeating work, and add better details to annotations. With these changes, your team can work faster, work together better, and deliver high‑quality results.


# March 2025 - Product Updates
Source: https://docs.labellerr.com/product-releases/march-2025

Advanced precision editing tools and better collaboration features

March 2025 marked a big step for Labellerr. We introduced advanced precision editing tools and better collaboration features. These updates make image annotation faster and more accurate. Our new AI-powered editing tools help teams work up to 10 times faster while keeping high quality.

## Major Feature Releases

### 1. Magic Editor Enhancement

<iframe title="Magic Editor Enhancement" />

Our new Magic Editor helps you refine image annotations at the pixel level. It fixes sharp edges and missing labels without disturbing your existing work.

**Key Features:**

* Make smooth boundary corrections using simple keyboard shortcuts
* Works perfectly with SAM's one-dot labeling feature for better precision
* Easily merge unlabeled areas by moving keypoints

This tool is very useful in retail for product outlining, in medical imaging, and for any object detection task where precision matters. It saves you time by removing the need to manually drag keypoints, all while keeping your annotation shapes perfect.

***

### 2. Precision Masking and Boundary Tools

<iframe title="Precision Masking and Boundary Tools" />

We also released new Precision Masking and Boundary Tools. These tools use a superpixel segmentation system to automatically group pixels and create masks for you.

**Key Features:**

* Create high-resolution masks without drawing them by hand
* Improve accuracy for irregular and complex shapes
* Fine control over object boundaries

**Use Cases:**

* **Fashion Industry**: Analyze fabric patterns and segment garments
* **Medical Imaging**: Create precise segmentations of tumors and organs
* **Automotive**: Annotate vehicle parts for autonomous driving applications

***

### 3. Advanced Editing Suite: Polygon Eraser & CLIP Mode

**Polygon Eraser:**

<iframe title="Polygon Eraser" />

* Selectively remove parts of your annotations with precision
* Adjust keypoints to create perfect polygon shapes
* Integrates smoothly with existing SAM annotations

**CLIP Mode:**

<iframe title="CLIP Mode" />

* Automatically refines boundaries and fixes overlapping areas in seconds
* Provides precise segmentation without manual keypoint stretching
* Works across medical imaging, autonomous driving, retail, and agriculture

***

### 4. SAM 2 Integration for Video Object Tracking

<iframe title="SAM 2 Integration for Video Object Tracking" />

We integrated Meta's Segment Anything Model 2 (SAM 2) directly into our video annotation platform. This update brings powerful AI-assisted object tracking to your workflows, making video annotation faster and more accurate than ever before.

**Key Benefits:**

* **Work Up to 10x Faster**: Automate tedious frame-by-frame annotation
* **Improve Accuracy**: SAM 2 captures fine details and handles moving objects smoothly
* **Simplify Your Workflow**: Intuitive process makes advanced object tracking accessible to everyone

***

## Technical Improvements

* **Enhanced SAM Integration**: One-click object annotation with better accuracy across different object types
* **Seamless Workflow**: Smooth transitions between editing tools without losing context
* **Advanced Quality Control**: Quality checks ensure annotation accuracy throughout the editing process

These updates make Labellerr a leading platform for high-precision data labeling, helping teams work faster and better.


# March 2026 - Product Updates
Source: https://docs.labellerr.com/product-releases/march-2026

Redesigned UI/UX, keypoint skeleton annotation, template versioning, and workspace-level guidelines

This month's product updates bring a refreshed user experience, smarter AI-assisted labeling, and expanded annotation capabilities. From Labellerr's redesigned interface to keypoint annotation with skeleton building, template versioning, and workspace-level guidelines, these features are designed to accelerate annotation speed, reduce clicks, improve collaboration, and support more complex labeling workflows.

## 1. Labellerr UI/UX Updates

<iframe title="Labellerr UI/UX Updates" />

Labellerr brings a completely redesigned interface focused on reducing friction and improving annotation speed. Key interactions have been streamlined so annotators can stay in flow without unnecessary clicks or navigation.

**Key Improvements:**

* Quickly switch between AI Mode and Manual Mode using keyboard shortcuts, press A for AI Mode and M for Manual Mode after selecting any annotation
* Right-click context menu for quick access to actions
* Draggable attributes popup for a flexible, clutter-free workspace
* Selection tool for managing multiple annotations at once
* SAM-powered label refinement for faster and more accurate results
* Change labels instantly via right-click on any annotation, select Change Label from the context menu and pick the new label without leaving the canvas
* Auto-detect and generate polygons using SAM with bounding box input for higher precision

## 2. Keypoint Annotation

<iframe title="Keypoint Annotation and Skeleton Building" />

Keypoint annotation now extends beyond individual point marking, you can build fully connected skeletons directly within your workflow. This unlocks more advanced use cases across pose estimation, facial recognition, and skeletal mapping.

**Key Features:**

* Mark specific points of interest on images with high precision
* Connect keypoints to build and visualize complete skeletons
* Supports complex multi-point annotation structures
* Ideal for pose estimation and facial landmark detection
* Perfect for biomechanics, sports analytics, and human body mapping

## 3. Template Versioning

<iframe title="Template Versioning" />

Template versioning gives teams full control over their annotation templates across projects. You can now track changes, manage versions, and roll back when needed without disrupting active workflows.

**Key Features:**

* Create and save multiple versions of annotation templates
* Track changes across project timelines
* Revert to previous versions with ease
* View version history with creator name and timestamp
* Apply any specific version to a project directly from the annotation settings

## 4. Workspace Level Guidelines

A dedicated Guidelines section is now available at the workspace level, making it easier to create, version, and manage annotation standards across all projects from one central place. This eliminates inconsistency and keeps every annotator aligned without project-by-project setup.

**Key Features:**

* Dedicated Guidelines section accessible directly from the workspace sidebar
* Create and manage multiple guidelines with full version history
* Track number of questions, versions, and linked projects at a glance
* Filter and search guidelines by name or creator
* Link guidelines to multiple projects from a single place

## How These Updates Help You

* **Smarter Labeling:** AI-assisted tools and right-click label changing help annotators work faster with fewer interruptions and repetitive clicks.

* **Better Collaboration:** Workspace-level guidelines ensure every team member follows the same annotation standards across all projects.

* **Greater Precision:** Keypoint annotation with skeleton building enables accurate, structured marking for complex computer vision use cases.

* **Consistent templates:** Template versioning gives teams full control over annotation templates, reducing errors and maintaining quality across project cycles.

* **Cleaner Experience:** A redesigned UI with draggable popups, context menus, and selection tools makes the annotation workspace more intuitive and efficient.

## Conclusive Thoughts

This month's updates reflect our continued focus on making annotation faster, more precise, and easier to manage at scale. With a redesigned interface, skeleton-based keypoint annotation, centralized guidelines, and template versioning, teams can now build more consistent and efficient labeling workflows.

These improvements were shaped by real annotation challenges across computer vision, healthcare, and large-scale dataset operations. Each update is designed to reduce manual effort and bring more clarity and control into the labeling process.

As we prepare for the next set of releases, we remain focused on helping teams scale with confidence through smarter tools, cleaner UX, and deeper workflow automation.

**The Labellerr Team**

## FAQs

**Q1. How does the new right-click context menu improve the annotation workflow?**

The right-click context menu gives annotators instant access to key actions such as changing labels, editing attributes, assigning groups, and accessing AI tools, all without leaving the canvas or navigating through separate menus. This significantly reduces clicks and keeps the annotation flow uninterrupted.

**Q2. What is the difference between Template Versioning and Workspace Level Guidelines?**

Template Versioning allows teams to track, manage, and roll back changes to annotation templates across different versions, ensuring no work is lost during updates. Workspace Level Guidelines, on the other hand, provide a centralized place to define and share annotation standards that apply across all projects in a workspace, ensuring consistency without requiring per-project setup.

**Q3. How does keypoint annotation with skeleton building benefit computer vision workflows?**

By connecting individual keypoints into a fully linked skeleton structure, annotators can capture spatial relationships between points, essential for tasks like pose estimation, action recognition, and human body mapping. This removes the need for external tools and keeps the entire skeleton annotation workflow within Labellerr.

**Q4. Can I apply a specific template version to an existing project without affecting other projects?**

Yes. Template versioning is managed at the project level through the annotation settings. You can view all available versions of a guideline and apply any specific version to a project independently, without impacting other linked projects.


# May 2025 - Product Updates
Source: https://docs.labellerr.com/product-releases/may-2025

Completely redesigned workflow experience with new landing page, datasets section, and API keys management

You told us you wanted a faster and more organized way to manage your projects, datasets, and API keys. We listened. Today, we are excited to announce a completely redesigned workflow experience.

Our May 2025 update introduces a new landing page, a dedicated datasets section, and a secure place to manage your API keys and much more. These changes will help you work faster, stay organized, and get more done.

***

## Your New Landing Page

We redesigned the welcome experience to help you get started faster. The new landing page is your central hub for everything you need.

![Landing Page](https://storage.googleapis.com/labellerr-cdn/%201%20%20Product%20Update%20May%202025/landing-page.webp)

**What's new:**

* A quick video guide helps you learn the basics right away
* **Quick Actions**: Start working in seconds with one-click access to:
  * **Recently Opened**: Jump back into your most recent project
  * **Create Project**: Start a new annotation project for your data
  * **Create Dataset**: Create a new dataset without creating a new project
  * **New API Key**: Generate a new API key for the Labellerr SDK
  * **Explore Your Data**: Run smart queries using Labellerr AI on your datasets

![Side Panel](https://storage.googleapis.com/labellerr-cdn/%201%20%20Product%20Update%20May%202025/side-panel.webp)

**Easy Navigation**: The new sidebar helps you find what you need:

* Home
* Projects
* Datasets
* API Keys

***

## Dedicated Datasets Section

![Datasets Page](https://storage.googleapis.com/labellerr-cdn/%201%20%20Product%20Update%20May%202025/datasets-labellerr.webp)

We created a dedicated section just for managing your datasets. This makes it easier to keep your data organized and ready for your projects.

**Key features:**

* **Easy Upload**: Quickly upload and create new datasets
* **Smart Exploration**: Run smart queries to find the data you need
* **Smooth Integration**: Easily connect your datasets to new annotation projects

***

## API Keys Management

![API Keys Management](https://storage.googleapis.com/labellerr-cdn/%201%20%20Product%20Update%20May%202025/labellerr-api-keys.webp)

Security and ease of use are important. That's why we created a new section to manage your API keys.

**Improvements:**

* **Generate and Manage Keys**: Create, view, and delete API keys from one place
* **Clear Instructions**: Clear steps for using your keys with our SDK and API
* **Better Security**: Track key usage to help you stay secure

***

## Streamlined Project Management

![Projects](https://storage.googleapis.com/labellerr-cdn/%201%20%20Product%20Update%20May%202025/project-list.webp)

We made it easier to create and manage your annotation projects.

* **Faster Project Creation**: Start new annotation projects with fewer clicks
* **Resume Recent Projects**: Dashboard shows your recently opened projects so you can get back to work quickly
* **Better Organization**: Improved project navigation to help you find your work faster

***

## Enhanced Documentation and Learning

We put all our learning resources in one place so you can find help when you need it.

* **Quick Links**: Find our product documentation, SDK, blogs, and demos right from the dashboard
* **Product Updates**: Get the latest news and release notes
* **Book a Demo**: New users can easily schedule a demo with our team

***

## Usability and Performance

We made several improvements to make the tool faster and easier to use:

* **Faster Navigation**: The interface is snappier, so you can move between pages more quickly
* **Modern Look**: Updated icons, fonts, and colors for a fresh, clean design
* **Better Search**: Improved search and filtering in documentation and datasets
* **New Keyboard Shortcuts**: Speed up your work with shortcuts like copy-pasting annotations

***

## How These Updates Help You

These changes are designed to make your workflow more productive:

* **Faster Onboarding**: New users can learn the tool and start their first project in minutes
* **Easier Data Management**: The dedicated datasets section keeps your data organized
* **Better Security**: The API keys section gives you more control over your integrations
* **More Productive Workflows**: Annotators can now start, resume, and explore projects with fewer clicks

***

## What's Next

We are already working on our next set of features, including:

* Updated File Management
* Object Detection Agent

<Info>
  We want to hear from you! Your feedback helps us decide what to build next.
</Info>

***

## Conclusion

Our May 2025 update delivers a faster, more organized, and more secure workflow. The new landing page, datasets section, and API keys management make it easier than ever to manage your projects. We encourage you to explore the new features and let us know what you think.


# May 2026 - Product Updates
Source: https://docs.labellerr.com/product-releases/may-2026

Smarter hand and pose tracking up to 33 points, attribute filtering, and redesigned keypoint template setups.

Labellerr introduces a set of improvements designed to make keypoint-based annotation more powerful, more intuitive, and easier to manage at scale. This release focuses on improving both annotation precision and operational efficiency for teams working across image and video datasets.

<Frame>
  <img alt="Hand Keypoint Overview" />
</Frame>

From enhanced hand tracking support to body pose annotation, improved filtering workflows, and a redesigned keypoint setup experience, these updates are built to reduce annotation complexity while giving teams greater control over how they manage structured labeling tasks.

Here’s what’s new.

## 1. Hand Keypoint Tracking on Image and Video (Up to 21 Points)

<iframe title="Hand Keypoint Tracking on Image and Video" />

Precise hand annotation is a critical requirement for many computer vision applications, especially in scenarios involving gesture interpretation, hand-object interaction, and egocentric understanding.

Labellerr now supports Hand Keypoint Tracking across both images and videos with up to 21 keypoints per hand, enabling teams to create detailed and structured annotations for hand movement and articulation.

This enhancement allows annotation teams to define fine-grained hand positions with greater consistency, making it easier to build high-quality datasets for motion-centric AI workflows.

**Why this matters:**
Hands are among the most complex and dynamic objects to annotate. Finger articulation, occlusions, rotation, partial visibility, and rapid motion often create inconsistencies during manual labeling.

With 21-point hand keypoint support, teams can now capture a more complete skeletal representation of the hand, improving annotation depth for downstream modeling tasks.

This is especially useful for:

* Gesture recognition systems
* Hand tracking applications
* AR/VR interaction modeling
* Human-computer interaction datasets
* Robotics hand-movement understanding
* Sign-related motion interpretation
* Fine-grained activity detection

### Built for Egocentric Video Annotation

A major advantage of this release is its relevance for egocentric video annotation workflows.

First-person or egocentric videos often contain hands interacting directly with tools, objects, or environments. These scenarios are common in:

* Industrial task monitoring
* Wearable-camera AI systems
* Assembly-line action tracking
* Sports motion analysis
* Human activity understanding
* Training simulation datasets

By supporting structured hand keypoint tracking on video, Labellerr helps teams annotate motion-rich sequences more effectively while preserving temporal consistency.

## 2. Body Pose Keypoint Tracking (Up to 33 Points)

<iframe title="Body Pose Keypoint Tracking" />

Human pose estimation remains one of the most important building blocks for modern computer vision systems.

Labellerr now introduces Body Pose Keypoint Tracking on images with support for up to 33 body keypoints, helping teams create richer skeletal annotations for full-body understanding tasks.

This enables more structured human pose labeling and better representation of body movement, alignment, posture, and positional relationships.

**Why 33-point pose annotation matters:**
Many pose-based AI models rely on detailed skeletal information rather than simple bounding boxes.

With expanded body keypoint support, annotation teams can represent complex body structures more accurately across varied human positions.

This becomes valuable for:

* Pose estimation model training
* Fitness and movement analysis
* Sports performance tracking
* Rehabilitation AI systems
* Safety monitoring
* Human behavior analysis
* Motion recognition tasks

Instead of relying only on object-level detection, teams can now annotate deeper structural relationships within the human body.

## 3. Filter Annotations Based on Attributes

<iframe title="Filter Annotations Based on Attributes" />

As annotation projects scale, managing large volumes of labeled objects becomes increasingly difficult.

Teams often need faster ways to isolate specific annotations, validate subsets of data, and inspect objects with particular metadata values.

Labellerr now supports the ability to filter annotations based on annotation attributes, making annotation review and dataset navigation significantly easier.

**Why this improves workflow efficiency:**
In large datasets, multiple annotated objects may contain varying attributes such as category-specific properties, task-level labels, or review states.

Without filtering, reviewing these subsets can become time-consuming.

With attribute-based filtering, teams can narrow annotation visibility and focus only on the data that matters.

This helps in scenarios like:

* Reviewing specific annotation categories
* Auditing labeled subsets
* Validating project-specific metadata groups
* Faster quality control workflows
* Dataset inspection and correction
* Large-scale annotation reviews
* Better operational control for annotation teams

Annotation is not just about labeling; it is also about validation, auditing, and iteration.

Filtering based on attributes helps teams reduce noise inside complex labeling environments and accelerate review tasks without manually scanning large annotation volumes.

This creates a cleaner workflow for QA teams, project managers, and annotation specialists handling structured datasets.

## 4. Keypoint Annotation Template Redesign

<iframe title="Keypoint Annotation Template Redesign" />

Creating keypoint structures should be simple, repeatable, and optimized for common computer vision workflows.

To improve usability and reduce setup friction, Labellerr has redesigned the Keypoint Annotation Template experience.

This update improves how teams configure and initialize keypoint-based annotation tasks.

### Faster keypoint setup

Keypoint annotation projects often require predefined skeletal layouts before labeling begins.

With the redesigned template workflow, setting up keypoint structures becomes more streamlined and intuitive, helping teams reduce project configuration overhead.

This is especially useful for repetitive workflows where standardized structures are commonly used.

### Preset support for Hand and Pose

A major addition to this redesign is preset support for Hand and Pose keypoint templates.

Instead of manually configuring common skeletal patterns from scratch, teams can now start faster using preset structures aligned with keypoint-based workflows.

This improves consistency and speeds up project initialization for tasks involving:

* Hand tracking
* Gesture datasets
* Pose estimation
* Human body analysis
* Motion-related annotation tasks

### Better consistency across teams

Standardized template selection reduces variation in annotation configuration across multiple projects.

For large annotation teams, this improves repeatability and helps maintain consistency between annotators, reviewers, and dataset managers.

Ultimately, the redesign makes keypoint project setup faster while improving usability for teams working with structured spatial annotations.

## How These Updates Help You

* **Greater Precision:** Expanded skeletal support with 21-point hand tracking and 33-point body pose estimation allows for fine-grained landmark representation.
* **Smarter Review Workflows:** Attribute-based filtering enables reviewers and QA teams to narrow visualization and quickly audit specific subsets of data.
* **Faster Onboarding & Configuration:** Redesigned template setups with hand and pose presets reduce manual layout creation and project initialization overhead.
* **Standardized Consistency:** Repeatable layout configurations and templates maintain high labeling consistency across large teams and projects.

## Conclusive Thoughts

The May 2026 Labellerr release focuses on one core goal: making structured annotation workflows more efficient while supporting increasingly advanced AI use cases.

With this update, teams can now:

* Annotate hand movement and articulation with up to 21 keypoints
* Build richer body pose datasets using 33-point skeletal tracking
* Review annotations faster with attribute-based filtering
* Launch keypoint workflows quicker using preset-driven template redesign

As AI models become more dependent on detailed spatial understanding, annotation platforms must support precision, flexibility, and scalability. These updates strengthen Labellerr’s ability to support teams building advanced computer vision datasets for modern AI systems, while reducing operational friction across the annotation lifecycle.

**The Labellerr Team**

## FAQs

**Q1. What is the limit for hand keypoints in this new release?**

Labellerr now supports up to 21 keypoints per hand for Hand Keypoint Tracking across both images and videos. This enables highly detailed, articulated gesture and interaction mapping.

**Q2. How many keypoints are supported for body pose annotation?**

We now support up to 33 keypoints for full-body pose tracking on images, offering a more complete and precise skeletal representation for pose estimation models.

**Q3. How does attribute filtering speed up annotation reviews?**

Attribute-based filtering lets teams isolate specific labeled objects by their properties, task metadata, or labels, eliminating the need to manually scroll and search through dense annotation datasets.

**Q4. Do I have to configure hand or body pose templates from scratch?**

No. With the redesigned keypoint template experience, Labellerr introduces presets for common hand and pose layouts so you can set up and launch structured projects instantly.


# November 2025 - Product Updates
Source: https://docs.labellerr.com/product-releases/november-2025

SAM3 integration, preview strips, polygon splitting, boundary annotations, and SDK enhancements

This month's release brings powerful AI-driven annotation capabilities, enhanced user experience improvements, and expanded SDK functionality. From SAM3's ability to label similar objects with a single prompt to intelligent preview strips and smarter polygon editing, these updates accelerate annotation workflows and improve dataset quality at scale.

## 1. SAM3 Integration: Label All Similar Objects with a Single Visual Prompt

<iframe title="SAM3 Integration - Label Similar Objects" />

Now you can label all similar objects like cars, players, or products using just one single visual prompt—whether it's a box or a polygon. SAM3 intelligently identifies and labels all similar instances across your image, dramatically reducing repetitive annotation work.

**Key Improvements:**

* Single visual prompt (box or polygon) automatically labels all similar objects in the image
* Intelligent object detection powered by SAM3's advanced segmentation capabilities
* Significant time savings for datasets with multiple instances of the same object class
* Works seamlessly with image-based projects
* Automated labeling maintains consistency across similar objects

**Future Work:**

* Support for negative prompting and incremental prompting to refine results
* Individual accept/reject controls for each detected object (accept all, reject all)
* Reduced latency for faster processing
* Extension to video projects for frame-by-frame similar object detection

This feature transforms how teams handle repetitive labeling tasks, making it possible to annotate hundreds of similar objects in seconds rather than hours.

***

## 2. File Preview Strip for Seamless Navigation

<iframe title="File Preview Strip Navigation" />

When viewing files in full-page mode, a smart preview strip now renders at the bottom, showing thumbnails of other files in the queue. This allows annotators and reviewers to navigate between files effortlessly without returning to the file listing page.

**Key Improvements:**

* Preview strip displays thumbnails of all files from the current page in the file listing
* Click any thumbnail to instantly open that file in full view
* Toggle visibility of the preview strip to maximize canvas space
* Expand and collapse the preview section as needed
* Auto-navigation: when a file is accepted or rejected, the next file in line opens automatically
* On the last file, the current file remains open after accept/reject
* Smart pagination: previous and next pages load automatically when navigating to the edges
* Accept and reject actions available directly from the preview mode
* Works across all data types (image, video, audio, document, text)

**Performance Optimizations:**

* Pre-fetching of file links and annotations for files adjacent to the current view
* Static thumbnails for audio and document files ensure consistent UI
* Smooth transitions between files with minimal loading time

This update creates a more fluid review experience, enabling teams to process files faster while maintaining context and continuity across their annotation queue.

***

## 3. Automatic Polygon Splitting in Clip Mode

<iframe title="Automatic Polygon Splitting in Clip Mode" />

Clip Mode now intelligently handles polygon splitting. When a clipping operation divides a polygon into multiple pieces, each piece automatically becomes a separate, fully editable polygon annotation.

**Previous Behavior:**

* When clipping resulted in multiple polygon pieces (MultiPolygon), only the largest piece by area was retained
* Smaller pieces were automatically discarded, leading to data loss

**New Behavior:**

* All resulting polygon pieces are preserved as individual annotations
* Each split polygon becomes independently editable
* Maintains annotation metadata and labels across all split instances
* Supports complex clipping scenarios with multiple resulting polygons

**Key Improvements:**

* Zero data loss during polygon clipping operations
* Automatic instance creation for each split piece
* Preserves annotation attributes and relationships
* Enables more precise editing workflows for complex shapes
* Intuitive behavior that matches user expectations

This enhancement is particularly valuable for annotating overlapping objects, partial occlusions, and complex scenes where precise boundary definition requires splitting annotations.

***

## 4. Improved Polygon and Polyline Annotations Near Boundaries

<iframe title="Boundary-Aware Polygon Annotations" />

Annotating objects that extend to image boundaries is now significantly easier. Users can place polygon and polyline points outside the image boundary, and the system automatically adjusts them to snap precisely to the edge—no more tedious zooming and manual alignment.

**Previous Workflow:**

* Annotators had to zoom in significantly to place points at the boundary edge
* Even with zoom, boundary points were often imprecise
* Manual adjustments were time-consuming and frustrating

**New Workflow:**

* Mark polygon or polyline points freely, even outside the image boundary
* Points automatically snap to the nearest boundary edge
* No user intervention required for boundary alignment
* Maintains precision without requiring zoom

**Key Improvements:**

* Intelligent boundary detection and automatic point adjustment
* Dramatically faster annotation for objects at image edges
* Eliminates precision errors at boundaries
* Works for both polygon and polyline annotation types
* Reduces cognitive load and physical effort during annotation
* Particularly valuable for satellite imagery, medical scans, and full-frame objects

This UX enhancement removes a common point of friction in annotation workflows, making boundary annotations as easy as annotating objects in the center of the image.

***

## 5. Model Inference via SDK

Teams can now run inference using their trained Autolabel models directly through the SDK, with flexible options for how predictions are applied to unlabeled files.

**Inference Modes:**

**Magic Wand Mode:**

* Enables the Magic Wand tool with three confidence score buckets
* Provides users with visual confidence indicators for each prediction
* Allows manual refinement before accepting annotations

**Pre-Label Mode:**

* Automatically annotates unlabeled files
* Preserves the current file status (keeps files in their existing workflow stage)
* Ideal for adding AI assistance without disrupting review pipelines

**Send-to-Review Mode:**

* Annotates unlabeled files and automatically advances them to the review stage
* Streamlines workflows by moving AI-labeled data directly into the review queue
* Reduces manual status updates for high-confidence predictions

**Key Improvements:**

* Programmatic access to trained Autolabel models
* Flexible annotation strategies based on confidence and workflow requirements
* Seamless integration with existing annotation and review pipelines
* Batch processing support for large datasets
* API-level control over model inference parameters

This SDK capability enables organizations to build automated labeling pipelines that combine AI predictions with human validation, significantly accelerating dataset preparation while maintaining quality control.

***

## 6. Autolabel Training Job Management via SDK

Training jobs can now be triggered, monitored, and managed entirely through the SDK, with transparent data splits and full control over the training lifecycle.

**Training Data Management:**

* Pull data from projects using predefined tags: train, val, and test
* Complete transparency in data distribution across training, validation, and test sets
* User-defined control over dataset splits for reproducible experiments
* Tag-based organization ensures consistent model training pipelines

**Training Pipeline:**

* Autolabel training jobs execute as Cloud Run jobs for scalability
* Progress tracking through MLflow integration (existing pipeline)
* Model storage and versioning in MLflow
* Real-time monitoring of training metrics and performance

**SDK Capabilities:**

* Trigger Training: Start training jobs with specified dataset splits
* Monitor Progress: Track training status, metrics, and progress in real-time
* Cancel Jobs: Stop running training jobs when needed
* Retrieve Statistics: Get detailed training metrics after model completion
* Download Models: Export trained models for offline deployment and inference

**Infrastructure Updates:**

* AutoLabelCore repository deprecated in favor of consolidated MLtraining repository
* Training management functions converted to Python and integrated into MLtraining
* Streamlined codebase for better maintainability and extensibility

**Key Improvements:**

* End-to-end programmatic control over model training lifecycle
* Transparent data management with tag-based splits
* Integration with industry-standard MLOps tools (MLflow)
* Ability to cancel, monitor, and retrieve training jobs
* Offline model deployment support
* Cleaner architecture with unified training interface

This update empowers data science teams to build fully automated training pipelines, from data preparation through model deployment, all controlled through code.

***

## How These Updates Help You

* **AI-Powered Efficiency**: SAM3 integration and SDK inference capabilities reduce manual annotation time by up to 10x for repetitive tasks
* **Seamless Navigation**: Preview strips and enhanced file navigation eliminate context switching and speed up review workflows
* **Precision at Scale**: Improved boundary handling and polygon splitting ensure accurate annotations without tedious manual adjustments
* **Automated Pipelines**: SDK training and inference capabilities enable end-to-end MLOps automation
* **Quality Control**: Flexible inference modes and confidence-based tools maintain high annotation standards while leveraging AI assistance

***

## What's Next

We are preparing additional enhancements including negative prompting for SAM3, video support for boundary annotations, and extended automation features for enterprise workflows.

***

## Wrapping Up

The November 2025 updates represent a significant leap forward in AI-assisted annotation and workflow automation. With SAM3's revolutionary one-prompt-many-objects capability, intelligent preview navigation, and comprehensive SDK control over training and inference, Labellerr continues to bridge the gap between manual annotation and fully automated pipelines.

These features are designed for teams that need to scale their labeling operations while maintaining the highest quality standards. As we move into 2026, our focus remains on empowering both annotators and ML engineers with intelligent tools that reduce repetitive work and accelerate the path from raw data to production-ready models.

**The Labellerr Team**

***

## FAQs

<AccordionGroup>
  <Accordion title="Q1. How does SAM3 differ from previous SAM versions in Labellerr?">
    SAM3 introduces the ability to label all similar objects in an image with a single visual prompt, whereas previous versions required individual prompts for each object. This dramatically reduces annotation time for datasets with multiple instances of the same object class, making it ideal for scenarios like crowd detection, vehicle counting, and product annotation.
  </Accordion>

  <Accordion title="Q2. Can I use the file preview strip with custom filters applied?">
    Yes, the preview strip respects all filters applied in the file listing page. When you navigate through files using the preview strip, your filters remain active, ensuring you only see relevant files in your queue. This includes status filters, tag filters, assignment filters, and search queries.
  </Accordion>

  <Accordion title="Q3. How do I choose between Magic Wand, Pre-Label, and Send-to-Review modes for SDK inference?">
    Use Magic Wand when you want human annotators to review and refine AI predictions with visual confidence indicators. Use Pre-Label when you want to add AI assistance without changing file workflow status. Use Send-to-Review when you have high confidence in predictions and want to streamline files directly into the review queue.
  </Accordion>

  <Accordion title="Q4. Can I monitor training jobs in real-time through the SDK?">
    Yes, the SDK provides real-time access to training job status, progress metrics, and performance statistics through integration with MLflow. You can query job status at any time and retrieve detailed metrics upon completion.
  </Accordion>
</AccordionGroup>


# October 2025 - Product Updates
Source: https://docs.labellerr.com/product-releases/october-2025

File tagging, full-screen view mode, SDK automation, and enhanced canvas shortcuts

This month's release focuses on improving how teams organize datasets, streamline annotations, and automate workflows through the SDK. From intelligent file tagging and new canvas shortcuts to SDK-level automation for user and file management, these updates make Labellerr faster, more intuitive, and ready for large-scale ML operations.

## 1. File Tagging for Dataset Organization

Users can now tag files within Labellerr projects to create structured train, validation, and test splits. This feature helps in preparing machine learning datasets directly within the Labellerr platform.

**Key Improvements:**

* Ability to add predefined tags such as train, val, and test
* Support for adding custom tags (e.g., batch-1, high-quality) for advanced organization
* Tags can be searched and filtered for quick access
* Real-time updates, changes reflect instantly across the system
* Backend support for tag storage and indexing through Firestore and Elasticsearch
* Enhanced search API allowing users to filter files based on tags

This update provides a more flexible and ML-friendly dataset management experience, making it easier to maintain structured data pipelines within Labellerr.

***

## 2. Reusable File Viewer Grid and List Component

<iframe title="Reusable File Viewer Grid Component" />

<iframe title="Reusable File Viewer List Component" />

A new reusable file viewer component has been developed to provide a consistent and efficient way to display images, audio, and video files across the Labellerr application. This ensures that all media assets follow a unified visual experience.

**Key Improvements:**

* Reusable grid and list view component for displaying project files uniformly
* Support for image, audio, and video previews in both views
* Hover-based video preview that allows users to quickly inspect content without fully opening it
* Optimized layout for handling large file collections with smooth performance
* Consistent UI and UX across all modules that display media assets
* Simplified integration for developers, allowing this component to be reused across the platform

This enhancement establishes a cohesive design system and improves the speed and ease of navigating through visual and multimedia datasets.

***

## 3. Full-Screen File View Mode with Contextual Controls

Users can now open files directly in full-screen view mode from the file listing page, enabling a distraction-free workspace for detailed annotation and review. The navigation and interaction experience has been redesigned for clarity, continuity, and control.

**Key Improvements:**

* New full-screen route replaces the previous popup-based file view for a seamless browsing experience
* Dedicated Back button restores users to the file listing page with existing filters preserved
* Collapsed questions panel by default for a cleaner layout; annotations panel remains visible
* Accept and Reject buttons available by default for files in Review or Client Review status

**Enhanced viewing interactions:**

* Toggle annotation visibility on the canvas
* Highlight annotations on hover
* Adjust annotation opacity
* Apply image filters directly from view mode
* Play and pause videos, and add markers on the timeline

**Action restrictions to maintain data integrity:**

* No new annotations or edits allowed
* No attribute modifications or group changes
* Classification updates and right-click keyframe actions disabled

This update provides a more immersive, intuitive review experience while preserving contextual continuity through stateful navigation and applied filters.

***

## 4. Polyline Annotations with Occlusion Support

Annotators can now mark occluded segments directly while drawing polylines, improving both speed and precision. This removes the need for separate occlusion-related questions and allows users to manage everything within a single workflow.

**Key Improvements:**

* Right-click detection during polyline drawing to mark occluded segments instantly
* Visual differentiation of occluded segments using gray dashed lines (#808080)
* Persistent data storage with occluded segments saved in the backend and restored on reload
* Backward compatibility with previously created annotations to ensure smooth transition
* Enhanced usability: annotations retain visual styling and occlusion indicators even after saving and reloading

This enhancement streamlines the annotation workflow for complex visual data, allowing users to mark visibility conditions more efficiently and maintain consistency across datasets.

***

## 5. Improved Polygon Eraser Transparency

<iframe title="Improved Polygon Eraser Transparency" />

The polygon eraser tool has been refined to offer better visual clarity while editing annotations. When eraser mode is activated, the targeted polygon now becomes fully transparent, allowing annotators to see the underlying regions clearly before erasing.

**Key Improvements:**

* Full 100% transparency applied to the target polygon when eraser mode is enabled
* Clear visualization of the underlying image area for accurate erasure
* Automatic restoration of original polygon opacity when eraser mode is turned off
* Backend persistence ensures erased regions are saved correctly and reloaded accurately
* Improved testing coverage across both image and video annotation modes

This enhancement provides greater precision and control during polygon editing, reducing guesswork and improving annotation accuracy.

***

## 6. Quick Label Change from Canvas

<iframe title="Quick Label Change from Canvas" />

Annotators can now change the label of any object directly from the canvas using a simple keyboard shortcut. This eliminates the need to search for the object in the annotations tray, making the relabeling process faster and more intuitive.

**Key Improvements:**

* Introduced keyboard shortcut (L) for quick label change directly from the canvas
* Simplified relabeling workflow for polygons and other object annotations
* Preserves remarks and metadata when the label is updated
* Reduces dependency on the annotation tray, improving speed and accuracy
* Streamlined UI behavior: relabeling now feels natural and integrated into the annotation flow

This feature enhances productivity by minimizing navigation steps and allowing annotators to make changes directly within their workspace.

***

## 7. Bulk File Assignment via SDK

A new SDK-level bulk assignment API has been introduced, allowing developers and enterprise clients to automate file assignment and status updates efficiently within their workflows.

**Key Improvements:**

* Ability to bulk-assign files to users or update file statuses directly via SDK
* Supports both file\_ids and slice\_ids for flexible bulk operations
* Integrated with Labellerr's advanced filters to search and retrieve files programmatically before assignment
* Validation checks for invalid user emails, unrecognized statuses, or files outside the project scope
* Comprehensive error handling and informative response messages for failed or partial assignments
* Backend consistency with existing Files section behavior in the Labellerr app

This addition empowers large-scale users and automation scripts to manage dataset workflows more effectively without manual intervention through the UI.

***

## 8. Project User Management via SDK

Developers can now add or remove users from Labellerr projects directly through the SDK, making it easier to programmatically manage large-scale labeling workflows and user assignments.

**Key Improvements:**

* Introduced SDK endpoints for adding and removing users from projects
* Users already present in the workspace can be added using their email ID
* If a user does not exist in the workspace, the SDK prompts for additional details (e.g., full name) before creation
* Import users from existing projects to replicate permissions and streamline setup
* Validation checks for invalid or duplicate email IDs
* Error handling with clear messages for missing or mismatched user information
* Seamless integration with project-level role and permission structures

This feature simplifies workflow automation for organizations and teams that manage multiple projects and contributors, ensuring smooth onboarding and access control through SDK automation.

***

## How These Updates Help You

* **Smarter Workflows**: Automate user and file operations seamlessly through the SDK, reducing repetitive management tasks
* **Faster Labeling**: Save time with intuitive canvas shortcuts and efficient bulk actions, allowing annotators to focus on quality
* **Better Visibility**: Experience improved clarity with enhanced viewers, list components, and full-screen file modes
* **ML-Ready Datasets**: Structure and tag your datasets effortlessly, enabling faster and cleaner model training pipelines

***

## Conclusive Thoughts

The October 2025 updates mark a strong stride toward a smarter and more scalable Labellerr.

With streamlined dataset management, unified viewing components, and SDK-powered automation, these upgrades help teams label, review, and manage projects faster than ever before.

As we continue evolving the platform, our focus remains on empowering both developers and annotators with a unified, intelligent workspace built for the future of data labeling.

**The Labellerr Team**

***

## FAQs

**Q1. How does file tagging improve dataset management in Labellerr?**

File tagging enables users to organize datasets into structured splits like train, validation, and test sets. It allows better searchability, filtering, and ML-readiness directly within the Labellerr platform.

**Q2. What are the key benefits of SDK-level automation in Labellerr?**

SDK automation allows teams to manage users, assign files, and update statuses programmatically. This reduces repetitive manual work and ensures consistent workflows across large-scale ML operations.

**Q3. How do the new canvas shortcuts and full-screen view improve annotation efficiency?**

Annotators can now relabel objects, toggle annotations, and review files faster with keyboard shortcuts and full-screen mode, reducing context-switching and improving productivity.


# September 2025 - Product Updates
Source: https://docs.labellerr.com/product-releases/september-2025

Smarter project indexing, polyline grouping, and required object annotations

This month's release introduces enhancements to project creation, improved handling of grouped annotations, and new validation for object-type tasks. Together, these updates make project workflows faster, more transparent, and more reliable for annotators and reviewers.

## 1. Start Annotating Projects Immediately with Smarter Indexing

<iframe title="Start Annotating Projects Immediately" />

Project creation is no longer blocked by Elasticsearch indexing delays or failures. Users can now begin annotating files immediately after project creation, while advanced search features become available once indexing completes.

**Key Improvements:**

* Projects are usable instantly after creation, regardless of indexing state
* Clear indexing states displayed across the UI: Indexing in Progress, Indexing Complete, or Indexing Failed
* Progress indicators with counts and ETA shown via popovers and banners
* Basic file search and filters (file status, file ID, file name) remain available even if indexing has not finished
* Advanced filters are gracefully limited until indexing completes
* In-app notifications on project creation, indexing completion, or indexing failure
* Email notifications sent if indexing takes longer than one minute, with guidance and tutorials on advanced search
* Support ticket option provided when indexing fails
* Analytics tracking for indexing duration, frequency of failures, and retries
* Observability improvements to monitor job success and recovery

These changes ensure project creation is seamless, with immediate usability and clear communication to reduce confusion and downtime.

***

## 2. Keep Complex Datasets Organized with Polyline Grouping

<iframe title="Polyline Grouping" />

Polyline annotations can now be grouped and managed just like other annotation types. For projects with dense or overlapping shapes, grouping makes it easier to keep related annotations connected, filter them quickly, and review them with clarity.

**Key Improvements:**

* Group IDs are now rendered in the left panel for all grouped polylines
* Grouped annotations are correctly highlighted both in the panel and on the canvas
* Filtering by group ID works reliably across grouped polylines
* Hovering on one annotation highlights the entire group for easier navigation

This improvement ensures greater consistency across annotation types and reduces confusion when working with multiple related polylines.

***

## 3. Guarantee Completeness with Required Object Annotations

Object-type annotations (polygons, bounding boxes, pixel masks) can now be marked as required. This prevents annotators from accidentally submitting incomplete files and ensures that critical object data is always captured.

**Key Improvements:**

* Support for marking object-type questions as required, similar to classification questions
* Required annotations are now indicated with a clear red asterisk on the UI
* Prevents accidental submission of incomplete files
* SDK and UI behavior aligned for consistent validation

This update ensures annotation quality by enforcing completeness before submission.

***

## How These Updates Help You

* **Faster Start**: Projects are now usable right after creation, with no waiting for indexing
* **Better Organization**: Grouped annotations bring more clarity to complex datasets
* **Stronger Validation**: Required object annotations protect against incomplete submissions

***

## What's Next

Our upcoming focus will be on expanding dataset management, strengthening collaboration tools, and refining annotation review workflows.

***

## Wrapping Up

The September 2025 release improves transparency in project creation, strengthens annotation consistency with grouping support, and raises quality standards with required object-type validation. These updates deliver smoother workflows and greater confidence in project outcomes.

We encourage you to explore the new features and continue sharing your feedback with us.

**Labellerr Team**


# Add Annotation Questions
Source: https://docs.labellerr.com/sdk/add-annotation-questions

Define annotation questions using Pydantic schemas in the Labellerr SDK for object detection and classification workflows.

<Card title="Overview" icon="circle-info">
  The Labellerr SDK uses **Pydantic schemas** to define annotation questions. Use the `AnnotationQuestion` schema to create type-safe questions for object-based annotations (bounding boxes, polygons, etc.) and classification workflows (dropdowns, radio buttons, etc.).
</Card>

## Required Question Structure

<Card title="Using AnnotationQuestion Schema" icon="asterisk">
  Every question must be defined using the `AnnotationQuestion` schema with the following fields:

  | Field | Type | Required | Description |
  | - | - | - | - |
  | `question_number` | `int` | Yes | Sequential number for the question (1, 2, 3, …) |
  | `question_id` | `str` | Yes | Unique identifier (UUID) - generate with `str(uuid.uuid4())` |
  | `question` | `str` | Yes | The user-facing label or prompt |
  | `question_type` | `QuestionType` | Yes | Enum value (e.g., `QuestionType.polygon`, `QuestionType.dropdown`) |
  | `required` | `bool` | Yes | Set to `True` if the annotator must answer |
  | `color` | `str` | Conditional | Required for object types (bounding\_box, polygon, polyline, dot) |
  | `options` | `List[Option]` | Conditional | Required for classification types (dropdown, radio, select, boolean) |

  <Note>
    **Object-based questions** (bounding\_box, polygon, polyline, dot) require a `color` parameter (hex code).

    **Classification questions** (dropdown, radio, select, boolean) require `options` as a list of `Option` objects.

    **Input questions** don't require either `color` or `options`.
  </Note>
</Card>

***

## Question Types Reference

<Accordion title="Available Question Types">
  **Object-Based Annotations:**

  * `QuestionType.bounding_box` - Rectangle annotations
  * `QuestionType.polygon` - Multi-point polygon shapes
  * `QuestionType.polyline` - Connected line segments
  * `QuestionType.dot` - Single point markers

  **Classification Annotations:**

  * `QuestionType.dropdown` - Single selection dropdown
  * `QuestionType.radio` - Radio button selection
  * `QuestionType.select` - Multi-select options
  * `QuestionType.boolean` - Yes/No toggle
  * `QuestionType.input` - Free text input

  **Specialized:**

  * `QuestionType.stt` - Speech-to-text
  * `QuestionType.imc` - Image classification
</Accordion>

***

## Examples

<Card title="Multiple Questions Template" icon="file-code">
  Create a template with multiple question types including object detection and classification:

  ```python theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.annotation_templates import create_template
  from labellerr.core.schemas import (
      CreateTemplateParams,
      AnnotationQuestion,
      QuestionType,
      Option,
      DatasetDataType
  )
  import uuid

  # Initialize client
  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  # Define questions using schema
  questions = [
      AnnotationQuestion(
          question_number=1,
          question="Draw crop boundary",
          question_type=QuestionType.polygon,
          required=True,
          question_id=str(uuid.uuid4()),
          color="#5F9EA0"  # Hex color for object types
      ),
      AnnotationQuestion(
          question_number=2,
          question="Mark vehicle",
          question_type=QuestionType.bounding_box,
          required=True,
          question_id=str(uuid.uuid4()),
          color="#FFAA00"
      ),
      AnnotationQuestion(
          question_number=3,
          question="Overall quality",
          question_type=QuestionType.radio,
          required=True,
          question_id=str(uuid.uuid4()),
          options=[
              Option(option_name="Good"),
              Option(option_name="Average"),
              Option(option_name="Poor")
          ]
      ),
      AnnotationQuestion(
          question_number=4,
          question="Additional remarks",
          question_type=QuestionType.input,
          required=False,
          question_id=str(uuid.uuid4())
      )
  ]

  # Create template
  template = create_template(
      client=client,
      params=CreateTemplateParams(
          template_name="Demo Template",
          data_type=DatasetDataType.image,
          questions=questions
      )
  )

  print(f"Template created: {template.annotation_template_id}")
  ```
</Card>

***

<Card title="Single Question Template" icon="play">
  Create a simple template with a single annotation question:

  ```python theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.annotation_templates import create_template
  from labellerr.core.schemas import (
      CreateTemplateParams,
      AnnotationQuestion,
      QuestionType,
      DatasetDataType
  )
  import uuid

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  questions = [
      AnnotationQuestion(
          question_number=1,
          question="Track object across frames",
          question_type=QuestionType.polygon,
          required=True,
          question_id=str(uuid.uuid4()),
          color="#FE1236"
      )
  ]

  template = create_template(
      client=client,
      params=CreateTemplateParams(
          template_name="Video Tracking Template",
          data_type=DatasetDataType.video,
          questions=questions
      )
  )

  print(f"Template created: {template.annotation_template_id}")
  ```
</Card>

***

<Card title="Classification Only Template" icon="list-check">
  Create a template with only classification questions (no object detection):

  ```python theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.annotation_templates import create_template
  from labellerr.core.schemas import (
      CreateTemplateParams,
      AnnotationQuestion,
      QuestionType,
      Option,
      DatasetDataType
  )
  import uuid

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  questions = [
      AnnotationQuestion(
          question_number=1,
          question="Image category",
          question_type=QuestionType.dropdown,
          required=True,
          question_id=str(uuid.uuid4()),
          options=[
              Option(option_name="Nature"),
              Option(option_name="Urban"),
              Option(option_name="Portrait")
          ]
      ),
      AnnotationQuestion(
          question_number=2,
          question="Contains people?",
          question_type=QuestionType.boolean,
          required=True,
          question_id=str(uuid.uuid4()),
          options=[
              Option(option_name="Yes"),
              Option(option_name="No")
          ]
      ),
      AnnotationQuestion(
          question_number=3,
          question="Tags",
          question_type=QuestionType.select,
          required=False,
          question_id=str(uuid.uuid4()),
          options=[
              Option(option_name="Outdoor"),
              Option(option_name="Indoor"),
              Option(option_name="Daytime"),
              Option(option_name="Nighttime")
          ]
      )
  ]

  template = create_template(
      client=client,
      params=CreateTemplateParams(
          template_name="Image Classification Template",
          data_type=DatasetDataType.image,
          questions=questions
      )
  )

  print(f"Template created: {template.annotation_template_id}")
  ```
</Card>

***

## Best Practices

<CardGroup>
  <Card title="Unique Question IDs" icon="fingerprint">
    Always generate unique question IDs using `str(uuid.uuid4())` to avoid conflicts. Reuse IDs only when intentionally updating an existing question.
  </Card>

  <Card title="Sequential Numbering" icon="list-ol">
    Ensure `question_number` values are sequential (1, 2, 3, ...) to maintain proper ordering in the annotation interface.
  </Card>

  <Card title="Color Selection" icon="palette">
    Use distinct hex colors for different object types to make them easily distinguishable in the annotation interface.
  </Card>

  <Card title="Clear Labels" icon="tag">
    Write concise, descriptive question text that clearly communicates what annotators should label.
  </Card>
</CardGroup>

***

## Related Documentation

<Card title="Create Projects" icon="folder-tree" href="/sdk/create-project-sdk">
  Learn how to create projects using annotation templates
</Card>


# SDK Changelog
Source: https://docs.labellerr.com/sdk/changelog

Track updates, improvements, and breaking changes across Labellerr SDK versions

<Note>
  **Latest Version: v2.0.0** - Major refactoring with improved architecture, enhanced payload structure, and new features. See details below.
</Note>

***

## Version 2.0.0 (November 2025)

<Warning>
  **Breaking Changes** - This release includes significant API changes. Please review the migration notes carefully.
</Warning>

### Architecture & Infrastructure

<AccordionGroup>
  <Accordion title="Modular Architecture">
    Complete restructuring from monolithic 2000+ line files to organized, maintainable modules:

    **New Structure:**

    * `labellerr/core/annotation_templates/` - Template management
    * `labellerr/core/autolabel/` - Model training features
    * `labellerr/core/connectors/` - S3 and GCS connections
    * `labellerr/core/datasets/` - Dataset CRUD operations
    * `labellerr/core/exports/` - Export handling with polling
    * `labellerr/core/projects/` - Project management
    * `labellerr/core/schemas/` - Pydantic validation models
    * `labellerr/core/users/` - User management

    **Benefits:**

    * Separation of concerns with single responsibility per module
    * Factory pattern for automatic type-specific object instantiation
    * Easier maintenance and extensibility
    * Better code discoverability
  </Accordion>

  <Accordion title="Enhanced Payload Structure with Type Safety">
    **Major Improvement:** All function parameters now use Pydantic models for validation instead of plain dictionaries.

    **Old Approach:**

    ```python theme={"dark"}
    # Plain dictionary - no validation
    payload = {"project_name": "My Project", "data_type": "image", ...}
    ```

    **New Approach:**

    ```python theme={"dark"}
    from labellerr.core.schemas import CreateProjectParams, RotationConfig

    # Type-safe with automatic validation
    params = CreateProjectParams(
        project_name="My Project",
        data_type="image",
        rotations=RotationConfig(
            annotation_rotation_count=1,
            review_rotation_count=1,
            client_review_rotation_count=1
        )
    )
    ```

    **Benefits:**

    * Automatic validation before API calls
    * IDE autocomplete and type checking
    * Clear, self-documenting schema fields
    * Early error detection
    * Organized schemas by domain (autolabel, connectors, datasets, exports, files, projects, users)
  </Accordion>

  <Accordion title="Improved Project Creation Pipeline">
    **New Workflow:** Project creation now follows an explicit, modular pipeline for better control and reusability.

    **Old Approach:**

    ```python theme={"dark"}
    # Everything in one call - datasets created inline
    project = create_project(
        client=client,
        payload={
            "project_name": "My Project",
            "folder_to_upload": "./images",
            "annotation_template_id": "template_123",
            ...
        }
    )
    ```

    **New Approach:**

    ```python theme={"dark"}
    # Step 1: Create dataset
    dataset = create_dataset_from_local(
        client=client,
        dataset_config=DatasetConfig(
            dataset_name="My Dataset",
            data_type="image"
        ),
        folder_to_upload="./images"
    )
    dataset.status()  # Wait for completion

    # Step 2: Get annotation template
    template = LabellerrAnnotationTemplate(client, "template_123")

    # Step 3: Create project with explicit dependencies
    project = create_project(
        client=client,
        params=CreateProjectParams(...),
        datasets=[dataset],
        annotation_template=template
    )
    ```

    **Why This Change?**

    * **Explicit Dependencies:** Datasets and templates validated before project creation
    * **Better Error Handling:** Issues caught earlier in the pipeline
    * **Reusability:** Same dataset can be attached to multiple projects
    * **Clearer Flow:** Each step is explicit, testable, and maintainable
    * **Type Safety:** Pydantic validation at each step
  </Accordion>
</AccordionGroup>

### New Features

<AccordionGroup>
  <Accordion title="Cloud Export Support (AWS S3)">
    Export annotations directly to cloud storage with automatic status polling:

    ```python theme={"dark"}
    from labellerr.core.schemas import CreateExportParams

    export = project.create_export(
        export_config=CreateExportParams(
            export_name="Production Export",
            export_format="json",
            connection_id="s3_conn_123",
            export_destination="s3",
            export_folder_path="bucket/exports/"
        )
    )
    # Automatically polls until completion
    final_status = export.status()
    ```

    **Features:**

    * Direct export to AWS S3
    * Automatic polling mechanism
    * Multiple export formats (JSON, CSV, COCO JSON)
    * Status filtering support
  </Accordion>

  <Accordion title="Autolabel Model Training">
    Train custom models on your annotated data with configurable hyperparameters:

    ```python theme={"dark"}
    from labellerr.core.autolabel import LabellerrAutoLabel
    from labellerr.core.schemas import TrainingRequest, Hyperparameters

    autolabel = LabellerrAutoLabel(client=client)
    job = autolabel.train(
        training_request=TrainingRequest(
            model_id="yolov11",
            hyperparameters=Hyperparameters(
                epochs=100,
                batch_size=16,
                learning_rate=0.001
            ),
            job_name="Custom Training"
        )
    )
    ```

    **Features:**

    * Train YOLOv11 and other models
    * Configurable hyperparameters
    * Job status tracking
    * List all training jobs
  </Accordion>

  <Accordion title="Enhanced Dataset Operations">
    **Split Dataset Creation:**

    * `create_dataset_from_local()` - For local file/folder uploads
    * `create_dataset_from_connection()` - For cloud storage connections

    **Auto-Pagination:**

    ```python theme={"dark"}
    # Iterate through all datasets automatically
    for dataset in list_datasets(client, datatype="image", scope="client", page_size=-1):
        process(dataset)
    ```

    **Additional Features:**

    * New `delete_dataset()` function
    * Improved sync operations for AWS S3 and GCS
    * Better status tracking with polling
    * Type-specific dataset classes (Image, Video, Audio, Document)
  </Accordion>

  <Accordion title="Annotation Template Management">
    Dedicated module for structured annotation template creation:

    ```python theme={"dark"}
    from labellerr.core.annotation_templates import create_annotation_guideline
    from labellerr.core.schemas import CreateTemplateParams, AnnotationQuestion

    template = create_annotation_guideline(
        client=client,
        params=CreateTemplateParams(
            data_type="image",
            template_name="Object Detection Template",
            questions=[
                AnnotationQuestion(
                    option_type="BoundingBox",
                    question_text="Identify objects",
                    options=[...]
                )
            ]
        )
    )
    ```

    **Features:**

    * Type-safe question definitions
    * Reusable templates across projects
    * Multiple question types (BoundingBox, polygon, radio, etc.)
    * Automatic validation
  </Accordion>

  <Accordion title="Enhanced Connection Management">
    **Dedicated Connection Classes:**

    * `LabellerrS3Connection` - AWS S3 operations
    * `LabellerrGCSConnection` - Google Cloud Storage operations

    **Features:**

    ```python theme={"dark"}
    from labellerr.core.connectors import LabellerrS3Connection
    from labellerr.core.schemas import AWSConnectionParams

    # Test connection before creating
    test_result = LabellerrS3Connection.test_connection(client, params)

    # Create connection with type safety
    connection = LabellerrS3Connection.create_connection(
        client=client,
        params=AWSConnectionParams(
            aws_access_key="...",
            aws_secrets_key="...",
            s3_path="s3://bucket/path/",
            connection_type="export",
            name="Production S3"
        )
    )
    ```

    * Connection testing before creation
    * Support for import and export types
    * Better error handling
    * Type-safe parameters
  </Accordion>
</AccordionGroup>

### Breaking Changes

<AccordionGroup>
  <Accordion title="Project Creation (HIGH IMPACT)">
    **Old approach:**

    ```python theme={"dark"}
    project = create_project(
        client=client,
        payload={
            "project_name": "My Project",
            "folder_to_upload": "./images",
            "annotation_template_id": "template_123",
            ...
        }
    )
    ```

    **New approach:**

    ```python theme={"dark"}
    # Step 1: Create dataset
    dataset = create_dataset_from_local(
        client=client,
        dataset_config=DatasetConfig(
            dataset_name="My Dataset",
            data_type="image"
        ),
        folder_to_upload="./images"
    )
    dataset.status()  # Wait for completion

    # Step 2: Get annotation template
    template = LabellerrAnnotationTemplate(client, "template_123")

    # Step 3: Create project
    project = create_project(
        client=client,
        params=CreateProjectParams(...),
        datasets=[dataset],
        annotation_template=template
    )
    ```

    **Why?** Explicit dependencies, better error handling, and dataset reusability.
  </Accordion>

  <Accordion title="Dataset Creation (MEDIUM IMPACT)">
    **Old:**

    ```python theme={"dark"}
    dataset = create_dataset(
        client=client,
        dataset_config={...},
        folder_to_upload="./images"
    )
    ```

    **New:**

    ```python theme={"dark"}
    from labellerr.core.datasets import create_dataset_from_local
    from labellerr.core.schemas import DatasetConfig

    dataset = create_dataset_from_local(
        client=client,
        dataset_config=DatasetConfig(
            dataset_name="My Dataset",
            data_type="image"
        ),
        folder_to_upload="./images"
    )
    ```
  </Accordion>

  <Accordion title="Import Changes (LOW IMPACT)">
    Update imports from root to `labellerr.core.*`:

    ```python theme={"dark"}
    # Core imports remain backward compatible
    from labellerr import LabellerrClient

    # New modular imports
    from labellerr.core.datasets import create_dataset_from_local, LabellerrDataset
    from labellerr.core.projects import create_project, LabellerrProject
    from labellerr.core.schemas import DatasetConfig, CreateProjectParams
    from labellerr.core.connectors import LabellerrS3Connection
    ```
  </Accordion>
</AccordionGroup>

### Additional Improvements

* **Connection Pooling**: Improved HTTP connection management for better performance
* **Error Handling**: Enhanced error messages with automatic retry logic
* **Polling Mechanism**: Smart status tracking for long-running operations (exports, datasets)
* **Testing Infrastructure**: Comprehensive unit and integration test coverage
* **Documentation**: Improved code examples and API documentation
* **Type-Specific Classes**: Specialized methods for Image, Video, Audio, and Document types
* **Performance**: Optimized request handling and data transfer

### Migration Notes

1. **Update SDK**: `pip install --upgrade labellerr`
2. **Update imports**: Change to new `labellerr.core.*` modules
3. **Refactor project creation**: Follow new 3-step process (dataset → template → project)
4. **Use Pydantic schemas**: Replace dict payloads with schema models
5. **Test thoroughly**: Validate all SDK operations in dev/staging before production

<Tip>
  Need help migrating? contact [support@labellerr.com](mailto:support@labellerr.com)
</Tip>

**GitHub Release**: [v2.0.0](https://github.com/tensormatics/SDKPython/releases/tag/v2.0.0)

***

## Version 1.0.1 (September 2025)

### Improvements

* New project creation flow with updated payload structure
* Better validation for `annotation_guide` and `annotation_template_id`
* `"created_by"` email now included automatically during project creation
* Modularized SDK structure for easier maintenance
* Automated release pipeline added via `release_manager`
* Enhanced export status handling (polling + download URL fetching)

### Bug Fixes

* Fixed `check_export_status` inconsistencies
* Improved error handling for invalid project creation payloads
* Corrected edge-case failures in export polling
* Minor fixes in annotation guide validation logic

### Branch Strategy

* **main** → production-ready releases
* **develop** → pre-release testing versions

**GitHub Release**: [https://github.com/Labellerr/SDKPython/releases/tag/v1.0.1](https://github.com/Labellerr/SDKPython/releases/tag/v1.0.1)

***

## Version 1.0.0 (December 2024)

### Initial Release

First public release of the Labellerr Python SDK.

### Core Features

* **Client Initialization**: Authenticate using `LabellerrClient`
* **Project Management**: Create and configure annotation projects
* **Dataset Operations**: Manage datasets across image, video, audio, text, and documents
* **Pre-annotations**: Upload annotations (sync & async)
* **Export Functionality**: Export annotations in `json`, `coco_json`, `csv`, `png`
* **Retrieval APIs**: Fetch all projects and datasets
* **Error Handling**: `LabellerrError` for managed exception handling

### Core Modules

* `LabellerrClient` — main API client
* Project operations (`initiate_create_project`)
* Pre-annotation upload methods
* Local export utilities
* Dataset retrieval helpers

**GitHub Release**: [https://github.com/Labellerr/SDKPython/releases/tag/v1](https://github.com/Labellerr/SDKPython/releases/tag/v1)

***

## Support & Resources

<CardGroup>
  <Card title="Documentation" icon="book" href="/sdk/getting-started">
    Comprehensive SDK guides and examples
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/tensormatics/SDKPython">
    View source code and report issues
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:support@labellerr.com">
    Get help from our team
  </Card>

  <Card title="Cookbooks" icon="code" href="/cookbooks/sdk-tutorials">
    End-to-end examples and tutorials
  </Card>
</CardGroup>

***

<Info>
  **Semantic Versioning**: We follow [SemVer](https://semver.org/). Breaking changes increment the major version (e.g., 1.x → 2.0).
</Info>


# Create Datasets
Source: https://docs.labellerr.com/sdk/create-dataset-sdk

Learn how to create datasets, upload files, connect cloud storage, enable multimodal indexing, and manage dataset operations in Labellerr using the Python SDK.

## Introduction

<Card title="What are Datasets?" icon="circle-info">
  A **dataset** in Labellerr is a standalone collection of files (images, videos, audio, documents, or text) that can be created independently and attached to one or multiple projects. This modular approach allows you to:

  * Reuse the same dataset across multiple annotation projects
  * Manage your data separately from project configurations
  * Connect cloud storage (AWS S3, Google Cloud Storage) for seamless data access
  * Enable advanced features like multimodal indexing

  ### Supported Data Types

  | Data Type | Description | Supported Extensions |
  | - | - | - |
  | image | Image files for visual annotation | .jpg, .jpeg, .png, .bmp, .tiff |
  | video | Video content for temporal annotation | .mp4 |
  | audio | Audio files for sound annotation | .mp3, .wav |
  | document | Document files for text analysis | .pdf |
  | text | Plain text files for text annotation | .txt |
</Card>

***

## Creating Datasets

### Import Required Modules

```python Required Imports lines icon="code" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.schemas import DatasetConfig
from labellerr.core.datasets import (
    create_dataset_from_local,
    create_dataset_from_connection,
    LabellerrDataset
)
```

***

### Method 1: Create Dataset with Local Files

<Tabs>
  <Tab title="Upload from Folder">
    <Card title="Create Dataset from Folder" icon="folder">
      ```python Create Dataset with Folder lines icon="folder-open" theme={"dark"}
      from labellerr.client import LabellerrClient
      from labellerr.core.schemas import DatasetConfig
      from labellerr.core.datasets import create_dataset_from_local

      client = LabellerrClient(
          api_key='your_api_key',
          api_secret='your_api_secret',
          client_id='your_client_id'
      )

      dataset = create_dataset_from_local(
          client=client,
          dataset_config=DatasetConfig(
              dataset_name="My Image Dataset",
              dataset_description="A collection of images for object detection",
              data_type="image"
          ),
          folder_to_upload="path/to/your/image/folder"
      )

      print(f"Dataset created with ID: {dataset.dataset_id}")
      print(f"Total files: {dataset.files_count}")
      ```

      <Info>
        **Limitations:**

        * Maximum of **2,500 files** per folder
        * Total folder size should not exceed **2.5 GB**
        * Local uploads are slower as files must be transferred through your machine to cloud storage. For large-scale datasets, use cloud storage connections (AWS S3/GCS) for faster direct access.
      </Info>
    </Card>
  </Tab>

  <Tab title="Upload Specific Files">
    <Card title="Create Dataset with File List" icon="list">
      ```python Create Dataset with File List lines icon="file" theme={"dark"}
      from labellerr.client import LabellerrClient
      from labellerr.core.schemas import DatasetConfig
      from labellerr.core.datasets import create_dataset_from_local

      client = LabellerrClient(
          api_key='your_api_key',
          api_secret='your_api_secret',
          client_id='your_client_id'
      )

      dataset = create_dataset_from_local(
          client=client,
          dataset_config=DatasetConfig(
              dataset_name="Curated Image Dataset",
              dataset_description="Specific images selected for annotation",
              data_type="image"
          ),
          files_to_upload=["path/to/image1.jpg", "path/to/image2.jpg", "path/to/image3.png"]
      )

      print(f"Dataset created with ID: {dataset.dataset_id}")
      ```
    </Card>
  </Tab>
</Tabs>

***

### Method 2: Create Dataset with AWS S3 Connection

<Card title="Connect AWS S3 Bucket" icon="aws">
  ```python Create Dataset with AWS S3 lines icon="aws" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.schemas import DatasetConfig, AWSConnectionParams, DatasetDataType, ConnectionType
  from labellerr.core.datasets import create_dataset_from_connection
  from labellerr.core.connectors import LabellerrS3Connection

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  # Create AWS S3 connection
  s3_connection = LabellerrS3Connection.create_connection(
      client=client,
      params=AWSConnectionParams(
          aws_access_key="your_aws_access_key",
          aws_secrets_key="your_aws_secret_key",
          path="s3://my-s3-bucket/path/to/data/",
          data_type=DatasetDataType.image,
          connection_type=ConnectionType._IMPORT,
          name="My S3 Import Connection",
          description="AWS S3 bucket for image datasets"
      )
  )

  # Create dataset using the connection
  dataset = create_dataset_from_connection(
      client=client,
      dataset_config=DatasetConfig(
          dataset_name="S3 Image Dataset",
          dataset_description="Images stored in AWS S3",
          data_type="image"
      ),
      connection=s3_connection,
      path="path/to/data/in/bucket"  # Relative path within the bucket
  )

  print(f"Dataset created with S3 connection: {dataset.dataset_id}")
  ```

  <Note>
    The SDK creates a connection to your S3 bucket and links it to the dataset. Files are accessed directly from S3 without local downloads.
  </Note>
</Card>

***

### Method 3: Create Dataset with Google Cloud Storage

<Card title="Connect GCS Bucket" icon="google">
  ```python Create Dataset with GCS lines icon="google" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.schemas import DatasetConfig, GCSConnectionParams, DatasetDataType, ConnectionType
  from labellerr.core.datasets import create_dataset_from_connection
  from labellerr.core.connectors import LabellerrGCSConnection

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  # Create GCS connection
  gcs_connection = LabellerrGCSConnection.create_connection(
      client=client,
      params=GCSConnectionParams(
          svc_account_json="path/to/service-account-key.json",
          path="gs://my-gcs-bucket/path/to/data/",
          data_type=DatasetDataType.video,
          connection_type=ConnectionType._IMPORT,
          name="My GCS Import Connection",
          description="Google Cloud Storage bucket for video datasets"
      )
  )

  # Create dataset using the connection
  dataset = create_dataset_from_connection(
      client=client,
      dataset_config=DatasetConfig(
          dataset_name="GCS Video Dataset",
          dataset_description="Videos stored in Google Cloud Storage",
          data_type="video"
      ),
      connection=gcs_connection,
      path="path/to/data/in/bucket"  # Relative path within the bucket
  )

  print(f"Dataset created with GCS connection: {dataset.dataset_id}")
  ```
</Card>

***

### Method 4: Use Existing Cloud Connection

<Card title="Reuse Connection" icon="link">
  If you've already created a cloud connection, you can reuse it for new datasets:

  ```python Create Dataset with Existing Connection lines icon="link" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.schemas import DatasetConfig
  from labellerr.core.datasets import create_dataset_from_connection
  from labellerr.core.connectors import LabellerrConnection

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  # Get existing connection
  connection = LabellerrConnection(client=client, connection_id="existing_connection_id_here")

  # Create dataset using existing connection
  dataset = create_dataset_from_connection(
      client=client,
      dataset_config=DatasetConfig(
          dataset_name="Reusing S3 Connection",
          data_type="image"
      ),
      connection=connection,
      path="path/to/data/in/bucket"
  )

  print(f"Dataset created using existing connection: {dataset.dataset_id}")
  ```

  <Note>
    **Connection Reuse:** You can create multiple datasets from the same connection by specifying different paths within your cloud storage.
  </Note>
</Card>

***

## Working with Datasets

### Retrieve an Existing Dataset

<Card title="Get Dataset by ID" icon="download">
  ```python Retrieve Dataset lines icon="download" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.datasets import LabellerrDataset

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  dataset = LabellerrDataset(client=client, dataset_id="your_dataset_id")

  # Access dataset properties
  print(f"Dataset ID: {dataset.dataset_id}")
  print(f"Data Type: {dataset.data_type}")
  print(f"Files Count: {dataset.files_count}")
  print(f"Status Code: {dataset.status_code}")
  ```

  <Info>
    **Status Codes:**

    * `300`: Dataset is ready and contains files
    * `501`: Dataset not found or invalid
  </Info>
</Card>

***

### Fetch Files from Dataset

<Card title="List Dataset Files" icon="list">
  ```python Fetch Files lines icon="list" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.datasets import LabellerrDataset

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  dataset = LabellerrDataset(client=client, dataset_id="your_dataset_id")
  files = dataset.fetch_files()

  print(f"Retrieved {len(files)} files from dataset")
  for file in files:
      print(f"File ID: {file['file_id']}, Name: {file['file_name']}")
  ```
</Card>

***

### Enable Multimodal Indexing

<Card title="Multimodal Indexing Feature" icon="brain">
  Enable advanced AI-powered multimodal indexing for your dataset to enable semantic search and intelligent file organization.

  ```python Enable Multimodal Indexing lines icon="sparkles" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.datasets import LabellerrDataset

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  dataset = LabellerrDataset(client=client, dataset_id="your_dataset_id")
  result = dataset.enable_multimodal_indexing(is_multimodal=True)

  print(f"Multimodal indexing enabled: {result}")
  ```

  <Note>
    **What is Multimodal Indexing?**

    Multimodal indexing uses AI to analyze and understand the content of your files (images, videos, audio, text) enabling:

    * Natural language search across your dataset
    * Semantic similarity detection
    * Intelligent file grouping and recommendations
    * Enhanced AI-assisted annotation workflows
  </Note>
</Card>

***

### Delete a Dataset

<Card title="Delete Dataset" icon="trash">
  ```python Delete Dataset lines icon="trash" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.datasets import LabellerrDataset

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  dataset = LabellerrDataset(client=client, dataset_id="dataset_to_delete")
  result = dataset.delete_dataset(dataset_id=dataset.dataset_id)

  print(f"Dataset deleted: {result}")
  ```

  <Warning>
    **Caution:** Deleting a dataset will remove it permanently. Ensure it's not attached to any active projects.
  </Warning>
</Card>

***

### Sync Cloud Datasets

<Card title="Synchronize Cloud Storage" icon="arrows-rotate">
  For datasets connected to cloud storage (AWS S3 or GCS), you can sync to fetch newly added files:

  ```python Sync Dataset lines icon="sync" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.datasets import LabellerrDataset

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  dataset = LabellerrDataset(client=client, dataset_id="your_dataset_id")
  result = dataset.sync_datasets(
      project=project, #pass entire object
      path="path/in/bucket",
      data_type="image",
      connection=connection #pass entire object   
  )

  print(f"Dataset synchronized: {result}")
  ```

  <Tip>
    Use this feature when new files are added to your cloud storage bucket and you want to make them available in your Labellerr dataset without creating a new dataset.
  </Tip>
</Card>

***

## Complete Workflow Example

<Card title="End-to-End Dataset Creation" icon="rocket">
  ```python Complete Dataset Workflow lines icon="rocket" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.schemas import DatasetConfig
  from labellerr.core.datasets import create_dataset_from_local, LabellerrDataset

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  # Step 1: Create dataset with local files
  dataset = create_dataset_from_local(
      client=client,
      dataset_config=DatasetConfig(
          dataset_name="Production Image Dataset",
          dataset_description="High-quality images for production annotation",
          data_type="image"
      ),
      folder_to_upload="path/to/images"
  )

  # Step 2: Wait for dataset processing to complete
  print(f"Dataset ID: {dataset.dataset_id}")
  dataset.status()  # Wait for dataset to be ready
  print(f"Files uploaded: {dataset.files_count}")

  # Step 3: Enable multimodal indexing
  indexing_result = dataset.enable_multimodal_indexing(is_multimodal=True)
  print(f"Multimodal indexing enabled: {indexing_result}")

  # Step 4: Fetch files for verification
  files = dataset.fetch_files()
  print(f"Total files in dataset: {len(files)}")

  # Now this dataset can be attached to one or more projects
  print(f"Dataset {dataset.dataset_id} is ready to be used in projects!")
  ```
</Card>

***

## Error Handling

<Card title="Best Practices for Error Handling" icon="shield">
  ```python Error Handling Example lines icon="exclamation-triangle" theme={"dark"}
  from labellerr.core.datasets import create_dataset_from_local, LabellerrDataset
  from labellerr.core.exceptions import LabellerrError

  try:
      dataset = create_dataset_from_local(
          client=client,
          dataset_config=DatasetConfig(dataset_name="Test Dataset", data_type="image"),
          folder_to_upload="path/to/folder"
      )
      print(f"Dataset created successfully: {dataset.dataset_id}")
      
      # Wait for processing to complete
      dataset.status()
      print(f"Dataset is ready with {dataset.files_count} files")
  except LabellerrError as e:
      print(f"Dataset creation failed: {str(e)}")
  ```
</Card>

***

## Troubleshooting Cloud Connections

<Warning>
  **Required Permissions**

  Before creating datasets from cloud storage, ensure your IAM user (S3) or Service Account (GCS) has the required permissions. See:

  * [AWS S3 Permissions Guide](/getting-started/connect-aws-s3)
  * [GCS Permissions Guide](/getting-started/connect-gcs)
</Warning>

### Common Issues

<Card title="Troubleshooting Reference" icon="bug">
  | Issue | Symptom | Solution |
  | - | - | - |
  | Dataset status 500 | "Dataset created successfully" but status shows 500/Failed | Connection lacks bucket permissions - test connection first |
  | "Dataset has no files" | Files exist in S3/GCS but dataset shows 0 files | IAM user/service account missing read permissions |
  | Internal server error | Error with tracking ID in UI | Check connection permissions, contact support with tracking ID |
</Card>

### Best Practice: Always Test Connection First

<Card title="Test Connection Before Creating Datasets" icon="shield-check">
  Always test your connection before creating datasets to catch permission issues early:

  ```python Test Connection theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.connectors import LabellerrConnection
  from labellerr.core.schemas import ConnectionType, DatasetDataType

  # Initialize client
  client = LabellerrClient(api_key, api_secret, client_id)

  # Get your existing connection
  connection = LabellerrConnection(client=client, connection_id="your_connection_id")

  # Test the connection on your specific path
  test_result = connection.test(
      path="s3://your-bucket/path/to/data/",  # or gs:// for GCS
      connection_type=ConnectionType._IMPORT,
      data_type=DatasetDataType.image
  )
  print(f"Connection test: {test_result}")
  ```

  <Note>
    **Path Formats:**

    * AWS S3: `s3://bucket-name/path/to/folder/`
    * GCS: `gs://bucket-name/path/to/folder/`
  </Note>
</Card>

### Checking Dataset Status After Creation

<Card title="Verify Dataset Status" icon="circle-check">
  Always check dataset status after creation to ensure it processed successfully:

  ```python Check Dataset Status theme={"dark"}
  from labellerr.core.datasets import create_dataset_from_connection

  # Create dataset
  dataset = create_dataset_from_connection(
      client=client,
      dataset_config=dataset_config,
      connection=connection,
      path="s3://your-bucket/path/to/data/"
  )
  print(f"Dataset ID: {dataset.dataset_id}")

  # Check status - this waits for processing to complete
  dataset.status()

  # Verify status code
  print(f"Status Code: {dataset.status_code}")
  print(f"Files Count: {dataset.files_count}")

  # Status codes:
  # 300 = Ready (success)
  # 500 = Failed (usually permissions issue)
  ```

  <Warning>
    If `status_code` is **500**, the dataset creation failed. This is usually due to:

    1. Missing bucket permissions on the IAM user/service account
    2. Invalid path format
    3. Bucket doesn't exist or is inaccessible

    Check the connection permissions and test the connection before retrying.
  </Warning>
</Card>

***

## Common Use Cases

<CardGroup>
  <Card title="Reusable Training Data" icon="recycle">
    Create a master dataset of training images that can be used across multiple annotation projects with different labeling requirements.
  </Card>

  <Card title="Cloud Storage Integration" icon="cloud">
    Connect your existing AWS S3 or GCS buckets to avoid data duplication and manage files directly from cloud storage.
  </Card>

  <Card title="Multi-Project Workflows" icon="sitemap">
    Use the same dataset for different annotation tasks - object detection in one project, segmentation in another.
  </Card>

  <Card title="Incremental Data Addition" icon="plus">
    Sync cloud datasets to continuously add new data to ongoing projects without manual uploads.
  </Card>
</CardGroup>

***

## Dataset Configuration Reference

<Card title="DatasetConfig Parameters" icon="list">
  | Parameter | Type | Required | Description | Example Value |
  | - | - | - | - | - |
  | dataset\_name | String | Yes | Name of the dataset | "Training Images 2024" |
  | data\_type | String | Yes | Type of data in dataset | "image", "video", "audio", "document", "text" |
  | dataset\_description | String | No | Description of dataset contents | "Customer-provided training data" |
  | connector\_type | String | No | Type of connector (default: "local") | "local", "aws", "gcp" |
</Card>

***

## Related Documentation

<CardGroup>
  <Card title="Create Projects" icon="folder-plus" href="/sdk/create-project-sdk">
    Learn how to create projects using standalone datasets
  </Card>

  <Card title="Retrieve Datasets" icon="download" href="/sdk/retrieve-projects-datasets-sdk">
    View and manage existing datasets and projects
  </Card>

  <Card title="Getting Started" icon="rocket" href="/sdk/getting-started">
    SDK installation and initialization guide
  </Card>
</CardGroup>

<Note>
  For technical support, contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Create Exports
Source: https://docs.labellerr.com/sdk/create-export-sdk

Learn how to use the Labellerr SDK to export project data locally or to AWS S3 in various formats, check export status, and fetch downloadable URLs.

### Local Export

The SDK provides functionality to export project data locally. This feature allows you to export annotations in various formats for further analysis or backup purposes.

**The export created will be available in the exports section of Labellerr dashboard. Here is where you can find the** [**export in our tool**](/actions/create-export)**.**

#### Acceptable values:

* **statuses**: File workflow statuses to include in the export
  * `None`, `'assigned'`, `'review'`, `'r_assigned'`, `'client_review'`, `'cr_assigned'`, `'accepted'`, `'rejected'`, `'client_rejected'`, `'skipped'`, `'r_skipped'`, `'cr_skipped'`, `'critical'`, `'r_critical'`, `'cr_critical'`
* **export\_format**: Output format for the exported data
  * `'json'`, `'coco_json'`, `'csv'`, `'png'`

<Accordion title="What do these status values mean?" icon="circle-info">
  **File Status Definitions:**

  * **`None`** - Unlabeled or pre-annotated files that haven't entered the annotation workflow yet
  * **`assigned`** - Files assigned to an annotator, annotation work is in progress
  * **`review`** - Files ready for review (passed annotation phase)
  * **`r_assigned`** - Files assigned to a reviewer, review work is in progress
  * **`client_review`** - Files that have passed internal review and are now in client review stage
  * **`cr_assigned`** - Files assigned for client review, client review work is in progress
  * **`accepted`** - Files that have completed all stages and passed by client (final approved state)
  * **`rejected`** - Files rejected by the reviewer during review stage
  * **`client_rejected`** - Files rejected by the client during client review stage
  * **`skipped`** - Files skipped by the annotator during annotation stage
  * **`r_skipped`** - Files skipped by the reviewer during review stage
  * **`cr_skipped`** - Files skipped by the client during client review stage
  * **`critical`** - Files skipped 2 times in annotation stage, will go into blocked state
  * **`r_critical`** - Files skipped 2 times in review stage, will go into blocked state
  * **`cr_critical`** - Files skipped 2 times in client review stage, will go into blocked state

  **Tip:** You can include multiple statuses in your export to capture files at different stages of your annotation workflow.
</Accordion>

#### Example Usage:

```python Local Export Example lines icon="download" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.schemas import CreateExportParams
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

project_id = 'your_project_id'

try:
    # Get project instance
    project = LabellerrProject(client=client, project_id=project_id)
    
    # Create export configuration using CreateExportParams
    export_config = CreateExportParams(
        export_name="Weekly Export",
        export_description="Export of all accepted annotations",
        export_format="coco_json",
        statuses=['review', 'r_assigned','client_review', 'cr_assigned','accepted']
    )
    
    # Create export
    export = project.create_export(export_config)
    print(f"Local export created successfully. Export ID: {export.report_id}")
    
    # Optionally wait for completion
    export.status()  # Polls until export is complete
    
except LabellerrError as e:
    print(f"Local export creation failed: {str(e)}")
```

**Note**: The export process creates a downloadable file link of your project's annotations based on the specified status filters. This is useful for backup purposes or when you need to process the annotations offline.

***

### S3 Export

The SDK also provides functionality to export project data directly to AWS S3 buckets. This feature allows you to export annotations in various formats directly to your S3 storage for automated workflows, backup, or integration with other systems.

**The export created will be available in the exports section of Labellerr dashboard. Here is where you can find the** [**export in our tool**](/actions/create-export)**.**

#### Prerequisites:

Before creating an S3 export, you need to:

1. Create an AWS S3 connection using your AWS credentials
2. Get the `connection_id` from the created connection

#### Example Usage:

```python S3 Export Example lines icon="cloud-arrow-up" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.connectors import LabellerrS3Connection
from labellerr.core.schemas import AWSConnectionParams, CreateExportParams
from labellerr.core.exceptions import LabellerrError

client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

# Create S3 connection
connection = LabellerrS3Connection.create_connection(
    client=client,
    params=AWSConnectionParams(
        aws_access_key="your_aws_access_key",
        aws_secrets_key="your_aws_secret_key",
        name="S3 Export Connection",
        description="Connection for exporting annotations to S3"
    )
)

# Create S3 export
project = LabellerrProject(client=client, project_id='your_project_id')
export = project.create_export(
    CreateExportParams(
        export_name="S3 Weekly Export",
        export_description="Export of all accepted annotations to S3",
        export_format="coco_json",
        statuses=['review', 'r_assigned', 'client_review', 'cr_assigned', 'accepted'],
        export_destination="s3",
        connection_id=connection.connection_id,
        export_folder_path="bucket_name/path/to/folder/"  # trailing slash is important
    )
)

print(f"Export ID: {export.report_id}")
export.status()  # Poll until completion
```

**Important Notes**:

* The `export_folder_path` should follow the pattern: `bucket_name/path/to/folder/` (the trailing slash is important)
* Make sure your AWS credentials have write permissions to the specified S3 bucket
* You can reuse the same `connection_id` for multiple exports without creating a new connection each time
* The export will be uploaded directly to your S3 bucket at the specified path

***

### List All Exports

The SDK provides functionality to retrieve all exports associated with a project. This method returns both completed and in-progress exports, making it easy to track and manage your export history.

#### Example Usage:

```python List All Exports Example lines icon="list" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

project_id = 'your_project_id'

try:
    # Get project instance
    project = LabellerrProject(client=client, project_id=project_id)
    
    # List all exports for the project
    exports = project.list_exports()
    
    print(f"Completed exports: {len(exports.completed)}")
    print(f"In-progress exports: {len(exports.in_progress)}")
    
    # Access individual completed exports
    for export in exports.completed:
        print(f"Export ID: {export.get('report_id')}")
        print(f"  Name: {export.get('export_name')}")
        print(f"  Status: {export.get('export_status')}")
        print(f"  Created: {export.get('created_at')}")
    
    # Access in-progress exports
    for export in exports.in_progress:
        print(f"In-progress Export ID: {export.get('report_id')}")
        print(f"  Name: {export.get('export_name')}")
        
except LabellerrError as e:
    print(f"Failed to list exports: {str(e)}")
```

**Response Structure:**

The `list_exports()` method returns an `ExportsListResponse` object with two properties:

* `completed`: List of all completed exports
* `in_progress`: List of all exports currently being processed

**Use Cases:**

* Track export history for a project
* Find specific export IDs for status checks or downloads
* Monitor ongoing export operations
* Audit export activities
* Automate export management workflows

***

### Incremental Export with Timestamp Filtering

<Note>
  **New Feature**: Filter files based on their last updated time to create incremental exports!
</Note>

You can now filter files based on their last updated timestamp when creating exports. This powerful feature enables incremental backups where only files modified after a specific time are exported, significantly reducing export size and processing time.

#### Key Features:

* **Timestamp Format**: Unix timestamp in milliseconds
* **Filter Criteria**: Files updated after the specified timestamp
* **Works with**: Both local and S3 export destinations
* **Optional Parameter**: When not provided, all files matching status criteria are exported

#### Example Usage - Incremental Local Export:

```python Incremental Export Example lines icon="clock-rotate-left" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.schemas import CreateExportParams
from labellerr.core.exceptions import LabellerrError
import time

# Initialize the client
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

project = LabellerrProject(client=client, project_id='your_project_id')

# Calculate timestamp for 7 days ago (in milliseconds)
seven_days_ago = int((time.time() - 7*24*60*60) * 1000)

try:
    # Create export with timestamp filter
    export_config = CreateExportParams(
        export_name="Weekly Incremental Export",
        export_description="Export files updated in last 7 days",
        export_format="coco_json",
        statuses=['review', 'accepted'],
        updated_after_timestamp=seven_days_ago  # Only files updated after this time
    )
    
    export = project.create_export(export_config)
    print(f"Export created with ID: {export.report_id}")
    
    # Wait for export to complete
    final_status = export.status()
    print(f"Export completed: {final_status}")
    
except LabellerrError as e:
    print(f"Export creation failed: {str(e)}")
```

#### Example Usage - Incremental S3 Export:

```python Incremental S3 Export Example lines icon="cloud" theme={"dark"}
from labellerr.core.schemas import CreateExportParams, ExportDestination
from datetime import datetime
import time

# Get timestamp for midnight today (in milliseconds)
today = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
today_midnight = int(today.timestamp() * 1000)

# Create incremental S3 export
export_config = CreateExportParams(
    export_name="Daily Incremental S3 Export",
    export_description="Export only files modified today",
    export_format="json",
    statuses=['accepted'],
    export_destination=ExportDestination.S3,
    connection_id="your_s3_connection_id",
    export_folder_path="bucket_name/exports/daily/",
    updated_after_timestamp=today_midnight  # Only files updated today
)

export = project.create_export(export_config)
print(f"S3 incremental export started: {export.report_id}")
```

#### Practical Use Cases:

<CardGroup>
  <Card title="Incremental Backups" icon="floppy-disk">
    Export only files modified since your last backup, reducing storage and bandwidth
  </Card>

  <Card title="Daily/Weekly Exports" icon="calendar">
    Automate exports for specific time windows (last 24 hours, last week, etc.)
  </Card>

  <Card title="Change Tracking" icon="timeline">
    Monitor and export recently modified annotations for quality control
  </Card>

  <Card title="Workflow Automation" icon="robot">
    Create automated pipelines that process only recent changes
  </Card>
</CardGroup>

**Important Notes:**

* The timestamp must be in **milliseconds** (multiply seconds by 1000)
* The filter is based on the file's "last updated time" in the system
* Combines with status filters - only files matching both criteria are exported
* Works seamlessly with both local and S3 export destinations

**Timestamp Conversion Examples:**

```python theme={"dark"}
import time
from datetime import datetime, timedelta

# Current time in milliseconds
now_ms = int(time.time() * 1000)

# 24 hours ago
yesterday = int((time.time() - 24*60*60) * 1000)

# Specific date and time
specific_date = datetime(2024, 12, 17, 0, 0, 0)
specific_timestamp = int(specific_date.timestamp() * 1000)

# Last Monday midnight
today = datetime.now()
days_since_monday = (today.weekday() - 0) % 7
last_monday = today - timedelta(days=days_since_monday)
last_monday_midnight = last_monday.replace(hour=0, minute=0, second=0, microsecond=0)
last_monday_ms = int(last_monday_midnight.timestamp() * 1000)
```

***

### Check Export Status

This method allows users to check the export status of a previously triggered export task (both local and S3 exports). The status will indicate whether the export is still processing, completed, or failed. For local exports, if successful, the function also sends the downloadable file link URL with its expiration time and status. For S3 exports, it indicates when the export has been successfully uploaded to your S3 bucket.

#### Example Usage :

```python Check Export Status Example lines icon="magnifying-glass" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

# Example input
project_id = 'your_project_id'
report_ids = ['export_report_id_1', 'export_report_id_2']

try:
    # Get project instance
    project = LabellerrProject(client=client, project_id=project_id)
    
    # Check export status
    status = project.check_export_status(
        report_ids=report_ids
    )
    
    print(status)
except LabellerrError as e:
    print(f"Failed to check export status: {str(e)}")
```

***

### Fetch Export Download URL

This endpoint is used to fetch the **downloadable link** for a previously created **local export** using the export's UUID and report ID. The response includes a signed URL from which the export file can be downloaded with the time left to expire.

**Note**: This method is only applicable for local exports. For S3 exports, the files are directly uploaded to your S3 bucket at the specified path.

#### Example Usage :

```python Fetch Download URL Example lines icon="link" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.exceptions import LabellerrError
import uuid

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

project_id = 'your_project_id'
report_ids = ['export_report_id']  # make sure it is a list
request_uuid = str(uuid.uuid4())

try:
    download_url = client.fetch_download_url(
        project_id=project_id,
        uuid=request_uuid,
        export_id=report_ids[0]
    )
    print(f"Download URL: {download_url}")
except LabellerrError as e:
    print(f"Failed to fetch download URL: {str(e)}")
```

***

## Export Management Features Summary

<CardGroup>
  <Card title="List All Exports" icon="list" href="#list-all-exports">
    Retrieve all completed and in-progress exports for your project
  </Card>

  <Card title="Incremental Exports" icon="clock-rotate-left" href="#incremental-export-with-timestamp-filtering">
    Filter files by timestamp for efficient incremental backups
  </Card>

  <Card title="Local Export" icon="download" href="#local-export">
    Export annotations to downloadable files
  </Card>

  <Card title="S3 Export" icon="cloud" href="#s3-export">
    Export directly to AWS S3 buckets
  </Card>

  <Card title="Export Status" icon="magnifying-glass" href="#check-export-status">
    Monitor export progress with automatic download URLs
  </Card>

  <Card title="Download URLs" icon="link" href="#fetch-export-download-url">
    Fetch signed download links for completed exports
  </Card>
</CardGroup>

***

## Quick Reference

### Export Formats

| Format | Description | Use Case |
| - | - | - |
| `json` | Standard JSON format | General purpose, easy to parse |
| `coco_json` | COCO dataset format | Computer vision, object detection |
| `csv` | Comma-separated values | Spreadsheet analysis, reports |
| `png` | Image format | Visual verification, masks |

### Export Statuses

| Status | Description |
| - | - |
| `review` | Files in review stage |
| `r_assigned` | Files assigned for review |
| `client_review` | Files in client review |
| `cr_assigned` | Files assigned for client review |
| `accepted` | Accepted/completed files |

### Common Timestamp Calculations

```python theme={"dark"}
import time
from datetime import datetime, timedelta

# Last 24 hours
yesterday = int((time.time() - 86400) * 1000)

# Last 7 days
week_ago = int((time.time() - 7*86400) * 1000)

# Last 30 days
month_ago = int((time.time() - 30*86400) * 1000)

# Start of today
today = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
today_start = int(today.timestamp() * 1000)

# Start of this week (Monday)
days_since_monday = (datetime.now().weekday() - 0) % 7
week_start = datetime.now() - timedelta(days=days_since_monday)
week_start = week_start.replace(hour=0, minute=0, second=0, microsecond=0)
week_start_ms = int(week_start.timestamp() * 1000)
```

***


# Create Projects
Source: https://docs.labellerr.com/sdk/create-project-sdk

Complete guide to creating annotation projects in Labellerr using the Python SDK with datasets, templates, and configuration.

## Overview

A **project** in Labellerr combines datasets with annotation guidelines to create a structured workflow for your team. This guide covers everything you need to create projects programmatically using the SDK.

<Card title="Project Creation Requirements" icon="circle-info">
  To create a project, you need three components:

  1. **Dataset(s)** - One or more datasets containing your files
  2. **Annotation Template** - Questions and labels defining your annotation schema
  3. **Project Configuration** - Settings for rotations, AI features, and workflow rules

  All components use validated schemas to catch errors before making API calls.
</Card>

<Card title="Supported Data Types" icon="database">
  * **image** - .jpg, .jpeg, .png, .bmp, .tiff
  * **video** - .mp4
  * **audio** - .mp3, .wav
  * **document** - .pdf
  * **text** - .txt
</Card>

***

## Quick Start

Here's the minimal code to create a project:

```python theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.datasets import create_dataset_from_local
from labellerr.core.annotation_templates import create_template
from labellerr.core.projects import create_project
from labellerr.core.schemas import *
import uuid

# Initialize client
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

# 1. Create dataset
dataset = create_dataset_from_local(
    client=client,
    dataset_config=DatasetConfig(dataset_name="My Dataset", data_type="image"),
    folder_to_upload="path/to/images"
)

# Wait for dataset to be ready
dataset.status()  # Polls until dataset processing is complete

# 2. Create annotation template
template = create_template(
    client=client,
    params=CreateTemplateParams(
        template_name="My Template",
        data_type=DatasetDataType.image,
        questions=[
            AnnotationQuestion(
                question_number=1,
                question="Object",
                question_id=str(uuid.uuid4()),
                question_type=QuestionType.bounding_box,
                required=True,
                color="#FF0000"
            )
        ]
    )
)

# 3. Create project
project = create_project(
    client=client,
    params=CreateProjectParams(
        project_name="My Project",
        data_type=DatasetDataType.image,
        rotations=RotationConfig(
            annotation_rotation_count=1,
            review_rotation_count=1,
            client_review_rotation_count=1
        )
    ),
    datasets=[dataset],
    annotation_template=template
)

print(f"✓ Project created: {project.project_id}")
```

***

## Step-by-Step Guide

### Step 1: Prepare Your Dataset

You can either create a new dataset or use an existing one.

<Tabs>
  <Tab title="Create New Dataset">
    ```python theme={"dark"}
    from labellerr.core.datasets import create_dataset_from_local
    from labellerr.core.schemas import DatasetConfig

    # From local folder
    dataset = create_dataset_from_local(
        client=client,
        dataset_config=DatasetConfig(
            dataset_name="Training Images",
            data_type="image"
        ),
        folder_to_upload="path/to/images"
    )

    # Wait for dataset processing to complete
    dataset.status()
    ```
  </Tab>

  <Tab title="Use Existing Dataset">
    ```python theme={"dark"}
    from labellerr.core.datasets import LabellerrDataset

    # Reference existing dataset by ID
    dataset = LabellerrDataset(
        client=client,
        dataset_id="your_dataset_id"
    )
    ```
  </Tab>
</Tabs>

***

### Step 2: Create Annotation Template

Define the questions your annotators will answer.

<Tabs>
  <Tab title="Simple Template">
    ```python theme={"dark"}
    from labellerr.core.annotation_templates import create_template
    from labellerr.core.schemas import *
    import uuid

    # Single bounding box question
    template = create_template(
        client=client,
        params=CreateTemplateParams(
            template_name="Object Detection",
            data_type=DatasetDataType.image,
            questions=[
                AnnotationQuestion(
                    question_number=1,
                    question="Detect Vehicle",
                    question_id=str(uuid.uuid4()),
                    question_type=QuestionType.bounding_box,
                    required=True,
                    color="#00FF00"
                )
            ]
        )
    )
    ```
  </Tab>

  <Tab title="Multiple Questions">
    ```python theme={"dark"}
    from labellerr.core.annotation_templates import create_template
    from labellerr.core.schemas import *
    import uuid

    questions = [
        # Object detection
        AnnotationQuestion(
            question_number=1,
            question="Vehicle",
            question_id=str(uuid.uuid4()),
            question_type=QuestionType.bounding_box,
            required=True,
            color="#FF0000"
        ),
        # Dropdown classification
        AnnotationQuestion(
            question_number=2,
            question="Vehicle Type",
            question_id=str(uuid.uuid4()),
            question_type=QuestionType.dropdown,
            required=True,
            options=[
                Option(option_name="Car"),
                Option(option_name="Truck"),
                Option(option_name="Motorcycle")
            ]
        ),
        # Yes/No question
        AnnotationQuestion(
            question_number=3,
            question="Good Image Quality?",
            question_id=str(uuid.uuid4()),
            question_type=QuestionType.boolean,
            required=False,
            options=[
                Option(option_name="Yes"),
                Option(option_name="No")
            ]
        )
    ]

    template = create_template(
        client=client,
        params=CreateTemplateParams(
            template_name="Detailed Vehicle Detection",
            data_type=DatasetDataType.image,
            questions=questions
        )
    )
    ```
  </Tab>

  <Tab title="Use Existing Template">
    ```python theme={"dark"}
    from labellerr.core.annotation_templates import LabellerrAnnotationTemplate

    # Reference existing template
    template = LabellerrAnnotationTemplate(
        client=client,
        annotation_template_id="your_template_id"
    )
    ```
  </Tab>
</Tabs>

***

### Step 3: Configure & Create Project

Now combine your dataset and template to create the project.

```python theme={"dark"}
from labellerr.core.projects import create_project
from labellerr.core.schemas import CreateProjectParams, RotationConfig, DatasetDataType

project = create_project(
    client=client,
    params=CreateProjectParams(
        project_name="Vehicle Detection Project",
        data_type=DatasetDataType.image,
        rotations=RotationConfig(
            annotation_rotation_count=1,  # Each file annotated once
            review_rotation_count=1,      # Reviewed once
            client_review_rotation_count=1  # Client review once
        ),
        use_ai=False,  # Optional: Enable AI assistance
        created_by="YOUR_EMAIL@company.com"  # Optional: Creator email
    ),
    datasets=[dataset],
    annotation_template=template
)

# Access project details
print(f"Project ID: {project.project_id}")
print(f"Data Type: {project.data_type}")
print(f"Template: {project.annotation_template_id}")
print(f"Datasets: {project.attached_datasets}")
```

***

## Common Scenarios

### Using Multiple Datasets

Attach multiple datasets to a single project for larger annotation workflows:

<Warning>
  **Homogeneous Data Requirement**

  All datasets attached to a single project **must be of the same data type** (e.g., all `image`, all `video`, etc.). You cannot mix different data types in the same project.
</Warning>

```python theme={"dark"}
from labellerr.core.datasets import LabellerrDataset

# Get multiple existing datasets
dataset1 = LabellerrDataset(client=client, dataset_id="dataset_id_1")
dataset2 = LabellerrDataset(client=client, dataset_id="dataset_id_2")
dataset3 = LabellerrDataset(client=client, dataset_id="dataset_id_3")

# Ensure all datasets are ready
for dataset in [dataset1, dataset2, dataset3]:
    dataset.status()

# Create project with all datasets
project = create_project(
    client=client,
    params=CreateProjectParams(
        project_name="Large Scale Annotation",
        data_type=DatasetDataType.image,
        rotations=RotationConfig(1, 1, 1)
    ),
    datasets=[dataset1, dataset2, dataset3],  # List of datasets
    annotation_template=template
)
```

***

### Multiple Annotation Rotations

For high-quality annotations, require multiple annotators per file:

```python theme={"dark"}
project = create_project(
    client=client,
    params=CreateProjectParams(
        project_name="High Quality Annotations",
        data_type=DatasetDataType.image,
        rotations=RotationConfig(
            annotation_rotation_count=3,  # 3 annotators per file
            review_rotation_count=2,      # 2 reviewers per file
            client_review_rotation_count=1
        )
    ),
    datasets=[dataset],
    annotation_template=template
)
```

***

### Video Project with Keyframes

For video annotation projects:

```python theme={"dark"}
from labellerr.core.schemas import DatasetDataType

# Create video dataset
video_dataset = create_dataset_from_local(
    client=client,
    dataset_config=DatasetConfig(
        dataset_name="Traffic Videos",
        data_type="video"
    ),
    folder_to_upload="path/to/videos"
)

# Wait for dataset processing to complete
video_dataset.status()

# Create video template
video_template = create_template(
    client=client,
    params=CreateTemplateParams(
        template_name="Vehicle Tracking",
        data_type=DatasetDataType.video,
        questions=[
            AnnotationQuestion(
                question_number=1,
                question="Track Vehicle",
                question_id=str(uuid.uuid4()),
                question_type=QuestionType.bounding_box,
                required=True,
                color="#FF0000"
            )
        ]
    )
)

# Create video project
video_project = create_project(
    client=client,
    params=CreateProjectParams(
        project_name="Vehicle Tracking Project",
        data_type=DatasetDataType.video,
        rotations=RotationConfig(1, 1, 1)
    ),
    datasets=[video_dataset],
    annotation_template=video_template
)
```

***

## Schema Reference

### CreateProjectParams

<Card title="Project Configuration Parameters" icon="list">
  | Parameter | Type | Required | Description | Example |
  | - | - | - | - | - |
  | `project_name` | str | Yes | Display name for your project | "Vehicle Detection" |
  | `data_type` | DatasetDataType | Yes | Type of data being annotated | DatasetDataType.image |
  | `rotations` | RotationConfig | Yes | Annotation and review cycle settings | RotationConfig(1, 1, 1) |
  | `use_ai` | bool | No | Enable AI-assisted annotation | True / False (default) |
  | `created_by` | str | No | Email of project creator | "[YOUR\_EMAIL@company.com](mailto:YOUR_EMAIL@company.com)" |

  <Note>
    The `data_type` must match the data type of all attached datasets.
  </Note>
</Card>

***

### RotationConfig

<Card title="Rotation Configuration" icon="arrows-rotate">
  Defines how many times each file goes through annotation and review cycles.

  **Constructor:**

  ```python theme={"dark"}
  RotationConfig(
      annotation_rotation_count: int,
      review_rotation_count: int,
      client_review_rotation_count: int
  )
  ```

  | Parameter | Type | Min Value | Description |
  | - | - | - | - |
  | `annotation_rotation_count` | int | 1 | Number of annotators per file |
  | `review_rotation_count` | int | 1 | Number of reviewers per file |
  | `client_review_rotation_count` | int | 1 | Number of client reviewers |

  **Examples:**

  ```python theme={"dark"}
  # Standard workflow: 1 annotator, 1 reviewer
  RotationConfig(1, 1, 1)

  # High quality: 3 annotators, 2 reviewers
  RotationConfig(3, 2, 1)

  # Review-focused: 1 annotator, 3 reviewers
  RotationConfig(1, 3, 1)
  ```

  <Tip>
    Higher rotation counts improve annotation quality but increase project time and cost. Balance based on your accuracy requirements.
  </Tip>

  <Warning>
    **Free User Rotation Limitations**

    For users on the **Free Plan**, rotation configuration is limited to the basic workflow:

    **Available Configuration:**

    * `RotationConfig(1, 1, 1)` - Only 1:1:1 rotation is available

    This means:

    * ✅ 1 annotator per file
    * ✅ 1 reviewer per file
    * ✅ 1 client reviewer per file

    **Upgrade for Advanced Rotations:**

    * `RotationConfig(3, 2, 1)` - Requires paid plan
    * `RotationConfig(2, 2, 1)` - Requires paid plan
    * Any configuration with values > 1 - Requires paid plan

    To unlock higher rotation counts and improve annotation quality through multiple annotators/reviewers, please upgrade your plan.
  </Warning>
</Card>

***

### QuestionType Enum

<Card title="Available Question Types" icon="question">
  Choose the appropriate question type for your annotation needs.

  <Tip>
    **New to annotation types?** Learn more about each annotation type with visual examples in our [Annotation Types Guide](https://docs.labellerr.com/actions/annotations-guide#these-are-the-annotation-types-that-you-can-use-on-labellerr).
  </Tip>

  **Object-Based Questions (Drawing):**

  | Type | Value | Use Case | Requires Color |
  | - | - | - | - |
  | `QuestionType.bounding_box` | "BoundingBox" | Rectangular object detection | ✅ Yes |
  | `QuestionType.polygon` | "polygon" | Irregular shape segmentation | ✅ Yes |
  | `QuestionType.polyline` | "polyline" | Line/path annotation | ✅ Yes |
  | `QuestionType.dot` | "dot" | Point marking (landmarks, keypoints) | ✅ Yes |

  **Classification Questions (Selection):**

  | Type | Value | Use Case | Requires Options |
  | - | - | - | - |
  | `QuestionType.dropdown` | "dropdown" | Single selection from many options | ✅ Yes |
  | `QuestionType.radio` | "radio" | Single selection with visible options | ✅ Yes |
  | `QuestionType.select` | "select" | Multiple selections allowed | ✅ Yes |
  | `QuestionType.boolean` | "boolean" | Yes/No or True/False questions | ✅ Yes (2 options) |
  | `QuestionType.input` | "input" | Free text entry | ❌ No |

  **Example Usage:**

  ```python theme={"dark"}
  # Object detection (requires color)
  AnnotationQuestion(
      question_type=QuestionType.bounding_box,
      color="#FF0000",  # Required for object types
      ...
  )

  # Classification (requires options)
  AnnotationQuestion(
      question_type=QuestionType.dropdown,
      options=[  # Required for classification types
          Option(option_name="Option 1"),
          Option(option_name="Option 2")
      ],
      ...
  )

  # Text input (no options needed)
  AnnotationQuestion(
      question_type=QuestionType.input,
      # No color or options required
      ...
  )
  ```
</Card>

***

## Import Users from Another Project

Copy the user list (with roles/permissions) from one project to another in the same workspace-existing users are not duplicated.

```python theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
import os

# Initialize client
client = LabellerrClient(
    api_key=os.getenv("API_KEY"),
    api_secret=os.getenv("API_SECRET"),
    client_id=os.getenv("CLIENT_ID"),
)

# Target project (already created)
target_project = LabellerrProject(
    client=client,
    project_id="your_target_project_id",
)

# Source project to import users from
source_project = LabellerrProject(
    client=client,
    project_id=os.getenv("IMPORT_USERS_FROM_PROJECT_ID"),
)

# Import users (roles/permissions preserved; no duplicates)
target_project.import_users(from_project=source_project)
print("Users imported successfully")
```

<Info>
  * Same-workspace only; roles/permissions are preserved.
  * If a user already exists in the target project, they are not duplicated.
</Info>

***

## Complete End-to-End Example

Here's a production-ready example with error handling:

```python theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.datasets import create_dataset_from_local
from labellerr.core.annotation_templates import create_template
from labellerr.core.projects import create_project
from labellerr.core.schemas import *
from labellerr.core.exceptions import LabellerrError
import uuid

def create_annotation_project():
    """Create a complete annotation project from scratch."""
    
    # Initialize client
    client = LabellerrClient(
        api_key='your_api_key',
        api_secret='your_api_secret',
        client_id='your_client_id'
    )
    
    try:
        # Step 1: Create dataset
        print("📦 Creating dataset...")
        dataset = create_dataset_from_local(
            client=client,
            dataset_config=DatasetConfig(
                dataset_name="Production Images Q1 2024",
                dataset_description="Customer submitted images for annotation",
                data_type="image"
            ),
            folder_to_upload="data/images"
        )
        print(f"   ✓ Dataset created: {dataset.dataset_id}")
        print(f"   Files count: {dataset.files_count}")
        
        # Wait for dataset processing to complete
        print("\n⏳ Waiting for dataset to be ready...")
        dataset.status()
        print("   ✓ Dataset is ready!")
        
        # Step 2: Create annotation template
        print("\n📋 Creating annotation template...")
        questions = [
            AnnotationQuestion(
                question_number=1,
                question="Vehicle Detection",
                question_id=str(uuid.uuid4()),
                question_type=QuestionType.bounding_box,
                required=True,
                color="#FF5733"
            ),
            AnnotationQuestion(
                question_number=2,
                question="Vehicle Category",
                question_id=str(uuid.uuid4()),
                question_type=QuestionType.dropdown,
                required=True,
                options=[
                    Option(option_name="Sedan"),
                    Option(option_name="SUV"),
                    Option(option_name="Truck"),
                    Option(option_name="Van"),
                    Option(option_name="Motorcycle")
                ]
            ),
            AnnotationQuestion(
                question_number=3,
                question="Image Clear?",
                question_id=str(uuid.uuid4()),
                question_type=QuestionType.radio,
                required=True,
                options=[
                    Option(option_name="Clear"),
                    Option(option_name="Blurry"),
                    Option(option_name="Dark")
                ]
            )
        ]
        
        template = create_template(
            client=client,
            params=CreateTemplateParams(
                template_name="Vehicle Detection Template Q1",
                data_type=DatasetDataType.image,
                questions=questions
            )
        )
        print(f"   ✓ Template created: {template.annotation_template_id}")
        
        # Step 3: Create project
        print("\n🚀 Creating project...")
        project = create_project(
            client=client,
            params=CreateProjectParams(
                project_name="Vehicle Detection - Q1 2024",
                data_type=DatasetDataType.image,
                rotations=RotationConfig(
                    annotation_rotation_count=2,  # Double annotation for quality
                    review_rotation_count=1,
                    client_review_rotation_count=1
                ),
                use_ai=True,  # Enable AI assistance
                created_by="YOUR_EMAIL@company.com"  # Replace with actual email
            ),
            datasets=[dataset],
            annotation_template=template
        )
        
        print(f"\n{'='*60}")
        print(f"✅ PROJECT CREATED SUCCESSFULLY")
        print(f"{'='*60}")
        print(f"Project ID:       {project.project_id}")
        print(f"Project Name:     Vehicle Detection - Q1 2024")
        print(f"Data Type:        {project.data_type}")
        print(f"Template ID:      {project.annotation_template_id}")
        print(f"Datasets:         {len(project.attached_datasets)}")
        print(f"{'='*60}")
        
        return project
        
    except LabellerrError as e:
        print(f"\n❌ Error creating project: {str(e)}")
        raise
    except Exception as e:
        print(f"\n❌ Unexpected error: {str(e)}")
        raise

# Run the function
if __name__ == "__main__":
    project = create_annotation_project()
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Dataset has no files error" icon="circle-exclamation">
    **Error:** `Dataset {dataset_id} has no files`

    **Cause:** The dataset was created but files haven't finished uploading or processing.

    **Solution:**

    * Always call `dataset.status()` before creating a project to ensure dataset is ready
    * This method polls until dataset processing is complete

    ```python theme={"dark"}
    dataset = create_dataset_from_local(...)
    dataset.status()  # Wait for completion
    project = create_project(...)  # Now safe to create
    ```

    * Verify folder path is correct and contains files
    * Check `dataset.files_count` to confirm files were uploaded
  </Accordion>

  <Accordion title="Data type mismatch" icon="exclamation-triangle">
    **Error:** Data type conflicts between project, dataset, and template

    **Solution:**

    * Ensure all components use the same data type:

    ```python theme={"dark"}
    # All must match
    dataset_config = DatasetConfig(data_type="image")
    template_params = CreateTemplateParams(data_type=DatasetDataType.image)
    project_params = CreateProjectParams(data_type=DatasetDataType.image)
    ```
  </Accordion>

  <Accordion title="Template creation fails" icon="file-circle-xmark">
    **Cause:** Missing required fields in questions (color for objects, options for classifications)

    **Solution:**

    * Object types require `color` field
    * Classification types require `options` list
    * Use `required=True` for mandatory questions
  </Accordion>

  <Accordion title="Authentication errors" icon="lock">
    **Solution:**

    * Verify API key and secret are correct
    * Check key hasn't expired
    * Ensure you have permissions to create projects
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Create Dataset" icon="database" href="/sdk/create-dataset-sdk">
    Learn how to create and manage datasets
  </Card>

  <Card title="Annotation Questions" icon="circle-question" href="/sdk/add-annotation-questions">
    Detailed guide on crafting annotation questions
  </Card>

  <Card title="Upload Pre-annotations" icon="upload" href="/sdk/upload-preannotation-sdk">
    Import existing annotations into your project
  </Card>

  <Card title="Export Annotations" icon="download" href="/sdk/create-export-sdk">
    Export completed annotations in various formats
  </Card>

  <Card title="Video Operations" icon="video" href="/sdk/video-project-operations-sdk">
    Special operations for video projects
  </Card>

  <Card title="Getting Started" icon="rocket" href="/sdk/getting-started">
    SDK installation and initialization guide
  </Card>
</CardGroup>

***

## Need Help?

<Note>
  For technical support or questions about project creation, contact us at [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Getting Started
Source: https://docs.labellerr.com/sdk/getting-started

Learn how to install and initialize the Labellerr SDK, a Python library for seamless interaction with the Labellerr platform to manage data annotations, projects, and exports.

<Note>
  **New version v2.0.0 of the SDK is available** with major improvements and new features. See the [Changelog](/sdk/changelog) for details and upgrade notes.
</Note>

## Introduction

The **Labellerr SDK** is a Python library designed to make interaction with the Labellerr platform simple and efficient. With this SDK, you can manage data annotations, projects, and exports seamlessly in your applications.

This documentation will guide you through installing the SDK, understanding its core functionalities, and handling common errors.

## Installation

To install the Labellerr SDK, use the following command:

<CodeBlock lang="bash" title="Install Labellerr SDK">
  pip install git+[https://github.com/Labellerr/SDKPython.git](https://github.com/Labellerr/SDKPython.git)
</CodeBlock>

## Getting Started

### Obtaining API Credentials

To use the Labellerr SDK, you'll need three credentials: `api_key`, `api_secret`, and `client_id`.

<Steps>
  <Step title="Log in to Labellerr">
    Log in to your Labellerr account at [https://login.labellerr.com/](https://login.labellerr.com/)
  </Step>

  <Step title="Create your Workspace">
    Create a new workspace or access your existing workspace from the dashboard.
  </Step>

  <Step title="Get your API Credentials">
    Visit your workspace API keys page:

    ```
    https://<your-workspace-name>.labellerr.com/workspace/api-keys
    ```

    From this page, you can obtain all three credentials:

    * **API Key & Secret**: Copy from the API Keys table
    * **Client ID**: Click the **Show Client ID** button to reveal and copy your client ID
  </Step>
</Steps>

<Tip>
  Keep your credentials secure and never commit them to version control. Consider using environment variables or a secure configuration file.
</Tip>

### Initialize the Client

Once you have your credentials, import and initialize the `LabellerrClient`. This client handles all communication with the Labellerr platform.

<Note>
  **Workspace IP Restriction / Allowlisting**

  If your workspace has [IP Allowlisting](/enterprise-security/ip-allowlisting) enabled under **Workspace Settings**, ensure that the IP address running your Python script/SDK environment is added to the allowed IP ranges. SDK requests made from non-allowlisted IP addresses will be blocked by the server.
</Note>

### Understanding the SDK Structure

The Labellerr SDK uses a **modular architecture** that organizes functionality into specialized modules:

* **`labellerr.client`** - Core client for authentication and API communication
* **`labellerr.core.datasets`** - Dataset creation and management operations
* **`labellerr.core.projects`** - Project creation and management operations
* **`labellerr.core.files`** - File operations and metadata access
* **`labellerr.core.schemas`** - Data validation and configuration models
* **`labellerr.core.exceptions`** - Error handling utilities

### Example Client Initialization:

```python Client Initialization theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
api_key = "your-api-key"
api_secret = "your-api-secret"
client_id = "your-client-id"

client = LabellerrClient(api_key, api_secret, client_id)
```

### Common Import Patterns

Depending on your use case, you'll import different modules:

```python Import Examples for Common Tasks theme={"dark"}
# For creating and managing datasets
from labellerr.core.datasets import (
    create_dataset_from_local,
    create_dataset_from_connection,
    LabellerrDataset
)
from labellerr.core.schemas import DatasetConfig

# For creating annotation templates
from labellerr.core.annotation_templates import (
    create_template,
    LabellerrAnnotationTemplate
)
from labellerr.core.schemas import (
    CreateTemplateParams,
    AnnotationQuestion,
    QuestionType
)

# For creating and managing projects
from labellerr.core.projects import create_project, LabellerrProject
from labellerr.core.schemas import CreateProjectParams, RotationConfig

# For video projects (includes keyframe operations)
from labellerr.core.projects import LabellerrVideoProject
from labellerr.core.schemas import KeyFrame

# For working with files
from labellerr.core.files import LabellerrFile

# For cloud connections
from labellerr.core.connectors import (
    LabellerrS3Connection,
    LabellerrGCSConnection,
    create_connection,
    list_connections,
    delete_connection
)

# For error handling
from labellerr.core.exceptions import LabellerrError
```

Replace `'your-api-key'` and `'your-api-secret'` with your actual credentials provided by Labellerr.

***

## Working with Cloud Connections

The Labellerr SDK supports seamless integration with cloud storage providers like AWS S3 and Google Cloud Storage (GCS). You can create, test, list, and manage connections programmatically.

<Warning>
  **Required Permissions**

  Before creating cloud connections, ensure your IAM user (S3) or Service Account (GCS) has the required permissions:

  | Provider | Import Permissions | Export Permissions |
  | - | - | - |
  | AWS S3 | `s3:GetObject`, `s3:ListBucket`, `s3:GetBucketCors`, `s3:GetBucketLocation`, `s3:PutBucketCors` | + `s3:PutObject`, `s3:DeleteObject` |
  | GCS | `storage.objects.get`, `storage.objects.list`, `storage.buckets.get`, `storage.buckets.update` | + `storage.objects.create`, `storage.objects.delete` |

  For detailed setup instructions, see:

  * [AWS S3 Permissions Guide](/getting-started/connect-aws-s3)
  * [GCS Permissions Guide](/getting-started/connect-gcs)
</Warning>

### Creating and Testing Connections

<Tabs>
  <Tab title="AWS S3 Connection">
    <Info>
      **S3 Connection with Explicit Path Testing**

      For AWS S3 connections, you must provide a specific path to test the connection. The SDK will validate access to that exact path in your S3 bucket.
    </Info>

    ```python Create and Test S3 Connection theme={"dark"}
    from labellerr.client import LabellerrClient
    from labellerr.core.connectors import LabellerrS3Connection
    from labellerr.core.schemas import AWSConnectionParams, AWSConnectionTestParams
    from labellerr.core.exceptions import LabellerrError

    # Initialize client
    client = LabellerrClient(api_key, api_secret, client_id)

    try:
        # Test S3 connection first (recommended)
        test_params = AWSConnectionTestParams(
            aws_access_key="your_aws_access_key",
            aws_secrets_key="your_aws_secret_key",
            path="s3://your-bucket-name/path/to/data",  # Explicit path required
            data_type="image",
            connection_type="import"
        )
        
        test_result = LabellerrS3Connection.test_connection(client, test_params)
        print(f"Connection test result: {test_result}")
        
        # If test succeeds, create the connection
        connection_params = AWSConnectionParams(
            client_id=client_id,
            aws_access_key="your_aws_access_key",
            aws_secrets_key="your_aws_secret_key",
            path="s3://your-bucket-name/path/to/data",
            data_type="image",
            name="My S3 Connection",
            description="Production data bucket",
            connection_type="import"
        )
        
        # create_connection automatically tests before creating
        s3_connection = LabellerrS3Connection.create_connection(client, connection_params)
        print(f"✓ S3 Connection created: {s3_connection.connection_id}")
        
    except LabellerrError as e:
        print(f"Connection failed: {str(e)}")
    ```

    <Note>
      **Path Validation:**

      * The path must be accessible with the provided credentials
      * Path format: `s3://bucket-name/folder/subfolder`
      * Test fails if permissions are insufficient or path doesn't exist
    </Note>
  </Tab>

  <Tab title="GCS Connection">
    <Info>
      **GCS Connection with Service Account**

      For Google Cloud Storage, you need to provide a service account JSON file. The connection test validates both credentials and path access.
    </Info>

    ```python Create and Test GCS Connection theme={"dark"}
    from labellerr.client import LabellerrClient
    from labellerr.core.connectors import LabellerrGCSConnection
    from labellerr.core.schemas import GCSConnectionParams, GCSConnectionTestParams
    from labellerr.core.exceptions import LabellerrError

    # Initialize client
    client = LabellerrClient(api_key, api_secret, client_id)

    try:
        # Test GCS connection first (recommended)
        test_params = GCSConnectionTestParams(
            svc_account_json="/path/to/service-account.json",
            path="gs://your-bucket-name/path/to/data",
            data_type="image",
            connection_type="import"
        )
        
        test_result = LabellerrGCSConnection.test_connection(client, test_params)
        print(f"Connection test result: {test_result}")
        
        # If test succeeds, create the connection
        connection_params = GCSConnectionParams(
            client_id=client_id,
            svc_account_json="/path/to/service-account.json",
            path="gs://your-bucket-name/path/to/data",
            data_type="image",
            name="My GCS Connection",
            description="Production GCS bucket",
            connection_type="import"
        )
        
        # create_connection automatically tests before creating
        gcs_connection = LabellerrGCSConnection.create_connection(client, connection_params)
        print(f"✓ GCS Connection created: {gcs_connection.connection_id}")
        
    except LabellerrError as e:
        print(f"Connection failed: {str(e)}")
    ```

    <Note>
      **Service Account Requirements:**

      * Service account must have `Storage Object Viewer` permission (minimum)
      * JSON key file must be valid and accessible
      * Path must exist in the specified GCS bucket
    </Note>
  </Tab>

  <Tab title="List & Manage Connections">
    ```python List and Manage Connections theme={"dark"}
    from labellerr.client import LabellerrClient
    from labellerr.core.connectors import list_connections, delete_connection
    from labellerr.core.schemas import ConnectorType, ConnectionType
    from labellerr.core.exceptions import LabellerrError

    # Initialize client
    client = LabellerrClient(api_key, api_secret, client_id)

    try:
        # List all S3 connections
        s3_connections = list_connections(
            client=client,
            connector=ConnectorType._S3,
            connection_type=ConnectionType.IMPORT
        )
        
        print("Available S3 Connections:")
        for conn in s3_connections:
            print(f"- ID: {conn.connection_id}")
        
        # List all GCS connections
        gcs_connections = list_connections(
            client=client,
            connector=ConnectorType._GCS
        )
        
        print("Available GCS Connections:")
        for conn in gcs_connections:
            print(f"- ID: {conn.connection_id}")
        
        # Delete a connection if needed
        # delete_response = delete_connection(client, connection_id="connection_id_here")
        # print(f"Connection deleted: {delete_response}")
        
    except LabellerrError as e:
        print(f"Operation failed: {str(e)}")
    ```
  </Tab>
</Tabs>

<Warning>
  **Connection Testing Best Practices**

  Always test your connection before creating datasets:

  * **Explicit Path Testing (S3)**: Provide the exact S3 path you'll use for data access
  * **Implicit Validation (GCS)**: GCS connections validate both credentials and path accessibility
  * **Error Handling**: Wrap connection operations in try-except blocks
  * **Credential Security**: Never hardcode credentials; use environment variables or secret managers
</Warning>

***

## Using Connections with Datasets

Once you've created and tested a cloud connection (S3 or GCS), you can use it to create datasets directly from your cloud storage. This allows you to manage large volumes of files without manual uploads, and keeps your data in sync with your existing cloud infrastructure.

<Card title="Create Datasets from Cloud Storage" icon="database" href="/sdk/create-dataset-sdk#method-2-create-dataset-with-aws-s3-connection">
  Learn how to create datasets using your S3 or GCS connections in our dedicated **Create Datasets** guide, including complete code examples and troubleshooting tips.
</Card>

***

## Localization & Data Residency

<AccordionGroup>
  <Accordion title="Region selection" icon="globe">
    Run workspaces and data in-country/region (e.g., India, EU) to keep traffic in-geo.
  </Accordion>

  <Accordion title="Data scope" icon="shield">
    Datasets, tool instances, and model-assisted labeling endpoints stay in the chosen region.
  </Accordion>

  <Accordion title="Latency" icon="bolt">
    Pick the nearest region to reduce round trips for uploads, model calls, and labeling.
  </Accordion>

  <Accordion title="On-prem / private cloud" icon="server">
    Available for strict residency or compliance needs—contact us to align on region and setup.
  </Accordion>
</AccordionGroup>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How do I get my client_id?">
    Visit your workspace API keys page at `https://<your-workspace-name>.labellerr.com/workspace/api-keys` and click the **Show Client ID** button to reveal and copy your client ID.
  </Accordion>

  <Accordion title="Where can I find my API credentials?">
    You can obtain your `api_key` and `api_secret` by visiting: `https://<your-workspace-name>.labellerr.com/workspace/api-keys`
  </Accordion>

  <Accordion title="Why am I getting connection/authorization errors when my credentials are correct?">
    If your workspace has IP allowlisting / IP restriction enabled, make sure the outgoing IP address of your machine, server, or CI/CD runner is included in the allowlist in **Workspace Settings**. See [IP Allowlisting](/enterprise-security/ip-allowlisting) for instructions.
  </Accordion>
</AccordionGroup>


# Magic Wand Filtering
Source: https://docs.labellerr.com/sdk/magic-wand-confidence-filtering

Filter and review pre-annotations by confidence levels using the intuitive slider control for efficient quality assurance workflows.

## Overview

The Magic Wand Confidence Filtering feature enables you to upload pre-annotations with confidence scores and dynamically filter them during review. This powerful tool helps your annotation team focus on reviewing predictions that need the most attention while maintaining efficient workflows.

<CardGroup>
  <Card title="Smart Filtering" icon="filter">
    Filter annotations by confidence levels in real-time with an interactive slider
  </Card>

  <Card title="Quality Control" icon="chart-line">
    Focus review efforts on low-confidence predictions that need human validation
  </Card>

  <Card title="Workflow Efficiency" icon="gauge-high">
    Accept high-confidence predictions quickly while carefully reviewing uncertain ones
  </Card>
</CardGroup>

***

## How It Works

When you upload pre-annotations with confidence buckets, the Magic Wand feature automatically appears in the annotation interface, allowing annotators to filter annotations based on their confidence levels.

<Steps>
  <Step title="Upload with Confidence Bucket">
    Upload your pre-annotations using the SDK with a specified confidence bucket parameter
  </Step>

  <Step title="Magic Wand Appears">
    The slider control automatically appears in the annotation interface for files with confidence-tagged annotations
  </Step>

  <Step title="Filter by Confidence">
    Annotators use the slider to show/hide annotations based on confidence thresholds
  </Step>

  <Step title="Review & Refine">
    Focus on reviewing lower-confidence predictions while quickly accepting high-confidence ones
  </Step>
</Steps>

***

## Visual Workflow

![Magic Wand confidence slider in action - filtering polygon annotations dynamically](https://storage.googleapis.com/labellerr-cdn/%200%20Documentation-template/magicwand.gif)

<Note>
  The slider control appears automatically when annotations are uploaded with confidence buckets. Drag the slider to show/hide annotations based on your selected confidence threshold.
</Note>

***

## SDK Implementation

### Upload Pre-annotations with Confidence Bucket

<Tabs>
  <Tab title="Low Confidence">
    <Info>
      **Use Case**: Model predictions with low certainty (\< 50% confidence) that require careful human review
    </Info>

    ```python theme={"dark"}
    from labellerr.client import LabellerrClient
    from labellerr.core.projects import LabellerrProject

    # Initialize client
    client = LabellerrClient(
        api_key='your_api_key',
        api_secret='your_api_secret',
        client_id='your_client_id'
    )

    # Get project instance and upload with low confidence bucket
    project = LabellerrProject(client=client, project_id='your_project_id')

    result = project.upload_preannotations(
        annotation_format='coco_json',
        annotation_file='annotations.json',
        conf_bucket='low',  # Low confidence annotations
        _async=False  # Default: blocks until completion
    )

    print(f"Status: {result['response']['status']}")
    ```

    <Note>
      **Best For**: Uncertain predictions, edge cases, or challenging images that need thorough human validation
    </Note>
  </Tab>

  <Tab title="Medium Confidence">
    <Info>
      **Use Case**: Model predictions with moderate certainty (50-80% confidence) that benefit from quick review
    </Info>

    ```python theme={"dark"}
    from labellerr.client import LabellerrClient
    from labellerr.core.projects import LabellerrProject

    # Initialize client
    client = LabellerrClient(
        api_key='your_api_key',
        api_secret='your_api_secret',
        client_id='your_client_id'
    )

    # Get project instance and upload with medium confidence bucket
    project = LabellerrProject(client=client, project_id='your_project_id')

    result = project.upload_preannotations(
        annotation_format='coco_json',
        annotation_file='annotations.json',
        conf_bucket='medium',  # Medium confidence annotations
        _async=False  # Default: blocks until completion
    )

    print(f"Status: {result['response']['status']}")
    ```

    <Note>
      **Best For**: Standard predictions that warrant verification but are likely accurate
    </Note>
  </Tab>

  <Tab title="High Confidence">
    <Info>
      **Use Case**: Model predictions with high certainty (> 80% confidence) that may only need spot-checking
    </Info>

    ```python theme={"dark"}
    from labellerr.client import LabellerrClient
    from labellerr.core.projects import LabellerrProject

    # Initialize client
    client = LabellerrClient(
        api_key='your_api_key',
        api_secret='your_api_secret',
        client_id='your_client_id'
    )

    # Get project instance and upload with high confidence bucket
    project = LabellerrProject(client=client, project_id='your_project_id')

    result = project.upload_preannotations(
        annotation_format='coco_json',
        annotation_file='annotations.json',
        conf_bucket='high',  # High confidence annotations
        _async=False  # Default: blocks until completion
    )

    print(f"Status: {result['response']['status']}")
    ```

    <Note>
      **Best For**: Highly confident predictions on clear, unambiguous objects that rarely need correction
    </Note>
  </Tab>
</Tabs>

***

## Complete Workflow Example

Here's a comprehensive example showing how to segment your model's predictions by confidence and upload them accordingly:

```python theme={"dark"}
import json
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.exceptions import LabellerrError

# Initialize client
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

# Project configuration
project_id = 'your_project_id'
project = LabellerrProject(client=client, project_id=project_id)

# Separate your predictions by confidence (cumulative filtering)
# When slider is at Low: shows ALL annotations (low + medium + high)
# When slider is at Medium: shows medium + high annotations only
# When slider is at High: shows only high confidence annotations
prediction_files = {
    'low': 'predictions_low_confidence.json',     # < 0.5 confidence
    'medium': 'predictions_medium_confidence.json', # >= 0.5 and <= 0.8 confidence
    'high': 'predictions_high_confidence.json'     # > 0.8 confidence
}

# Upload each confidence bucket
results = {}

for confidence_level, file_path in prediction_files.items():
    try:
        print(f"Uploading {confidence_level} confidence annotations...")
        
        result = project.upload_preannotations(
            annotation_format='coco_json',
            annotation_file=file_path,
            conf_bucket=confidence_level
        )
        
        results[confidence_level] = result
        print(f"✓ {confidence_level.capitalize()} confidence upload complete")
        
        # Extract metadata
        metadata = result['response'].get('metadata', {})
        if 'files_not_updated' in metadata:
            print(f"  Files processed: {metadata.get('files_not_updated', [])}")
            
    except LabellerrError as e:
        print(f"✗ Failed to upload {confidence_level} confidence: {str(e)}")
        results[confidence_level] = {'error': str(e)}

# Summary
print("\n" + "="*50)
print("Upload Summary:")
print("="*50)
for level, result in results.items():
    status = "Success" if 'error' not in result else "Failed"
    print(f"{level.capitalize()}: {status}")
```

***

## Confidence Bucket Guidelines

Choose the appropriate confidence bucket based on your model's prediction confidence scores. The Magic Wand uses **cumulative filtering**, where each threshold level progressively filters annotations:

<Info>
  **How Cumulative Filtering Works**:

  * **Low threshold** (slider at lowest): Shows ALL annotations (low + medium + high)
  * **Medium threshold** (slider at middle): Shows medium + high annotations only (filters out low)
  * **High threshold** (slider at highest): Shows only high confidence annotations (filters out low + medium)
</Info>

<CardGroup>
  <Card title="Low Confidence" icon="circle-exclamation">
    **Confidence Range**: 0% - 50%

    **Characteristics**:

    * Uncertain predictions
    * Multiple possible labels
    * Challenging image conditions
    * Edge cases

    **Slider Behavior**:

    * Visible at ALL slider positions
    * Always shown regardless of threshold
    * Requires thorough manual review
  </Card>

  <Card title="Medium Confidence" icon="circle-half-stroke">
    **Confidence Range**: 50% - 80%

    **Characteristics**:

    * Likely accurate predictions
    * Some ambiguity present
    * Standard image conditions
    * Common object types

    **Slider Behavior**:

    * Visible at medium and high thresholds
    * Hidden when slider filters to low only
    * Quick verification recommended
  </Card>

  <Card title="High Confidence" icon="circle-check">
    **Confidence Range**: 80% - 100%

    **Characteristics**:

    * Very confident predictions
    * Clear, unambiguous objects
    * Ideal image conditions
    * Well-trained categories

    **Slider Behavior**:

    * Visible only at high threshold
    * Hidden at low and medium thresholds
    * Minimal corrections needed
  </Card>
</CardGroup>

***

## Magic Wand Usage in Annotation Interface

Once annotations are uploaded with confidence buckets, annotators can leverage the Magic Wand slider:

<AccordionGroup>
  <Accordion title="Accessing the Magic Wand" icon="wand-magic-sparkles">
    1. Open a file with uploaded pre-annotations
    2. Look for the Magic Wand icon/slider in the left sidebar
    3. The tool appears automatically when confidence-tagged annotations exist
  </Accordion>

  <Accordion title="Using the Confidence Slider" icon="sliders">
    1. Drag the slider to adjust the confidence threshold
    2. Annotations below the threshold are hidden
    3. Annotations above the threshold remain visible
    4. Use this to focus on reviewing specific confidence ranges
  </Accordion>

  <Accordion title="Review Workflow Optimization" icon="bolt">
    **Efficient Review Strategy**:

    1. Start with low confidence threshold (show all annotations)
    2. Review and correct low-confidence predictions first
    3. Gradually increase threshold to review medium confidence
    4. Quickly verify high-confidence predictions
    5. Submit when all confidence levels are validated
  </Accordion>
</AccordionGroup>

***

## Parameter Reference

### `conf_bucket` Parameter

<ParamField type="string">
  Specifies the confidence level for uploaded pre-annotations

  **Valid Values**:

  * `'low'` - For predictions with low confidence (typically \< 50%)
  * `'medium'` - For predictions with medium confidence (typically 50-80%)
  * `'high'` - For predictions with high confidence (typically > 80%)

  **Default**: `None` (no confidence filtering applied)

  <Warning>
    The confidence bucket parameter is **case-sensitive**. Use lowercase values: `'low'`, `'medium'`, `'high'`
  </Warning>
</ParamField>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Magic Wand Not Appearing" icon="eye-slash">
    **Symptom**: The slider control doesn't appear in the annotation interface.

    **Resolution Steps**:

    * Verify annotations were uploaded with `conf_bucket` parameter specified
    * Confirm the confidence bucket value was set to 'low', 'medium', or 'high'
    * Check that pre-annotations were successfully applied (no file name mismatches)
    * Refresh the annotation interface
    * Ensure you're using the latest version of Labellerr
  </Accordion>

  <Accordion title="All Annotations Same Confidence" icon="equals">
    **Symptom**: Slider doesn't filter anything; all annotations appear at same level.

    **Resolution Steps**:

    * Verify you uploaded different confidence buckets in separate uploads
    * Check that you didn't upload all predictions with the same conf\_bucket value
    * Ensure your prediction pipeline correctly segments by confidence
    * Re-upload with properly categorized confidence levels
  </Accordion>

  <Accordion title="Incorrect Confidence Categories" icon="triangle-exclamation">
    **Symptom**: Annotations appear in wrong confidence categories.

    **Resolution Steps**:

    * Review your confidence score thresholds in preprocessing
    * Verify the mapping between confidence scores and bucket labels
    * Check for any errors in your prediction segmentation logic
    * Consider recalibrating your model if systematic misalignment exists
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Upload Pre-annotations" icon="upload" href="/sdk/upload-preannotation-sdk">
    Complete guide to uploading pre-annotations via SDK
  </Card>

  <Card title="Create Project" icon="folder-plus" href="/sdk/create-project-sdk">
    Set up projects programmatically for annotation workflows
  </Card>

  <Card title="Segment Anything" icon="scissors" href="/features/segment-anything">
    Learn about Meta's SAM integration for one-click segmentation
  </Card>
</CardGroup>

***

## Support

<Note>
  For technical assistance with the Magic Wand Confidence Filtering feature, contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>

<Tip>
  **Pro Tip**: Combine Magic Wand filtering with keyboard shortcuts for maximum annotation efficiency. Low-confidence annotations get thorough review, while high-confidence ones can be quickly validated and accepted.
</Tip>


# Manage Data Connectors
Source: https://docs.labellerr.com/sdk/manage-connections-sdk

Learn how to create, list, and delete AWS S3 and GCP GCS data connector credentials using the Labellerr Python SDK.

## Introduction

<Card title="What are Data Connectors?" icon="circle-info">
  A **data connector** in Labellerr is a saved set of cloud storage **credentials** (for AWS S3 or Google Cloud Storage) that authorises Labellerr to securely access your bucket, without storing or moving credentials manually on every operation.

  Connectors are reusable, once a connector credential is saved, it can be used across multiple datasets and projects. The SDK provides full lifecycle management:

  * **Create** connector credentials for AWS S3 or GCP GCS
  * **Test** connector credentials before saving them
  * **List** all existing connector credentials by provider and type
  * **Delete** connector credentials that are no longer needed

  ### Connector Types

  | Type | Enum Value | Description |
  | - | - | - |
  | Import | `ConnectionType._IMPORT` | Pull files from cloud storage into Labellerr |
  | Export | `ConnectionType._EXPORT` | Push annotation results back to cloud storage |

  ### Provider Types

  | Provider | Enum Value | Description |
  | - | - | - |
  | AWS S3 | `ConnectorType._S3` | Amazon Simple Storage Service |
  | GCP GCS | `ConnectorType._GCS` | Google Cloud Storage |
</Card>

***

## Required Imports

```python Required Imports lines icon="code" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.schemas import (
    ConnectionType,
    ConnectorType,
    AWSConnectionParams,
    AWSConnectionTestParams,
    GCSConnectionParams,
    GCSConnectionTestParams
)
from labellerr.core.connectors import (
    LabellerrS3Connection,
    LabellerrGCSConnection,
    list_connections,
    delete_connection
)
from labellerr.core.exceptions import LabellerrError
```

***

## Connect to AWS S3

<Card title="Connect AWS S3 Bucket" icon="aws">
  Use `LabellerrS3Connection` to create a connection to your Amazon S3 bucket. It is strongly recommended to **test the connection first** before saving it to ensure your IAM credentials and path are valid.

  <Steps>
    <Step title="Initialize the Client">
      Create a `LabellerrClient` instance with your API credentials.
    </Step>

    <Step title="Test the Connection (Recommended)">
      Call `LabellerrS3Connection.test_connection()` with a specific S3 path to validate credentials and permissions.
    </Step>

    <Step title="Create the Connection">
      Call `LabellerrS3Connection.create_connection()` to persist the connection for future use.
    </Step>
  </Steps>

  ```python Connect to AWS S3 lines icon="aws" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.connectors import LabellerrS3Connection
  from labellerr.core.schemas import AWSConnectionParams, AWSConnectionTestParams, ConnectionType
  from labellerr.core.exceptions import LabellerrError

  # Initialize the client with your API credentials
  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  try:
      # Step 1: Test the connection first (recommended)
      test_params = AWSConnectionTestParams(
          aws_access_key="your_aws_access_key",
          aws_secrets_key="your_aws_secret_key",
          path="s3://your-bucket-name/path/to/data/",
          data_type="image",
          connection_type="import"
      )

      test_result = LabellerrS3Connection.test_connection(client, test_params)
      print(f"✓ Connection test result: {test_result}")

      # Step 2: Create the connection
      connection_params = AWSConnectionParams(
          aws_access_key="your_aws_access_key",
          aws_secrets_key="your_aws_secret_key",
          path="s3://your-bucket-name/path/to/data/",
          data_type="image",
          connection_type=ConnectionType._IMPORT,
          name="My S3 Import Connection",
          description="Production AWS S3 bucket for image datasets"
      )

      s3_connection = LabellerrS3Connection.create_connection(client, connection_params)

      # Print connection details
      print(f"✓ S3 Connection created successfully!")
      print(f"  Connection ID   : {s3_connection.connection_id}")
      print(f"  Connection Name : {s3_connection.name}")
      print(f"  Provider        : AWS S3")
      print(f"  Type            : Import")
      print(f"  Path            : s3://your-bucket-name/path/to/data/")

  except LabellerrError as e:
      print(f"✗ Connection failed: {str(e)}")
  ```

  <Warning>
    **Required IAM Permissions for AWS S3**

    Your IAM user must have the following permissions on the target bucket:

    | Use Case | Required Permissions |
    | - | - |
    | Import (read data) | `s3:GetObject`, `s3:ListBucket`, `s3:GetBucketCors(Optional)`, `s3:GetBucketLocation`, `s3:PutBucketCors(Optional)` |
    | Export (write results) | All import permissions + `s3:PutObject`, `s3:DeleteObject` |

    For a step-by-step IAM setup guide, see [Connect AWS S3](/getting-started/connect-aws-s3).
  </Warning>

  <Note>
    **S3 Path Format:** Always use the `s3://bucket-name/folder/subfolder/` format. Include a trailing slash for folder paths.
  </Note>
</Card>

***

## Connect to GCP (Google Cloud Storage)

<Card title="Connect GCP GCS Bucket" icon="google">
  Use `LabellerrGCSConnection` to create a connection to your Google Cloud Storage bucket. You will need a **service account JSON key file** with the appropriate permissions.

  <Steps>
    <Step title="Initialize the Client">
      Create a `LabellerrClient` instance with your API credentials.
    </Step>

    <Step title="Test the Connection (Recommended)">
      Call `LabellerrGCSConnection.test_connection()` to validate your service account credentials and path access.
    </Step>

    <Step title="Create the Connection">
      Call `LabellerrGCSConnection.create_connection()` to save the connection for future use.
    </Step>
  </Steps>

  ```python Connect to GCP GCS lines icon="google" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.connectors import LabellerrGCSConnection
  from labellerr.core.schemas import GCSConnectionParams, GCSConnectionTestParams, ConnectionType
  from labellerr.core.exceptions import LabellerrError

  # Initialize the client with your API credentials
  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  try:
      # Step 1: Test the connection first (recommended)
      test_params = GCSConnectionTestParams(
          svc_account_json="/path/to/service-account-key.json",
          path="gs://your-bucket-name/path/to/data/",
          data_type="image",
          connection_type="import"
      )

      test_result = LabellerrGCSConnection.test_connection(client, test_params)
      print(f"✓ Connection test result: {test_result}")

      # Step 2: Create the connection
      connection_params = GCSConnectionParams(
          svc_account_json="/path/to/service-account-key.json",
          path="gs://your-bucket-name/path/to/data/",
          data_type="image",
          connection_type=ConnectionType._IMPORT,
          name="My GCS Import Connection",
          description="Production GCS bucket for image datasets"
      )

      gcs_connection = LabellerrGCSConnection.create_connection(client, connection_params)

      # Print connection details
      print(f"✓ GCS Connection created successfully!")
      print(f"  Connection ID   : {gcs_connection.connection_id}")
      print(f"  Connection Name : {gcs_connection.name}")
      print(f"  Provider        : Google Cloud Storage")
      print(f"  Type            : Import")
      print(f"  Path            : gs://your-bucket-name/path/to/data/")

  except LabellerrError as e:
      print(f"✗ Connection failed: {str(e)}")
  ```

  <Warning>
    **Required GCS Service Account Permissions**

    Your service account must have the following roles/permissions:

    | Use Case | Required Permissions |
    | - | - |
    | Import (read data) | `storage.objects.get`, `storage.objects.list`, `storage.buckets.get`, `storage.buckets.update(Optional)` |
    | Export (write results) | All import permissions + `storage.objects.create`, `storage.objects.delete` |

    For a step-by-step service account setup guide, see [Connect GCS](/getting-started/connect-gcs).
  </Warning>

  <Note>
    **GCS Path Format:** Always use the `gs://bucket-name/folder/subfolder/` format. Include a trailing slash for folder paths. Your service account JSON key file must be readable from the machine running the SDK.
  </Note>
</Card>

***

## List Connections

<Card title="List All Connections" icon="list">
  Use `list_connections()` to retrieve all saved connections for a given cloud provider and connection type. This is useful to inspect existing connections, find a connection ID to reuse, or audit what connections are configured.

  ```python List Connections lines icon="list" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.schemas import ConnectionType, ConnectorType
  from labellerr.core.connectors import list_connections
  from labellerr.core.exceptions import LabellerrError

  # Initialize the client with your API credentials
  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  try:
      # List all S3 import connections
      connections = list_connections(client, ConnectorType._S3, ConnectionType._IMPORT)

      for conn in connections:
          print(f"  Connection ID   : {conn.connection_id}")
          print(f"  Connection Name : {conn.name}")
          print(f"  Description     : {conn.description}")
          print(f"  Provider        : {conn.connector_type}")
          print(f"  Connection Type : {conn.connection_type}")
          print(f"  Created At      : {conn.created_at}")
          print("-" * 50)

  except LabellerrError as e:
      print(f"✗ Failed to list connections: {str(e)}")
  ```

  <Tip>
    You can filter connections by swapping `ConnectorType._S3` for `ConnectorType._GCS` to list GCS connections, and `ConnectionType._IMPORT` for `ConnectionType._EXPORT` to list export connections.
  </Tip>
</Card>

## Delete a Connection

<Card title="Delete Connection" icon="trash">
  Use `delete_connection()` to permanently remove a saved connection by its connection ID. This is useful for cleaning up unused or outdated connections.

  ```python Delete Connection lines icon="trash" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.connectors import delete_connection
  from labellerr.core.exceptions import LabellerrError

  # Initialize the client with your API credentials
  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  # The connection ID you want to delete
  connection_id_to_delete = "your_connection_id_here"

  try:
      response = delete_connection(client, connection_id=connection_id_to_delete)

      print(f"✓ Connection deleted successfully!")
      print(f"  Deleted Connection ID : {connection_id_to_delete}")
      print(f"  Response              : {response}")

  except LabellerrError as e:
      print(f"✗ Failed to delete connection: {str(e)}")
  ```

  <Warning>
    **Caution:** Deleting a connection is **permanent**. Any datasets that were linked to this connection will lose access to the cloud storage path. Ensure no active datasets or projects depend on this connection before deleting.
  </Warning>
</Card>

## Error Handling

<Card title="Best Practices for Error Handling" icon="shield">
  Always wrap connection operations in `try-except` blocks using `LabellerrError` to handle failures gracefully.

  ```python Error Handling Example lines icon="exclamation-triangle" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.connectors import LabellerrS3Connection, list_connections, delete_connection
  from labellerr.core.schemas import AWSConnectionParams, ConnectionType, ConnectorType
  from labellerr.core.exceptions import LabellerrError

  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  # Create connection with error handling
  try:
      params = AWSConnectionParams(
          aws_access_key="your_aws_access_key",
          aws_secrets_key="your_aws_secret_key",
          path="s3://your-bucket/data/",
          data_type="image",
          connection_type=ConnectionType._IMPORT,
          name="My S3 Connection"
      )
      conn = LabellerrS3Connection.create_connection(client, params)
      print(f"✓ Created: {conn.connection_id}")

  except LabellerrError as e:
      print(f"✗ Create failed: {str(e)}")

  # List connections with error handling
  try:
      connections = list_connections(client, ConnectorType._S3, ConnectionType._IMPORT)
      for conn in connections:
          print(f"  ID: {conn.connection_id}, Name: {conn.name}")

  except LabellerrError as e:
      print(f"✗ List failed: {str(e)}")

  # Delete connection with error handling
  try:
      response = delete_connection(client, connection_id="connection_id_to_delete")
      print(f"✓ Deleted: {response}")

  except LabellerrError as e:
      print(f"✗ Delete failed: {str(e)}")
  ```
</Card>

***

## API Reference

<AccordionGroup>
  <Accordion title="LabellerrS3Connection.create_connection(client, params)" icon="aws">
    ```python theme={"dark"}
    from labellerr.core.connectors import LabellerrS3Connection
    from labellerr.core.schemas import AWSConnectionParams

    connection = LabellerrS3Connection.create_connection(
        client=client,
        params=AWSConnectionParams(
            aws_access_key="...",
            aws_secrets_key="...",
            path="s3://bucket/path/",
            data_type="image",
            connection_type=ConnectionType._IMPORT,
            name="Connection Name",
            description="Optional description"
        )
    )
    ```

    **Returns:** `LabellerrS3Connection` object with properties:

    * `connection_id: str` — Unique identifier for the connection
    * `name: str` — Display name of the connection
    * `description: str` — Optional description
    * `connector_type: str` — Always `"s3"` for S3 connections
    * `connection_type: str` — `"import"` or `"export"`
    * `created_at: datetime` — Timestamp of creation
  </Accordion>

  <Accordion title="LabellerrGCSConnection.create_connection(client, params)" icon="google">
    ```python theme={"dark"}
    from labellerr.core.connectors import LabellerrGCSConnection
    from labellerr.core.schemas import GCSConnectionParams

    connection = LabellerrGCSConnection.create_connection(
        client=client,
        params=GCSConnectionParams(
            svc_account_json="/path/to/service-account.json",
            path="gs://bucket/path/",
            data_type="image",
            connection_type=ConnectionType._IMPORT,
            name="Connection Name",
            description="Optional description"
        )
    )
    ```

    **Returns:** `LabellerrGCSConnection` object with properties:

    * `connection_id: str` — Unique identifier for the connection
    * `name: str` — Display name of the connection
    * `description: str` — Optional description
    * `connector_type: str` — Always `"gcs"` for GCS connections
    * `connection_type: str` — `"import"` or `"export"`
    * `created_at: datetime` — Timestamp of creation
  </Accordion>

  <Accordion title="list_connections(client, connector, connection_type)" icon="list">
    ```python theme={"dark"}
    from labellerr.core.connectors import list_connections
    from labellerr.core.schemas import ConnectorType, ConnectionType

    connections = list_connections(
        client=client,
        connector=ConnectorType._S3,        # or ConnectorType._GCS
        connection_type=ConnectionType._IMPORT  # or ConnectionType._EXPORT
    )

    for conn in connections:
        print(conn.connection_id)
    ```

    **Parameters:**

    | Parameter | Type | Description |
    | - | - | - |
    | `client` | `LabellerrClient` | Authenticated client instance |
    | `connector` | `ConnectorType` | `ConnectorType._S3` or `ConnectorType._GCS` |
    | `connection_type` | `ConnectionType` | `ConnectionType._IMPORT` or `ConnectionType._EXPORT` |

    **Returns:** Iterable of connection objects, each with `connection_id`, `name`, `description`, `connector_type`, `connection_type`, `created_at`.
  </Accordion>

  <Accordion title="delete_connection(client, connection_id)" icon="trash">
    ```python theme={"dark"}
    from labellerr.core.connectors import delete_connection

    response = delete_connection(
        client=client,
        connection_id="your_connection_id_here"
    )
    print(response)
    ```

    **Parameters:**

    | Parameter | Type | Description |
    | - | - | - |
    | `client` | `LabellerrClient` | Authenticated client instance |
    | `connection_id` | `str` | ID of the connection to delete |

    **Returns:** Response object or confirmation message from the API.
  </Accordion>
</AccordionGroup>

***

## Common Use Cases

<CardGroup>
  <Card title="Reuse Across Datasets" icon="recycle">
    Create one S3 or GCS connection and use the same `connection_id` across multiple datasets, avoiding repeated credential entry.
  </Card>

  <Card title="Import Large Datasets" icon="cloud-arrow-down">
    Connect directly to cloud storage buckets containing thousands of files, bypassing local upload limits (2,500 files / 2.5 GB).
  </Card>

  <Card title="Export Annotations" icon="cloud-arrow-up">
    Create an export-type connection to automatically push completed annotation exports back to your S3 or GCS bucket.
  </Card>

  <Card title="Audit & Cleanup" icon="shield-check">
    Use `list_connections()` periodically to audit all active connections and `delete_connection()` to remove unused ones.
  </Card>
</CardGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Create Datasets" icon="database" href="/sdk/create-dataset-sdk">
    Use your connections to create datasets directly from cloud storage
  </Card>

  <Card title="Connect AWS S3" icon="aws" href="/getting-started/connect-aws-s3">
    Step-by-step guide to configure AWS IAM permissions for S3
  </Card>

  <Card title="Connect GCS" icon="google" href="/getting-started/connect-gcs">
    Step-by-step guide to configure a GCS service account
  </Card>
</CardGroup>

<Note>
  For technical support, contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# MCP Server
Source: https://docs.labellerr.com/sdk/mcp-server

Use Labellerr with AI assistants like Claude and Cursor through the Model Context Protocol (MCP) server for natural language data annotation workflows.

## Introduction

The **Labellerr MCP Server** enables seamless interaction with the Labellerr platform using natural language through AI assistants such as **Claude Desktop** and **Cursor**. Built on the Model Context Protocol (MCP), it provides 23 comprehensive tools for managing datasets, projects, annotations, and exports through conversational interfaces.

## Quick Start

### Prerequisites

* Python 3.8 or higher
* Git installed on your system
* Labellerr API credentials (API Key, API Secret, Client ID) - [Get your credentials](https://docs.labellerr.com/sdk/getting-started#obtaining-api-credentials)
* Claude Desktop or Cursor installed

### Installation

First, clone the SDKPython repository:

```bash Clone Repository theme={"dark"}
git clone https://github.com/Labellerr/SDKPython.git
cd SDKPython
```

Then install the required dependencies:

```bash Install Dependencies theme={"dark"}
pip install -r requirements.txt
```

### Configuration

<Tabs>
  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json Cursor Configuration theme={"dark"}
    {
      "mcpServers": {
        "labellerr": {
          "command": "python3",
          "args": ["/FULL/PATH/TO/SDKPython/labellerr/mcp_server/server.py"],
          "env": {
            "LABELLERR_API_KEY": "your_api_key",
            "LABELLERR_API_SECRET": "your_api_secret",
            "LABELLERR_CLIENT_ID": "your_client_id"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to Claude Desktop config:

    * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

    ```json Claude Desktop Configuration theme={"dark"}
    {
      "mcpServers": {
        "labellerr": {
          "command": "python3",
          "args": ["/FULL/PATH/TO/SDKPython/labellerr/mcp_server/server.py"],
          "env": {
            "LABELLERR_API_KEY": "your_api_key",
            "LABELLERR_API_SECRET": "your_api_secret",
            "LABELLERR_CLIENT_ID": "your_client_id"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  **Important**: Use the absolute path to `server.py`. Restart your AI assistant completely after configuration.
</Warning>

## Available Tools

The MCP server provides **23 comprehensive tools** organized into 5 functional categories to manage your complete annotation workflow:

<AccordionGroup>
  <Accordion title="Project Management (4 tools)" icon="folder-tree">
    <ResponseField name="project_create" type="tool">
      Create a new annotation project (requires dataset\_id and template\_id)
    </ResponseField>

    <ResponseField name="project_list" type="tool">
      List all projects in your workspace
    </ResponseField>

    <ResponseField name="project_get" type="tool">
      Get detailed information about a specific project
    </ResponseField>

    <ResponseField name="project_update_rotation" type="tool">
      Update annotation rotation configuration
    </ResponseField>
  </Accordion>

  <Accordion title="Dataset Management (5 tools)" icon="database">
    <ResponseField name="dataset_create" type="tool">
      Create dataset with automatic file upload and status polling
    </ResponseField>

    <ResponseField name="dataset_upload_files" type="tool">
      Upload individual files to create a dataset
    </ResponseField>

    <ResponseField name="dataset_upload_folder" type="tool">
      Upload an entire folder of files
    </ResponseField>

    <ResponseField name="dataset_list" type="tool">
      List all datasets with filtering options
    </ResponseField>

    <ResponseField name="dataset_get" type="tool">
      Get detailed information about a dataset
    </ResponseField>
  </Accordion>

  <Accordion title="Annotation Operations (6 tools)" icon="pen-to-square">
    <ResponseField name="template_create" type="tool">
      Create annotation template with questions/guidelines
    </ResponseField>

    <ResponseField name="annotation_export" type="tool">
      Export project annotations in various formats (JSON, COCO, CSV, PNG)
    </ResponseField>

    <ResponseField name="annotation_check_export_status" type="tool">
      Check status of export jobs
    </ResponseField>

    <ResponseField name="annotation_download_export" type="tool">
      Get download URL for completed exports
    </ResponseField>

    <ResponseField name="annotation_upload_preannotations" type="tool">
      Upload pre-annotations (synchronous)
    </ResponseField>

    <ResponseField name="annotation_upload_preannotations_async" type="tool">
      Upload pre-annotations (asynchronous)
    </ResponseField>
  </Accordion>

  <Accordion title="Monitoring Tools (4 tools)" icon="chart-line">
    <ResponseField name="monitor_system_health" type="tool">
      Check MCP server health and connection status
    </ResponseField>

    <ResponseField name="monitor_active_operations" type="tool">
      List all active operations and their status
    </ResponseField>

    <ResponseField name="monitor_project_progress" type="tool">
      Get progress statistics for a project
    </ResponseField>

    <ResponseField name="monitor_job_status" type="tool">
      Monitor background job status
    </ResponseField>
  </Accordion>

  <Accordion title="Query Tools (4 tools)" icon="magnifying-glass">
    <ResponseField name="query_project_statistics" type="tool">
      Get detailed statistics for a project
    </ResponseField>

    <ResponseField name="query_dataset_info" type="tool">
      Get detailed information about a dataset
    </ResponseField>

    <ResponseField name="query_operation_history" type="tool">
      Query history of operations performed
    </ResponseField>

    <ResponseField name="query_search_projects" type="tool">
      Search for projects by name or type
    </ResponseField>
  </Accordion>
</AccordionGroup>

## Usage Examples

Interact with the MCP server using natural language commands through your AI assistant. Below are common usage patterns:

### Create a Complete Project

```
Create an image annotation project called "Product Detection" with 
bounding boxes for "Product" and "Defect". Upload images from 
/Users/me/products and use my email user@example.com
```

**Automated workflow:**

1. Upload images from the specified folder
2. Create a dataset with uploaded files
3. Generate an annotation template with bounding box questions
4. Create and link the project with all resources

### Monitor Project Progress

```
What's the progress on all my annotation projects?
```

### Export Annotations

```
Export all accepted annotations from project abc123 in COCO JSON format
```

### Upload Additional Data

```
Upload images from /Users/me/more-data to dataset xyz789
```

## Project Creation Workflow

The MCP server implements a structured three-step workflow for creating annotation projects. When you request a complete project, the server automatically executes all steps in sequence.

<Info>
  **Automated Workflow**: Describe your requirements in natural language, and the MCP server handles the complete workflow automatically.
</Info>

<Steps>
  <Step title="Step 1: Create Dataset" icon="database">
    The server uploads your files and creates a dataset.

    **Process:**

    * Files are uploaded to cloud storage
    * Dataset is created and linked
    * Processing status is monitored until completion

    **Example request:**

    ```
    Create a dataset called "Training Data" from folder /path/to/images
    ```

    **Server response:**

    ```
    Uploaded 150 images
    Dataset created: dataset_abc123
    Dataset ready for annotation
    ```
  </Step>

  <Step title="Step 2: Create Template" icon="pen-to-square">
    The server creates an annotation template with your specified questions.

    **Process:**

    * Annotation questions are defined
    * Question types are configured (BoundingBox, polygon, etc.)
    * Template is validated and saved

    **Example request:**

    ```
    Create an annotation template with bounding boxes for "Car" and "Truck"
    ```

    **Server response:**

    ```
    Template created: template_xyz789
    Questions: Car (BoundingBox), Truck (BoundingBox)
    ```
  </Step>

  <Step title="Step 3: Create Project" icon="folder-plus">
    The server links the dataset and template to create your project.

    **Process:**

    * Dataset and template are validated
    * Project is created with proper configuration
    * Resources are linked and ready for annotation

    **Example request:**

    ```
    Create a project using dataset dataset_abc123 and template template_xyz789
    ```

    **Server response:**

    ```
    Project created: project_final_456
    Linked dataset: dataset_abc123 (150 files)
    Linked template: template_xyz789
    Ready to start annotation
    ```
  </Step>
</Steps>

<Tip>
  **Unified Command**: You can create everything in one natural language request:

  ```
  Create an image annotation project called "Vehicle Detection" with 
  bounding boxes for "Car" and "Truck". Upload images from 
  /Users/me/vehicles and use my email user@example.com
  ```

  The MCP server will automatically execute all three steps and provide you with the final project ID.
</Tip>

**Workflow Benefits:**

* Proper resource management
* Clear project structure
* Validation at each step
* Automatic error handling

## Supported Data Types

The MCP server supports the following data types across all tools:

| Data Type | Supported Formats |
| - | - |
| **Image** | JPG, PNG, TIFF |
| **Video** | MP4 |
| **Audio** | MP3, WAV |
| **Document** | PDF |
| **Text** | TXT |

## Export Formats

Annotations can be exported in multiple industry-standard formats:

| Format | Description |
| - | - |
| **json** | Labellerr native format with complete annotation metadata |
| **coco\_json** | COCO dataset format for computer vision tasks |
| **csv** | Comma-separated values for tabular data analysis |
| **png** | Segmentation masks for pixel-level annotations |

## Error Handling

The MCP server provides descriptive error messages to help diagnose and resolve issues:

```
Error: dataset_id is required
Message: Please create a dataset first using dataset_upload_folder
```

All operations are logged in the operation history and can be queried using natural language:

```
Show me the history of operations I've performed
```

## Troubleshooting

### AI Assistant Doesn't Show Tools

**Resolution steps:**

1. Completely restart your AI assistant (quit and reopen the application)
2. Verify the path to `server.py` is absolute (starts with `/` on macOS/Linux or `C:\` on Windows)
3. Test the server manually: `python3 /path/to/server.py`
4. Check the MCP configuration file for syntax errors

### Authentication Errors

**Resolution steps:**

1. Obtain fresh credentials from your Labellerr workspace
2. Update the configuration file with the correct API credentials
3. Ensure all three credentials (API Key, API Secret, Client ID) are present
4. Restart your AI assistant after updating credentials

### File Upload Issues

**Common causes and solutions:**

* Verify file paths are absolute, not relative
* Check file system permissions for read access
* Confirm file formats match the specified data type
* Ensure sufficient disk space for upload operations

***

## Advanced Features

### Operation History

The server maintains a comprehensive log of all operations with timestamps, durations, and status information. Query the operation history using natural language:

```
Show me failed operations from the last hour
```

### Resource Caching

Active projects and datasets are cached in memory for improved performance and faster access. View currently cached resources:

```
What Labellerr resources are currently active?
```

### Status Polling

Dataset creation includes automatic status polling to monitor processing completion. Configure timeout settings as needed:

```python theme={"dark"}
dataset_create(
  folder_path="/path/to/data",
  wait_for_processing=True,
  processing_timeout=300  # 5 minutes
)
```

## Additional Resources

For comprehensive documentation and technical references:

* **[GitHub Repository](https://github.com/Labellerr/SDKPython)** - Source code and examples
* **[MCP Server README](https://github.com/Labellerr/SDKPython/blob/main/labellerr/mcp_server/README.md)** - Detailed server documentation

## Next Steps

<CardGroup>
  <Card title="SDK Documentation" icon="code" href="/sdk/getting-started">
    Learn about the Python SDK for programmatic access
  </Card>

  <Card title="Create Projects" icon="folder-plus" href="/sdk/create-project-sdk">
    Detailed guide on creating annotation projects
  </Card>

  <Card title="Export Data" icon="download" href="/sdk/create-export-sdk">
    Learn how to export your annotated data
  </Card>

  <Card title="Cookbooks" icon="book" href="/cookbooks/sdk-tutorials">
    Practical examples and tutorials
  </Card>
</CardGroup>


# Retrieve Projects & Datasets
Source: https://docs.labellerr.com/sdk/retrieve-projects-datasets-sdk

Learn how to retrieve all projects and datasets associated with a client in Labellerr using the SDK, including linked and unlinked datasets.

### Retrieving All Projects for a Client

You can retrieve all projects associated with a specific client ID using the SDK's project listing functionality:

<Note>
  **Important:** The `list_projects()` method only retrieves projects created after **April 15th, 2025**.
</Note>

#### Example Usage:

```python Retrieve All Projects lines icon="folder-open" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import list_projects
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

try:
    # List all projects - returns list of LabellerrProject objects
    projects = list_projects(client)
    
    print(f"Found {len(projects)} projects:")
    for project in projects:
        print(f"- Project ID: {project.project_id}")
        print(f"  Data Type: {project.data_type}")
        print(f"  Attached Datasets: {len(project.attached_datasets)}")
        print(f"  Created By: {project.created_by}")
        print(f"  Status Code: {project.status_code}")
        
except LabellerrError as e:
    print(f"Failed to retrieve projects: {str(e)}")
```

This method is useful when you need to:

* List all projects for a client
* Find specific project IDs
* Check project statuses and configurations
* Get an overview of client's work
* Access project properties programmatically

This returns a list of `LabellerrProject` objects, each with access to properties like `project_id`, `data_type`, `attached_datasets`, `created_by`, and more.

### Retrieving All Datasets

You can retrieve both linked and unlinked datasets associated with a client using the SDK's dataset listing capabilities:

#### Example Usage:

```python Retrieve All Datasets lines icon="database" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.datasets import list_datasets
from labellerr.core.schemas import DataSetScope
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

try:
    # Get all datasets using list_datasets with auto-pagination
    datasets_generator = list_datasets(
        client=client,
        datatype='image',
        scope=DataSetScope.client,  # or DataSetScope.project
        page_size=-1  # Auto-paginate through all datasets
    )
    
    # Iterate through the generator
    print("Datasets:")
    for dataset in datasets_generator:
        print(f"- Dataset ID: {dataset.get('dataset_id')}")
        print(f"  Name: {dataset.get('name')}")
        print(f"  Description: {dataset.get('description')}")
        print(f"  Data Type: {dataset.get('data_type')}")
        print(f"  Files Count: {dataset.get('files_count', 0)}")

except LabellerrError as e:
    print(f"Failed to retrieve datasets: {str(e)}")
```

<Note>
  **Pagination Support:**

  * Returns a **generator** that yields individual datasets
  * Use `page_size=-1` to automatically paginate through all datasets (recommended)
  * Use specific `page_size` to limit results (e.g., `page_size=20`)
  * Use `last_dataset_id` for manual pagination across multiple requests
  * Generator approach is memory-efficient for large numbers of datasets
</Note>

<Tip>
  **Available Scope Options:**

  * `DataSetScope.client` - Datasets with client-level permissions
  * `DataSetScope.project` - Datasets with project-level permissions
</Tip>

This method is useful when you need to:

* Get a comprehensive list of all datasets in your workspace
* Filter datasets by specific data types (image, video, audio, document, text)
* Organize datasets by scope (client-level or project-level permissions)
* Efficiently iterate through large numbers of datasets with pagination
* Memory-efficient processing of datasets using generators

#### Advanced Pagination Examples

<Tabs>
  <Tab title="Auto-Pagination (Recommended)">
    ```python Auto-Paginate Through All Datasets theme={"dark"}
    from labellerr.core.datasets import list_datasets
    from labellerr.core.schemas import DataSetScope

    # Auto-paginate through all datasets (memory-efficient)
    all_datasets = list_datasets(
        client=client,
        datatype='image',
        scope=DataSetScope.client,
        page_size=-1  # Automatically handles all pages
    )

    # Process datasets as they're retrieved
    for dataset in all_datasets:
        print(f"Processing dataset: {dataset.get('name')}")
        # Do something with each dataset
    ```
  </Tab>

  <Tab title="Fixed Page Size">
    ```python Get Specific Number of Datasets theme={"dark"}
    from labellerr.core.datasets import list_datasets
    from labellerr.core.schemas import DataSetScope

    # Get only first 20 datasets
    datasets = list_datasets(
        client=client,
        datatype='video',
        scope=DataSetScope.client,
        page_size=20
    )

    # Convert generator to list
    dataset_list = list(datasets)
    print(f"Retrieved {len(dataset_list)} datasets")
    ```
  </Tab>

  <Tab title="Manual Pagination">
    ```python Manual Pagination Across Requests theme={"dark"}
    from labellerr.core.datasets import list_datasets
    from labellerr.core.schemas import DataSetScope

    # First page
    page_1 = list(list_datasets(
        client=client,
        datatype='image',
        scope=DataSetScope.client,
        page_size=10
    ))

    # Get last dataset ID for next page
    last_id = page_1[-1].get('dataset_id') if page_1 else None

    # Second page using last_dataset_id
    if last_id:
        page_2 = list(list_datasets(
            client=client,
            datatype='image',
            scope=DataSetScope.client,
            page_size=10,
            last_dataset_id=last_id
        ))
    ```
  </Tab>
</Tabs>

### Retrieving Files from a Dataset

You can fetch all files from a specific dataset using the `fetch_files()` method:

#### Example Usage:

```python Fetch Files from Dataset lines icon="file" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.datasets import LabellerrDataset
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

try:
    # Get dataset instance
    dataset = LabellerrDataset(client=client, dataset_id="your_dataset_id")
    
    # Fetch all files
    files = dataset.fetch_files()
    
    print(f"Dataset contains {len(files)} files:")
    for file in files:
        print(f"- File ID: {file.get('file_id')}")
        print(f"  File Name: {file.get('file_name')}")
        print(f"  Status: {file.get('status')}")
        
except LabellerrError as e:
    print(f"Failed to fetch files: {str(e)}")
```

This method is useful when you need to:

* Get a list of all files in a dataset
* Check file statuses before creating a project
* Verify dataset contents
* Build custom file processing workflows

### Working with Projects and Datasets

#### Get Project Information

```python Get Project Details lines icon="folder" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

try:
    # Get project instance
    project = LabellerrProject(client=client, project_id="your_project_id")
    
    # Access project properties
    print(f"Project ID: {project.project_id}")
    print(f"Data Type: {project.data_type}")
    print(f"Attached Datasets: {project.attached_datasets}")
    
except LabellerrError as e:
    print(f"Failed to retrieve project: {str(e)}")
```

#### Attach Datasets to a Project

```python Attach Datasets lines icon="link" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.exceptions import LabellerrError

client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

try:
    project = LabellerrProject(client=client, project_id="your_project_id")
    
    # Attach a single dataset
    result = project.attach_dataset_to_project(dataset_id="dataset_id_to_attach")
    
    # Or attach multiple datasets at once
    # result = project.attach_dataset_to_project(dataset_ids=["dataset_1", "dataset_2"])
    
    print(f"Dataset(s) attached successfully: {result}")
    
except LabellerrError as e:
    print(f"Failed to attach dataset: {str(e)}")
```

#### Detach Datasets from a Project

```python Detach Datasets lines icon="unlink" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.exceptions import LabellerrError

client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

try:
    project = LabellerrProject(client=client, project_id="your_project_id")
    
    # Detach a single dataset
    result = project.detach_dataset_from_project(dataset_id="dataset_id_to_detach")
    
    # Or detach multiple datasets at once
    # result = project.detach_dataset_from_project(dataset_ids=["dataset_1", "dataset_2"])
    
    print(f"Dataset(s) detached successfully: {result}")
    
except LabellerrError as e:
    print(f"Failed to detach dataset: {str(e)}")
```

<Note>
  **Important:** When detaching datasets from a project, the method no longer requires `client_id` and `project_id` parameters as these are automatically derived from the project instance.
</Note>

### Bulk Assign Files

You can bulk assign multiple files to a new status in a project, optionally assigning them to a specific user.

<Warning>
  **Important Requirement:** The user being assigned to (specified in `assign_to` parameter) must already be added to the project. If the user is not present in the project, the bulk assign operation will fail.
</Warning>

#### Example Usage:

```python Bulk Assign Files lines icon="layer-group" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.exceptions import LabellerrError

client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

try:
    project = LabellerrProject(client=client, project_id="your_project_id")
    
    # Bulk assign files to review status
    result = project.bulk_assign_files(
        file_ids=["file_id_1", "file_id_2", "file_id_3"],
        new_status="review",
        assign_to="ASSIGNEE_EMAIL@company.com"  # Optional: Replace with actual user email
    )
    
    print(f"Files assigned successfully: {result}")
    
except LabellerrError as e:
    print(f"Failed to bulk assign files: {str(e)}")
```

<Card title="Acceptable Status Values" icon="list">
  | Status | Description |
  | - | - |
  | `annotation` | Assign files for annotation |
  | `review` | Assign files for review after annotation |
  | `client_review` | Assign files for client review |
  | `accepted` | Mark files as accepted |
  | `rejected` | Mark files as rejected |
</Card>

### When to Use Bulk Assign

**Bulk assign is essential for automating annotation workflows:**

<Card title="Common Use Cases" icon="list">
  | Use Case | Example |
  | - | - |
  | **Batch Assignment** | Assign 100 images to annotator at once instead of clicking 100 times |
  | **Status Progression** | Move all "annotation" files to "review" status after completion |
  | **Team Management** | Distribute files across multiple team members efficiently |
  | **Workflow Automation** | Automate the flow: annotation → review → client\_review → accepted |
  | **Onboarding** | Assign initial set of files to new annotators |
  | **Quality Control** | Send all files to a senior reviewer before client submission |
</Card>

**Example Scenario:**
Imagine you have 500 images that need annotation. After annotators finish, you want to send them all to review status. Without bulk assign, you'd click 500 times. With `bulk_assign_files()`, it's one API call:

```python theme={"dark"}
# After annotation is complete
result = project.bulk_assign_files(
    file_ids=all_500_file_ids,
    new_status="review",
    assign_to="REVIEWER_EMAIL@company.com"  # Replace with actual reviewer email
)
```

### Error Handling

The Labellerr SDK uses a custom exception class, `LabellerrError`, to indicate issues during API interactions. Always wrap your function calls in `try-except` blocks to gracefully handle errors.

#### Example:

```python Error Handling Example lines icon="exclamation-triangle" theme={"dark"}
from labellerr.core.exceptions import LabellerrError
from labellerr.core.projects import LabellerrProject

try:
    # Example function call
    project = LabellerrProject(client=client, project_id="project_id")
    datasets = project.attached_datasets
except LabellerrError as e:
    print(f"An error occurred: {str(e)}")
```

***

## API Reference

### Function Signatures

<AccordionGroup>
  <Accordion title="list_projects(client)" icon="folder">
    ```python theme={"dark"}
    from labellerr.core.projects import list_projects

    def list_projects(client: LabellerrClient) -> list[LabellerrProject]:
        """
        Retrieves a list of projects associated with a client ID.
        
        Parameters:
            client: LabellerrClient instance
            
        Returns:
            List of LabellerrProject objects with properties:
            - project_id: str
            - data_type: str
            - attached_datasets: list
            - created_by: str
            - created_at: datetime
            - annotation_template_id: str
            - status_code: int
        """
    ```

    **Example:**

    ```python theme={"dark"}
    projects = list_projects(client)
    for project in projects:
        print(f"{project.project_id}: {project.data_type}")
    ```
  </Accordion>

  <Accordion title="list_datasets(client, datatype, scope, page_size, last_dataset_id)" icon="database">
    ```python theme={"dark"}
    from labellerr.core.datasets import list_datasets
    from labellerr.core.schemas import DataSetScope

    def list_datasets(
        client: LabellerrClient,
        datatype: str,
        scope: DataSetScope,
        page_size: int = 10,
        last_dataset_id: str = None
    ) -> Generator:
        """
        Retrieves datasets by parameters with pagination support.
        
        Parameters:
            client: LabellerrClient instance
            datatype: Type of data ('image', 'video', 'audio', 'document', 'text')
            scope: DataSetScope.client or DataSetScope.project
            page_size: Number of datasets per page (default: 10, -1 for auto-pagination)
            last_dataset_id: ID of last dataset from previous page (for manual pagination)
            
        Returns:
            Generator yielding dataset dictionaries with keys:
            - dataset_id: str
            - name: str
            - description: str
            - data_type: str
            - files_count: int
            - created_at: datetime
            - created_by: str
        """
    ```

    **Examples:**

    ```python theme={"dark"}
    # Auto-paginate through all
    for dataset in list_datasets(client, 'image', DataSetScope.client, page_size=-1):
        print(dataset['name'])

    # Get first 20 only
    datasets = list(list_datasets(client, 'video', DataSetScope.client, page_size=20))
    ```
  </Accordion>

  <Accordion title="LabellerrDataset.fetch_files()" icon="file">
    ```python theme={"dark"}
    from labellerr.core.datasets import LabellerrDataset

    dataset = LabellerrDataset(client=client, dataset_id="dataset_id")
    files = dataset.fetch_files()
    ```

    **Returns:**

    List of file dictionaries with metadata including:

    * file\_id: str
    * file\_name: str
    * status: str
    * file\_type: str
    * file\_size: int
  </Accordion>

  <Accordion title="LabellerrProject - Properties" icon="folder-tree">
    ```python theme={"dark"}
    from labellerr.core.projects import LabellerrProject

    project = LabellerrProject(client=client, project_id="project_id")

    # Available properties:
    project.project_id           # str: Project identifier
    project.data_type            # str: Data type (image, video, etc.)
    project.attached_datasets    # list: List of dataset IDs
    project.created_by           # str: Creator email
    project.created_at           # datetime: Creation timestamp
    project.annotation_template_id  # str: Template ID
    project.status_code          # int: Project status code
    ```

    **Methods:**

    * `attach_dataset_to_project(dataset_id=None, dataset_ids=None)`
    * `detach_dataset_from_project(dataset_id=None, dataset_ids=None)`
    * `bulk_assign_files(file_ids, new_status, assign_to=None)`
    * `upload_preannotations(annotation_format, annotation_file, conf_bucket=None, _async=False)`
    * `create_export(export_config)`
    * `list_exports()` - Get all exports (completed and in-progress) for the project
    * `check_export_status(report_ids)` - Check status of specific exports
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup>
  <Card title="Use Auto-Pagination" icon="arrows-rotate">
    Set `page_size=-1` for `list_datasets()` to automatically handle all pages without manual intervention
  </Card>

  <Card title="Leverage Generators" icon="memory">
    Process datasets as they're retrieved instead of loading all into memory at once
  </Card>

  <Card title="Filter by Scope" icon="filter">
    Use `DataSetScope.client` for workspace-level datasets or `DataSetScope.project` for project-specific ones
  </Card>

  <Card title="Error Handling" icon="shield-check">
    Always wrap API calls in try-except blocks to catch `LabellerrError` exceptions
  </Card>
</CardGroup>

***

The Labellerr SDK is a fast and reliable solution for managing annotation workflows. Want to try it end-to-end? Refer to this [**Google Colab Cookbook**](https://colab.research.google.com/github/Labellerr/Hands-On-Learning-in-Computer-Vision/blob/main/SDK%20Tutorials/Labellerr_SDK_End_to_End_Annotation_Pipeline.ipynb) for a ready-to-run tutorial. For more related cookbooks and examples, please visit our repository: [Labellerr Hands-On Learning](https://github.com/Labellerr/Hands-On-Learning-in-Computer-Vision)


# Upload Pre-annotations
Source: https://docs.labellerr.com/sdk/upload-preannotation-sdk

Accelerate annotation workflows by importing existing labels into Labellerr projects through the Python SDK.

## Overview

Pre-annotations enable you to import existing labels into your Labellerr projects, significantly reducing manual annotation effort. This feature allows your team to focus on reviewing and refining pre-loaded annotations rather than creating them from scratch.

<CardGroup>
  <Card title="Workflow Efficiency" icon="bolt">
    Reduce annotation time by up to 70% through pre-loaded label imports
  </Card>

  <Card title="File Size Limit" icon="database">
    Support for annotation files up to 25 MB
  </Card>

  <Card title="Format Support" icon="file-code">
    Industry-standard COCO JSON format compatibility
  </Card>
</CardGroup>

## Critical Requirements

<Warning>
  **File Name Matching is Mandatory**

  For pre-annotations to function correctly, file names in your annotation JSON must exactly match the image file names in your Labellerr project.

  **Validation Checklist:**

  * Image file names in JSON (e.g., `"file_name"` field in COCO format) match uploaded image names
  * File extensions match precisely (`.jpg`, `.png`, `.jpeg`)
  * File names are case-sensitive (`image.jpg` is not equal to `Image.jpg`)

  **Examples:**

  ```json theme={"dark"}
  // Correct - exact match
  {"file_name": "burger.jpeg"}  → Uploaded as: burger.jpeg

  // Incorrect - extension mismatch
  {"file_name": "burger.jpeg"}  → Uploaded as: burger.jpg

  // Incorrect - case mismatch
  {"file_name": "burger.jpeg"}  → Uploaded as: Burger.jpeg
  ```

  Mismatched file names will prevent annotations from being applied to the corresponding images.
</Warning>

## Uploading Attributes with Pre-annotations

Attributes (such as Radio, Dropdown, Select, Boolean, and Input fields attached to bounding boxes, polygons, or masks) can be included directly within the `coco_json` file structure.

### JSON Schema / Structure Explanation

Attributes are formatted inside each item of the `annotations` array:

* **`attributes`** *(array of objects)*: List of attribute answers for the annotation.
  * `name` *(string)*: Must match the `componentClass` defined in the project template's metadata for that question.
  * `fieldType` *(string)*: The attribute input type (e.g., `"radio"`, `"dropdown"`, `"select"`, `"boolean"`, `"input"`, `"sentiment"`).
  * `answer` *(list of strings)*: Selected option value(s) or input string (e.g., `["option_a"]` or `["text value"]`).
  * `id` *(integer)*: Sequential ID index for the attribute in the array.

<Note>
  **Option Validation**:
  For constrained attribute types (`radio`, `dropdown`, `select`, `boolean`), answer values are validated against the allowed options defined in the project metadata. Values not matching predefined options will be ignored. For `input` attributes, free-form text is accepted.
</Note>

### Sample COCO JSON Payload (`coco_with_attributes.json`)

```json theme={"dark"}
{
    "images": [
        {
            "id": 1552111613,
            "width": 1196,
            "height": 576,
            "file_name": "sample_image.png"
        }
    ],
    "annotations": [
        {
            "id": 101,
            "image_id": 1552111613,
            "category_id": 1,
            "bbox": [223, 161, 236, 177],
            "area": 41772,
            "iscrowd": 0,
            "attributes": [
                {
                    "id": 0,
                    "name": "attri1",
                    "fieldType": "radio",
                    "answer": ["a"]
                },
                {
                    "id": 1,
                    "name": "in",
                    "fieldType": "input",
                    "answer": ["Sample input text"]
                }
            ]
        },
        {
            "id": 102,
            "image_id": 1552111613,
            "category_id": 0,
            "bbox": [613, 179, 164, 135],
            "area": 22140,
            "iscrowd": 0,
            "attributes": [
                {
                    "id": 0,
                    "name": "at2",
                    "fieldType": "dropdown",
                    "answer": ["a1"]
                }
            ]
        }
    ],
    "categories": [
        {
            "id": 0,
            "name": "person1"
        },
        {
            "id": 1,
            "name": "person2"
        }
    ]
}
```

### Python SDK Code Snippet

```python theme={"dark"}
import os
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject

# Initialize the Labellerr SDK Client
client = LabellerrClient(
    api_key=os.getenv("LABELLERR_API_KEY"),
    api_secret=os.getenv("LABELLERR_API_SECRET"),
    client_id=os.getenv("LABELLERR_CLIENT_ID")
)

# Connect to your project
project = LabellerrProject(
    client=client, 
    project_id="YOUR_PROJECT_ID"
)

# Upload pre-annotations including attributes
response = project.upload_preannotations(
    annotation_format="coco_json",
    annotation_file="coco_with_attributes.json"
)

print("Pre-annotation Upload Submitted Successfully:")
print(response)
```

## Implementation

The SDK provides a unified method with optional async behavior:

<Tabs>
  <Tab title="Synchronous (Default)">
    <Info>
      **Recommended for:** Batch processing scripts and sequential workflows where blocking behavior is acceptable
    </Info>

    ```python theme={"dark"}
    from labellerr.client import LabellerrClient
    from labellerr.core.projects import LabellerrProject
    from labellerr.core.exceptions import LabellerrError

    # Initialize client with credentials
    client = LabellerrClient(
        api_key='your_api_key',
        api_secret='your_api_secret',
        client_id='your_client_id'
    )

    # Configure upload parameters
    project_id = 'project_123'
    annotation_format = 'coco_json'
    annotation_file = '/path/to/annotations.json'

    try:
        # Get project instance
        project = LabellerrProject(client=client, project_id=project_id)
        
        # Execute synchronous upload (blocks until complete)
        result = project.upload_preannotations(
            annotation_format=annotation_format,
            annotation_file=annotation_file,
            _async=False  # Default: blocks until completion
        )
        
        # Validate completion status
        if result['response']['status'] == 'completed':
            print("Pre-annotations processed successfully")
            
            # Extract metadata
            metadata = result['response'].get('metadata', {})
            print(f"Processing metadata: {metadata}")
            
    except LabellerrError as e:
        print(f"Upload failed: {str(e)}")
    ```

    <Note>
      **Execution Behavior**: This method blocks execution until processing completes. Processing duration varies based on file size and annotation count.
    </Note>
  </Tab>

  <Tab title="Asynchronous">
    <Info>
      **Recommended for:** Production applications, web services, and scenarios requiring non-blocking operations
    </Info>

    ```python theme={"dark"}
    from labellerr.client import LabellerrClient
    from labellerr.core.projects import LabellerrProject
    from labellerr.core.exceptions import LabellerrError

    # Initialize client with credentials
    client = LabellerrClient(
        api_key='your_api_key',
        api_secret='your_api_secret',
        client_id='your_client_id'
    )

    # Configure upload parameters
    project_id = 'project_123'
    annotation_format = 'coco_json'
    annotation_file = '/path/to/annotations.json'

    try:
        # Get project instance
        project = LabellerrProject(client=client, project_id=project_id)
        
        # Initiate asynchronous upload (returns a Future)
        future = project.upload_preannotations(
            annotation_format=annotation_format,
            annotation_file=annotation_file,
            _async=True  # Returns immediately with Future
        )
        
        print("Upload initiated - processing asynchronously")
        
        # You can execute other operations while waiting
        # perform_other_tasks()
        
        # Retrieve result when ready
        try:
            result = future.result(timeout=300)  # 5 minute timeout
            
            if result['response']['status'] == 'completed':
                print("Pre-annotations processed successfully")
                metadata = result['response'].get('metadata', {})
                print(f"Processing metadata: {metadata}")
                
        except TimeoutError:
            print("Processing exceeded timeout threshold")
        except Exception as e:
            print(f"Processing error: {str(e)}")
            
    except LabellerrError as e:
        print(f"Upload initialization failed: {str(e)}")
    ```

    <Note>
      **Execution Behavior**: Returns immediately with a Future object, enabling concurrent task execution during background processing.
    </Note>
  </Tab>
</Tabs>

***

## Method Comparison

Use the `_async` parameter to control execution behavior:

<CardGroup>
  <Card title="Synchronous (_async=False)" icon="hourglass">
    **Use Cases:**

    * Batch processing scripts
    * Sequential workflow automation
    * Single-threaded operations

    **Characteristics:**

    * Simplified implementation
    * Direct result return
    * Blocking execution model
    * Default behavior
  </Card>

  <Card title="Asynchronous (_async=True)" icon="rocket">
    **Use Cases:**

    * Web applications
    * Real-time dashboards
    * Large-scale file processing

    **Characteristics:**

    * Non-blocking operation
    * Returns Future object immediately
    * Configurable timeout handling
    * Parallel task support
  </Card>
</CardGroup>

***

## Processing Workflow

Both implementation methods follow an identical server-side processing pipeline:

<Steps>
  <Step title="File Upload">
    Annotation JSON file is transmitted to Labellerr infrastructure
  </Step>

  <Step title="Format Validation">
    File structure and format are validated against COCO specification and project schema
  </Step>

  <Step title="File Name Resolution">
    Image file names referenced in annotations are matched against project assets
  </Step>

  <Step title="Annotation Application">
    Validated annotations are applied to matched images within the project
  </Step>

  <Step title="Status Return">
    Processing status and metadata are returned to the client application
  </Step>
</Steps>

<Tip>
  **Performance Guidelines**: Processing duration correlates with file size and annotation count. Files under 1 MB with fewer than 100 annotations typically process within 30 seconds. Larger datasets may require several minutes.
</Tip>

***

## Common Use Cases

<CardGroup>
  <Card title="Model Prediction Integration" icon="brain">
    Import machine learning model predictions as pre-annotations for human validation and correction workflows
  </Card>

  <Card title="Platform Migration" icon="download">
    Transfer annotations from external annotation platforms to Labellerr infrastructure
  </Card>

  <Card title="Project Replication" icon="recycle">
    Reuse annotations from completed projects as foundation for similar initiatives
  </Card>

  <Card title="Automated Pipeline Integration" icon="wand-magic-sparkles">
    Upload annotations generated by automated systems or custom scripts for review workflows
  </Card>
</CardGroup>

***

## Troubleshooting Guide

<AccordionGroup>
  <Accordion title="Annotations Not Applied to Images" icon="circle-exclamation">
    **Symptom**: Upload completes successfully but annotations are not visible on project images.

    **Resolution Steps**:

    * Verify exact file name matching between JSON and uploaded images (case-sensitive)
    * Confirm file extension consistency (`.jpg` vs `.jpeg` vs `.png`)
    * Validate annotation format parameter is set to `'coco'`
    * Ensure images were uploaded to project prior to pre-annotation upload
  </Accordion>

  <Accordion title="Upload Timeout or Connection Failure" icon="clock">
    **Symptom**: Upload operation fails with timeout or network connection errors.

    **Resolution Steps**:

    * Verify file size is within 25 MB limit
    * Utilize asynchronous method with extended timeout configuration
    * Confirm network stability and connectivity
    * Validate JSON file conforms to COCO format specification
    * Consider splitting large files into smaller batches
  </Accordion>

  <Accordion title="Format Validation Error" icon="file-circle-xmark">
    **Symptom**: API returns format or structure validation errors.

    **Resolution Steps**:

    * Validate JSON structure against COCO format specification
    * Ensure all required COCO fields are present (`images`, `annotations`, `categories`)
    * Verify annotation coordinates are within valid image bounds
    * Confirm category IDs in annotations match category definitions
  </Accordion>

  <Accordion title="Authentication or Permission Errors" icon="lock">
    **Symptom**: Upload fails with authentication or authorization errors.

    **Resolution Steps**:

    * Verify API key and secret credentials are correct
    * Confirm client ID matches your organization
    * Validate write access permissions for the target project
    * Ensure project exists and project ID is accurate
  </Accordion>
</AccordionGroup>

***

## Response Schema

Successful upload operations return a structured response:

```json theme={"dark"}
{
  "response": {
    "status": "completed",
    "activity_id": "9c696f10-7e76-40e0-9852-34b99be2db52",
    "metadata": {
      "total_annotations": 42,
      "matched_files": 10,
      "unmatched_files": 0,
      "processing_time_seconds": 15.3
    }
  }
}
```

<Note>
  **Status Values**:

  * `completed` - Annotations successfully applied to project
  * `processing` - Upload in progress (asynchronous method)
  * `failed` - Processing encountered errors (review error details)
</Note>

***

## Best Practices

<CardGroup>
  <Card title="Pre-Upload Validation" icon="check-double">
    * Validate JSON format locally before upload
    * Test with small sample datasets initially
    * Verify file name matching requirements
  </Card>

  <Card title="Asynchronous for Scale" icon="gauge-high">
    * Files exceeding 5 MB
    * Datasets with over 1000 annotations
    * Production application integrations
  </Card>

  <Card title="Activity Monitoring" icon="chart-line">
    * Track activity IDs for audit trails
    * Review metadata for processing insights
    * Monitor unmatched file counts
  </Card>

  <Card title="Batch Processing Strategy" icon="layer-group">
    * Partition large datasets into batches
    * Implement parallel processing where applicable
    * Design robust error handling mechanisms
  </Card>
</CardGroup>

## Related Documentation

<CardGroup>
  <Card title="Project Creation" icon="folder-plus" href="/sdk/create-project-sdk">
    Create and configure projects programmatically via SDK
  </Card>

  <Card title="Export Annotations" icon="file-export" href="/sdk/create-export-sdk">
    Export annotated datasets in multiple formats
  </Card>

  <Card title="SDK Getting Started" icon="rocket" href="/sdk/getting-started">
    Complete SDK initialization and configuration guide
  </Card>
</CardGroup>

<Note>
  For technical support, contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# Video Operations
Source: https://docs.labellerr.com/sdk/video-project-operations-sdk

Learn how to manage keyframes in video projects using the Labellerr Python SDK, including adding, updating, and deleting keyframes for video annotation workflows.

## Introduction

<Card title="What are Keyframes?" icon="circle-info">
  **Keyframes** in video annotation are specific frames selected for annotation within a video file. Instead of annotating every frame, you can select key moments that represent important changes or events in the video.

  This approach:

  * Reduces annotation time and cost
  * Focuses on critical frames
  * Maintains annotation quality
  * Enables efficient video annotation workflows
</Card>

***

## Video Project Setup

### Import Required Modules

```python Required Imports lines icon="code" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.schemas import KeyFrame
from labellerr.core.exceptions import LabellerrError
```

<Note>
  **Important:** Keyframe operations are only available for video projects. The `LabellerrProject` class automatically detects video projects and provides these methods.
</Note>

***

## Adding or Updating Keyframes

### KeyFrame Schema

Before adding keyframes, you need to understand the KeyFrame structure:

```python KeyFrame Structure lines icon="code" theme={"dark"}
from labellerr.core.schemas import KeyFrame

keyframe = KeyFrame(
    frame_number=100,      # Frame number (must be >= 0)
    is_manual=True,        # Whether it's manually selected
    method="manual",       # Selection method
    source="manual"        # Source of the keyframe
)
```

<Card title="KeyFrame Parameters" icon="list">
  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `frame_number` | int | Yes | Frame number in the video (must be ≥ 0) |
  | `is_manual` | bool | No | Whether keyframe was manually selected (default: True) |
  | `method` | str | No | Selection method (default: "manual") |
  | `source` | str | No | Source of the keyframe (default: "manual") |
</Card>

***

### Add or Update Keyframes

You can add new keyframes or update existing ones using the same method:

```python Add/Update Keyframes lines icon="plus" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject
from labellerr.core.schemas import KeyFrame

client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

try:
    # Get video project instance
    project = LabellerrProject(client=client, project_id="video_project_id")
    
    # Define keyframes to add/update
    keyframes = [
        KeyFrame(frame_number=0, is_manual=True, method="manual", source="manual"),
        KeyFrame(frame_number=100, is_manual=True, method="manual", source="manual"),
        KeyFrame(frame_number=200, is_manual=True, method="manual", source="manual")
    ]
    
    # Add or update keyframes for a specific video file
    result = project.add_or_update_keyframes(
        file_id="video_file_id",
        keyframes=keyframes
    )
    
    print(f"Keyframes added/updated successfully: {result}")
    
except LabellerrError as e:
    print(f"Failed to add/update keyframes: {str(e)}")
```

<Info>
  **Behavior:**

  * If a keyframe with the same frame\_number already exists, it will be updated
  * If the frame\_number is new, a new keyframe will be added
</Info>

***

### Batch Keyframe Creation

You can efficiently add multiple keyframes at once:

```python Batch Keyframe Creation lines icon="layer-group" theme={"dark"}
from labellerr.core.schemas import KeyFrame

# Create keyframes at regular intervals (every 30 frames)
keyframes = []
for frame_num in range(0, 300, 30):  # 0, 30, 60, 90, ..., 270
    keyframes.append(
        KeyFrame(frame_number=frame_num, is_manual=True, method="manual", source="manual")
    )

project = LabellerrProject(client=client, project_id="video_project_id")

result = project.add_or_update_keyframes(
    file_id="video_file_id",
    keyframes=keyframes
)

print(f"Added {len(keyframes)} keyframes")
```

***

## Deleting Keyframes

### Delete Specific Keyframes

Remove keyframes by specifying their frame numbers:

```python Delete Keyframes lines icon="trash" theme={"dark"}
from labellerr.client import LabellerrClient
from labellerr.core.projects import LabellerrProject

client = LabellerrClient(
    api_key='your_api_key',
    api_secret='your_api_secret',
    client_id='your_client_id'
)

try:
    project = LabellerrProject(client=client, project_id="video_project_id")
    
    # Delete specific keyframes by frame number
    result = project.delete_keyframes(
        file_id="video_file_id",
        keyframes=[0, 100, 200]  # List of frame numbers to delete
    )
    
    print(f"Keyframes deleted successfully: {result}")
    
except LabellerrError as e:
    print(f"Failed to delete keyframes: {str(e)}")
```

<Warning>
  **Caution:** Deleting keyframes also removes any annotations associated with those frames. This action cannot be undone.
</Warning>

***

## Complete Workflow Example

<Card title="End-to-End Keyframe Management" icon="rocket">
  ```python Complete Keyframe Workflow lines icon="rocket" theme={"dark"}
  from labellerr.client import LabellerrClient
  from labellerr.core.projects import LabellerrProject
  from labellerr.core.schemas import KeyFrame
  from labellerr.core.exceptions import LabellerrError

  # Initialize client
  client = LabellerrClient(
      api_key='your_api_key',
      api_secret='your_api_secret',
      client_id='your_client_id'
  )

  try:
      # Step 1: Get video project
      project = LabellerrProject(client=client, project_id="video_project_id")
      print(f"Working with project: {project.project_id}")
      
      # Step 2: Add initial keyframes (every 60 frames for first 5 minutes at 30fps)
      initial_keyframes = [
          KeyFrame(frame_number=i, is_manual=True, method="manual", source="manual")
          for i in range(0, 9000, 60)  # 9000 frames = 5 min at 30fps
      ]
      
      result = project.add_or_update_keyframes(
          file_id="video_file_id",
          keyframes=initial_keyframes
      )
      print(f"Added {len(initial_keyframes)} keyframes")
      
      # Step 3: Update specific keyframes (e.g., adjust frame 1800)
      updated_keyframes = [
          KeyFrame(frame_number=1800, is_manual=True, method="manual", source="manual")
      ]
      
      result = project.add_or_update_keyframes(
          file_id="video_file_id",
          keyframes=updated_keyframes
      )
      print(f"Updated keyframe at frame 1800")
      
      # Step 4: Delete unwanted keyframes
      frames_to_delete = [3600, 7200]  # Remove keyframes at 2min and 4min marks
      result = project.delete_keyframes(
          file_id="video_file_id",
          keyframes=frames_to_delete
      )
      print(f"Deleted {len(frames_to_delete)} keyframes")
      
  except LabellerrError as e:
      print(f"Error in keyframe workflow: {str(e)}")
  ```
</Card>

***

## Common Use Cases

<CardGroup>
  <Card title="Regular Interval Sampling" icon="clock">
    Select keyframes at regular intervals (e.g., every 30 frames) for consistent annotation coverage
  </Card>

  <Card title="Scene Change Detection" icon="film">
    Use automated scene detection to identify keyframes at scene transitions
  </Card>

  <Card title="Event-Based Selection" icon="star">
    Manually select keyframes at important events or actions in the video
  </Card>

  <Card title="Adaptive Sampling" icon="wand-magic-sparkles">
    Adjust keyframe density based on video content complexity
  </Card>
</CardGroup>

***

## Best Practices

<Card title="Keyframe Selection Guidelines" icon="lightbulb">
  ### Optimal Keyframe Density

  * **Low motion videos:** 1 keyframe every 2-3 seconds
  * **Medium motion videos:** 1 keyframe every 1-2 seconds
  * **High motion videos:** 1 keyframe every 0.5-1 second
  * **Critical events:** Always include keyframes at important moments

  ### Performance Considerations

  * Add keyframes in batches rather than one-by-one
  * Validate frame numbers before submission
  * Handle errors gracefully with try-except blocks
  * Consider video length and framerate when selecting intervals

  ### Annotation Quality

  * Include keyframes that capture state changes
  * Ensure sufficient coverage for temporal tracking
  * Balance between annotation workload and quality
  * Review keyframe selection before starting annotation
</Card>

***

## Error Handling

<Card title="Common Errors and Solutions" icon="triangle-exclamation">
  ```python Error Handling Example lines icon="shield" theme={"dark"}
  from labellerr.core.exceptions import LabellerrError

  try:
      project = LabellerrProject(client=client, project_id="video_project_id")
      
      keyframes = [
          KeyFrame(frame_number=100, is_manual=True, method="manual", source="manual")
      ]
      
      result = project.add_or_update_keyframes(
          file_id="video_file_id",
          keyframes=keyframes
      )
      
  except LabellerrError as e:
      if "not found" in str(e).lower():
          print("Error: Video file or project not found")
      elif "invalid frame" in str(e).lower():
          print("Error: Frame number is invalid")
      else:
          print(f"Error: {str(e)}")
  ```

  ### Common Issues

  | Error | Cause | Solution |
  | - | - | - |
  | Invalid frame number | Negative frame number | Ensure frame\_number ≥ 0 |
  | File not found | Invalid file\_id | Verify the video file exists in the project |
  | Project not video type | Non-video project | Keyframes only work with video projects |
  | Validation error | Invalid KeyFrame structure | Check all required fields are provided |
</Card>

***

## Advanced Usage

### Custom Keyframe Selection Logic

```python Custom Keyframe Logic lines icon="code" theme={"dark"}
def select_keyframes_with_threshold(video_length_frames, min_interval=30, max_interval=90):
    """
    Intelligently select keyframes based on video length.
    """
    keyframes = []
    
    if video_length_frames < 3000:  # Short video
        interval = min_interval
    elif video_length_frames < 10000:  # Medium video
        interval = 60
    else:  # Long video
        interval = max_interval
    
    for frame_num in range(0, video_length_frames, interval):
        keyframes.append(
            KeyFrame(frame_number=frame_num, is_manual=True, method="manual", source="manual")
        )
    
    return keyframes

# Use the custom logic
keyframes = select_keyframes_with_threshold(video_length_frames=18000)
project.add_or_update_keyframes(file_id="video_file_id", keyframes=keyframes)
```

***

## Related Documentation

<CardGroup>
  <Card title="Create Projects" icon="folder-plus" href="/sdk/create-project-sdk">
    Learn how to create video annotation projects
  </Card>

  <Card title="Retrieve Projects" icon="download" href="/sdk/retrieve-projects-datasets-sdk">
    Retrieve project information and file lists
  </Card>

  <Card title="Getting Started" icon="rocket" href="/sdk/getting-started">
    SDK installation and initialization guide
  </Card>
</CardGroup>

<Note>
  For technical support, contact [support@tensormatics.com](mailto:support@tensormatics.com)
</Note>


# System Requirements
Source: https://docs.labellerr.com/system-requirements/system-requirements

Verify your hardware and network setup to ensure optimal performance during heavy data annotation workflows.

To perform heavy data annotation smoothly on high-resolution video timeline tracking, and AI-assisted segmentation, your system should meet or exceed the following specifications.

<CardGroup>
  <Card title="System Memory" icon="memory">
    **Minimum 16 GB RAM**

    Required to cache high-resolution image sequences and run multi-instance models smoothly in the browser.
  </Card>

  <Card title="Processor (CPU)" icon="microchip">
    **Intel i5 10th Gen** *(or Mac/Apple Silicon equivalent)*

    Ensures low-latency browser canvas rendering and fast calculations for polygon edits and AI predictions.
  </Card>

  <Card title="Web Browser" icon="chrome">
    **Google Chrome Supported Only**

    Our canvas engine is optimized specifically for Chrome. Other browsers may experience interface lag or feature errors.
  </Card>

  <Card title="Network Speed" icon="wifi">
    **Minimum 5 Mbps Bandwidth**

    Ensures seamless cloud dataset retrieval, pre-annotation injection, and fast export operations.
  </Card>
</CardGroup>

***

## Performance Recommendations for Heavy Annotation

<Note>
  When working with long video sequences (100MB - 500MB) or dense datasets with hundreds of overlapping bounding boxes, hardware specs become critical to prevent browser tab crashes.
</Note>

### Why Chrome is Required?

Labellerr leverages GPU-accelerated WebGL rendering. Google Chrome provides the most compliant and highly-optimized runtime for these features.

### Recommended Environment Setup:

* **Hardware Acceleration:** Ensure *Hardware Acceleration* is enabled in Chrome Settings (`chrome://settings/system`).
* **Network Stability:** A wired ethernet connection or strong 5 GHz Wi-Fi is recommended to ensure continuous streaming of frames without buffering.
* **Tab Management:** Close unnecessary browser tabs and resource-heavy background applications during intensive annotation runs.


# Datasets
Source: https://docs.labellerr.com/tutorials/datasets

Learn about datasets in Labellerr - how to create, manage, and work with workspace-level datasets for your annotation projects.

<Note>
  This guide is meant for users to understand the concept of a dataset, how to create a new dataset, how to make changes, types of datasets etc. The guide also covers in-depth details about linking new datasets, exporting data from existing datasets and overall management datasets.
</Note>

<Card title="Topics Covered" icon="database">
  This guide covers dataset management in Labellerr:

  * **What are Datasets?** - Understanding data collection concepts
  * **Workspace Level Datasets** - Organization-wide data management
  * **Creating Datasets** - Step-by-step dataset creation process
  * **Dataset Types** - Supported file formats and data types
  * **Dataset Linking** - Connecting datasets to projects
  * **Dataset Management** - Editing, exporting, and maintaining datasets
</Card>

## Datasets

Datasets are an ordered collection of the data. On Labellerr, data is segregated based on file type and the supported data types in Labellerr are Image, Audio, Video, Text or Document.

<Frame>
  <img alt="Dataset overview" />
</Frame>

## Workspace Level Datasets

Datasets created at the workspace level are referred to as *Workspace-Level Datasets*. To create a Workspace-Level Dataset, the toggle buttons for "Enable Review Cycle" and "Client Review Cycle" must be enabled. These datasets are accessible to all users within the workspace and can be linked to any project in the workspace.

### Permission Level to Create Workspace Level Datasets

<Frame>
  <img alt="Permission levels for datasets" />
</Frame>

<Frame>
  <img alt="Dataset permission interface" />
</Frame>

## Create Workspace Level Datasets

<Steps>
  <Step title="Accessing Datasets Screen">
    Redirect to the Workspace Level Datasets page in your workspace by clicking 'Datasets' options. After that, you would be redirected to the following page.

    <Info>
      Alternatively, the Dataset page can be accessed through your dashboard by clicking on the settings options from the taskbar> Selecting 'Datasets' option on the left.
    </Info>
  </Step>

  <Step title="New Dataset and View All Datasets">
    Click the Button "**Create New dataset**"

    <Frame>
      <img alt="Create new dataset button" />
    </Frame>
  </Step>

  <Step title="Selecting Data Type">
    Select the type of Data you have and click on **next.**

    <Frame>
      <img alt="Select data type for dataset" />
    </Frame>
  </Step>

  <Step title="Uploading Files from Sources">
    Select the Source from where you want to upload data-files.

    <Frame>
      <img alt="Upload sources selection" />
    </Frame>

    ### 1. Google Drive

    Click on 'Google Drive' from the sources list, then click 'Create New Collection', authorize using your email ID, and select the data from Google Drive that you want to import. Enter any name in 'Connection Name' and Connection Description(Optional). Click 'Create Connection'.

    <Frame>
      <img alt="Google Drive connection setup" />
    </Frame>

    ### 2. Google Cloud Storage

    Click 'Google Cloud storage' from the sources list. Here are the [details](https://drive.google.com/file/d/1VETRHSDf7m3nV_KAe6Rc4ObxR4Z6lCYm/view?usp=sharing) to connect data with GCS. OR

    You can follow the steps outlined in the attached PDF to attach data from GCS.

    ### 3. Amazon S3

    Click 'Amazon s3' from the sources list. Here are the [details](https://drive.google.com/file/d/1eeZ9Hab4Fb6r89LE6hpSH1mn78UKh-If/view?usp=sharing) to connect data with it. OR

    You can follow the steps outlined in the attached PDF to attach data from s3 connection.

    ### 4. Upload from Local

    Upload the files and name the dataset, provide a description and click "**Create Dataset**".

    <Frame>
      <img alt="Local upload interface" />
    </Frame>

    <Info>
      For more on how to create projects and new datasets check out the [Create A New Project Page](/getting-started/create-project).
    </Info>
  </Step>
</Steps>

## Managing Datasets

Datasets can be edited such that new files can be added, old ones deleted, or existing datasets from other projects can also be attached.

To manage or make changes to your dataset, through your dashboard, click on the settings options from the taskbar> Selecting Dataset option>Click on the view all dataset>Click on the 3 dots

<Frame>
  <img alt="Dataset management options" />
</Frame>

<Frame>
  <img alt="Dataset management interface" />
</Frame>

<Note>
  For further assistance contact **[support@tensormatics.com](mailto:support@tensormatics.com)**
</Note>


# Image Editing Icons Guide
Source: https://docs.labellerr.com/tutorials/image-editing-icons

Learn about the image editing tools available in Labellerr to enhance your annotation experience and improve labeling accuracy.

Labellerr provides additional tools to edit image samples for a better labelling experience.

<Frame>
  <img alt="Image editing toolbar" />
</Frame>

## Available Tools

### Pan Tool (Hand Icon)

**Pan Tool(Hand)** icon lets you move the Image after selecting it. This is useful when you want a certain edge of the image or in complex images where detailed annotating is required.

### Display Settings (Gear Icon)

**Display(Gear)** icon lets you change the brightness, contrast, hue, saturation and luminance. It is especially useful for details that are often missed in a very dark/bright picture or for the detection of an object that blends with the environment.

<Frame>
  <img alt="Display settings panel" />
</Frame>

### Configure Annotations (Stroke Icon)

**Configure Annotations(Increasing Stroke)** icon allows edge reduction or anchor radius editing in different type of annotations like bounding box/polygon/line/segmentation.

<Frame>
  <img alt="Annotation configuration" />
</Frame>

### Zoom Tool

**Zoom** icon as the name suggests lets you zoom in and zoom out. This can be useful when the image pixels are huge and specific pixels have to be highlighted with precision. It also serves as useful while using dot annotation in high pixel images.

<Frame>
  <img alt="Zoom controls" />
</Frame>

### Reset Tool

**Reset** icon allows you to rotate the image left or right or reset the file to its original position.

<Frame>
  <img alt="Reset and rotation controls" />
</Frame>

<Tip>
  These tools are designed to work together to give you maximum flexibility when annotating complex images or working with challenging lighting conditions.
</Tip>


# Importing Users from One Project to Another
Source: https://docs.labellerr.com/tutorials/importing-users

Learn how to import users from one project to another within the same workspace in Labellerr.

## Overview

This guide provides step-by-step instructions on how to import users from a selected project into the required project within the same workspace.

## Prerequisites

* You must have the necessary permissions to import users
* Ensure that both the source and target projects exist within the same workspace
* Check this to learn about [Workspace](/tutorials/workspace)

## Steps to Import Users

<Steps>
  <Step title="Navigate to the Settings section">
    1. Log in to your workspace
    2. Go to the Settings section from the main dashboard of the current project

    <Frame>
      <img alt="Navigate to Settings" />
    </Frame>
  </Step>

  <Step title="Access the Users option">
    1. Click on the **Users** option within the **Settings** section

    <Frame>
      <img alt="Access Users option" />
    </Frame>

    2. Locate and click on the **Import Users** button

    <Frame>
      <img alt="Import Users button" />
    </Frame>
  </Step>

  <Step title="Select the Source project">
    <Frame>
      <img alt="Select source project" />
    </Frame>

    1. A dialog box will open, prompting you to select the project from which you want to import users
    2. Choose the desired project from the drop-down list
    3. Once the project is selected, the **Import** button will be enabled
    4. Click on the **Import** button to finalize the import process
  </Step>

  <Step title="Verification">
    <Frame>
      <img alt="Verify imported users" />
    </Frame>

    1. Verify that all the users are successfully imported to the project
    2. All the imported users will be shown along with the current users list
  </Step>
</Steps>

## Additional Notes

<Info>
  * If a user already exists in the target project, they will not be duplicated
  * Users will retain their roles and permissions as assigned in the source project
</Info>

<Note>
  For further assistance, please contact [support@tensormatics.com](mailto:support@tensormatics.com).
</Note>


# Key Definitions of Data Annotation
Source: https://docs.labellerr.com/tutorials/key-definitions

Essential terms and definitions you'll encounter while using Labellerr for data annotation and machine learning projects.

<Note>
  Here are some of the key definitions a user would come across while using Labellerr.
</Note>

## Terminology Reference

| Key | Definition |
| - | - |
| **Annotation** | Annotation is the process of labeling or tagging data (such as text, images, videos, or audio) to provide meaningful information or context for machine learning models. This process helps models understand and learn patterns in the data for tasks like object detection, classification, transcription, or segmentation. |
| **Auto Label** | A tool that can be set up to call auto labeling predictions powered by A.I. |
| **Attributes** | The attributes of an object refer to additional properties or characteristics that provide more context or details about the object being labeled. |
| **Bounding Box** | A rectangular box drawn around an object to define its location and size. |
| **Bulk Assign** | Owners and Supereditors have the option of changing the status and reassigning samples to one of the annotators through manual selection. The assigned files would then be displayed for action to the particular user. |
| **Classification** | Classifications are structured questions used to capture specific details about an object, ensuring consistency in annotations. Examples include formats like radio buttons, dropdowns, input fields, and multi-select options. |
| **Data type** | The type of data to be selected for a project. For. E.g. Image, Video, Audio, Text. |
| **Dataset** | A collection of Data files that are added to Labellerr for annotation. A project may have multiple datasets. |
| **Data Sources** | The source from which data is uploaded. On Labellerr, data can be uploaded from Google Drive, Dropbox, Google Cloud Storage, Amazon S3, Microsoft Azure, and Local Drives/Storages. |
| **Data Curation** | Data curation is the practice of gathering and managing data to use for analytical purposes. |
| **Export** | The process of saving annotated files in formats like JSON, CSV, or PNG for use. |
| **File Type** | File types are the file format supported. For E.g Pictures (JPG/PNG), Video (MP4), text (.txt files), etc. |
| **Guidelines** | A set of instructions or parameters that can be added to each object, classification, or file to help annotators in labeling. Guidelines can be added while creating a dataset or by reviewers. |
| **Hotkeys** | Keyboard shortcuts that speed up annotation tasks. |
| **Interpolation** | Creating annotations for in-between frames in a video automatically. |
| **Masking** | Covering specific areas of an image for pixel-perfect segmentation. |
| **Metadata** | Additional information about files, such as timestamp or location. |
| **Object** | Objects refer to the specific entities or elements in an image, video, text, or other data types that need to be labeled or identified. |
| **Workspaces** | A workspace is a 'Centralized environment' enabling large organizations to manage and track multiple projects under the same domain. A single Organization might have a single subsidiary or teams where each team might own a separate workspace. |
| **Project** | Projects include multiple datasets, users, annotations, etc with a single datatype. For E.g A project named 'Buildings' with image files can have multiple datasets of Buildings all of the same 'Image' file type. |
| **Polygon** | A multi-sided shape used to annotate irregular objects more precisely. |
| **Polygon Line Width** | The thickness of the border around a polygon. |
| **Taxonomy** | Taxonomy is the system of organizing things into categories based on the shared characteristics. A template with a set of objects and classifications or filtration can be created and saved to be made available and applied to future projects. |
| **Status** | File status shows the progress of a file in the annotation process, such as unassigned, in progress, pending review, or completed. It helps track tasks and identify files needing attention or rework. |
| **Segmentation** | Dividing an image or object into parts, such as semantic or instance segmentation. |
| **User Roles** | Users can be assigned different roles which grant them access to a different interface and activities on Labellerr. A user can be an Annotator, Reviewer, Admin, Supervisor, etc. |

<Note>
  For further assistance contact **[support@tensormatics.com](mailto:support@tensormatics.com)**
</Note>


# Labellerr Shortcut Keys Guide
Source: https://docs.labellerr.com/tutorials/shortcut-keys

Master keyboard shortcuts to speed up your annotation workflow in Labellerr across different data types.

## Keyboard Shortcuts Reference

| Category | Action | Shortcut |
| - | - | - |
| **General** | Toggle shortcuts menu | `f1` |
| | Delete an active object | `del` or `backspace` |
| | Toggle annotation question | `1-9` |
| | Zoom in | `alt + i` |
| | Zoom out | `alt + k` |
| | Move image position | `ctrl + mouse left button` (hold & drag) |
| | Reset image position | `r` |
| | Copy selected bounding box | `ctrl + c` |
| | Paste selected bounding box | `ctrl + v` |
| | Undo action | `ctrl + z` |
| | Redo action | `ctrl + y` |
| **Annotations** | Deselect selected annotation | `ctrl + d` |
| | Toggle visibility of all annotations | `h` |
| | Edit attributes of selected annotation | `e` |
| | Toggle grouping mode | `ctrl + g` |
| | Create in-progress polygon anchors | `shift + mouse move` |
| | Complete in-progress polygon object | `n` |
| | Remove in-progress polygon object | `del` or `backspace` |
| | Remove in-progress polygon anchor | `mouse right click` |
| | Increase transparency of polygon annotations | `shift + t + +` |
| | Decrease transparency of polygon annotations | `shift + t + -` |
| **Audio** | Play/Pause | `space` |
| | Delete selected segment | `del` or `backspace` |
| | Deselect selected segment | `ctrl + d` |
| | Zoom in | `ctrl + +` |
| | Zoom out | `ctrl + -` |
| **Video** | Play/Pause | `space` |
| | Previous frame | `left arrow` |
| | Next frame | `right arrow` |
| | Skip to start frame | `ctrl + shift + left arrow` |
| | Skip to end frame | `ctrl + shift + right arrow` |
| | Interpolate all bounding boxes and dots | `shift + t` |

<Tip>
  Press `f1` at any time while annotating to see the shortcuts menu directly in the interface.
</Tip>


# User Permissions
Source: https://docs.labellerr.com/tutorials/user-permissions

Understand different user roles and permission levels in Labellerr workspaces, and what access each role provides.

Workspaces are **configured based on the level of access** granted, meaning that a user is only able to access the content based on their authorization level (which can be changed anytime). For eg., if User A is working as an annotator, then he has access to only annotation. Access to review or export is restricted.

Following is a list of roles that can be assigned to users across parallel workspaces.

<Frame>
  <img alt="User roles hierarchy" />
</Frame>

## Role-Based Access Levels

### Annotator

An Annotator level clearance would allow the user access to the following screen and its contents: **Label and Files**.

<Frame>
  <img alt="Annotator interface" />
</Frame>

### Reviewer

A Reviewer level clearance would allow the user access to the following screen and its contents: **Review and Files**

<Frame>
  <img alt="Reviewer interface" />
</Frame>

### Client Reviewer

A Client Reviewer level clearance would allow the user access to the following screen and its contents: **Client Review and Files and export**.

<Info>
  In case the Client Review and Review Process are disabled for a project and a user is assigned such a role, then a limited screen would appear with restricted access.
</Info>

### Supervisor

A Supervisor level clearance would allow the user access to the following screen and its contents: **Label, Review, Export and Settings**.

<Frame>
  <img alt="Supervisor interface" />
</Frame>

### Admin

An Admin level clearance would allow the user access to the following screen and its contents **Label, Review, Client Review, Files, Export and Settings** (and other workspaces if any)

<Frame>
  <img alt="Admin interface" />
</Frame>

### Super Admin (Owner)

A Super Admin (or Owner of the Project) level clearance would allow the user access to the following screen and its contents: **Label, Review, Client Review, Files, Activity, Export and Settings** (and other workspaces if any)

<Frame>
  <img alt="Super Admin interface" />
</Frame>

## Related Resources

For importing users from one project to another, please visit the [Import Users from a project](/tutorials/importing-users) tutorial.


# Workspace
Source: https://docs.labellerr.com/tutorials/workspace

Learn about workspaces in Labellerr - how they work, features they offer, and how to manage multiple workspaces effectively.

<Note>
  This guide would help the user grasp the concept of a workspace, how it works and what features does a workspace on Labellerr have to offer? Moreover, how to manage multiple workspaces?
</Note>

<Card title="Topics Covered" icon="briefcase">
  This guide covers workspace management in Labellerr:

  * **What Are Workspaces?** - Understanding the centralized environment concept
  * **Workspace Structure** - How workspaces organize projects and teams
  * **Access Control** - Role-based permissions and user management
  * **Switching Workspaces** - Managing multiple workspaces effectively
  * **User Permissions** - Clearance levels and authorization management
</Card>

A workspace is a 'Centralized environment' enabling large organizations to manage and track multiple projects under the same domain.

A single Organization might have a single subsidiary or teams where each team might own a separate workspace. Activities are isolated based on their respective projects. Multiple activities can be performed in a workspace at the same time. Access is restricted based on user authorization. Workspaces on Labellerr are analogous to those on platforms such as Slack.

## Key Features

| Feature | Description |
| - | - |
| **Role-based Access Control** | Workspaces are configurated based on the level of access granted, meaning that a user is only able to access the content based on their authorization level (which can be changed anytime). For eg., if User A is working as an annotator, then he has access to only annotation. Access to review or export is restricted. |
| **Flexible User Permissions** | Labellerr allows more flexibility by allowing each user to be assigned a different level of clearance in individual projects under the same domain. For e.g. user A can be a 'Super Admin' for project A and an 'Annotator' for project B. |
| **Real-time Updates** | Changes show in real-time that reflect on all the screens of each user working on that workspace. This also allows users from different time zones to work with ease and stay aligned with the team. |
| **Advanced Filtering & Tracking** | It is also easy to Sort files and Track user activity on Labellerr. Sorting can be done throughout Labellerr using filtration options and statistical tracking (which also works in real-time) is always on display on the Dashboard. |

## Switching Workspaces

The interactive UI of Labellerr is quick to grasp and easy to use. Workspaces can be accessed through the switch workspace screen on the top right corner of the dashboard.

<Warning>
  **Only Admins, Superadmins, and Clients owning multiple workspaces can switch workplaces.** Non-admins can only view files for annotation or review on the projects they have been assigned.
</Warning>

<Frame>
  <img alt="Workspace switcher interface" />
</Frame>

<Info>
  Any changes made to the level of clearance, files added, annotated, etc. are instantly visible on all screens in real-time.
</Info>

## Workspace Admins

<Frame>
  <img alt="Workspace admin interface" />
</Frame>

## Workspace Outlook based on Clearance Level

The number of features and actions is restricted based on the clearance level of the user.

<Info>
  Following is a list of roles that can be assigned to users across parallel workspaces.

  <Frame>
    <img alt="User roles hierarchy" />
  </Frame>
</Info>

<CardGroup>
  <Card title="Learn More" icon="question-circle">
    * For more on how to change user clearance levels, check out the [User Settings Guide](/features/user-settings)
    * To know more on what permissions or features each user authorization grants, visit the [User Permissions](/tutorials/user-permissions) page
  </Card>
</CardGroup>

<Note>
  For further assistance contact **[support@tensormatics.com](mailto:support@tensormatics.com)**
</Note>