Face Computation

Computes an "face space" used for face recognition.

*
* This idea/algorhitm was derieved from Matthew A. Turn and Alex P. Pentland
* paper, titled: "Face Recognition using Eigenfaces"
* (<a href="http://www.cs.ucsb.edu/~mturk/Papers/mturkCVPR91.pdf">http://www.cs.ucsb.edu/~mturk/Papers/mturk-CVPR91.pdf</a>)
*<br><br>
* The way this algorhitm works is by treating face recognition as a
* "two-dimensional recognition problem, taking advantage of the fact that
* faces are normally upright and thus may be described by a small set
* of 2-D characterisits views. Face images are projected onto a
* feature space ("face space") that best encodes the variation
* among known face images. The face space is defined by the
* "eigenfaces", which are the eigenvectors of the set of faces;
* they do not necessarily correspond to isolated features such as eyes,
* ears, and noses." (quoted from the paper's abstract)
*<br><br>
* This work is released to the public with no license and no warranties.
* Do with the code as you wish.
* <br><b>NOTE</b>: This package uses Jama for computing eigenvalues and
eigenvectors.
*
* Which is available at:
* <a
href="http://math.nist.gov/javanumerics/jama/">http://math.nist.gov/javanumerics/ja
ma/</a><br><br>
* And in case you are worreid about its copyright states:<br><br>
*
* This software is a cooperative product of The MathWorks and the National Institute
of Standards
* and Technology (NIST) which has been released to the public domain. Neither The
MathWorks nor NIST assumes any
* responsibility whatsoever for its use by other parties, and makes no guarantees,
expressed or implied, about its quality,
* reliability, or any other characteristic.
Face Creator
Creates the FaceBundle's from the list of images and tries to
* match against submitted image.
Our threshold for accepting the matched image. Anything above this
* number is considered as not found in any of the face-spaces.
*/
Our minimum distance observed for the submitted image in the
* face-spaces.
*This determines if caching of face-spaces should be activated.
* Anything above zero means yes. Anything else means no.
*/
Match against the given file.
*
* @return The Identifier of the image in the face-space. If image not
* found (based on THRESHOLD) null is returned.

*/
/**
* Construct the face-spaces from the given directory. There
* must be at least sixteen images in that directory and each image
* must have the same dimensions. The face-space bundles are also
* cached in that directory for speeding up further initialization.
*
* @param n The directory where the training images are located.
*
* @throws FileNotFoundException The <code>n</code> directory does not exist.
* @throws IOException Problems reading images from the given directory or saving
* the cache file (if caching is enabled)
* @throws IllegalArgumentException The arguments submitted are wrong.
* @throws ClassNotFoundException The cached objects are out-of-date or are
* not this version's face-space objects
*
*/
Read each set of 16 images.
/**
* Submit a set of sixteen images in the <code>dir</code> directory and
* construct a face-space object. This can be done either by reading the
* cached objects (if there are any) or computing the {@link FaceBundle}.
*
* @param dir Directory where the images reside
* @param files String array of the names of the files (ie: "image01.jpg")
* @throws FileNotFoundException The <code>dir</code> directory does not exist.
Or the <code>files</code> are nonexistent
* @throws IOException Problems reading images from the given directory or saving
* the cache file (if caching is enabled)
* @throws IllegalArgumentException The arguments submitted are wrong.
* @throws ClassNotFoundException The cached objects are out-of-date or are
* not this version's face-space objects
*
*/
Check to see if a FaceBundle cache has been saved.
/**
* Caches the face-space object in <code>f</code> file.
*
* @param f File where to save it
* @param bundle The face-space object.
* @throws FileNotFoundException The <code>f</code> is invalid.
* @throws IOException Problems reading the data.
*
*/
/**
* Read the cache object from file.
*
* @param f File where to read from.
* @throws ClassNotFoundException The cached objects are out-of-date or are
* not this version's face-space objects
* @throws FileNotFoundException The <code>f</code> is invalid.
* @throws IOException Problems reading the data.
*/
/**
* Construct the face-spaces from the given directory.

*
* @param dir The directory where to read from.
* @param id The names of the files which to read from.
* @throws FileNotFoundException The <code>dir</code> directory does not exist.
Or the <code>id[]</code> are nonexistent
* @throws IOException Problems reading images from the given directory
* @throws IllegalArgumentException The image files are either wrong format or
there is an image with the wrong dimensions.
*/

Face Bundle
/**
* The face-space bundle generated by {@link EigenFaceComputation}.
* This bundle has all the relevant information to try to match an image
* The computation to be done (to find the submitted image in this
* bundles' face-space) is quite fast.
* For more about the algorithm, consult (<a
href="http://www.cs.ucsb.edu/~mturk/Papers/mturkCVPR91.pdf">http://www.cs.ucsb.edu/~mturk/Papers/mturk-CVPR91.pdf</a>)
*
* Each FaceBundle contains
* sixteen images and their identifying string.
* <br><b>NOTE</b>: This object is serializable, therefere its possible
* to cache these face-spaces thus eliminating the computation process
* in {@link EigenFaceComputation}.
*
/**
* The length of the vector-images stored in the face-space bundle. The
* submitted image <b>MUST</b> of the same length or greater (if its greater
* only <code>length</code> will be considered).
*/
/**
* The face-space object containing:
*
* <ol>
* <li>An average face array.
* <li>Eigenspace of images
* <li>Face space of images
* <li>List of names identifying each image
* </ol>
*
* @param avgF Average face (used to normalize the image to be matched against)
* @param wk The eigenface componenets (projected onto the eigenspace)
* @param eigV The eigenspace (onto which the matched image will be projected
too)
* @param id A String array representing each of the sixteen images represented
* by this face-space.
*
*/
/**
* Submit an image of matching against the face-space.
* The results are published in <code>distance()</b> and <code>getID()</code>.
*

* @param face The vector-array of the image. The image must be off
<b>length</b>
*
*/
/**
* Submit an image of matching against the face-space.
* The results are published in <code>distance()</b> and <code>getID()</code>.
*
* @param face The vector-array of the image. The image must be off
<b>length</b>
*
*/
/**
* Submit an image of matching against the face-space.
* The results are published in <code>distance()</b> and <code>getID()</code>.
*
* @param face The vector-array of the image. The image must be off
<b>length</b>
*
*/
/**
* Clear the submitted image from the face-space object.
*/
/**
* The distance of how far away the submitted image is in this
* face-space object. Consult <code>getID()</code> for the name
* of the image that it was most near too.
*
* @return >= 0 or if no image has been submitted:
<code>Double.MAX_VALUE</code>
*/
/**
* The ID of the submitted image in this face-space object.
*
* @return A string, but if no image has been submitted a
ArrayOutOfBoundException
*
* @throws ArrayOutOfBoundException if there has been no image submitted.
*/
/**
* All the names of the images in this face-space.
*
* @return getNames().length == 16
*/
/**
* Compare this face-space bundle to another. If this bundle has
* a smaller distance than the other, -1 is returned. 1 if its opposite.
* <b>NOTE</b>: There is no checking if the other face-space bundle
* has computed its values for the same image.
*/
/**
* Get a string representation.
*/
/**
* Do the computation..

*
*/
/*
* Find the minimun distance from the input_wk as compared to wk
*/
/*
* Normalize our minimum distance.
*/
/**
* Divide each element in <code>v</code> by <code>b</code>
* No checking for division by zero.
*
* @param v vector containing numbers.
* @param b scalar used to divied each element in the v vector
*
* @return a vector having each element divided by <code>b</code> scalar.
*
*/
/**
* The sum of the vector.
*
* @param a vector with numbers
* @return a scalar with the sum of each element in the <code>a</code> vector
*/
/**
* The max of the vector a.
*
* @param a the vector
*
* @return the sum of all the elements on <code>a</code>
*/

Image Canvas
/**
* Canvas used to display any type of image. As long as its submitted
* in byte[], int[] or double[] format with the appropiate
* width and height. Also the image is converted into grayscale.
*
*/
/**
* Image displayed from the given array.
*
* @param bytes the byte array with the each element being an 8bit RGB
* tuple
* @param width The width of the iamge
* @param height The height of the image
*/
/**

* Image displayed from the given array.

*
* @param doubles the double array with the each element being an 64bit RGB
* tuple. The alpha color is reset to FF and only the 24bits (from left to
* right of each element are displayed).
*
* @param width The width of the iamge
* @param height The height of the image
*/
/**
* Image displayed from the given array.
*
* @param int the int array with the each element being an 32bit RGB
* tuple. No conversion done.
*
* @param width The width of the iamge
* @param height The height of the image
*/
/**
* Paint on our given object the given image.
*
*/
File Viewer
/**
* JPG/PPM file viewer.
*
* Uses ImageCanvas to displayed the custom xxxFile implementations.
*
*/

JPG File
/**
* JPG File reader/writer. Uses native com.sun libraries (which
* may deprecate at any time)
*
*/
/**
* Read the PPM File.
*
* @throws FileNotFoundException if the directory/image specified is wrong
* @throws IOException if there are problems reading the file.
*/
/**
* Get the height of the PPM image.
*
* @return the height of the image.
*/
/**
* Get the width of the PPM image.
*

* @return the width of the image.

*/
/**
* Get the data as byte array. Data is of any type that
* has been read from the file (usually 8bit RGB)
*
* @return The data of the image.
*/
/**
* Get the data as double array. Data is of any type that
* has been read from the file (usually 8bit RGB put into an 64bit double)
*
* @return The data of the image.
*/
/**
* Write to <code>fn</code> file the <code>data</code> using the
* <code>width, height</code> variables. Data is assumed to be 8bit RGB.
*
* @throws FileNotFoundException if the directory/image specified is wrong
* @throws IOException if there are problems reading the file.
*/
/**
* Read the image from the specified file.
*
* @throws FileNotFoundException pretty obvious
* @throws IOException filesystem related problems
*/

xxxFile
/**
* Get the height of the PPM image.
*
* @return the height of the image.
*/
public int getHeight();
/**
* Get the width of the PPM image.
*
* @return the width of the image.
*/
public int getWidth();
/**
* Get the data as byte array. Data is of any type that
* has been read from the file (usually 8bit RGB)
*
* @return The data of the image.
*/
public byte[] getBytes();
/**

* Get the data as double array. Data is of any type that

* has been read from the file (usually 8bit RGB put into an 64bit double)
*
* @return The data of the image.
*/