Image Processing Toolkit 🖼️📦

A modular, production-ready Python package and Command-Line Interface (CLI) for digital image processing, structural similarity computation, color histogram analysis, and visual transformations. Built on top of scikit-image, Pillow, NumPy, and matplotlib.

---

📌 Overview

Image Processing Toolkit addresses the need for a simple, extensible, and clean interface to common computer vision and image manipulation tasks. It simplifies operations like computing structural similarity indexes (SSIM), color histogram matching, dimensional scaling, rotation, blurring, and contrast adjustment without requiring users to write verbose boilerplate code.

It provides both a Python API for seamless integration into larger data science/CV workflows and a CLI Interface for rapid terminal-based file transformations.

---

✨ Key Features

• Structural Similarity Analysis (SSIM): Compute exact similarity scores between images and generate normalized spatial difference maps.
• Histogram Matching & Plotting: Align visual styles across images and visualize RGB/Grayscale channel distributions.
• Image Transformations: High-quality anti-aliased resizing, angle rotation, grayscale conversion, Gaussian blur filtering, and brightness/contrast adjustments.
• Command-Line Interface (CLI): Direct terminal commands to process images without writing Python scripts.
• Type-Checked I/O Engine: Safe file loading and saving via Pillow integration with automatic directory creation and range normalization.
• Comprehensive Test Suite: Automated unit and integration testing via pytest.

---

🛠️ Tech Stack

• Language: Python 3.8+
• Core Processing Engine: scikit-image, NumPy
• I/O & Image Format Engine: Pillow (PIL)
• Visualization: matplotlib
• CLI & Packaging: argparse, setuptools
• Testing: pytest

---

🚀 Getting Started

Prerequisites

Ensure you have Python 3.8 or higher installed on your system.

Installation

Option 1: Install via Pip

pip install image-processing

Option 2: Install from Source (Editable Mode)

git clone https://github.com/Fesisp/image-processing-toolkit.git
cd image-processing-toolkit
pip install -e .

---

💡 Usage

1. Python API

import image_processing as ip

# Load images safely
img1 = ip.read_image("path/to/image1.png")
img2 = ip.read_image("path/to/image2.png")

# Structural Similarity (SSIM) & Difference Map
score, diff_map = ip.find_difference(img1, img2)
print(f"Similarity Score: {score:.4f}")

# Image Transformations
gray_img = ip.convert_to_grayscale(img1)
blurred_img = ip.apply_gaussian_blur(img1, sigma=1.5)
rotated_img = ip.rotate_image(img1, angle=45)
adjusted_img = ip.adjust_brightness_contrast(img1, alpha=1.2, beta=0.1)

# Plotting & Visualization
ip.plot_result(img1, img2, diff_map, titles=["Original A", "Original B", "Difference"])
ip.plot_histogram(img1)

# Export output image
ip.save_image(adjusted_img, "output/enhanced.png")

2. Command Line Interface (CLI)

The package installs the image-processing binary executable directly into your PATH:

# Calculate difference map and SSIM score between two images
image-processing diff image1.png image2.png -o output/diff_map.png

# Convert an image to grayscale
image-processing grayscale input.png -o output/gray.png

# Apply Gaussian blur (custom sigma)
image-processing blur input.png --sigma 2.5 -o output/blurred.png

# Resize image by proportion scale (e.g. 0.5 = 50%)
image-processing resize input.png 0.5 -o output/resized.png

# Rotate image by angle in degrees
image-processing rotate input.png 90 -o output/rotated.png

---

🧪 Testing

Run the automated test suite with pytest:

python -m pytest

---

👤 Author

Felipe da Silva Spinola

• GitHub: @Fesisp

---

📄 License

Distributed under the MIT License. See LICENSE for details.