Skip to main content

​
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.

Workflow Efficiency

Reduce annotation time by up to 70% through pre-loaded label imports

File Size Limit

Support for annotation files up to 25 MB

Format Support

Industry-standard COCO JSON format compatibility

​
Critical Requirements

File Name Matching is MandatoryFor 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:
// 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.

​
Implementation

The SDK provides a unified method with optional async behavior:
  • Synchronous (Default)
  • Asynchronous
Recommended for: Batch processing scripts and sequential workflows where blocking behavior is acceptable
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)}")
Execution Behavior: This method blocks execution until processing completes. Processing duration varies based on file size and annotation count.

​
Method Comparison

Use the _async parameter to control execution behavior:

Synchronous (_async=False)

Use Cases:
  • Batch processing scripts
  • Sequential workflow automation
  • Single-threaded operations
Characteristics:
  • Simplified implementation
  • Direct result return
  • Blocking execution model
  • Default behavior

Asynchronous (_async=True)

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

​
Processing Workflow

Both implementation methods follow an identical server-side processing pipeline:
1

File Upload

Annotation JSON file is transmitted to Labellerr infrastructure
2

Format Validation

File structure and format are validated against COCO specification and project schema
3

File Name Resolution

Image file names referenced in annotations are matched against project assets
4

Annotation Application

Validated annotations are applied to matched images within the project
5

Status Return

Processing status and metadata are returned to the client application
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.

​
Common Use Cases

Model Prediction Integration

Import machine learning model predictions as pre-annotations for human validation and correction workflows

Platform Migration

Transfer annotations from external annotation platforms to Labellerr infrastructure

Project Replication

Reuse annotations from completed projects as foundation for similar initiatives

Automated Pipeline Integration

Upload annotations generated by automated systems or custom scripts for review workflows

​
Troubleshooting Guide

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

​
Response Schema

Successful upload operations return a structured response: 
{
  "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
    }
  }
}
Status Values:
  • completed - Annotations successfully applied to project
  • processing - Upload in progress (asynchronous method)
  • failed - Processing encountered errors (review error details)

​
Best Practices

Pre-Upload Validation

  • Validate JSON format locally before upload
  • Test with small sample datasets initially
  • Verify file name matching requirements

Asynchronous for Scale

  • Files exceeding 5 MB
  • Datasets with over 1000 annotations
  • Production application integrations

Activity Monitoring

  • Track activity IDs for audit trails
  • Review metadata for processing insights
  • Monitor unmatched file counts

Batch Processing Strategy

  • Partition large datasets into batches
  • Implement parallel processing where applicable
  • Design robust error handling mechanisms

Project Creation

Create and configure projects programmatically via SDK

Export Annotations

Export annotated datasets in multiple formats

SDK Getting Started

Complete SDK initialization and configuration guide
For technical support, contact [email protected]