🚀 VIVAA — Versatile Intelligent Visual Annotator & Data Augmentation Suite

The Ultimate Desktop Suite for High-Speed Computer Vision Dataset Preparation, Multi-Modal Labeling, Pose Estimation & Real-Time Data Augmentation.

---

💡 What is VIVAA?

VIVAA (Versatile Intelligent Visual Annotator) is an all-in-one, high-performance computer vision dataset engineering desktop suite built with PyQt5, OpenCV, Albumentations, and PyTorch.

Engineered for AI researchers, computer vision engineers, and dataset annotators, VIVAA eliminates fragmented tooling by combining 5 complete dataset workflows into a single, intuitive software package. Whether you are training YOLOv8, YOLO11, Detectron2, Mask R-CNN, or custom PyTorch Pose Models, VIVAA streamlines dataset creation from raw image ingest to fully formatted, augmented datasets.

[!TIP] Install in seconds via PyPI: pip install vivaa and launch instantly with vivaa from your terminal!

---

🔥 Key Innovations & Cool Features

VIVAA is packed with custom algorithms, real-time rendering features, and intelligent UI design tailored for hyper-efficient data annotation:

┌──────────────────────────────────────────────────────────────────────────────────┐
│                             VIVAA SMART ENGINE                                   │
├──────────────────────────┬───────────────────────────┬───────────────────────────┤
│ 🎨 Golden Ratio Color    │ 🎯 Cosmetic Scaling       │ 🦴 1-Click Pose Engine    │
│ Visually distinct QColors│ 2px crisp guides on 4K    │ Sequential auto-advancing │
│ via Golden Ratio HSV     │ monitors via setCosmetic  │ keypoint placement        │
├──────────────────────────┼───────────────────────────┼───────────────────────────┤
│ ✂️ Live Mask Opacity     │ 🧪 Dual-Canvas Preview    │ ⚡ QThread Batch Engine   │
│ 0-100% transparency with │ Real-time side-by-side    │ Multi-threaded batch data │
│ Freehand Lasso & Polygon │ augmentation studio       │ pipeline processor        │
└──────────────────────────┴───────────────────────────┴───────────────────────────┘

🎨 Golden Ratio Class Color Scheme

VIVAA dynamically generates visually distinct, high-contrast colors for every new class label using the Golden Ratio Conjugate: $$h = (\text{class_id} \times 0.618033988749895) \pmod{1.0}$$ All bounding boxes, instance polygons, and skeleton bones associated with a class retain identical, harmonious color hues throughout your session for total multi-class visual clarity.

🎯 Cosmetic Resolution-Invariant Vector Scaling

Standard graphics viewports shrink canvas lines when zooming out and make them unreadably thick when zooming in. VIVAA applies setCosmetic(True) on crosshairs, guidelines, bounding boxes, and skeleton links. Crosshair guidelines stay at an exact, crisp 2-pixel width regardless of zoom level or display resolution (HD, 2K, 4K).

🦴 Single Left-Click Sequential Skeleton Engine

Annotating pose keypoints is 10x faster: simply Left-Click on the image to place nodes. VIVAA automatically draws color-coded limb connections (cyan for left limbs, magenta for right limbs, yellow for torso) and advances to the next keypoint in sequence (Nose $\rightarrow$ Left Eye $\rightarrow$ Right Eye...). No awkward hotkeys or manual joint selection needed!

✂️ Multi-Vertex & Freehand Lasso Instance Masking

Switch seamlessly between Click-to-Place Polygons for geometric objects and Freehand Lasso (click & drag around object contours) for organic shapes. Drag vertex handles to refine control points, and adjust the Mask Opacity Slider (0% to 100%) in real time to inspect underlying image textures.

🧪 Real-Time Dual-Canvas Augmentation Studio

Stack 12+ image transformations (CLAHE, Blur, Gaussian Noise, Rotation, Flipping, Color Jitter, Crop/Pad) and preview original vs augmented images side-by-side in real time. Use the interactive RulerSlider with degree tick marks for precision rotation tweaks.

