Image Processing Toolkit (OpenCV & NumPy)

A lightweight, modular, and high-performance command-line image processing toolkit built from scratch using OpenCV and NumPy. Designed for quick image manipulations, computer vision prototyping, and educational purposes.

Table of Contents

• Problem Statement
• Features
• Architecture Diagram
• Dataset
• Installation
• Usage
• Results
• Demo
• Future Improvements
• License

Problem Statement

Image processing tasks often require heavy frameworks or complex pipelines just to perform basic operations like filtering, thresholding, or color manipulation. Developers and students frequently need a lightweight, dependency-minimal, and highly readable tool to quickly manipulate image matrices without the overhead of deep learning libraries. This toolkit solves that by providing an Object-Oriented, chainable interface for standard computer vision tasks.

Features

• Modular OOP Design: Stateful ImageToolkit class allows chaining operations seamlessly.
• OpenCV Integration: Leverages industry-standard algorithms for Edge Detection, Blurring, and Color Space conversions.
• NumPy Matrix Math: Direct pixel manipulation for lightning-fast Brightness adjustment, Inversion, and Thresholding.
• Non-Destructive Editing: Built-in reset() function to instantly revert to the original loaded image.
• Interactive CLI: User-friendly Command Line Interface for real-time interaction without writing boilerplate code.

Architecture Diagram

graph TD
    A[User / CLI Interface] -->|Inputs Commands| B(ImageToolkit Class)
    B -->|Holds State| C[(Current Image Matrix)]

    B --> D{Operation Type?}

    D -->|Algorithmic Vision| E[OpenCV Core]
    D -->|Direct Pixel Math| F[NumPy Arrays]

    E -->|Returns| C
    F -->|Returns| C

    C -->|Display/Save| G[Output Image / Window]

    style B fill:#2d3436,stroke:#00cec9,stroke-width:2px,color:#fff
    style C fill:#0984e3,stroke:#74b9ff,stroke-width:2px,color:#fff

Loading

Installation

This project uses uv, an extremely fast Python package installer and resolver, to manage the environment.

Prerequisites

• Python 3.8 or higher
• uv installed on your system

Setup Steps

1. Install uv if you do not have it already:

   # macOS / Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows (PowerShell)
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the repository and navigate into it:

   git clone https://github.com/SultanAhmmed/image-processing-toolkit.git
   cd image-processing-toolkit

3. Initialize the project and add dependencies using uv:

   uv init
   uv add opencv-python numpy

Usage

Running via CLI

Run the toolkit using uv run to automatically use the project's virtual environment:

uv run python main.py

Follow the interactive menu:

==============================
   IMAGE PROCESSING TOOLKIT
==============================
1. Load Image
2. Show Current Image
3. Convert to Grayscale
...
Enter your choice (0-10):

Programmatic Usage

You can also import the toolkit into your own Python scripts:

from toolkit import ImageToolkit

tk = ImageToolkit()
tk.load_image("sample.jpg")

tk.to_grayscale()
tk.apply_blur(kernel_size=7)
tk.adjust_brightness(factor=1.2)

tk.save_image("output.jpg")

Results

The toolkit processes images in real-time. Below is a comparison of operations applied to a sample image:

Original Image	Grayscale + Edge Detection	NumPy Thresholding

Demo

Watch the toolkit in action! The GIF below demonstrates loading an image, applying a Gaussian blur, detecting edges, and resetting to the original.

Future Improvements

• GUI implementation with CustomTkinter or PyQt6.
• Batch processing for entire directories of images.
• HSV color masking for object extraction.
• Histogram equalization for contrast enhancement.
• Web API wrapper with FastAPI.

License

This project is licensed under the GNU General Public License v3.0 or later.

---

Made with Python, OpenCV, and NumPy