Sylwester Bala

Thank you for using the MicroStitcher tool.

The Wiki is going to have the most important information like how to build and use this tool.

  1. How to build?

You need to have CMake to be able to build the project successfully otherwise you can create Makefile or any project for other IDEs and build it manually. From definition the project is independent from any other libraries and should run on any platform. I have been testing on MacOSX only.

If you have CMake already installed then follow the instructions below:
- Download the source code
- Go into the folder where CMakeLists.txt file exists and call:
On Linux and Unix systems:
cmake -G "Unix Makefiles"
On Windows:
cmake -G "Visual Studio 8 2005"
- After that Makefiles are ready and you can start build binary
On Unix systems:

On Windows
  Open Visual Studio solution, which has just been created by cmake and build the project there.
  • If compilation succeeded that's it. In ./bin/ folder you can find MicroStritcher binary

  • How to use?
    2.1. First of all the tool is capable of reading non-compressed, RGB, TGA files only. If you have them in any other formats, no worries there is very easy way to convert them automatically. For this purpose you will need only one additional command line tool called "nconvert", which can be downloaded from http://www.xnview.com/en/nconvert.html.
    Having this tool you can write command as below to convert all images at once like in the example below. All PNG files from "imgs" folder are converted to TGA files written into "tmp" folder:

./nconvert -out tga -overwrite -merge_alpha -o tmp/img#### imgs/*.png

- out tga: means the output files will be TGA
- merge_alpha: the image, which has an Alpha channel will be converted to RGB
- -o: output dir where TGAs files will be written
- tmp: existing empty folder where TGA files will be written
- img####: naming files with numbering where #### means numbering file with 4 number format
- imgs/*.png: source folder where PNG images exist, that will be converted to TGAs

2.2. Prepare list of files you have to convert. If you have all of them in a single folder, it can be done quite easily by the following command:

find pwd/tmp -name *.tga > tmp/patches.txt

2.3. Now you are ready to run the MicroStitcher tool with the following command:

./MicroStitcher -patches=tmp/patches.txt -out=outImage.tga

There few additional very useful parameters that one may want to use especially cropping function which can be defined globally and every single patch will be cropped to the specified area like below:

./MicroStitcher -patches=tmp/patches.txt -crop="[60,9], [1430,820]" -out=outImage.tga

Where -crop has to be understood as the following definition -crop="[TOP-LEFT-CORNER-X-Y], [RIGHT-BOTTOM-CORNER-X-Y]". In case of map screenshots one can get rid of some additional control points which are not necessarily desired during stitching them into one big image.

Other options are a bit more advanced and should be used when the algorithm cannot stitch images from some reasons. For this purpose one can define minimum number of control points which has to be matched. The parameter is called -numCtrlPoints=NUMBER (by default the NUMBER is 8). Another parameter which might improve stitching images is -coefCtrlPoint, the parameter is a bit tricky because it describes contrast level of a single control point which is going to be used for searching an alternative control point in the other image. The higher value is the less source control points are created and the less chance become that the same control point will be found in the comparing image. Higher number may also means that performance will be far more better then for the lower values. On the other hand the lower value is the performance is worse and stitching is less reliable. One has to tune this parameter keeping in mind an appropriate balance. From my experience the reasonable values are in range [50, 150] by default 100 is used.

./MicroStitcher -patches=tmp/patches.txt -crop="[60,9], [1430,820]" -coefCtrlPoint=50 -numCtrlPoints=6 -out=outImage.tga

That's it. Good luck and have lots of time saved by using this tool instead of stitching images manually.