oscarlorentzon / repstruct

Python library for finding representative structures in image collections

About repstruct

Repstruct is a python library for finding representative structures in large image collections. It is implemented according to the theory of the Master's thesis Finding reprensentative structures in large image collections by Oscar Lorentzon and Nils Lundahl.

The results are obtained by an approach using bags of visual words and colors. The implementation extracts SIFT descriptors as well as colors from the images in the collection and creates feature vectors from histograms created by classifying the features against training data. A collection of images is downloaded from Flickr for a specified tag and the results of the algorithm are presented by plotting the group of closest images and then the most representative.

Running

To be able to download images from Flickr an API key is required. An API key can be requested from Flickr's App Garden.

The rsbundler file can be run from the command line in the following way:

bin/run TAG -a FLICKR_API_KEY

The API key can also be provided by adding a text file called flickr_key.txt with the API key in the root of the project. Then the bundler can be run as follows:

bin/run TAG

To view additional bundler options run the bundler with the -h flag:

bin/run -h

Continuous integration

Dependencies

You need to have Python 2.7+ and the following libraries to run the algorithm:

• OpenCV
• SciPy
• NumPy
• Matplotlib
• Enum34
• PyYAML

The following libraries are required to run the tests:

• Setuptools
• Mock
• Nose

Installing dependencies on Ubuntu

1. OpenCV - Install by following the steps in the Ubuntu OpenCV installation guide.

2. NumPy, SciPy, PyYAML, Enum34, Setuptools, Mock, Nose and Matplotlib - Install pip and run:

    sudo apt-get install gfortran
    sudo pip install -r requirements.txt
    sudo apt-get install python-matplotlib
   

Example output

The images below show the result from a run using the tag steppyramid. The first output image shows the collection images plotted against their feature vector projection onto the third and fourth principal components.

The second output image shows the result after running the algorithm. On top all collection images are shown, in the middle the thirty closest images are shown and at the bottom the five most representative images are shown.

The third output image shows the result for finding all structures ordered according to a score based on the representative result.