# Duplicate Image Finder (difPy)
**Tired of going through all images in a folder and comparing them manually to check if they are duplicates?**
The Duplicate Image Finder (difPy) Python package **automates** this task for you!
Read more on how the algorithm of difPy works in my Medium article **[Finding Duplicate Images with Python](https://towardsdatascience.com/finding-duplicate-images-with-python-71c04ec8051)**.
For a **detailed usage guide**, please view the official **[difPy Usage Documentation](https://difpy.readthedocs.io/)**.
-------
## Description
difPy searches for images in **one or more different folders**, compares the images it found and checks whether these are duplicates. It then outputs the **image files classified as duplicates** as well as the **images having the lowest resolutions**, so you know which of the duplicate images are safe to be deleted. You can then either delete them manually, or let difPy delete them for you.
difPy does not compare images based on their hashes. It compares them based on their tensors i. e. the image content - this allows difPy to **not only search for duplicate images, but also for similar images**.
difPy leverages Python's **multiprocessing capabilities** and is therefore able to perform at high performance even on large datasets.
## Table of Contents
1. [Basic Usage](https://github.com/elisemercury/Duplicate-Image-Finder#basic-usage)
2. [Output](https://github.com/elisemercury/Duplicate-Image-Finder#output)
3. [Additional Parameters](https://github.com/elisemercury/Duplicate-Image-Finder#additional-parameters)
4. [CLI Usage](https://github.com/elisemercury/Duplicate-Image-Finder#cli-usage)
## Basic Usage
To make difPy search for duplicates **within one folder**:
```python
import difPy
dif = difPy.build("C:/Path/to/Folder/")
search = difPy.search(dif)
```
To search for duplicates **within multiple folders**:
```python
import difPy
dif = difPy.build(["C:/Path/to/FolderA/", "C:/Path/to/FolderB/", "C:/Path/to/FolderC/",...])
search = difPy.search(dif)
```
Folder paths can be specified as standalone Python strings, or within a list. With `difPy.build()`, difPy first scans the images in the provided folders and builds a collection of images by generating image tensors. `difPy.search()` then starts the search for duplicate images.
## Output
difPy returns various types of output that you may use depending on your use case:
### I. Search Result Dictionary
A **JSON formatted collection** of duplicates/similar images (i. e. **match groups**) that were found, where the keys are a **randomly generated unique id** for each image file:
```python
search.result
> Output:
{20220819171549 : {"location" : "C:/Path/to/Image/image1.jpg",
"matches" : {30270813251529 : "location": "C:/Path/to/Image/matched_image1.jpg",
"mse": 0.0},
{72214282557852 : "location": "C:/Path/to/Image/matched_image2.jpg",
"mse": 0.0},
... }
...
}
```
### II. Lower Quality Files
A **JSON formatted collection** of duplicates/similar images that have the **lowest quality** among match groups:
```python
search.lower_quality
> Output:
{"lower_quality" : ["C:/Path/to/Image/duplicate_image1.jpg",
"C:/Path/to/Image/duplicate_image2.jpg", ...]}
```
Lower quality images then can be **moved to a different location**:
```python
search.move_to(search, destination_path="C:/Path/to/Destination/")
```
Or **deleted**:
```python
search.delete(search, silent_del=False)
```
### III. Process Statistics
A **JSON formatted collection** with statistics on the completed difPy processes:
```python
search.stats
> Output:
{"directory" : ("C:/Path/to/Folder_A/", "C:/Path/to/Folder_B/", ... ),
"process" : {"build" : {"duration" : {"start" : "2023-08-28T21:22:48.691008",
"end" : "2023-08-28T21:23:59.104351",
"seconds_elapsed" : "70.4133"},
"parameters" : {"recursive" : True,
"in_folder" : False,
"limit_extensions" : True,
"px_size" : 50}},
"search" : {"duration" : {"start" : "2023-08-28T21:23:59.106351",
"end" : "2023-08-28T21:25:17.538015",
"seconds_elapsed" : "78.4317"},
"parameters" : {"similarity_mse" : 0}
"files_searched" : 5225,
"matches_found" : {"duplicates" : 5,
"similar" : 0}}}
"invalid_files" : {"count" : 230,
"logs" : {...}}}
```
## Additional Parameters
difPy supports the following parameters:
```python
difPy.build(*directory, recursive=True, in_folder=False, limit_extensions=True,
px_size=50, show_progress=False, logs=True)
```
```python
difPy.search(difpy_obj, similarity='duplicates', show_progress=False, logs=True)
```
## CLI Usage
difPy can also be invoked through the CLI by using the following commands:
```python
python dif.py #working directory
python dif.py -D "C:/Path/to/Folder/"
python dif.py -D "C:/Path/to/Folder_A/" "C:/Path/to/Folder_B/" "C:/Path/to/Folder_C/"
```
difPy CLI supports the following arguments:
```python
dif.py [-h] [-D DIRECTORY [DIRECTORY ...]] [-Z OUTPUT_DIRECTORY]
[-r {True,False}] [-i {True,False}] [-le {True,False}]
[-px PX_SIZE] [-p {True,False}] [-s SIMILARITY]
[-mv MOVE_TO] [-d {True,False}] [-sd {True,False}]
[-l {True,False}]
```
If no directory parameter is given in the CLI, difPy will **run on the current working directory**.
When running from the CLI, the output of difPy is written to files and **saved in the working directory** by default. To change the default output directory, specify the `-Z / -output_directory` parameter. The "xxx" in the output filenames is the current timestamp:
```python
difPy_xxx_results.json
difPy_xxx_lower_quality.json
difPy_xxx_stats.json
```
-------
For a **detailed usage guide**, please view the official **[difPy Usage Documentation](https://difpy.readthedocs.io/)**.
Raw data
{
"_id": null,
"home_page": "https://github.com/elisemercury/Duplicate-Image-Finder",
"name": "difPy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "duplicate,image,finder,similarity,pictures",
"author": "Elise Landman",
"author_email": "elisejlandman@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/51/61/f5e4be1db74a51aecbc58f33ef94ce07e13a5e9d9d6f20bbfc6beb901e8f/difPy-4.0.1.tar.gz",
"platform": null,
"description": "# Duplicate Image Finder (difPy)\r\n\r\n**Tired of going through all images in a folder and comparing them manually to check if they are duplicates?**\r\n\r\nThe Duplicate Image Finder (difPy) Python package **automates** this task for you!\r\n\r\nRead more on how the algorithm of difPy works in my Medium article **[Finding Duplicate Images with Python](https://towardsdatascience.com/finding-duplicate-images-with-python-71c04ec8051)**.\r\n\r\nFor a **detailed usage guide**, please view the official **[difPy Usage Documentation](https://difpy.readthedocs.io/)**.\r\n\r\n-------\r\n\r\n## Description\r\ndifPy searches for images in **one or more different folders**, compares the images it found and checks whether these are duplicates. It then outputs the **image files classified as duplicates** as well as the **images having the lowest resolutions**, so you know which of the duplicate images are safe to be deleted. You can then either delete them manually, or let difPy delete them for you.\r\n\r\ndifPy does not compare images based on their hashes. It compares them based on their tensors i. e. the image content - this allows difPy to **not only search for duplicate images, but also for similar images**.\r\n\r\ndifPy leverages Python's **multiprocessing capabilities** and is therefore able to perform at high performance even on large datasets. \r\n\r\n\r\n## Table of Contents\r\n1. [Basic Usage](https://github.com/elisemercury/Duplicate-Image-Finder#basic-usage)\r\n2. [Output](https://github.com/elisemercury/Duplicate-Image-Finder#output)\r\n3. [Additional Parameters](https://github.com/elisemercury/Duplicate-Image-Finder#additional-parameters)\r\n4. [CLI Usage](https://github.com/elisemercury/Duplicate-Image-Finder#cli-usage)\r\n\r\n## Basic Usage\r\nTo make difPy search for duplicates **within one folder**:\r\n\r\n```python\r\nimport difPy\r\ndif = difPy.build(\"C:/Path/to/Folder/\")\r\nsearch = difPy.search(dif)\r\n``` \r\nTo search for duplicates **within multiple folders**:\r\n\r\n```python\r\nimport difPy\r\ndif = difPy.build([\"C:/Path/to/FolderA/\", \"C:/Path/to/FolderB/\", \"C:/Path/to/FolderC/\",...])\r\nsearch = difPy.search(dif)\r\n``` \r\n\r\nFolder paths can be specified as standalone Python strings, or within a list. With `difPy.build()`, difPy first scans the images in the provided folders and builds a collection of images by generating image tensors. `difPy.search()` then starts the search for duplicate images.\r\n\r\n## Output\r\ndifPy returns various types of output that you may use depending on your use case: \r\n\r\n### I. Search Result Dictionary\r\nA **JSON formatted collection** of duplicates/similar images (i. e. **match groups**) that were found, where the keys are a **randomly generated unique id** for each image file:\r\n\r\n```python\r\nsearch.result\r\n\r\n> Output:\r\n{20220819171549 : {\"location\" : \"C:/Path/to/Image/image1.jpg\",\r\n \"matches\" : {30270813251529 : \"location\": \"C:/Path/to/Image/matched_image1.jpg\",\r\n \"mse\": 0.0},\r\n {72214282557852 : \"location\": \"C:/Path/to/Image/matched_image2.jpg\",\r\n \"mse\": 0.0},\r\n ... }\r\n ...\r\n}\r\n``` \r\n\r\n### II. Lower Quality Files\r\nA **JSON formatted collection** of duplicates/similar images that have the **lowest quality** among match groups: \r\n\r\n```python\r\nsearch.lower_quality\r\n\r\n> Output:\r\n{\"lower_quality\" : [\"C:/Path/to/Image/duplicate_image1.jpg\", \r\n \"C:/Path/to/Image/duplicate_image2.jpg\", ...]}\r\n``` \r\n\r\nLower quality images then can be **moved to a different location**:\r\n\r\n```python\r\nsearch.move_to(search, destination_path=\"C:/Path/to/Destination/\")\r\n```\r\nOr **deleted**:\r\n\r\n```python\r\nsearch.delete(search, silent_del=False)\r\n```\r\n\r\n### III. Process Statistics\r\n\r\nA **JSON formatted collection** with statistics on the completed difPy processes:\r\n\r\n```python\r\nsearch.stats\r\n\r\n> Output:\r\n{\"directory\" : (\"C:/Path/to/Folder_A/\", \"C:/Path/to/Folder_B/\", ... ),\r\n \"process\" : {\"build\" : {\"duration\" : {\"start\" : \"2023-08-28T21:22:48.691008\",\r\n \"end\" : \"2023-08-28T21:23:59.104351\",\r\n \"seconds_elapsed\" : \"70.4133\"},\r\n \"parameters\" : {\"recursive\" : True,\r\n \"in_folder\" : False,\r\n \"limit_extensions\" : True,\r\n \"px_size\" : 50}},\r\n \"search\" : {\"duration\" : {\"start\" : \"2023-08-28T21:23:59.106351\",\r\n \"end\" : \"2023-08-28T21:25:17.538015\",\r\n \"seconds_elapsed\" : \"78.4317\"},\r\n \"parameters\" : {\"similarity_mse\" : 0}\r\n \"files_searched\" : 5225,\r\n \"matches_found\" : {\"duplicates\" : 5,\r\n \"similar\" : 0}}}\r\n \"invalid_files\" : {\"count\" : 230,\r\n \"logs\" : {...}}}\r\n```\r\n\r\n## Additional Parameters\r\ndifPy supports the following parameters:\r\n\r\n```python\r\ndifPy.build(*directory, recursive=True, in_folder=False, limit_extensions=True, \r\n px_size=50, show_progress=False, logs=True)\r\n```\r\n\r\n```python\r\ndifPy.search(difpy_obj, similarity='duplicates', show_progress=False, logs=True)\r\n```\r\n\r\n## CLI Usage\r\ndifPy can also be invoked through the CLI by using the following commands:\r\n\r\n```python\r\npython dif.py #working directory\r\n\r\npython dif.py -D \"C:/Path/to/Folder/\"\r\n\r\npython dif.py -D \"C:/Path/to/Folder_A/\" \"C:/Path/to/Folder_B/\" \"C:/Path/to/Folder_C/\"\r\n```\r\n\r\ndifPy CLI supports the following arguments:\r\n\r\n```python\r\ndif.py [-h] [-D DIRECTORY [DIRECTORY ...]] [-Z OUTPUT_DIRECTORY] \r\n [-r {True,False}] [-i {True,False}] [-le {True,False}] \r\n [-px PX_SIZE] [-p {True,False}] [-s SIMILARITY] \r\n [-mv MOVE_TO] [-d {True,False}] [-sd {True,False}] \r\n [-l {True,False}]\r\n```\r\n\r\nIf no directory parameter is given in the CLI, difPy will **run on the current working directory**.\r\n\r\nWhen running from the CLI, the output of difPy is written to files and **saved in the working directory** by default. To change the default output directory, specify the `-Z / -output_directory` parameter. The \"xxx\" in the output filenames is the current timestamp:\r\n\r\n```python\r\ndifPy_xxx_results.json\r\ndifPy_xxx_lower_quality.json\r\ndifPy_xxx_stats.json\r\n```\r\n\r\n-------\r\n\r\nFor a **detailed usage guide**, please view the official **[difPy Usage Documentation](https://difpy.readthedocs.io/)**.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "difPy Duplicate Image Finder - automated search for duplicate or similar images.",
"version": "4.0.1",
"project_urls": {
"Download": "https://github.com/elisemercury/Duplicate-Image-Finder/archive/refs/tags/v4.0.1.tar.gz",
"Homepage": "https://github.com/elisemercury/Duplicate-Image-Finder"
},
"split_keywords": [
"duplicate",
"image",
"finder",
"similarity",
"pictures"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5b2fcbbcc873506763f8b8a32929328d763754ec1060c1e319acc5f346e3cd72",
"md5": "27459cfa875a63640f81fe00d79e6fc1",
"sha256": "0a8f43d47f80fc8cf3e9bd9c0b4e97604dc6216fb35a49c21993e076f8acb601"
},
"downloads": -1,
"filename": "difPy-4.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27459cfa875a63640f81fe00d79e6fc1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11822,
"upload_time": "2023-09-27T19:42:42",
"upload_time_iso_8601": "2023-09-27T19:42:42.351314Z",
"url": "https://files.pythonhosted.org/packages/5b/2f/cbbcc873506763f8b8a32929328d763754ec1060c1e319acc5f346e3cd72/difPy-4.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5161f5e4be1db74a51aecbc58f33ef94ce07e13a5e9d9d6f20bbfc6beb901e8f",
"md5": "34054bb8834841388f7daeffa63e5d64",
"sha256": "7210b077c1d8650e3c530ae4ed5a1a59edb9ff3e02e39d59c7f5fe916808bc34"
},
"downloads": -1,
"filename": "difPy-4.0.1.tar.gz",
"has_sig": false,
"md5_digest": "34054bb8834841388f7daeffa63e5d64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15087,
"upload_time": "2023-09-27T19:42:43",
"upload_time_iso_8601": "2023-09-27T19:42:43.601581Z",
"url": "https://files.pythonhosted.org/packages/51/61/f5e4be1db74a51aecbc58f33ef94ce07e13a5e9d9d6f20bbfc6beb901e8f/difPy-4.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-27 19:42:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "elisemercury",
"github_project": "Duplicate-Image-Finder",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "difpy"
}
JSON
