File	Date	Author	Commit
OpenCVTest.vcxproj	2013-07-31	Liam D Gray	[a46420] Initial commit
README.txt	2013-07-31	Liam D Gray	[f667ba] Added REAME, PDF image of a pointer that works ...
Rounded pointer.pdf	2013-07-31	Liam D Gray	[f667ba] Added REAME, PDF image of a pointer that works ...
TrackX.cpp	2013-07-31	Liam D Gray	[a46420] Initial commit
TrackX.exe	2013-07-31	Liam D Gray	[a46420] Initial commit
lkdemo.cpp	2013-07-31	Liam D Gray	[a46420] Initial commit
sample.csv	2013-07-31	Liam D Gray	[f667ba] Added REAME, PDF image of a pointer that works ...
stdafx.cpp	2013-07-31	Liam D Gray	[a46420] Initial commit
stdafx.h	2013-07-31	Liam D Gray	[a46420] Initial commit
targetver.h	2013-07-31	Liam D Gray	[a46420] Initial commit

Read Me

TrackXY:

 Track horizontal and vertical displacement of an object (ideally a rounded pointer) against a uniform field of contrasting color.


Output a CSV (comma-separated value) file with columns as follows:

sample number, time (from first sample) in milliseconds, x coordinate in pixels, y coordinate in pixels, number of clicks

See sample.csv for a sample output in CSV format.


USAGE:



For Windows, download the archive (for version 0.7 it is "windows-0.7.zip"), extract it to a location of your choosing, and double-click the .exe file(currently trackx.exe) to start TrackXY.

After starting TrackXY, a console window will open. Enter camera number (typically 0 for built-in camera  or 1 for an external camera) and press Enter. Enter a filename and press Enter. A video display window will open, showing the webcam's view.  Click the mouse in the video display window to start recording. If applicable, click again to mark each new segment with a counter that increments in the column "number of clicks."

TrackXY works with a scene in which the tracked object is singular and stands out clearly from the background. A black & white image, with black pointer on white background, or vice versa, works very well.   TrackXY has been tuned to work best when tracking a rounded pointer such as Google uses to mark a point in Google Maps.  (The included "Rounded pointer.pdf" works well when affixed to the moving object and the  camera is close to it.)  The essential thing is that, in the image, one point should be more singular than the others.  Two additional points serve as "chaperones," points of reference to help keep track of the main point.  The chaperone points tend to drift along the curved boundary between black and white, but this is okay because only one point is being logged, the one tracking the singular feature.



LICENSE (brief summary):


TrackXY is released under BSD license, as is the OpenCV library and Lukas-Kanade demo (lkdemo.cpp) on which TrackXY is based.  See below for full license terms.



INSTALLATION


The current code is known to compile in Microsoft Visual Studio C++ 2010 and a project file for that compiler is included.  The program has run and worked well under Windows 7.

The code has been linked against OpenCV 2.4.2 and requires its DLLs for 32-bit Windows.  The Windows version also requires the Visual C++ 2010 "Redistributable Package."  These are copyright Intel and Microsoft respectively and bound by their respective terms.  They can be downloaded from the following locations:



OpenCV-2.4.2.exe (OpenCV 2.4.2 compiled for Windows):

http://sourceforge.net/projects/opencvlibrary/files/opencv-win/2.4.2/OpenCV-2.4.2.exe/download



(The easiest way to install the OpenCV libraries for TrackXY is to run the OpenCV .exe file to extract the self-extracting archive to <folder> and then copy the files from <folder>\build\x86\VC10\bin to the folder in which TrackX.exe resides.)



Microsoft Visual C++ 2010 Redistributable Package for x86 (32-bit Windows -- tested with TrackXY):


http://www.microsoft.com/en-us/download/details.aspx?id=5555



Microsoft Visual C++ 2010 Redistributable Package for x64 (most 64-bit Windows installations):


http://www.microsoft.com/en-us/download/details.aspx?id=14632



Microsoft Visual C++ 2010 Redistributable Package for IA64 (Windows for 64-bit Itanium):


http://www.microsoft.com/en-us/download/details.aspx?id=2054


PORTING



TrackXY was originally compiled with Xcode on Mac OS X Leopard and ran there.  The latest version has not been compiled on Mac OS and some Windows-specific APIs are being used. I intend to make it more portable in the future.

ROAD MAP



I'd like to make it more user-friendly as well.

I welcome feature requests, suggestions, and feedback, and, of course, please feel free to check out, enhance, and submit code back into the project repository at SourceForge:  http://sourceforge.net/projects/trackxy

Solution designed by Liam Gray <liamdgray@gmail.com> for Bill Murphy with input from Simon Tang.

DONATIONS



If you can, please make a donation to my PayPal account, liamdgray@gmail.com , to support further development of TrackXY and other open-source developments.

Please also consider making a donation to, and/or joining, the Society for Scientific Exploration (SSE) at http://www.scientificexploration.org/join/ [The SSE bears no responsibility for TrackXY. But I developed TrackXY to facilitate replications of an experiment presented at the 2012 meeting of the SSE.]



LICENSE (detail):



IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING. 

By downloading, copying, installing or using the software you agree to this license.
If you do not agree to this license, do not download, install,
copy or use the software.



TrackXY Copyright (C) 2012, Liam D. Gray

OpenCV Copyright (C) 2000-2006, Intel Corporation, all rights reserved.

Third party copyrights are property of their respective owners. 

All rights reserved.



Redistribution and use in source and binary forms, with or without modification, are permitted  provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.



Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.



THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 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 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


Liam D. Gray
San Diego, California
liamdgray@gmail.com
Skype ID: liamdgray