tadqeeq 1.4.0

An interactive PyQt5 image annotation tool for segmentation masks and bounding boxes.

Tadqeeq – Image Annotator Tool

An interactive image annotation tool built with PyQt5, designed for efficient labeling of segmentation masks and bounding boxes.

Developed by Mohamed Behery @ RTR Software Development - An "Orbits" Subsidiary 📅 April 30, 2025 🪪 Licensed under the MIT License

---

🚀 Features

• ✅ Minimalist Interactive Design
• 🖌️ Scroll through label classes / Adjust pen size with the mouse wheel
• 🎨 Supports segmentation masks (.png) and bounding boxes (.txt)
• 🧠 Dynamic label color generation (HSV-based)
• 💬 Floating labels showing hovered and selected classes
• 💾 Auto-save and manual save (Ctrl+S)
• 🧽 Flood-fill segmentation with a postprocessing stage of binary hole filling
• 🚫 Middle-click erase mode and double-click to clear all

---

📦 Installation

Option 1: Install via pip

pip install tadqeeq

Option 2: Run from source

git clone https://github.com/orbits-it/tadqeeq.git
cd tadqeeq
pip install -r requirements.txt

---

🛠️ Usage

Import in your code:

from tadqeeq import ImageAnnotator

Run demo from command line (if installed via pip):

tadqeeq [--autosave|--use_bounding_boxes]* <images_directory_path> <annotations_directory_path>

Note: If the annotations file is PNG one, the tool uses segmentation masks with class-labeled pixels on a white background.
If it's a .txt file, it uses YOLO-style bounding boxes formatted as:

label_index x_offset y_offset width height

---

🧭 Controls

Action	Mouse/Key
Draw / Fill segment	Left-click / double-click
Erase (one object)	Right-click + Left-click
Toggle erase mode	Right-click
Clear all	Double right-click
Scroll through labels / Adjust pen size	Mouse wheel
Save annotations	Ctrl+S
Show label on hover	Hover cursor
Navigate through images (CLI only)	A / D

---

📁 Project Structure

root/
├── tadqeeq/
|   ├── __init__.py         # Entry point for importing
|   ├── widgets.py          # Contains ImageAnnotator class
|   ├── utils.py            # Helper methods (flood fill, bounding box logic)
|   ├── implementations.py  # Contains an example integration of ImageAnnotator class
|   ├── cli.py              # Entry point for full solution
├── README.md
├── LICENSE
├── setup.py
├── pyproject.toml
└── requirements.txt

---

🧑‍💻 Contributing

Repository

Pull requests are welcome!
If you add features (e.g. COCO export, brush tools, batch processing), please document them in the README.

---

📄 License

This project is licensed under the MIT License.
See LICENSE for the full license text.

---

💡 Acknowledgements

🎉 Built for computer vision practitioners needing fast, mouse-based labeling with clean overlays and autosave logic.

🌟 Special thanks to PyQt5 for providing the powerful and flexible GUI toolkit that made the development of this interactive image annotator possible.

---

🔗 Related Resources

• PyQt5 Docs
• NumPy
• scikit-image
• SciPy