Ferns Point Detection

----------------------------------------
Project Information
----------------------------------------
The goal of this project was to try and achieve as close to real time as possible
point detection.  We use it our lab for the purposes of object tracking,
positioning, and orientation.  The source code provided was written initially by the 
Computer Vision Lab, Ecole Polytechnique Federale de Lausanne (EPFL), Switzerland.

Significant code changes have been made to improve for our purpose this basic demo
code that was freely distributed.  Modifications that have been made include:

- Use of OpenMP for parallelizing training and other tasks resulting in   significant   improvement in execution times.
- Speed improvements by optimizing (or removing) un-needed loops.
- Removal of memory leaks.  
- Allowing the code to compile and run on Windows.  
- All of the compiler warnings and messages have been fixed.  

This demo also has been modified to display the model and tracking image in the   same frame as well as the matching points between the model and input image.

http://www.eecs.ucf.edu/~abehal/AssistiveRobotics/

----------------------------------------
Libraries and SDKs Used
----------------------------------------
Two outside code sources where used to help facilitate this
project.  One is an open source C++ command line API called
TCLAP (we used version 1.1.0), which is included with this
archive using their license (MIT).

The other one in use is OpenCV (Open Source Computer Vision).
We use version 1.0 of the library.  Please see their site on
SourceForge for downloads and installation.

----------------------------------------
Operating Systems
----------------------------------------
This code was written and tested to work in a Windows (XP/NT/2003)
environment.  However, there has been an effort to keep the original
code usable in a Linux operating environment. The system that we 
have used to test this has been Ubuntu (7.10/8.04).

----------------------------------------
Installation & Compilation
----------------------------------------

Windows:
--------
Extract the top level TCLAP files in the file tclap-1.1.0.zip to the
directory:
	C:\tclap
This should create the directory structure of:
	C:\tclap\config\
	C:\tclap\docs\
	C:\tclap\examples\
	C:\tclap\include\
	C:\tclap\msc\
	C:\tclap\tests\

Download and install OpenCV.  The instructions for installing it on Windows
can be found on their wiki page.  A direct link used at the time of the
writing is given below.

http://opencvlibrary.sourceforge.net/VisualC%2B%2B

Next you need to add the required paths to the Visual Studio environment
variables.  To do this open Visual Studio and go to Tools > Options...
Expand "Projects and Solutions" and click "VC++ Directories"

Add to "Include Files"
	C:\tclap\include

After completing these tasks there should be a Microsoft Visual Studio
project file that was included with this download.  Open that *.vcproj
file this should have all the required settings to allow for the application
to be successfully compiled.

Linux (Ubuntu):
---------------
Installing the necessary dependencies in Ubuntu should be fairly straight
forward.  Both the TCLAP library and OpenCV library are found in the Ubuntu
package manager (most likely any other major distribution will also have
these packages in there repositories).

First make sure that Universe repository is available for software sources.
Go to System > Administration > Software Sources.  Then on the first tab,
which should be labeled "Ubuntu Software" make sure there is a check box next
to "Community-maintained Open Source software (universe)".  Than reload the
repository by running at the terminal:

sudo apt-get update

If you have never compiled any source on this Ubuntu machine you will need to
install the gcc compiler and other basic tools for compiling on Linux.  To do
this in Ubuntu, open a terminal and type:

sudo apt-get install build-essential

To install the OpenCV dependencies for this project open a terminal and type:

sudo apt-get install libcv1 libcvaux1 libcvaux-dev libcv-dev libhighgui1 libhighgui-dev

After installing OpenCV the only other dependencies required for building this
project will be the TCLAP library.  To install TCLAP open a terminal and type:

sudo apt-get install libtclap-dev

After installing all of the dependencies listed above you now will have two
options for compiling this source code.  One is a make file that is included
with this source.  Open a terminal move into the directory where the source
is located and type:

make

This will build the ferns demo application with debug symbols and without OpenMP
enabled.  There are 4 different ways that the code can be compiled:

make TYPE=debug			# This is default
make TYPE=release		# Removes debugging symbols and optimizes
make TYPE=debug-openmp		# Same as default, now with OpenMP
make TYPE=release-openmp	# Same as release, now with OpenMP
make clean			# deletes everything that was created during make

The other option, is to use the Code::Blocks IDE for Linux to compile the code.
Installing Code::Blocks is beyond the scope of this README.  However, there are
tutorials on how to install the IDE.

http://www.linuxlifestyles.com/forum/index.php?topic=8.msg9#msg9

Included with this file is a .cpb file that is a Code::Blocks project file that
will enable you to compile this project.

----------------------------------------
Licenses and Disclaimers
----------------------------------------

Ferns UCF Disclaimers
---------------------
 
This code was written under the supervision of Dr. Aman Behal at the 
University of Central Florida Nanoscience Technology Center.
By using this code, you agree that this software is distributed as-is,
without warranty of any kind.

This code based on the work of the Computer Vision Lab, 
Ecole Polytechnique Federale de Lausanne (EPFL), Switzerland.  As such
is released using their Licensing Agreements.

IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, CONSEQUENTIAL OR ANY OTHER
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE
PROGRAM, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. YOU
HEREBY WAIVE ANY CLAIMS FOR DAMAGES OF ANY KIND AGAINST
CONTRIBUTORS WHICH MAY RESULT FROM YOUR USE OF THE PROGRAM.

Ferns Licensing
---------------

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Templatized C++ Command Line Parser Library (TCLAP)
---------------------------------------------------

The MIT License

Copyright (c) 2003 Michael E. Smoot

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