⚡ Multi-Threaded Batch Augmentation Processing

Process thousands of dataset images in seconds without freezing the UI. VIVAA uses a dedicated background QThread BatchWorker with live progress feedback, error tracking, and automatic file saving.

---

🔄 Complete VIVAA Workflow

VIVAA covers the entire end-to-end dataset pipeline, taking your project from raw unorganized images to production-ready trained models.

flowchart TD
    A[📁 Raw Image Collection] --> B[🚀 Launch VIVAA Suite]
    
    subgraph Selection [1. Workflow Selection]
        B --> C1[📦 Object Detection]
        B --> C2[✂️ Instance Segmentation]
        B --> C3[🦴 Keypoint Pose Estimation]
        B --> C4[🏷️ Image Classification]
        B --> C5[🎨 Data Augmentation]
    end
    
    subgraph Annotation [2. Interactive Annotation & Labeling]
        C1 --> D1[Draw Rect / Square / Circle / Polygon<br/>YOLO Normalized BBoxes]
        C2 --> D2[Polygon & Freehand Lasso Masks<br/>Live Opacity Control]
        C3 --> D3[1-Click Joint Placement<br/>COCO 17 / Hand 21 / Face 5 / Custom]
        C4 --> D4[Single & Multi-Label Tagging<br/>Auto-Completer & Undo Stack]
    end

    subgraph Processing [3. Synthetic Data Augmentation]
        D1 & D2 & D3 & D4 --> E[🎨 Data Augmentation Studio]
        E --> F[Dual-Canvas Real-Time Filter Preview<br/>12+ Stackable Transformations]
        F --> G[⚡ QThread Multi-Threaded Batch Engine]
    end

    subgraph Export [4. Production Dataset Export]
        G --> H1[YOLO txt / YOLOv8-Seg / YOLOv8-Pose]
        G --> H2[COCO JSON Format Masks & Keypoints]
        G --> H3[Structured Class Folders & CSV Metadata]
    end

    H1 & H2 & H3 --> I[🤖 Model Training: YOLOv8 / YOLO11 / PyTorch / Detectron2]

Step-by-Step Dataset Pipeline

1. Import Raw Data: Open any folder of images (.png, .jpg, .jpeg, .bmp, .tiff).
2. Select Task Module: Choose the required workflow from the interactive VIVAA launcher dashboard.
3. Annotate & Label: Use interactive vector tools, hotkeys, auto-completers, and pose templates.
4. Augment Dataset: Open the Data Augmentation Studio, build a custom filter stack, preview results side-by-side, and run background batch generation.
5. Export & Train: Export directly into standard YOLO or COCO directory structures for immediate model training.

---

📊 VIVAA Feature Matrix

Feature / Capability	📦 Object Detection	✂️ Instance Segmentation	🦴 Keypoint Detection	🏷️ Image Classification	🎨 Data Augmentation
Primary Output	YOLO .txt BBoxes	YOLO Seg .txt & COCO JSON	YOLOv8-Pose .txt & COCO JSON	Subfolders / Metadata CSV	Augmented Image Dataset
Drawing Geometries	Rect, Square, Circle, Poly	Multi-Vertex Poly & Lasso	Joint Nodes & Skeleton Links	N/A	Dual Viewport Canvas
Interactive Handles	Corner Resize & Drag	Vertex Edit / Add / Remove	Drag Keypoints & Visibility	Auto-Suggest Dropdown	Precision RulerSlider
Color System	Golden Ratio HSV	Golden Ratio HSV + Opacity	Color-Coded Limb Segments	Visual Tag Badges	Real-Time RGB / HSV
Target AI Models	YOLOv5 - YOLO11, R-CNN	YOLOv8-Seg, Mask R-CNN	YOLOv8-Pose, PyTorch Pose	ResNet, EfficientNet, ViT	All CV Models

