README

ARCHIVE-VISION

Archive-Vision (archv or arch-v) is a collection of computer vision programs written in C++ which utilizes functions from the OpenCV library to perform analysis on large image sets. The primary function is to locate recurring patterns within each image in a set of images. Arch-v locates features from a given seed image within an imageset and outputs the image(s) with the most similarities. The first program, processImages.cpp, generates text files containing the keypoints and their mathmatical descriptors; with the keypoints, analysis can be done to compare images and find matches. The second program, scanDatabase.cpp, finds the images that are most similar to a given seed image. The third program, drawMatches.cpp, compares two images, locates their matches based on homography, then draws the keypoints and their relative match; this is most useful when the best matches have already been found.

The best use for arch-v is to find images which are similar to a seed image. The standard method is to process the image set that you will compare your seed image to, scan through the generated dataset with a given seed image to find the best matches, then draw identifiers for matching features between the seed image and its best match.

Therefore, the method is as follows:

processImages

scanDatabase

drawMatches

SETTING UP ARCH-V

In order to compile and run this project you will need to install the OpenCV library.

Note: click here to download the documentation for setting up arch-v on macOS.

Installing OpenCV

For OpenCV, you need several dependencies: gcc, g++, cmake and several video and image libraries specified on their site. For Linux, use these links to install OpenCV:

Once OpenCV is installed and the libraries are included, go to your arch-v directory and run make all. You should be left with an executable (.exe) version of each program: processImages.exe, scanDatabase.exe, and drawMatches.exe.

Note: all image files should be .jpg and click here if you wish to download the same imageset that this documentation will be using.

PROCESS IMAGES

processImages reads in a parameter file (for SURF), an input directory that contains the images to be processed, and an output directory to put the YAML files containing their discovered keypoints and their descriptors.

Using processImages

When running processImages, the <path to input directory> is the imageset that you are trying to process. The output directory, which is where the .yml files will be stored, must already exist. This program is the most computationally intensive component of arch-v and should take several minutes to complete.

These files will then be read in for the homography matching component of arch-v. Looking at the first .yml file, the first matrix contains the keypoints and the second matrix contains the descriptors for the keypoints:

After this step has been completed, you can run the second program to find matches for your seed image within the image set.

SCAN DATABASE

scanDatabase reads in a seed image, the directory of .yml files, a filepath to an output json (text) file, and the path to the SURF parameter file.

The program reads in your seed image, extracts the keypoints and descriptors like processImages had, and compares that information with the keypoints and descriptors from every .yml file; this is essentially comparing the seed image against every image in the imageset. Each comparison is done using a robust filter, that checks for sensitivity, symmetry, as well as geometric proximity of the matches. Images are then ranked based on the number of matches they have with the seed image.

When the program finishes, it will have saved the output in json from to the text file with the names that you had specified <path to output file>. Combining the top hits should look similar to the following image:

The seed image is in the top left, the best match is immediately to the right (being the seed image itself), the second best is the first image in the second row, and so on. The filename and distance are included on top of each image. The distance refers to the remaining number of matches.

DRAW MATCHES

drawMatches takes as input two images, the path to an output image file as well as the path to the parameter file. It is best to use similar parameters to what was used in the first two steps to find these two images that are known to be similar. The code is also self contained so you can input any two images and any SURF parameter files to find the keypoints that match and have passed the robust homography filter.

BONUS

showKeypoints takes as input one image, path to output file with .jpg ending, and path to a paramater file. This will display all the keypoints, their size, and orientation onto the input image. This is useful for finding a good set of parameters for your image set

scanDatabaseImage does the same thing as scanDatabase but combines the best results into a single image. Takes the same inputs as scanDatabase. Outputs output.txt and output.jpg. output.txt is the ordered images and the number of matches.