Package: pimmi
PIMMI : Python IMage MIningPIMMI is a software that performs visual mining in a corpus of images. Its main objective is to find all copies,
total or partial, in large volumes of images and to group them together. Our initial goal is to study the reuse
of images on social networks (typically, our first use is the propagation of memes on Twitter). However, we believe
that its use can be much wider and that it can be easily adapted for other studies. The main features of PIMMI
are therefore :ability to process large image corpora, up to several millions filesbe robust to some modifications of the images, typical of their reuse on social networks (crop, zoom,
composition, addition of text, ...)be flexible enough to adapt to different use cases (mainly the nature and volume of the image corpora)PIMMI is currently only focused on visual mining and therefore does not manage metadata related to images.
The latter are specific to each study and are therefore outside our scope. Thus, a study using PIMMI
will generally be broken down into several steps:constitution of a corpus of images (jpg and/or png files) and their metadatachoice of PIMMI parameters according to the criteria of the corpusindexing the images with PIMMI and obtaining clusters of reused imagesexploitation of the clusters by combining them with the descriptive metadata of the imagesPIMMI relies on existing technologies and integrates them into a simple data pipeline:Use well-established local image descriptors (Scale Invariant Feature Transform: SIFT) to represent images
as sets of keypoints. Geometric consistency verification is also used. (OpenCVimplementation
for both).To adapt to large volumes of images, it relies on a well known vectors indexing library that provides some
of the most efficient algorithms implementations (FAISS) to query
the database of keypoints.Similar images are grouped together using standard community detection algorithms on the graph of similarities.PIMMI is a library developed in Python, which can be used through a command line interface. It is multithreaded.
A rudimentary web interface to visualize the results is also provided, but more as an example than for
intensive use (Pimmi-ui).The development of this software is still in progress : we warmly welcome beta-testers, feedback,
proposals for new features and even pull requests !Initial authorsBéatrice MazoyerNicolas HervéInstall with pyenv and pippyenvvirtualenv3.7.0pimmi-env
pyenvactivatepimmi-env
pipinstall-Upip
pipinstallpimmiInstall from sourcepython3-mvenv/tmp/pimmi-envsource/tmp/pimmi-env/bin/activate
pipinstall-Upip
gitclonegit@github.com:nrv/pimmi.gitcdpimmi
pipinstall-rrequirements.txtpipinstall-e.Demo# --- Play with the demo dataset 1# Create a default index structure and fill it with the demo dataset. An 'index' directory will be created,# it will contain the 2 files of the pimmi index : dataset1.IVF1024,Flat.faiss and# dataset1.IVF1024,Flat.metapimmifilldemo_dataset/dataset1dataset1# Query the same dataset on this index, the results will be stored in# index/dataset1.IVF1024,Flat.mining_000000.csvpimmiquerydemo_dataset/dataset1dataset1# Post process the mining results in order to visualize thempimmiclustersdataset1# You can also play with the configuration parameters. First, generate a default configuration filepimmicreate-configmy_pimmi_conf.yml# Then simply use this configuration file to relaunch the mining steps (erasing without prompt the# previous data)pimmifill--erase--force--config-pathmy_pimmi_conf.ymldemo_dataset/dataset1dataset1
pimmiquery--config-pathmy_pimmi_conf.ymldemo_dataset/dataset1dataset1
pimmiclusters--config-pathmy_pimmi_conf.ymldataset1Test on the Copydays datasetYou can find the dataset explanationshere. Unfortunately, the data files are not available anymore, you can get them fromweb archive.Create a project structure and uncompress all the files in the same images directory.copydays
└───index
└───images
    └───crop
    │   └───crops
    │       └───10
    │       └───15
    │       └───20
    │       └───30
    │       └───40
    │       └───50
    │       └───60
    │       └───70
    │       └───80
    └───original
    └───jpeg
    │   └───jpegqual
    │       └───3
    │       └───5
    │       └───8
    │       └───10
    │       └───15
    │       └───20
    │       └───30
    │       └───50
    │       └───75
    └───strongYou can then play with the different parameters and evaluate the results. If you want to loop over several parameters to optimize your settings, you may have a look at eval_copydays.sh.cdscripts
mkdirindex
pimmi--sift-nfeatures1000--index-typeIVF1024,Flatfill/path/to/copydays/images/copydays
pimmi--query-sift-knn1000--query-dist-ratio-threshold0.8--index-typeIVF1024,Flatquery/path/to/copydays/images/copydayspimmi--index-typeIVF1024,Flat--algocomponentsclusterscopydays
pythoncopydays_groundtruth.py/path/to/copydays/images/index/copydays.IVF1024,Flat.mining.clusters.csv
pimmievalindex/copydays.IVF1024,Flat.mining.groundtruth.csv--query-columnimage_statuscluster precision: 0.9924645454677958
cluster recall: 0.7406974660159374
cluster f1: 0.7856752626502786
query average precision: 0.8459113427266295Happy hacking !