Metadata-Version: 2.4
Name: vivaa
Version: 1.0.4
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

# 🚀 VIVA: Versatile Intelligent Visual Annotation Tool ⚙️

<p align="center">
  <img src="https://img.shields.io/badge/🚀%20Boost%20Your-Speed%20of%20Annotation-brightgreen?style=for-the-badge" />
  <img src="https://img.shields.io/badge/🧠%20Focus%20On-Accuracy%2C%20Not%20Repetition-blue?style=for-the-badge" />
  <img src="https://img.shields.io/badge/💾%20Perfect%20For-Custom%20Dataset%20Creation-orange?style=for-the-badge" />
</p>

---



## 🧠 Overview

**VIVA** is a modern, **smart visual annotation tool** built with **PyQt5**, designed to streamline dataset preparation for computer vision tasks such as **object detection** and **image classification**.

Whether annotating a **custom dataset** or working with a **well-organized dataset**, **VIVA** significantly reduces annotation time for users through its:

- ⚡ **Intuitive Interface** — Simple, clean, and user-friendly design  
- 🧠 **Smart Automation Techniques** — Efficient features that simplify repetitive tasks  
- 🧩 **Optimized Workflow Design** — Smooth navigation and quick annotation management  

✨ These capabilities allow annotators to focus more on **accuracy** and less on **manual repetitive work**, making **VIVA** a powerful tool for **AI developers**, **researchers**, and **dataset creators**.

---

## 🌟 Key Features

- 🪶 User-friendly **PyQt5 GUI**  
- 🎯 Object detection and image classification annotation modules  
- ⌨️ Efficient keyboard shortcuts and Smart Options for fast labeling  
- 🔍 Zoom, pan, and interactive label visualization  
- 🧾 YOLO-compatible output formats  
- 🧩 Integrated Data Augmentation Studio
- 🧬 Advanced Data Augmentation Module
- 🔄 Pipeline-Based Augmentation Workflow
- 👀 Real-Time Augmentation Preview
- ⚡ Batch Augmentation Processing
- 🎲 Smart Cycle Augmentation Mode
- 🚀 Modular design for future expansion (segmentation, keypoint detection)  

---

## 🧰 Object Detection Annotation

VIVA’s **Object Detection Module** is packed with innovative features:  

- 🎯 **Bounding Box Limits:** Set a maximum number of boxes per image; auto-switch to the next image when the limit is reached  
- 🧠 **Smart Undo:** Press `A` to navigate to the previous image and delete the last bounding box drawn  
- 🔺 **Flexible Shapes:** Draw rectangles, squares, circles, or polygons  
- ⌨️ **Keyboard Shortcuts:**  
  - `Del` → Remove boxes  
  - `A` → Smart Previous image with Delete Function  
  - `D` → Next image  
  - `Enter` → Save  
  - 🖱️ One-click mode for drawing boxes  
- 🪟 **Interactive GUI:** Zoom, pan, color-coded boxes, and label reflector for multi-class clarity  
- 📂 **File Navigation:** Browse images with progress tracking (e.g., “3/10”)  
- ⚠️ **Error Handling:** Clear `QMessageBox` alerts ensure smooth operation  

💡 These features make **VIVA uniquely efficient**, saving annotation time compared to other tools.

---

## 🖼️ Image Classification Annotation

VIVA’s **Image Classification Module** streamlines labeling with:  

- 🔘 **Single & Multi-Label Modes:** Toggle between single-label and multi-label modes via radio buttons  
- 💡 **Auto-Suggestion for Labels:** Completer suggests previously used labels while typing  
- 🪄 **Default Label Application:** Apply a default label to images using the `Space` key; single-mode overwrites existing labels with confirmation  
- ⌨️ **Time-Saving Shortcuts:**  
  - `D` → Next image  
  - `A` → Previous image (clears labels for quick corrections)  
  - `Del` → Remove selected/all labels  
- 📁 **Efficient File Management:** Copies images to label-specific directories with progress tracking  
- 🔍 **Interactive GUI:** Zoom in/out, reset zoom, and pan with clean layout  
- 🪞 **Label Reflector:** Displays current labels with visual feedback  
- ⚠️ **Robust Error Handling:** User-friendly alerts for missing directories or invalid images  

⚡ These features minimize repetitive tasks, making annotation faster and more intuitive than competing tools.

---
## 🧬 Data Augmentation Studio (New in VIVA 1.0.2)

VIVA now includes a powerful **Data Augmentation Studio** designed to help AI developers create diverse and robust datasets directly from the GUI.

The augmentation workflow follows a **pipeline-based approach**, allowing users to stack multiple transformations, preview results instantly, and apply them to entire datasets.

---

### 🚀 Core Features

* 👀 Real-time side-by-side preview (Original vs Augmented)
* 🧩 Pipeline-based augmentation workflow
* ⚡ Batch augmentation for entire datasets
* 🎲 Smart Cycle Augmentation Mode
* 📁 Separate output directory management
* 🖱️ Interactive GUI controls with sliders
* ⌨️ Keyboard navigation between images (`A/D` or Arrow Keys)

---

### 📐 Geometric Transformations

VIVA supports the following geometric augmentations:

* 🔄 Rotation (-360° to +360°)
* ↔️ Translation (X/Y offsets)
* 🔍 Scaling
* 📏 Resizing
* ✂️ Center Cropping
* 🔀 Horizontal Flip
* 🔁 Vertical Flip
* 📐 Shearing

These operations can be combined into custom augmentation pipelines.

---

### 🎨 Color & Lighting Augmentations

