# simplestitcher

## Summary

simplestitcher is a small program built on top of OpenCV that is capable of aligning overlapping images from a two-dimensional plane. Notably, it does not compensate for lens distortion or three-dimensional perspective, so it's not suitable for general photography. However, it's quite straightforward for aligning and stitching images from a microscope, for example.

I have developed and tested simplestitcher on amd64 gnu/linux; however, it should build on any platform where gcc and OpenCV are available. For convenience, I also provide a win32 build here, but it is quite bare: it's just a zipfile with the necessary DLLs and a command-line executable.

## Implementation

simplestitcher operates in a series of stages:

1. Feature detection. SURF [1] features and their associated 128-value descriptors are extracted from each image.
2. Pairwise matching. For every pair of images, feature descriptors are compared (in the naïve $O(n^2)$ way). A robust 2D alignment is then computed using RANSAC [2]. The cost of the pairwise alignment is taken to be the average of the Euclidean norms of the error vectors for the alignments of each of the inlying matches.
3. Global alignment. A global alignment is computed by finding the minimum spanning tree of a graph whose nodes correspond to the input images, and whose edges correspond to the pairwise alignments computed in the previous step. The costs of the edges correspond to the error values for the alignments. If the graph is not connected, then the program aborts.
4. Stitching. An image of suitable dimensions is created, and then filled by sampling (using cubic spline interpolation) from the original images.

## Usage and command-line options

simplestitcher provides only a rudimentary command-line interface. It accepts a list of filenames as arguments, performs the alignment and stitching, and, if successful, writes the resulting image to a file whose name is chosen based on the current date and time.

A number of command-line options are supported:

  --ransac_num_iterations=N
Run N iterations of the basic RANSAC loop.
--ransac_sample_size=N
In each RANSAC iteration, compute a potential alignment using a random
sample containing N matched features.
--ransac_min_inliers=N
In each RANSAC iteration, discard a potential alignment unless it produces
at least N inliers.
--ransac_inlier_tolerance=X
Maximum Euclidean distance between a matched feature's actual position and
its position under the potential alignment, if it is to be classified as an
inlier.
--descriptor_match_threshold
Maximum 2-norm difference between descriptor vectors if their features are
to be considered a match.
--output_file
If specified, the output image will be written to this file (in a format
determined by the file extension).  If this flag is not specified, the
output filename is chosen based on the current date and time.