nedo-vision-annotator 1.0.0

Nedo Vision Annotator Service for Automated Image Annotation

Nedo Vision Annotator Service

Overview

Python service that automatically annotates dataset images using AI models. Listens to RabbitMQ for image processing tasks, runs inference using YOLO/RF-DETR models with GPU acceleration, and sends annotations back to the manager via gRPC.

Features

• Automated Annotation: Process images from RabbitMQ queue automatically
• Multi-Model Support: YOLO and RF-DETR detection models
• GPU Acceleration: Automatic CUDA detection for faster inference
• Batch Processing: Efficient batch annotation submission
• Local Storage: SQLite-based annotation queue before sending
• Authentication: Token-based authentication with manager
• Configuration Management: Persistent configuration storage
• Status Reporting: Real-time status updates to manager

Architecture

Core Components

1. Configuration Management (config/ConfigurationManager.py)

   • SQLite-based key-value storage
   • Stores: server_host, server_port, token, annotator_id
   • Convenience methods for common config keys

2. Database Management (database/)

   • SQLAlchemy-based architecture with entity-repository pattern
   • Local annotation storage with pending queue
   • Entities: DatasetAnnotation
   • Repositories: DatasetAnnotationRepository
   • Session management with connection pooling

3. AI Models (models/AIModel.py)

   • AI model entity representation
   • Support for YOLO and RF-DETR models
   • Class management for object detection
   • Version tracking for model updates

4. Detection (detection/)

   • BaseDetector: Abstract base class for all detectors
   • YOLODetector: Ultralytics YOLO detection with GPU support
   • RFDETRDetector: RF-DETR detection with GPU support
   • Standardized output: [{"label": str, "confidence": float, "bbox": [x1, y1, x2, y2]}]
   • Normalized bounding boxes (0-1 range)

5. Core Logic (core/)

   • DatasetManager: Dataset synchronization and management
   • ModelLoader: AI model loading, caching, and version control

6. Background Tasks (tasks/)

   • AnnotationProcessor: Image download and detection processing
   • AnnotationSender: Batch annotation submission to manager
   • MessageHandler: RabbitMQ message routing and validation
   • StatusReporter: Periodic status updates

7. Services (services/)

   • GrpcClientBase: Base gRPC client with authentication
   • AnnotatorGrpcClient: Manager communication for datasets, images, and annotations
   • RabbitMQConsumer: Message queue consumer with reconnection logic

Main Service (annotator_service.py)

• Entry point for the annotator service
• Manages service lifecycle (initialization, start, stop)
• Signal handling for graceful shutdown
• Configuration initialization and validation
• Coordinates all background tasks

CLI (cli.py)

Command-line interface with the following arguments:

• --token (required): Authentication token for the annotator
• --server-host: Manager server host (default: be.vision.sindika.co.id)
• --server-port: gRPC port (default: 50051)
• --storage-path: Data storage path (default: data)
• --batch-size: Annotations per batch (default: 50)
• --send-interval: Send interval in seconds (default: 60)

Installation

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Usage

# Run annotator service
nedo-vision-annotator --token YOUR_TOKEN --server-host localhost

# Or with Python module
python -m nedo_vision_annotator.cli --token YOUR_TOKEN

# With custom settings
nedo-vision-annotator \
  --token YOUR_TOKEN \
  --server-host localhost \
  --server-port 50051 \
  --batch-size 100 \
  --send-interval 30

Dependencies

• gRPC: Communication with manager (grpcio, grpcio-tools, protobuf)
• RabbitMQ: Message queue (pika)
• AI/ML: Model inference (torch, torchvision, ultralytics, rfdetr<=1.2.0, opencv-python, numpy)
• Database: Local storage (sqlalchemy)
• System: Resource monitoring (psutil)

gRPC Services

AnnotatorService

The annotator uses the following gRPC methods:

• GetConnectionInfo: Fetch RabbitMQ connection details and annotator ID
• GetDatasetList: Get assigned datasets with AI model information
• GetAIModelList: List AI models assigned to annotator's datasets
• DownloadAIModel: Stream download AI model files
• GetImage: Download image file from storage
• SendAnnotations: Submit batch of annotations to manager
• UpdateStatus: Report annotator status (connected/disconnected)

Data Flow

1. Initialization

   • Connect to manager via gRPC using authentication token
   • Fetch annotator ID and RabbitMQ connection information
   • Retrieve assigned datasets with AI model configurations
   • Download and load required AI models

2. Processing Loop

   • Listen to dedicated RabbitMQ queue for annotation requests
   • Receive message with dataset item ID and image path
   • Download image from storage via gRPC
   • Run inference using assigned AI model
   • Store annotations locally with normalized bounding boxes (0-1 range)
   • Batch annotations for efficient submission

3. Annotation Submission

   • Collect pending annotations up to batch size
   • Group annotations by dataset item
   • Send batch to manager via gRPC
   • Delete local annotations after successful submission
   • Retry on failure with exponential backoff

4. Model Management

   • Load AI models on demand when processing starts
   • Cache loaded models in memory for reuse
   • Monitor model versions and re-download on updates
   • Support for YOLO and RF-DETR model types

5. Status Reporting

   • Periodic status updates (connected/disconnected)
   • System metrics: CPU usage, temperature, RAM usage, latency
   • Automatic reconnection handling on network issues

Configuration

The annotator stores configuration in SQLite database at {storage_path}/config/config.db:

• server_host: Manager server hostname
• server_port: Manager gRPC port
• token: Authentication token
• annotator_id: Unique annotator identifier (fetched from manager)

Logging

Logs are written to stdout with the following format:

YYYY-MM-DD HH:MM:SS [LEVEL] Message

Log levels:

• ERROR: Critical errors and failures
• WARNING: Non-critical issues
• INFO: Important events and status changes
• DEBUG: Detailed debugging information (disabled by default)

Error Handling

• Authentication Failures: Automatic shutdown on invalid token
• Network Issues: Automatic reconnection with exponential backoff
• Model Loading Errors: Logged and skipped, service continues
• RabbitMQ Disconnection: Automatic reconnection attempts
• gRPC Errors: Retry logic with timeout handling

Performance

• GPU Acceleration: Automatic CUDA detection and usage
• Batch Processing: Configurable batch size for efficient submission
• Connection Pooling: Database connection pool for concurrent operations
• Model Caching: In-memory model cache to avoid reloading
• Async Operations: Background threads for non-blocking tasks