pyblurry 1.0.2
Performs analysis on images to determine whether they are blurry.
Requires Python: >=3.10
Keywords: blur, blurry, detection, image, laplacian

pyblurry
========

Performs analysis on images to determine whether they are blurry.
-----------------------------------------------------------------
**pyblurry** is a simple library providing functionality to
determine whether images are blurry using different detection
algorithms.

Installation
------------
The easiest is to use pip:

```
$ pip install pyblurry
```

Usage
-----
To determine whether an image is blurry using the fastest and simplest analysis method with the `is_blurry` function:

```
>>> import pyblurry
>>> pyblurry.is_blurry(image="blurry_image.jpg")
True
>>> pyblurry.is_blurry(image="non_blurry_image.png")
False
```

To perform an analysis using all detection methods with the `analyze` function:

```
>>> pyblurry.analyze(image="blurry_image.jpg")
{"elapsed_time": 1.17062349896878, "laplacian-simple": {"confidence": 1.0, "is_blurry": true, "resized": true, "elapsed_time": 0.08787570800632238, "laplacian_variance": 2.11518251626384, "laplacian_threshold": 19.0}, "laplacian-local-blur": {"confidence": 0.9916666666666667, "is_blurry": true, "resized": true, "elapsed_time": 0.06633887498173863, "local_laplacian_variance": 2.11518251626384, "global_laplacian_variance": 2.11518251626384, "laplacian_threshold": 70.0}, "laplacian-face-detection": {"confidence": 0.9916666666666667, "is_blurry": true, "resized": true, "elapsed_time": 0.18917625001631677, "faces_detected": false, "laplacian_variance": 2.11518251626384, "laplacian_threshold": 20.0}, "perceptual-robust": {"confidence": 0.9583333333333333, "is_blurry": true, "resized": true, "elapsed_time": 0.7872245829785243, "perceptual_mean": 0.8366243655027964, "perceptual_threshold": 0.395}, "fast-fourier-transform": {"confidence": 0.9333333333333333, "is_blurry": true, "resized": true, "elapsed_time": 0.04000808298587799, "fft_mean": -5.397502609440028, "fft_mean_threshold": 10.0}}
```

The `analyze` function can be used with the `use_algorithms` parameter to specify which analysis algorithms to use, or with the `exclude_algorithms` to specify which algorithms not to use:

```
>>> pyblurry.analyze(image="blurry_image.jpg", use_algorithms=("laplacian-simple", "fast-fourier-transform"))
{"elapsed_time": 0.06035354104824364, "laplacian-simple": {"confidence": 1.0, "is_blurry": true, "resized": true, "elapsed_time": 0.026116708060726523, "laplacian_variance": 2.11518251626384, "laplacian_threshold": 19.0}, "fast-fourier-transform": {"confidence": 0.9333333333333333, "is_blurry": true, "resized": true, "elapsed_time": 0.03423683298751712, "fft_mean": -5.397502609440028, "fft_mean_threshold": 10.0}}
```

and it can be used with the `exclude_algorithms` parameter to specify which algorithms to exclude:

```
>>> pyblurry.analyze(image="blurry_image.jpg", exclude_algorithms=("laplacian-simple", "fast-fourier-transform"))
{"elapsed_time": 0.8824597500497475, "laplacian-local-blur": {"confidence": 0.9916666666666667, "is_blurry": true, "resized": true, "elapsed_time": 0.015356042073108256, "local_laplacian_variance": 2.11518251626384, "global_laplacian_variance": 2.11518251626384, "laplacian_threshold": 70.0}, "laplacian-face-detection": {"confidence": 0.9916666666666667, "is_blurry": true, "resized": true, "elapsed_time": 0.10222391597926617, "faces_detected": false, "laplacian_variance": 2.11518251626384, "laplacian_threshold": 20.0}, "perceptual-robust": {"confidence": 0.9583333333333333, "is_blurry": true, "resized": true, "elapsed_time": 0.7648797919973731, "perceptual_mean": 0.8366243655027964, "perceptual_threshold": 0.395}}
```

The individual analysis classes can be found in its own modules and can be used independently:

```
>>> from pyblurry.fourier import FastFourierTransformAnalysis
>>> fourier_method = FastFourierTransformAnalysis(image_filepath="blurry_image.jpg")
>>> fourier_method.analyze()
{"method": "fast-fourier-transform", "confidence": 0.9333333333333333, "is_blurry": true, "resized": true, "elapsed_time": 0.049961082986555994, "fft_mean": -5.397502609440028, "fft_mean_threshold": 10.0}

>>> from pyblurry.laplacian_face_detection import LaplacianDetectingFaces
>>> laplacian_with_faces_method = LaplacianDetectingFaces(image_filepath="blurry_image.jpg")
>>> laplacian_with_faces_method.analyze()
{"method": "laplacian-face-detection", "confidence": 0.9916666666666667, "is_blurry": true, "resized": true, "elapsed_time": 0.126255749957636, "faces_detected": false, "laplacian_variance": 2.11518251626384, "laplacian_threshold": 20.0}

>>> from pyblurry.laplacian_local_blur import LaplacianDetectingLocalizedBlur
>>> laplacian_with_local_blur_method = LaplacianDetectingLocalizedBlur(image_filepath="blurry_image.jpg")
>>> laplacian_with_local_blur_method.analyze()
{"method": "laplacian-local-blur", "confidence": 0.9916666666666667, "is_blurry": true, "resized": true, "elapsed_time": 0.034303167019970715, "local_laplacian_variance": 2.11518251626384, "global_laplacian_variance": 2.11518251626384, "laplacian_threshold": 70.0}

>>> from pyblurry.laplacian_simple import LaplacianSimpleAnalysis
>>> laplacial_simple_method = LaplacianSimpleAnalysis(image_filepath="blurry_image.jpg")
>>> laplacial_simple_method.analyze()
{"method": "laplacian-simple", "confidence": 1.0, "is_blurry": true, "resized": true, "elapsed_time": 0.0004107499262318015, "laplacian_variance": 2.11518251626384, "laplacian_threshold": 19.0}

>>> from pyblurry.perceptual import PerceptualRobustAnalysis
>>> perceptual_method = PerceptualRobustAnalysis(image_filepath="blurry_image.jpg")
>>> perceptual_method.analyze()
{"method": "perceptual-robust", "confidence": 0.9583333333333333, "is_blurry": true, "resized": true, "elapsed_time": 0.8531872910680249, "perceptual_mean": 0.8366243655027964, "perceptual_threshold": 0.395}
```

The default threshold values for each of the analysis methods has been tuned with a sample of 60 blurry and 60 non-blurry images (also being used for unit tests). The threshold values can (and maybe should) be adjusted if the blur detection is not accurate for the images being used.