Metadata-Version: 2.4
Name: PrepImage
Version: 1.0.0
Summary: PrepImage — A Unified Framework for Computer Vision Dataset Preparation
Author: Harsh Sachan, ICAR-Indian Agricultural Statistics Research Institute (IASRI), New Delhi, Shalini Kumari, ICAR-Indian Agricultural Statistics Research Institute (IASRI), New Delhi, Md Ashraful Haque, ICAR-Indian Agricultural Statistics Research Institute (IASRI), New Delhi, Sudeep Marwaha, ICAR-Central Institute of Agricultural Engineering (CIAE), Bhopal, Chandan Kumar Deb, ICAR-Indian Agricultural Statistics Research Institute (IASRI), New Delhi
License: MIT
Project-URL: Repository, https://github.com/harsh-iasri/PrepImage
Keywords: image,dataset,preprocessing,annotation,augmentation,gui,pyside6,qt
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: X11 Applications :: Qt
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.6
Requires-Dist: Pillow>=10.0
Requires-Dist: ImageHash>=4.3
Requires-Dist: numpy>=1.24
Dynamic: license-file

<p align="center">
  <img src="src/prepimage/screens/images/preimage.png" alt="PrepImage logo" width="180"/>
</p>

<h1 align="center">PrepImage</h1>

<p align="center">
  <b>A Unified Framework for Computer Vision Dataset Preparation</b><br/>
  Deduplicate, clean, crop, resize, annotate, and augment image datasets — all in one desktop app.
</p>

<p align="center">
  <a href="https://pypi.org/project/prepimage/"><img src="https://img.shields.io/pypi/v/prepimage.svg?color=blue" alt="PyPI version"></a>
  <a href="https://pypi.org/project/prepimage/"><img src="https://img.shields.io/pypi/pyversions/prepimage.svg" alt="Python versions"></a>
  <a href="https://github.com/harsh-iasri/PrepImage/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://github.com/harsh-iasri/PrepImage"><img src="https://img.shields.io/badge/GitHub-repo-181717?logo=github" alt="GitHub repo"></a>
  <a href="https://pypi.org/project/prepimage/"><img src="https://img.shields.io/badge/pip%20install-prepimage-blue?logo=python&logoColor=white" alt="pip install prepimage"></a>
</p>

---

Preparing an image dataset for a computer vision or AI project usually means
stitching together a pile of one-off scripts — one for finding duplicates,
another for resizing, another still for labeling and augmenting. **PrepImage**
replaces all of that with a single, modern PySide6 (Qt) desktop application:
open a folder of raw images, and clean, standardize, label, and expand it
into a training-ready dataset without leaving the app.

<p align="center">
  <img src="src/prepimage/screens/images/Front_Page.png" alt="PrepImage home screen" width="850"/>
</p>

## Table of Contents

