Merge pull request #107 from elisemercury/v4.1.3

V4.1.3

Author: elisemercury

README.md

@@ -69,7 +69,7 @@ Folder paths can be specified as standalone Python strings, or within a list. Wi
 ## Output
 difPy returns various types of output that you may use depending on your use case: 
 
-### I. Search Result Dictionary
+### I. Search Result
 A **JSON formatted collection** of duplicates/similar images (i. e. **match groups**) that were found. Each match group has a primary image (the key of the dictionary) which holds the list of its duplicates including their filename and MSE (Mean Squared Error). The lower the MSE, the more similar the primary image and the matched images are. Therefore, an MSE of 0 indicates that two images are exact duplicates.
 
 ```python
@@ -84,7 +84,7 @@ search.result
 ``` 
 
 ### II. Lower Quality Files
-A **list** of duplicates/similar images that have the **lowest quality** among match groups: 
+A **list** of duplicates/similar images that have the **lowest quality** (image resolution) among match groups: 
 
 ```python
 search.lower_quality
@@ -105,7 +105,7 @@ Or **deleted**:
 search.delete(silent_del=False)
 ```
 
-### III. Process Statistics
+### III. Search Statistics
 
 A **JSON formatted collection** with statistics on the completed difPy processes:
 

difPy/dif.py

@@ -349,6 +349,7 @@ def _search_union(self):
 
         # format the end result
         result = self._group_result_union(result_raw)
+        
         return result
 
     def _search_infolder(self):
@@ -734,9 +735,11 @@ def _sort_imgs_by_size(img_list):
         # Function for sorting a list of images based on their file sizes
         imgs_sizes = []
         for img in img_list:
-            img_size = (os.stat(str(img)).st_size, img)
+            with Image.open(img) as image:
+                resolution = image.size
+            img_size = (sum(resolution), img)
             imgs_sizes.append(img_size)
-        sort_by_size = [file for size, file in sorted(imgs_sizes, reverse=True)]
+        sort_by_size = [file for size, file in sorted(imgs_sizes, reverse=True)] # Highest first
         return sort_by_size
 
 class _generate_stats:

difPy/version.py

@@ -1 +1 @@
-__version__ = '4.1.2'
+__version__ = '4.1.3'

docs/app.rst

@@ -6,8 +6,8 @@
 copyright = '2024, Elise Landman'
 author = 'Elise Landman'
 
-release = 'v4.1.2'
-version = 'v4.1.2'
+release = 'v4.1.3'
+version = 'v4.1.3'
 
 # -- General configuration
 

docs/concepts.rst

@@ -1,7 +1,28 @@
+.. _search.lower_quality:
+
+Lower Quality Files
+^^^^^^^^^^
+
+A **list** of duplicates/similar images that have the **lowest resolution** among match groups: 
+
 .. code-block:: python
 
    search.lower_quality
 
    > Output:
    ['C:/Path/duplicate_image1.jpg', 
-    'C:/Path/duplicate_image2.jpg', ...]
+    'C:/Path/duplicate_image2.jpg', ...]
+
+To find the lower quality images, difPy compares the **image resolutions** (pixel width x pixel height) within a match group and selects all images that have lowest image file resolutions among the group.
+
+Lower quality images then can be **moved** to a different location (see :ref:`search.move_to`):
+
+.. code-block:: python
+   
+   search.move_to(destination_path='C:/Path/to/Destination/')
+
+Or **deleted** (see :ref:`search.delete`):
+
+.. code-block:: python
+
+   search.delete(silent_del=False)

docs/conf.py

@@ -0,0 +1,6 @@
+.. _output:
+
+Output
+----------------
+
+difPy returns various types of output:

docs/output/lower_quality.rst

@@ -1,3 +1,10 @@
+.. _search.result:
+
+Search Result
+^^^^^^^^^^
+
+A **dictionary** of duplicates/similar images (i. e. **match groups**) that were found. Each match group has a primary image (the key of the dictionary) which holds the list of its duplicates including their filename and MSE (Mean Squared Error). The lower the MSE, the more similar the primary image and the matched images are. Therefore, an MSE of 0 indicates that two images are exact duplicates.
+
 .. code-block:: python
 
    search.result

docs/output/main.rst

@@ -1,3 +1,5 @@
+When :ref:`in_folder` is set to ``True``, the result output is slightly modified and matches are grouped in their separate folders, with the key of the dictionary being the folder path.
+
 .. code-block:: python
 
    search.result

docs/output/result.rst

@@ -1,3 +1,10 @@
+.. _search.stats:
+
+Search Statistics
+^^^^^^^^^^
+
+A **JSON formatted collection** with statistics on the completed difPy process:
+
 .. code-block:: python
 
    search.stats

docs/output/result_infolder.rst

@@ -1,7 +1,7 @@
 in_folder (bool)
 ++++++++++++
 
-By default, difPy will search for matches in the union of all directories specified in the :ref:`directory` parameter. To have difPy only search for matches within each folder separately, set ``in_folder`` to ``True``.
+By default, difPy will search for matches in the union of all directories specified in the :ref:`directory` parameter. To have difPy only search for matches within each folder separately, set ``in_folder`` to ``True``. The structure of the ``search.result`` output will be slightly different if ``in_folder`` is set to ``True`` (see :ref:`output`).
 
 ``True`` = searches for matches only among each individual directory, including subdirectories
 

docs/output/stats.rst

@@ -1,11 +1,12 @@
+.. _parameters:
+
 Parameters
-=====
+----------------
 
-.. _parameters:
 .. _difPy.build:
 
 difPy.build
-------------
+^^^^^^^^^^
 
 Before difPy can perform any search, it needs to build its image repository and transform the images in the provided directory into tensors. This is what is done when ``difPy.build()`` is invoked.
 
@@ -73,7 +74,7 @@ Upon completion, ``difPy.build()`` returns a ``dif`` object that can be used in
 .. _difPy.search:
 
 difPy.search
-------------
+^^^^^^^^^^
 
 After the ``dif`` object has been built using :ref:`difPy.build`, the search can be initiated with ``difPy.search``. 
 
@@ -103,20 +104,18 @@ After the search is completed, further actions can be performed using :ref:`sear
 .. _difPy_obj:
 
 difPy_obj 
-^^^^^^^^^^^^
+++++++++++++
 
 The required ``difPy_obj`` parameter should be pointing to the ``dif`` object that was built during the invocation of :ref:`difPy.build`. 
 
 .. _similarity: 
 
 .. include:: /parameters/similarity.rst
 
-
 .. _lazy:
 
 .. include:: /parameters/lazy.rst
 
-
 .. _rotate:
 
 .. include:: /parameters/rotate.rst
@@ -144,7 +143,7 @@ The required ``difPy_obj`` parameter should be pointing to the ``dif`` object th
 .. _search.move_to:
 
 search.move_to
-------------
+^^^^^^^^^^
 
 difPy can automatically move the lower quality duplicate/similar images it found to another directory. Images can be moved by invoking ``move_to`` on the difPy search:
 
@@ -171,11 +170,11 @@ difPy can automatically move the lower quality duplicate/similar images it found
 .. _search.delete:
 
 search.delete
-------------
+^^^^^^^^^^
 
 difPy can automatically delete the lower quality duplicate/similar images it found. Images can be deleted by invoking ``delete`` on the difPy search:
 
-.. note::
+.. warning::
 
    Please use with care, as this cannot be undone.