Metadata-Version: 2.4
Name: image-quality-analysis
Version: 0.1.0
Summary: A Python package for analyzing image quality.
Author-email: Ateeq Azam <mr.ateeqazam@gmail.com>
License: CC BY-ND
Project-URL: Homepage, https://github.com/semwaqas/image-quality-score
Project-URL: Repository, https://github.com/semwaqas/image-quality-score
Keywords: image processing,image quality,computer vision
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: scikit-learn
Dynamic: license-file

# Image Quality Checker

This package provides a comprehensive image quality assessment tool that analyzes various aspects of an image to generate a final quality score.  It leverages OpenCV, NumPy, SciPy, and scikit-learn for image processing and analysis.

## Features

*   **Blur Detection:** Calculates Laplacian variance to estimate image blurriness.  Adapts the blur threshold based on whether the image contains a face (portrait mode).
*   **Resolution Analysis:** Determines the image resolution (height * width).
*   **Brightness and Contrast:** Measures the mean (brightness) and standard deviation (contrast) of the grayscale image.
*   **Motion Blur Estimation:** Analyzes the frequency domain using the Discrete Fourier Transform (DFT) to estimate motion blur.
*   **Edge Density:**  Calculates the density of edges in the image using the Canny edge detector.
*   **Color Standard Deviation:**  Evaluates the standard deviation of color channels in the HSV color space.
*   **Entropy:** Computes the entropy of the grayscale image histogram, providing a measure of image complexity.
*   **Dominant Color Check:**  Uses K-means clustering to determine if a single color dominates the image (more than 93% of pixels).  This helps identify images that are mostly uniform (and likely uninformative).
*   **Foreground Cropping:** Attempts to crop the image to the main foreground object, improving analysis accuracy by focusing on the relevant region.
*   **Small Image Bypass:**  Images smaller than 3KB are automatically passed (considered "good enough" for quality since processing such small images is often unnecessary/unreliable).
*   **Weighted Final Score:** Combines all individual metrics into a single, weighted quality score, normalized to a range between 0 and 1.  Higher scores indicate better quality.
*   **Error Handling:** Includes a `try-except` block to gracefully handle potential errors during image processing.
*   **Face detection:** Uses Haar cascades to identify the faces in the image.


## Detailed Blur Analysis

*   **Blur Detection:** Utilize the Laplacian variance method. Higher variance indicates sharper regions.

*   **Blur Ratio:** Calculate the percentage of blurry blocks relative to the total blocks in the image.

*   **Blur Classification:** Use thresholds on the blur ratio and connected component analysis for "Portrait-like" classification.

*   **Blur Map:** Generate a grayscale image where blurry regions are white and sharp regions are black.

*   **Overall Blur Assessment:** Determine if the image is blurry overall based on the blur ratio.

## Installation

```bash
pip install image-quality-analysis
```

These dependencies are typically installed automatically with the pip command above.

## Usage: Quality Analysis

```python
import cv2
from image_quality_checker import image_quality_score
import image_quality_checker


# Load an image and convert it to bytes
image_path = "path/to/your/image.jpg"  # Replace with the actual path
with open(image_path, "rb") as img_file:
    image_bytes = img_file.read()

# Check image quality
result = image_quality_score(image_bytes)
print("result", result)

# If the image is not good
if result < 0.5:  # You might choose a different threshold
    print("Image quality is low.")
else:
    print("Image quality is acceptable.")

# If the return is "True"
if result is True:
    print("Image is predominantly a single color, very low quality, very small or is corrupt.")
# If exception occurs
if isinstance(result, Exception):
    print(f"An error occurred: {result}")

```

# Usage: Blur Analysis

```python
from image_quality_checker import analyze_blur

image_path = r"E:\Ateeq\dataset\ai\all_in_one\ai\ai(14).jpg"

result = analyze_blur(image_path)

print(f"Blur Ratio: {result['blur_ratio']:.2f}%")
print(f"Category: {result['category']}")
print(f"Overall Blur: {result['overall_blur']}")
```


**Explanation:**

1.  **Import necessary modules:** `cv2` for image processing, `image_quality_score` from the installed package, and `image_quality_checker` to print the file path.

2.  **Load the image:** Reads the image file as bytes.  This is important because the function is designed to work with byte data (e.g., from a network request or database).

3.  **Call `image_quality_score`:** Passes the image bytes to the function, which performs all the quality checks.

4.  **Interpret the result:**
    *   If a numerical score is returned, it represents the quality.  You'll need to determine a suitable threshold (e.g., 0.5) based on your application's requirements.
    *   If `True` is returned, the image is either predominantly a single color, very small (<3KB), or the image data is invalid (cannot be decoded).
    *   If an Exception is returned, an error occurred during processing.

## Function: `image_quality_score(image_bytes)`

*   **Input:** `image_bytes` (bytes): The image data as a byte string.
*   **Output:**
    *   `float`: A normalized quality score between 0 and 1 (inclusive) if the image can be processed successfully.
    *   `True`: If the image is predominantly a single color, or if the image is too small (<3KB), or image data is invalid.
    *  `Exception`: If any Exception is raised.

## Function: `crop_foreground(img)`

*  **Input:**  `img` (NumPy array): The input image as a NumPy array (OpenCV image format).
*   **Output:**
    *    `NumPy array`: The cropped image, focusing on the largest detected foreground object. If no foreground object is found, returns the original image.

## Weights and Max Values

The final score is calculated using weighted contributions from individual metrics:

| Metric           | Weight | Max Value (for Normalization) |
| ---------------- | ------ | ----------------------------- |
| blur\_score     | 0.1    | blur\_threshold (30 or 60)   |
| resolution       | 0.1    | 1000000                      |
| brightness       | 0.1    | 255                          |
| contrast         | 0.1    | 255                          |
| motion\_blur    | 0.1    | 100                          |
| edge\_density   | 0.25   | 0.05                         |
| color\_std\_dev | 0.15   | 100                          |
| entropy          | 0.1    | 8.0                          |

Each metric is normalized by dividing its value by the corresponding `max_value` (and clamped to 1.0).

## Notes

*   The Haar cascade classifier (`haarcascade_frontalface_default.xml`) is used for face detection and must be available (it's usually included with OpenCV).
*   The choice of thresholds (e.g., `blur_threshold`, the cut off value for the `final_score` etc.) might need to be adjusted based on the specific requirements of your application and the types of images you are processing.  Experimentation is key.
*   The `crop_foreground` function uses basic edge detection and contour analysis.  For more robust foreground segmentation, consider using more advanced techniques (e.g., GrabCut, deep learning-based segmentation).
*   Consider logging the individual metric values for more detailed analysis and debugging.
* The package now has a check on the file size and, if it is below 3 KB it's considered valid.
* Image is resized to 256x256 for consistency in processing.

## License
This project is licensed under the Creative Commons Attribution-NoDerivatives (CC BY-ND) License.