- [Why PrepImage](#why-prepimage)
- [Modules](#modules)
  - [1. Duplicate, Blur & Noise Detection](#1-duplicate-blur--noise-detection)
  - [2. Image Preprocessing](#2-image-preprocessing-crop--resize--rename)
  - [3. Image Annotation](#3-image-annotation)
  - [4. Image Augmentation](#4-image-augmentation)
- [Installation](#installation)
- [Usage](#usage)
- [Requirements](#requirements)
- [Project Layout](#project-layout)
- [License](#license)
- [Contributors](#contributors)

## Why PrepImage

- **One app, four workflows** — deduplication, preprocessing, annotation, and
  augmentation share one consistent, modern dark-themed interface instead of
  four different scripts and conventions.
- **Built for real datasets** — background worker threads keep the UI
  responsive on folders with thousands of images; every long-running step
  shows live progress.
- **Training-format aware** — exports YOLO `.txt`, Pascal VOC `.xml`, and
  COCO-style `.json` annotations, and augments images *with* their labels so
  bounding boxes and polygons stay correct after a flip, rotation, or crop.
- **Nothing leaves your machine** — PrepImage is a local desktop tool; your
  images and labels never get uploaded anywhere.

## Modules

### 1. Duplicate, Blur & Noise Detection

<p align="center">
  <img src="src/prepimage/screens/images/Duplicate_page.png" alt="Duplicate, Blur & Noise Detection screen" width="850"/>
</p>

Scans a folder of images and flags three kinds of problems that quietly hurt
model training if they slip into a dataset:

- **Duplicate & near-duplicate images** — found via perceptual
  average-hashing (`imagehash`), then grouped so you can keep one
  representative from each group instead of every copy.
- **Blurry images** — detected via a Laplacian-variance sharpness score.
- **Noisy images** — detected via a median-filter residual noise estimate.

Enable any combination of the three **Detection Options** and run one scan;
each category gets its own results tab with its own thumbnail grid. From
there you can **Forward Unique → Preprocess** (send the clean set straight
into the next module), **Download Unique Images**, or **Download
Duplicates** for manual review.

**Directories**

| Field | Purpose |
|---|---|
| **Input Directory** | The folder of images to scan. Required. |
| *(no separate output field)* | Results stay in memory until you explicitly export them — each export action (Forward, Download Unique, Download Duplicates) prompts for its own destination folder when clicked. |

### 2. Image Preprocessing (Crop / Resize / Rename)

<p align="center">
  <img src="src/prepimage/screens/images/Preprocess_page.png" alt="Preprocessing screen" width="850"/>
</p>

Batch-normalizes a folder of images into a consistent size and naming
scheme — the shape most training pipelines expect:

- Crops every image to a square, trimming evenly from the longer side
  (never stretching or distorting the image).
- Resizes the square result to a fixed target size in pixels.
- Renames output files sequentially with a custom prefix.
- Zoomable thumbnail gallery to review and select which images to process
  before running.

**Directories**

| Field | Purpose |
|---|---|
| **Input Directory** | Folder of source images to process. Required. |
| **Output Directory** | Folder where cropped/resized/renamed images are written. Required. |

### 3. Image Annotation

<p align="center">
  <img src="src/prepimage/screens/images/annotation_page.png" alt="Image Annotation screen" width="850"/>
</p>

A full labeling workspace for building object detection and segmentation
datasets:

- **Bounding boxes** for object detection and **polygons** for pixel-level
  segmentation, with an optional rasterized mask PNG export.
- Per-image class labels, editable at any time (a "⋮" menu on every class
  and every annotation row covers editing, recoloring, renaming, changing
  class, and deleting).
- Undo/redo — whole-shape while browsing, per-vertex while a polygon is
  still being drawn.
- Export to **YOLO `.txt`**, **Pascal VOC `.xml`**, and/or **COCO-style
  `.json`** — pick any combination — with class names round-tripped through
  a per-folder `classes.txt` so relabeling later doesn't lose your class
  names.
- Zoom/pan canvas, keyboard shortcuts, and an in-app shortcuts reference.

**Directories**

| Field | Purpose |
|---|---|
| **Input Image Folder** | Folder of images to annotate. Required. |
| **Custom Save Directory** | Where annotation files (and masks, if enabled) are saved. Optional — defaults to the input image folder if left blank. |

### 4. Image Augmentation

<p align="center">
  <img src="src/prepimage/screens/images/Augmentation_page.png" alt="Data Augmentation screen" width="850"/>
</p>

Expands a dataset by generating pixel-level and geometric variations of
each image, in two modes:

- **Image Augmentation** — augments a folder of images with no annotations
  to carry along.
- **Annotated Image Augmentation** — augments images *and* their existing
  YOLO `.txt` annotations together. Pixel/non-geometric augmentations
  (brightness, contrast, sharpen, Gaussian blur, saturation, Gaussian
  noise, grayscale) leave box coordinates untouched; geometric ones
  (horizontal/vertical flip, 90°/180°/270° rotation) transform the
  coordinates to match, so every saved label still lines up with its image.

**Target Images** controls how many augmented images to generate in total;
**Max Aug / Img** caps how many augmented variants can come from any single
source image. Augmented files follow the naming convention
`originalname_SHORTCODE1_SHORTCODE2_0001.ext`, so it's obvious at a glance
which combination of augmentations produced a given output.

**Directories**

| Field | Purpose |
|---|---|
| **Input Image Folder** | Folder of source images (in Annotated mode, this folder should also contain the matching `.txt` label for each image). Required. |
| **Output Image Folder** | Folder where augmented images (and, in Annotated mode, their updated `.txt` labels) are written. Required. |

## Installation

### From PyPI

```bash
pip install prepimage
```

### From source (editable / dev mode)

```bash
git clone https://github.com/harsh-iasri/PrepImage.git
cd prepimage/prepimage_pkg
pip install -e .
```

## Usage

```bash
prepimage
```

or, without installing the console script:

```bash
python -m prepimage
```

## Requirements

- Python >= 3.9
- [PySide6](https://pypi.org/project/PySide6/) — Qt GUI framework
- [Pillow](https://pypi.org/project/Pillow/) — image I/O and processing
- [ImageHash](https://pypi.org/project/ImageHash/) — perceptual hashing for duplicate detection
- [NumPy](https://pypi.org/project/numpy/) — array operations for preprocessing, blur/noise detection, and augmentation

All of the above are installed automatically as dependencies.

## Project Layout

```
prepimage_pkg/
├── pyproject.toml
├── README.md
├── LICENSE
└── src/
    └── prepimage/
        ├── __init__.py
        ├── __main__.py            # entry point (`prepimage` / `python -m prepimage`)
        ├── app.py                 # QMainWindow + navigation (QStackedWidget)
        ├── theme.py               # colors, fonts, global stylesheet
        ├── widgets.py             # ToolCard (painted card, hover zoom)
        ├── assets.py              # shared logo loading helper
        ├── duplicates.py          # duplicate/blur/noise detection core logic
        ├── preprocess.py          # crop/resize/rename core logic
        ├── augment.py             # augmentation engine + box/polygon transforms
        └── screens/
            ├── __init__.py
            ├── home.py             # landing page (hero + 4 tool cards + About dialog)
            ├── duplicates.py       # Duplicate, Blur & Noise Detection screen
            ├── preprocess.py       # Preprocessing screen
            ├── annotate.py         # Image Annotation screen (boxes + polygons)
            ├── augment.py          # Image Augmentation screen
            ├── working.py          # shared "under construction" placeholder
            └── images/             # screenshots + logo bundled with the package
```

## License

Released under the [MIT License](LICENSE).

## Contributors

| Name | Affiliation |
|---|---|
| Harsh Sachan | ICAR-Indian Agricultural Statistics Research Institute (IASRI), New Delhi |
| Shalini Kumari | ICAR-Indian Agricultural Statistics Research Institute (IASRI), New Delhi |
| Md Ashraful Haque | ICAR-Indian Agricultural Statistics Research Institute (IASRI), New Delhi |
| Sudeep Marwaha | ICAR-Central Institute of Agricultural Engineering (CIAE), Bhopal |
| Chandan Kumar Deb | ICAR-Indian Agricultural Statistics Research Institute (IASRI), New Delhi |

Contributions are welcome — feel free to open an issue or pull request on
[GitHub](https://github.com/harsh-iasri/PrepImage).
