This release of the software is a beta release, meaning it is a release for testers, not those who just want it to work. Current known issues are summarised at the end of this file.

Usage Instructions
------------------
This application is used for taking photos of real world objects and creating an approximate computer model using a 'wizard' interface. It needs the Java Runtime Environment version 5 or above installed to run. This can be downloaded from:http://www.java.com/en/download/

The object to be modelled needs to be sitting on the same calibration sheet in all shots and not have been moved.

To get exact dimensions of the object the computer must be fed in information about the calibration sheet, specifically the size of the paper it was printed on and, less critically, any margins. It is assumed that the calibration sheet is scaled to fill the printable area on the paper it is printed out on and the user can choose the paper size and margins as well as whether or not the aspect ratio of the original calibration sheet was kept when it was so scaled. This information is entered into the program, along with linking to the jpg source file for the calibration sheet in the first step of the wizard. The user then just selects the photos to be processed and the output file to be produced in the second step and lets the computer do its work and save the output file. For more details, including various default settings, see the tutorial included under the docs folder (tutorial.pdf or tutorial.odf). This goes through an example using the included example calibration sheet and the images under the folder "test image sequence".

If the details for the dimensions of the calibration sheet are slightly wrong the program will still work but the computer generated object may look squashed or stretched. If the stated dimensions of the calibration sheet are too far out then one or more of the images may not be fully processed as the circles on the calibration sheet will not be identified properly.

An example calibration sheet is included in this release (example_calibration_sheet.jpg) but others can be made if that is not suitable.

A calibration sheet consists of a white background with multiple black circles (all the same size) placed in a semi-random pattern.

The pattern should be unique from as many angles as possible, preferrably when many of the circles are not visible in the image, as this is what the computer uses to figure out where the camera was when the image was taken. It is not known what the best calibration sheet is, but the worst would be a set of circles ordered in a circle as this will look the same from multiple directions.

The example calibration sheet has worked for all test images so far but it is designed to be used in such a way that at least 6 of the 9 circles be visible in all images which limits the size and shape of objects that can be processed to those that are small enough so that in all images no more than 3 of the circles are covered.

For more details, read the bundled documentation.

To run this program under Linux: double click the run.sh file.
To run this program under MacOS X: double click the run.command file.
To run this program under Windows: double click the run.bat file.

Once the program has been successfully run once it will store the settings used in a file called reprapscanning.properties in the subfolder .reprap in the users home folder.


Under Linux this folder will be: ~/.reprap or /home/<username>/.reprap

Under MaxOS X this folder will be: ~/.reprap or /Users/<username>/.reprap

Under Windows XP this folder will be: C:\Documents and Settings\<username>\.reprap

Under Windows Vista/7 this folder will be: C:\Users\<username>\.reprap

This file can be edited and settings changed if need be. Also the run file can also be edited to use a different preferences file if the user so desired. If this file does not exist the default settings are used and a new copy of this file is saved when the program successfully terminates. For a list of these settings and what they do, read the Software Technical Report in the bundled documentation.

The output file is an ASCII STL file. To view the object you will need software that can interpret this file format, for example the Reprap Host software (downloadable along with with software from http://sourceforge.net/projects/reprap/) or the ReplicatorG software (downloadable from http://replicat.org/download)

Current issues
--------------
* The image segmentation procedure doesn't deal well with shadows. I have a few ideas about this and will work on them.
* The calculation of lens distortion when it is high is currently commented out as it has not yet been tested.
* Currently the calculation for adjusting ellipse on the calibration sheet to the expected ellipse in the image, especially the new centre of the ellipse, is based on the currently estimated camera parameters is based on transforming sampled points around the circumference of the ellipse to estimate the center and using the transformed point furtherest from this as indicative of the major axis length and direction. This is slow and cumbersome, there should be a way of using the known geometry to calculate it quickly but when I tried it gave the wrong answer and was practically impossible to debug so it was supplanted in favour of the current method. This should be looked into again.
* The image of the absolute conic matrix calculated from the planar homography matrix is supposed to be symmetric positive definite by definition but this is not necessarily the case. In most cases recalculating the planar homography with less point pairs fixes this, leading to the conclusion that the homography was over-constrained, but is not always be the case and I don't know why. I have got a workaround in that a polar decomposition is performed and only the symmetric positive definite part is used but this may be indicative of a deeper problem.
* The test for whether a point is behind or in front of a camera is giving the inverse answer according my interpretation of the formula i.e. it indicate the point it is behind the camera when it is in front and vice-versa. I have inverted the answer and left it but this needs to be looked into to figure out if I am mis-understanding the formula or if there is a deeper issue.
* Currently the voxel based outline is the absolute maximal size of the object based on a siloutte outline against the calibration sheet. This should be able to be further refined with the use of recursive sub-voxel division and/or colour/feature/texture matching within this volume. Both of these need to be worked on.
* The output file is currently an ASCII stl file. This should be changed/added to so that the output can be saved as a binary STL file.

Reece Arnott 1st September 2010