vivaa 1.0.2
VIVA: Versatile Intelligent Visual Annotation Tool
License: MIT
Requires Python: >=3.8

# 🚀 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  
- 🧩 Modular design for future expansion (augmentation, segmentation)  

---

## 🧰 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.

---

## 💻 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 Tool** – To enhance datasets with transformations and increase model robustness  
- 🎨 **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.