---

⚡ Installation & Quickstart

Option 1: Install via PyPI (Recommended)

pip install vivaa

Option 2: Clone & Install from Source

git clone https://github.com/your_github_username/VIVA.git
cd VIVA
pip install -r requirements.txt

---

🚀 Launching VIVAA

You can start VIVAA directly from your command line or terminal:

# 1. Direct CLI Command (after pip install)
vivaa

# 2. Python Module Execution
python -m vivaa

# 3. Script Execution from Source
python vivaa/main.py

---

💻 Python API Integration

Integrate VIVAA windows and annotation tools directly into your custom Python applications or PyQt5 interfaces:

import sys
from PyQt5.QtWidgets import QApplication
from vivaa import (
    MainWindow, 
    AnnotationTool, 
    InstanceSegmentationTool, 
    KeypointDetectionTool, 
    ClassificationTool, 
    DataAugmentationTool
)

# Launch the unified VIVAA Main Dashboard
app = QApplication(sys.argv)
window = MainWindow()
window.showMaximized()
sys.exit(app.exec_())

---

🔍 Module Deep-Dive

📦 1. Bounding Box Object Detection (object_detection.py)

Designed for training object detectors such as YOLOv5, YOLOv8, YOLO11, and Faster R-CNN.

• Versatile Vector Tools: Draw standard Rectangles, Constrained Squares, Circles, or Free Polygons.
• Class Reflector & Auto-Limit: Live sidebar listing all annotations with 1-click focus and box-count limits (e.g., 0/100).
• Crosshair Guidelines: High-precision cursor guides with cosmetic resolution scaling.
• Export Format: Standard YOLO normalized format (class_id xc yc w h).

✂️ 2. Pixel-Accurate Instance Segmentation (instance_segmentation.py)

Engineered for fine-grained polygon mask annotation.

• Polygon & Freehand Lasso Modes: Left-click perimeter points or drag freehand to trace complex contours.
• Vertex Control Point Editing: Click & drag vertex nodes to tweak mask boundaries; insert or remove points seamlessly.
• Live Mask Opacity Slider: Adjust fill transparency from 0% (invisible guide) to 100% (solid mask fill).
• Export Formats: YOLOv8 Segmentation (.txt) and COCO Polygon Mask JSON (.json).

🦴 3. Keypoint Detection & Pose Estimation (keypoint_detection.py)

Tailored for human pose, hand landmark, and facial keypoint tracking.

• Pre-Configured Skeleton Templates:
  • 🧍 COCO 17-Keypoints: Full-body pose (Nose, Eyes, Ears, Shoulders, Elbows, Wrists, Hips, Knees, Ankles).
  • 🖐️ Hand 21-Keypoints: Wrist + 4 joint nodes per finger (Thumb, Index, Middle, Ring, Pinky).
  • 👤 Face 5-Keypoints: Eyes, Nose, and Mouth corners.
  • ⚙️ Custom Free Keypoints: Build custom skeleton structures on the fly.
• Visibility Flags: Supports standard COCO joint visibility flags:
  • v=2: Labeled & Visible (Solid Keypoint Node)
  • v=1: Labeled & Occluded (Hollow / Dim Node)
  • v=0: Absent / Unlabeled
• Export Formats: YOLOv8-Pose (.txt) and COCO Keypoints JSON (.json).

🏷️ 4. Multi-Label Image Classification (image_classification.py)

Fast, keyboard-driven image cataloging and multi-tag assignment.

• Single & Multi-Label Modes: Instant radio button toggling for single class assignment or multi-tagging.
• Smart QCompleter Search: Instant auto-suggestions based on existing dataset categories as you type.
• Undo Stack (Ctrl+Z): Revert mislabeled items instantly.
• Dataset Organization: Automatically copy/move files into structured class folders or generate CSV metadata.

🎨 5. Real-Time Data Augmentation Studio (data_augmentation.py)

