A lightweight image processing toolkit built from scratch using NumPy, implementing classical image processing algorithms without relying on high-level computer vision libraries such as OpenCV for the core operations.
The primary goal of this project is to understand how image processing algorithms work internally by implementing them manually using NumPy.
- Load images
- Save images
- Display images
- Image information
- Horizontal Flip
- Vertical Flip
- Rotate 90°
- Rotate 180°
- Rotate 270°
- Crop
- Nearest Neighbor Resize
- Grayscale Conversion
- Negative Image
- Brightness Adjustment
- Contrast Adjustment
- Gamma Correction
- Mean Blur
- Gaussian Blur
- Sharpen
- Laplacian Edge Detection
- Emboss
numpy-image-processing-toolkit/
│
├── demo.py
├── requirements.txt
├── README.md
│
├── images/
│ ├── input/
│ │ └── sample.png
│ │
│ └── output/
│ ├── transformations/
│ ├── filters/
│ └── convolution/
│
└── toolkit/
├── __init__.py
├── io.py
├── transform.py
├── filters.py
├── convolution.py
└── utils.py
Instead of calling existing image processing functions from libraries like OpenCV, every algorithm in this project is implemented manually using NumPy.
The project follows a modular design:
- io.py → Image loading, saving, displaying and information
- transform.py → Geometric image transformations
- filters.py → Pixel-wise image operations
- convolution.py → Convolution-based filters and reusable convolution engine
- utils.py → Helper utilities
A reusable apply_kernel() function powers all convolution-based filters, minimizing duplicate code while keeping the implementation easy to understand.
- Python 3.10+
- NumPy
- Pillow
- Matplotlib
Clone the repository:
git clone https://github.com/<your-username>/numpy-image-processing-toolkit.git
cd numpy-image-processing-toolkitInstall the required dependencies:
pip install -r requirements.txtPlace an image inside:
images/input/
Run the demo script:
python demo.pyAll processed images will automatically be generated inside:
images/output/
organized into:
output/
├── transformations/
├── filters/
└── convolution/
from toolkit.io import load_image, save_image
from toolkit.filters import grayscale
from toolkit.convolution import gaussian_blur
# Load image
image = load_image("images/input/sample.png")
# Apply filters
gray = grayscale(image)
blur = gaussian_blur(image)
# Save outputs
save_image(gray, "gray.png")
save_image(blur, "blur.png")| Function | Description |
|---|---|
load_image() |
Load an image into a NumPy array |
save_image() |
Save a NumPy array as an image |
show_image() |
Display an image |
image_info() |
Display image metadata |
| Function | Description |
|---|---|
flip_horizontal() |
Flip image horizontally |
flip_vertical() |
Flip image vertically |
rotate_90() |
Rotate image by 90° |
rotate_180() |
Rotate image by 180° |
rotate_270() |
Rotate image by 270° |
crop() |
Crop a region of the image |
resize_nearest() |
Resize image using nearest-neighbor interpolation |
| Function | Description |
|---|---|
grayscale() |
Convert RGB image to grayscale |
negative() |
Generate image negative |
brightness() |
Increase or decrease brightness |
contrast() |
Adjust image contrast |
gamma_correction() |
Apply gamma correction |
| Function | Description |
|---|---|
mean_blur() |
Apply 3×3 mean filter |
gaussian_blur() |
Apply 3×3 Gaussian blur |
sharpen() |
Sharpen the image |
edge_detection() |
Detect edges using Laplacian kernel |
emboss() |
Produce an embossed effect |
The following images were generated using the implemented algorithms.
Original Image
| Original | Horizontal Flip | Vertical Flip |
|---|---|---|
|
 |
 |
| Rotate 90° | Rotate 180° | Rotate 270° |
|---|---|---|
 |
 |
 |
| Crop | Resize |
|---|---|
 |
 |
| Grayscale | Negative |
|---|---|
 |
 |
| Brightness +50 | Brightness -50 |
|---|---|
 |
 |
| Contrast | Gamma (0.5) | Gamma (2.0) |
|---|---|---|
 |
 |
 |
| Mean Blur | Gaussian Blur |
|---|---|
 |
 |
| Sharpen | Edge Detection | Emboss |
|---|---|---|
 |
 |
 |
This project focuses on implementing image processing algorithms manually using NumPy.
- NumPy array manipulation
- Nested-loop pixel processing
- RGB channel operations
- Convolution using custom kernels
- Nearest-neighbor interpolation
- Gamma transformation
- Contrast stretching
- Pixel clipping and normalization
The convolution filters are implemented using a reusable apply_kernel() function.
Implemented kernels include:
- Mean Filter
- Gaussian Filter
- Sharpen Filter
- Laplacian Edge Detection
- Emboss Filter
This design eliminates duplicate code while keeping each filter implementation concise and easy to understand.
The current implementation prioritizes algorithmic understanding over optimization.
Most operations are implemented using explicit pixel-wise iteration to demonstrate how image processing algorithms work internally.
Future versions may introduce vectorized NumPy implementations to significantly improve performance while preserving the same functionality.
The following features are planned for future releases:
- Vectorized NumPy implementation for improved performance
- Support for custom kernel sizes (5×5, 7×7, ...)
- Median Blur
- Bilateral Filter
- Sobel Edge Detection
- Prewitt Edge Detection
- Histogram Equalization
- Binary and Adaptive Thresholding
- Morphological Operations (Erosion & Dilation)
- Command Line Interface (CLI)
- Comprehensive unit tests
- API documentation
Most image processing libraries provide highly optimized implementations, making it easy to use image processing algorithms without understanding how they work.
This project takes the opposite approach.
Every algorithm is implemented manually using NumPy to understand the mathematics and logic behind image processing techniques such as geometric transformations, pixel-wise operations, and convolution.
The objective is educational rather than performance-oriented.
Contributions, bug reports, feature requests, and suggestions are welcome.
If you would like to contribute:
- Fork the repository.
- Create a new branch.
- Make your changes.
- Commit your work.
- Open a Pull Request.
This project is licensed under the MIT License.
See the LICENSE file for more information.
Priyam
AI Student | Python Developer | NumPy & Computer Vision Enthusiast
GitHub: https://github.com/Priyam792
LinkedIn: www.linkedin.com/in/priyam-saini-0548bb24a
This project was developed as part of my journey to understand image processing from first principles by implementing classical algorithms using only NumPy.
Special thanks to the open-source Python ecosystem for providing the tools that make learning and experimentation possible.
⭐ If you found this project useful, consider giving it a star!