Image Enhancer AI

An AI-assisted image enhancement and document correction toolkit built with Python, OpenCV, and TensorFlow.

Image Enhancer AI automatically analyzes an input image, detects its characteristics, and applies appropriate enhancement operations through dedicated photo and document processing pipelines.

---

Features

General Image Enhancement

• Image type detection
• Blur detection
• Blur correction and sharpening
• Noise detection
• Noise removal
• Brightness analysis
• Brightness correction
• Contrast analysis
• Contrast enhancement
• CLAHE enhancement
• Image quality evaluation

Rotation Correction

• CNN-based major rotation detection
• Supports 0°, 90°, 180°, and 270°
• Confidence-based rotation correction
• Safety threshold to prevent unsafe automatic corrections

Document Processing

• Document image detection
• Perspective detection
• Perspective correction
• Major document rotation analysis
• Table detection
• Table angle detection
• Minor table rotation correction
• Document enhancement
• Final document quality evaluation

---

Architecture

The package uses an automatic processing engine.

Input Image
     |
     v
Image Type Detection
     |
     +--------------------+
     |                    |
     v                    v
Photo Pipeline       Document Pipeline
     |                    |
     v                    v
Rotation              Perspective
Blur                  Rotation
Noise                 Table Analysis
Brightness            Noise
Contrast              Blur
CLAHE                 Brightness
Quality               Contrast
                      Enhancement
                           |
                           v
                    Quality Evaluation

---

Installation

Install from PyPI

pip install image-enhancer-ai

Install from Source

Clone or download the project.

Create a virtual environment:

python -m venv .venv

Activate it on Windows:

.venv\Scripts\activate

Upgrade pip:

python -m pip install --upgrade pip

Install the project:

pip install .

---

Install from Wheel

Build the package:

python -m pip install build
python -m build

This creates distribution files inside:

dist/
├── image_enhancer_ai-1.0.1-py3-none-any.whl
└── image_enhancer_ai-1.0.1.tar.gz

Install the wheel:

pip install dist/image_enhancer_ai-1.0.0-py3-none-any.whl

---

Basic Usage

from image_enhancer import ImageEnhancer

enhancer = ImageEnhancer()

image, report = enhancer.process(
    "input.jpg"
)

enhancer.save(
    image,
    "output.jpg"
)

for line in report:
    print(line)

---

Access Detailed Metadata

For applications that require detailed processing information:

from image_enhancer import ImageEnhancer

enhancer = ImageEnhancer()

result = enhancer.process_result(
    "input.jpg"
)

print("Quality:", result.metadata["quality_score"])

print("Grade:", result.metadata["quality_grade"])

print("Blur:", result.metadata["blur_detected"])

print("Noise:", result.metadata["noise_level"])

print(
    "Rotation:",
    result.metadata["major_rotation_angle"]
)

enhancer.save(
    result.image,
    "output.jpg"
)

---

Complete Example

from image_enhancer import ImageEnhancer

enhancer = ImageEnhancer()

result = enhancer.process_result(
    "photo.jpg"
)

print("Processing completed")

for line in result.report:
    print(line)

enhancer.save(
    result.image,
    "enhanced_photo.jpg"
)

---

Processing Result

The detailed API returns an EnhancementResult object containing:

• image
• report
• metadata

Image

The final enhanced image as a NumPy array.

Report

A list of human-readable processing results.

Example:

Detected Image Type : document
Detection Confidence : 66.7%
Perspective Correction : Not Required
Major Rotation : 180
Major Rotation Confidence : 0.311
Major Rotation Correction : Skipped
Noise Level : Medium
Blur Correction : Not Required
Final Quality Score : 85.24
Final Quality Grade : Good
Document Enhancement : Completed

Metadata

Machine-readable processing information.

Example:

{
    "image_type_confidence": 0.667,
    "perspective_confidence": 0.0,
    "perspective_corrected": False,
    "major_rotation_angle": 180,
    "major_rotation_confidence": 0.311,
    "major_rotation_corrected": False,
    "noise_level": "Medium",
    "blur_detected": False,
    "blur_score": 699.44,
    "quality_score": 85.24,
    "quality_grade": "Good"
}

---

Rotation Safety

Major rotation correction is confidence-based.

The CNN predicts one of the following orientations:

• 0°
• 90°
• 180°
• 270°

A correction is applied only when the model confidence reaches the configured safety threshold.

If the confidence is below the threshold, the original orientation is preserved.

This prevents uncertain CNN predictions from automatically rotating an image incorrectly.

---

Testing

The project contains tests for:

• Blur detection and correction
• Noise detection and correction
• Brightness analysis
• Quality evaluation
• Perspective detection
• Perspective correction
• Table detection
• Table rotation
• CNN rotation model mapping
• CNN rotation prediction
• Document pipeline
• Photo pipeline
• Full enhancement engine
• Public API

Run the tests individually:

python tests/test_blur.py
python tests/test_noise.py
python tests/test_brightness.py
python tests/test_quality.py
python tests/test_perspective_detector.py
python tests/test_perspective.py
python tests/test_table.py
python tests/test_table_rotation_step.py
python tests/test_table_correction.py
python tests/test_cnn_mapping.py
python tests/test_cnn_prediction.py
python tests/test_document_pipeline.py
python tests/test_photo_pipeline.py
python tests/test_engine.py
python tests/test_public_api.py

---

Model Files

The CNN rotation model is packaged with the library.

Model file:

image_enhancer/models/rotation_model.h5

Class mapping:

image_enhancer/models/class_mapping.json

These files are included when building the Python package distribution.

---

Supported Python Versions

The package targets:

• Python 3.10
• Python 3.11
• Python 3.12

---

Dependencies

Main dependencies include:

• NumPy
• OpenCV
• TensorFlow

---

Project Status

Version: 1.0.0

The core image enhancement system has been implemented and tested, including:

• Photo processing pipeline
• Document processing pipeline
• Image type detection
• Blur correction
• Noise correction
• Brightness and contrast processing
• Perspective correction
• Table rotation correction
• CNN-based major rotation detection
• Image quality evaluation
• Enhancement engine
• Public Python API

---

License

This project is licensed under the MIT License.