Interactive image enhancement and synthetic dataset expansion.

• 12+ Stackable Filters: CLAHE, Gaussian Blur, Brightness/Contrast, Sharpen, Gaussian Noise, Color Jitter, Rotation, Horizontal/Vertical Flip, Scale, Crop/Pad.
• Dual-Canvas Synchronous Preview: Interactive side-by-side original and augmented viewports.
• Custom RulerSlider: Angle rotation slider with degree markings (-360° to +360°) and center alignment guides.
• QThread Background Processor: Batch process entire dataset directories asynchronously with progress bars.

---

⌨️ Annotator Keyboard Shortcuts

Accelerate your annotation workflow with built-in hotkeys:

Shortcut Key	Action	Supported Modules
D or Right Arrow	Next Image & Auto-Save Annotations	All Modules
A or Left Arrow	Previous Image	All Modules
Delete or Backspace	Delete Selected Bounding Box / Keypoint / Polygon	Detection, Seg & Keypoint
Ctrl + Z	Undo Last Action / Label Assignment	Classification & Detection
Ctrl + Scroll Wheel	Zoom Canvas In / Out	Detection, Seg & Keypoint
Middle Click + Drag	Pan / Move Viewport Canvas	Detection, Seg & Keypoint
Left Click	Place Keypoint / Polygon Vertex	Keypoint & Instance Seg
Double Click	Complete Polygon Loop & Render Mask Fill	Instance Segmentation

---

📦 Supported Export Formats & Framework Compatibility

VIVAA exports directly into industry-standard CV dataset schemas:

Format Name	Output File Type	Target AI Framework / Model
YOLO Object Detection	.txt (class_id xc yc w h)	YOLOv5, YOLOv7, YOLOv8, YOLOv9, YOLO11
YOLO Segmentation	.txt (class_id x1 y1 x2 y2 ...)	YOLOv8-Seg, YOLO11-Seg, Ultralytics
YOLOv8-Pose	.txt (class_id xc yc w h px1 py1 v1 ...)	YOLOv8-Pose, YOLO11-Pose
COCO Keypoints & Masks	.json (Full COCO Schema)	Detectron2, MMClassification, PyTorch
Class Directory Structure	Image Subfolders (/cat, /dog)	torchvision ImageFolder, Keras
CSV Metadata	.csv (filename, label1, label2)	Pandas, Custom Deep Learning Pipelines

---

🧰 Technology Stack & System Requirements

  ┌─────────────────────────────────────────────────────────────┐
  │                      TECH STACK ENGINE                      │
  ├───────────────────┬──────────────────┬──────────────────────┤
  │ Python 3.8+       │ PyQt5 GUI        │ OpenCV & Albumentations
  │ Core Language     │ Desktop Windowing│ CV Processing & Augs │
  └───────────────────┴──────────────────┴──────────────────────┘

Layer	Component	Version Requirement	Purpose
Language	Python	>= 3.8	Core execution environment
GUI Framework	PyQt5	>= 5.15.11	Graphics viewports, widgets, and theme engine
Computer Vision	OpenCV	>= 4.11.0	Matrix transformations, contours, and color spaces
Augmentation	Albumentations	>= 2.0.6	High-performance pipeline image transformations
Math & Data	NumPy & Pandas	>= 1.26.4	Vectorized coordinate calculations & CSV I/O
Deep Learning	PyTorch & Torchvision	>= 2.7.0	Tensor processing & dataset model integrations

---

📄 License & Attribution

VIVAA is open-source software released under the MIT License.

• Author: Vishnu Vardhan Reddy Biyyapu
• Contact & Support: vardhan101101@gmail.com
• PyPI Package: https://pypi.org/project/vivaa/
• GitHub Repository: https://github.com/your_github_username/VIVA

---

Developed with ❤️ for the Global Computer Vision & Artificial Intelligence Community.
Star ⭐ this repository on GitHub if VIVAA accelerated your dataset workflow!