Improve dataset robustness against lighting variations:

* ☀️ Brightness Adjustment
* 🌗 Contrast Adjustment
* 🌈 Saturation Control
* 🎭 Hue Shifting
* ⚡ Gamma Correction
* 💡 Exposure Adjustment
* 🧠 CLAHE (Contrast Limited Adaptive Histogram Equalization)

---

### 🌫 Blur & Noise Augmentations

Simulate real-world image imperfections:

* 🌫 Gaussian Blur
* 🧹 Median Blur
* 🚗 Motion Blur
* 🎲 Gaussian Noise
* ⚪ Salt & Pepper Noise
* 📦 JPEG Compression Artifacts

---

### 🧩 Pipeline Builder

Create complex augmentation workflows by stacking operations:

1. Select an augmentation
2. Adjust parameters
3. Click **Preview**
4. Click **Set** to add it to the pipeline
5. Repeat to build multi-step transformations

Pipeline operations can be removed individually using the built-in context menu.

---

### ⚡ Batch Augmentation

Apply the entire augmentation pipeline to all images inside a folder.

Features:

* Background processing
* Progress tracking
* Automatic saving to output directory
* Responsive UI during execution

---

### 🎲 Smart Cycle Augmentation Mode

Smart Cycle Mode automatically cycles augmentation parameters across images to generate highly diverse datasets.

Examples:

* Rotation: `0, 15, 30, -15`
* Brightness: `0, 20, 40, -20`
* Contrast: `0, 15, -15`
* Saturation: `0, 25, -25`
* Hue: `0, 30, -30`

This feature helps generate multiple dataset variations with minimal manual effort.

---

### 📂 Output Management

Augmented images are automatically saved to a user-selected output folder.

Generated files are named using:

```text
image_aug.jpg
image_cycle.jpg
```

making it easy to distinguish standard batch outputs from Smart Cycle outputs.

---

### 🎯 Why Use It?

The Data Augmentation Studio helps:

* Improve model generalization
* Increase dataset diversity
* Simulate real-world conditions
* Reduce overfitting
* Accelerate dataset preparation workflows

making VIVA a complete toolkit for both dataset annotation and dataset enhancement.

## 💻 Tech Stack

- 🐍 **Python** – Core logic and processing  
- 🖥️ **PyQt5** – GUI interface  
- 🎯 **YOLO Integration** – Optimized for object detection datasets  
- 🧩 **Modular Design** – Scalable for future modules like augmentation or segmentation  

---

## 🖼 Background Image Attribution

🖌️ The background image used in VIVA:

- **Title:** *"4K Marvel and DC Vector Art"*  
- **Author / Source:** Wallpapers.com  
- **URL:** [https://wallpapers.com/wallpapers/4k-marvel-and-dc-vector-art-pmkg7yqt3zz8bmcc.html](https://wallpapers.com/wallpapers/4k-marvel-and-dc-vector-art-pmkg7yqt3zz8bmcc.html)  
- **License:** Free, Attribution required  
- **Modifications:** Color filters applied for VIVA’s UI  

✅ This attribution satisfies the license requirement and ensures legal usage.

---

## 🔮 Future Works

🚧 The following modules are planned for future development:

- 🧬 **Data Augmentation Studio** ✅ – Implemented in VIVA 1.0.3
- 🎨 **Instance Segmentation & Key Point Detection Tools** – For detailed labeling in complex vision tasks  
- 👨‍💻 All future updates will be developed solely by the project author  

---

## 🪪 License

This project is licensed under the MIT License
. © 2025 Vishnu Vardhan Reddy Biyyapu

---

## 📦 Installation

Follow these steps to install and run **VIVA**:



### 1. Install Python

Make sure you have **Python 3.8 or higher** installed:

```bash
python --version
```
---
## 2. Create a Virtual Environment (Recommended)

It’s recommended to use a virtual environment to avoid conflicts with other Python packages:

```bash
python -m venv viva_env
```

Activate the environment:

- Windows:
```bash
viva_env\Scripts\activate
```
- Linux / macOS:
```bash
source viva_env/bin/activate
```
---
## 3. Install Required Packages

- Before running VIVA, install all required packages listed in requirements.txt:
```bash
pip install -r requirements.txt
```

This ensures all Python dependencies needed for VIVA are installed correctly.
⚠️ Note: Installing from PyPI (pip install viva) will also install these dependencies automatically.
---
## 4. Install and Run VIVA

After dependencies are installed:

From terminal/command prompt:
```bash
vivaa
```

From Python script:
```bash
from vivaa.main import main
main()
```
---
## 🛠 Workflow & Help Section

After successfully installing and running **VIVA** (`viva` command), you can access the **Help Section** directly from the application to learn about its workflow, shortcuts, and smart options designed for faster annotation.

### How to Access Help:

1. Launch VIVA using the terminal or command prompt:

```bash
vivaa
```
2. In the main VIVA window, hover your mouse over the title bar “VIVA □ ▭ ○”.
3. Click on the title — this will open the Help Section.

--

## 🎥 Demo Video

See **VIVA in action**! Watch a short demo showing the object detection and image classification modules, shortcuts, and smart options in real-time.

🔗 [Watch the demo of Object Detection Annotation Tool on LinkedIn](https://www.linkedin.com/feed/update/urn:li:activity:7354882949181292544/)

🔗 [Watch the demo of Image Classification Tool on LinkedIn](https://www.linkedin.com/feed/update/urn:li:activity:7357883048501108736/)
> Note: The video showcases VIVA’s workflow, time-saving features, and user-friendly interface for dataset annotation.
