Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/erdogant/clustimage

clustimage is a python package for unsupervised clustering of images.
https://github.com/erdogant/clustimage

clustering image-analysis image-processing python3

Last synced: about 1 month ago
JSON representation

clustimage is a python package for unsupervised clustering of images.

Awesome Lists containing this project

README 

        
# clustimage



[![Python](https://img.shields.io/pypi/pyversions/clustimage)](https://img.shields.io/pypi/pyversions/clustimage)

[![Pypi](https://img.shields.io/pypi/v/clustimage)](https://pypi.org/project/clustimage/)

[![Docs](https://img.shields.io/badge/Sphinx-Docs-Green)](https://erdogant.github.io/clustimage/)

[![LOC](https://sloc.xyz/github/erdogant/clustimage/?category=code)](https://github.com/erdogant/clustimage/)

[![Downloads](https://static.pepy.tech/personalized-badge/clustimage?period=month&units=international_system&left_color=grey&right_color=brightgreen&left_text=PyPI%20downloads/month)](https://pepy.tech/project/clustimage)

[![Downloads](https://static.pepy.tech/personalized-badge/clustimage?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=Downloads)](https://pepy.tech/project/clustimage)

[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/erdogant/clustimage/blob/master/LICENSE)

[![Forks](https://img.shields.io/github/forks/erdogant/clustimage.svg)](https://github.com/erdogant/clustimage/network)

[![Issues](https://img.shields.io/github/issues/erdogant/clustimage.svg)](https://github.com/erdogant/clustimage/issues)

[![Project Status](http://www.repostatus.org/badges/latest/active.svg)](http://www.repostatus.org/#active)

[![DOI](https://zenodo.org/badge/423822054.svg)](https://zenodo.org/badge/latestdoi/423822054)

[![Medium](https://img.shields.io/badge/Medium-Blog-blue)](https://erdogant.github.io/clustimage/pages/html/Documentation.html#)

[![Colab](https://colab.research.google.com/assets/colab-badge.svg?logo=github%20sponsors)](https://erdogant.github.io/clustimage/pages/html/Documentation.html#colab-notebook)

[![Donate](https://img.shields.io/badge/Support%20this%20project-grey.svg?logo=github%20sponsors)](https://erdogant.github.io/clustimage/pages/html/Documentation.html#)



The aim of ``clustimage`` is to detect natural groups or clusters of images. It works using a multi-step proces of carefully pre-processing the images, extracting the features, and evaluating the optimal number of clusters across the feature space.

The optimal number of clusters can be determined using well known methods suchs as *silhouette, dbindex, and derivatives* in combination with clustering methods, such as *agglomerative, kmeans, dbscan and hdbscan*.

With ``clustimage`` we aim to determine the most robust clustering by efficiently searching across the parameter and evaluation the clusters.

Besides clustering of images, the ``clustimage`` model can also be used to find the most similar images for a new unseen sample.



A schematic overview is as following:





  




``clustimage`` overcomes the following challenges: 



    * 1. Robustly groups similar images.

    * 2. Returns the unique images.

    * 3. Finds higly similar images for a given input image.

    * 4. Cluster on datetime or latlon coordinates when using photos.



``clustimage`` is fun because:



    * It does not require a learning proces.

    * It can group any set of images.

    * It can return only the unique() images.

    * it can find highly similar images given an input image.

    * it can map photos on an interactive map with thumbnails and clusterlabels so that you easily structure your photos.

    * It provided many plots to improve understanding of the feature-space and sample-sample relationships

    * It is build on core statistics, such as PCA, HOG, EXIF data and many more, and therefore it does not has a dependency block.

    * It works out of the box.



# 

**⭐️ Star this repo if you like it ⭐️**

#



### Blogs



* Read the [blog](https://towardsdatascience.com/a-step-by-step-guide-for-clustering-images-4b45f9906128) to get a structured overview how to cluster images.



# 



### [Documentation pages](https://erdogant.github.io/clustimage/)



On the [documentation pages](https://erdogant.github.io/clustimage/) you can find detailed information about the working of the ``clustimage`` with many examples. 



# 



### Installation



##### It is advisable to create a new environment (e.g. with Conda). 

```bash

conda create -n env_clustimage python=3.8

conda activate env_clustimage

```



##### Install bnlearn from PyPI

```bash

pip install clustimage            # new install

pip install -U clustimage         # update to latest version

```



##### Directly install from github source

```bash

pip install git+https://github.com/erdogant/clustimage

```  



##### Import clustimage package



```python

from clustimage import clustimage

```






### Examples



The results obtained from the clustimgage library is a dictionary containing the following keys:



    * img       : image vector of the preprocessed images

    * feat      : Features extracted for the images

    * xycoord   : X and Y coordinates from the embedding

    * pathnames : Absolute path location to the image file

    * filenames : File names of the image file

    * labels    : Cluster labels



### Examples Mnist dataset:



##### [Example: Clustering mnist dataset](https://erdogant.github.io/clustimage/pages/html/Examples.html#)



In this example we will be using a flattened grayscale image array loaded from sklearn. The unique detected clusters are the following:





  

  

  

  




**Click on the underneath scatterplot to zoom-in and see ALL the images in the scatterplot**





  




#



##### [Example: Plot the explained variance](https://erdogant.github.io/clustimage/pages/html/Examples.html#cluster-evaluation)





  

  

  

  

  




#



##### [Example: Plot the unique images](https://erdogant.github.io/clustimage/pages/html/Examples.html#detect-unique-images)





  

  

  




#



##### [Example: Plot the dendrogram](https://erdogant.github.io/clustimage/pages/html/Examples.html#dendrogram)





  

  

  




 



### Examples Flower dataset:



##### [Example: cluster the flower dataset](https://erdogant.github.io/clustimage/pages/html/Examples.html#id5)





  

  

  

  




##### [Example: Make scatterplot with clusterlabels](https://erdogant.github.io/clustimage/pages/html/Examples.html#id7)





  

  

  

  

  

  




##### [Example: Plot the unique images per cluster](https://erdogant.github.io/clustimage/pages/html/Examples.html#id6)





  






  




##### [Example: Plot the images in a particular cluster](https://erdogant.github.io/clustimage/pages/html/Examples.html#id8)





  




##### [Example: Make prediction for unseen input image](https://erdogant.github.io/clustimage/pages/html/Examples.html#predict-unseen-sample)





  





  





  




 



#### [Example: Clustering of faces on images](https://erdogant.github.io/clustimage/pages/html/Examples.html#clustering-of-faces)






  

  



  



  

  



  

  



  







#### [Example: Break up the steps](https://erdogant.github.io/clustimage/pages/html/Examples.html#breaking-up-the-steps)






#### [Example: Extract images belonging to clusters](https://erdogant.github.io/clustimage/pages/html/Examples.html#extract-images-belonging-to-clusters)






### Support



	This project needs some love! ❤️ You can help in various ways.



	* Become a Sponsor!

	* Star this repo at the github page.

	* Other contributions can be in the form of feature requests, idea discussions, reporting bugs, opening pull requests.

	* Read more why becoming an sponsor is important on the Sponsor Github Page.

	

	Cheers Mate.