Metadata-Version: 2.4
Name: image-enhancer-ai-upload
Version: 1.0.1
Summary: AI-powered image enhancement and document correction toolkit
Author: Image Enhancer AI Team
License: MIT License
        
        Copyright (c) 2026 Image Enhancer AI Team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Keywords: image-processing,image-enhancement,computer-vision,opencv,document-processing,image-quality,rotation-correction,blur-detection,noise-removal
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0,>=1.24
Requires-Dist: opencv-python<5.0,>=4.8
Requires-Dist: tensorflow<2.20,>=2.15
Dynamic: license-file

# 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.

```text
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

```bash
pip install image-enhancer-ai
```

### Install from Source

Clone or download the project.

Create a virtual environment:

```bash
python -m venv .venv
```

Activate it on Windows:

```bash
.venv\Scripts\activate
```

Upgrade pip:

```bash
python -m pip install --upgrade pip
```

Install the project:

```bash
pip install .
```

---

## Install from Wheel

Build the package:

```bash
python -m pip install build
python -m build
```

This creates distribution files inside:

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

Install the wheel:

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

---

# Basic Usage

```python
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:

```python
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

```python
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:

```text
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:

```python
{
    "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:

```bash
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:

```text
image_enhancer/models/rotation_model.h5
```

Class mapping:

```text
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.
