Metadata-Version: 2.4
Name: vivaa
Version: 1.0.5
Summary: VIVA: Versatile Intelligent Visual Annotation and Data Augmentation Tool
Home-page: https://github.com/your_github_username/VIVA
Author: Vishnu Vardhan Reddy Biyyapu
Author-email: Vishnu Vardhan Reddy Biyyapu <vardhan101101@gmail.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt5>=5.15.11
Requires-Dist: numpy>=1.26.4
Requires-Dist: opencv-python>=4.11.0.86
Requires-Dist: Pillow>=11.1.0
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: matplotlib>=3.10.1
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🚀 VIVAA — Versatile Intelligent Visual Annotator & Data Augmentation Suite

<p align="center">
  <img src="https://img.shields.io/badge/VIVAA-v1.0.5-8A2BE2?style=for-the-badge&logo=python&logoColor=white" alt="VIVAA Version" />
  <img src="https://img.shields.io/badge/PyPI-vivaa-blue?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI Package" />
  <img src="https://img.shields.io/badge/Python-3.8%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python Version" />
  <img src="https://img.shields.io/badge/GUI-PyQt5-41CD52?style=for-the-badge&logo=qt&logoColor=white" alt="PyQt5 GUI" />
  <img src="https://img.shields.io/badge/Computer_Vision-OpenCV%20%7C%20PyTorch-FF6F00?style=for-the-badge&logo=opencv&logoColor=white" alt="OpenCV & PyTorch" />
  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="MIT License" />
</p>

<p align="center">
  <b>The Ultimate Desktop Suite for High-Speed Computer Vision Dataset Preparation, Multi-Modal Labeling, Pose Estimation & Real-Time Data Augmentation.</b>
</p>

---

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

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

```bash
pip install vivaa
```

### Option 2: Clone & Install from Source

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

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

```python
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](LICENSE)**.

* **Author**: Vishnu Vardhan Reddy Biyyapu
* **Contact & Support**: [vardhan101101@gmail.com](mailto:vardhan101101@gmail.com)
* **PyPI Package**: [https://pypi.org/project/vivaa/](https://pypi.org/project/vivaa/)
* **GitHub Repository**: [https://github.com/your_github_username/VIVA](https://github.com/your_github_username/VIVA)

---

<p align="center">
  <b>Developed with ❤️ for the Global Computer Vision & Artificial Intelligence Community.</b><br/>
  <i>Star ⭐ this repository on GitHub if VIVAA accelerated your dataset workflow!</i>
</p>
