yash101/AI

Welcome to my OpenCV Template! As soon as you open the main.cpp file, you may realise
that there are just a ton of comments! Well, I wrote this template to accelerate the
learning process for OpenCV for the students I am teaching. It is extremely annoying
to debug lag problems. Many times, lag is caused because you are downloading the
frames slower than new frames are available. Many times, you can fix this through a
trial-and-error method, where you reduce the maximum frame rate of the camera. However,
this process if extremely unreliable. If you get a lag spike in the middle of a match,
your program will get stuck in the lag loop. You can have some leeway, but that
reduces the maximum frame rate of your program! Instead, I have come up with a
solution in which I have two threads, one thread downloading the images and one for
actually processing the images! This is how the grabber thread works. Basically, the
thread waits for a new frame to be available and immediately downloads it. It discards
the old one. It then saves it in a Matrix, available to every thread! When the
processing loop is done processing the old image, the processing thread copies the
image we saved before and processes it. It continues indefinitely, until the function
exit() is called, terminating all threads and shutting down the program. Here's a
visualisation of the process that goes on and on:

THREAD 1 [GRABBER]				THREAD 2 [PROCESSING]
------------------                              ---------------------
1. Download the image in a temporary		1. Wait for an image to be available
	matrix					2. Download the image
2. Validate the image				3. Make a local copy to make the
3. Lock the destination matrix				matrix available elsewhere
4. Overwrite destination matrix with		4. Validate the local copy
	new data				5. Process the local copy
5. Perform again				6. Perform again

The image is stored in the destination image while in transit between the two threads.

Now, you may wonder, why use this template? This is a template to make rapid
prototyping possible. You just need to set up the compiler and copy over the template
and write your code. You don't need to initialise the camera or do anything like that.
This template also creates a directory structure, sorted by project name. There are
locations to save with            4. Validate the local copy
        new data                                5. Process the local copy
5. Perform again                                6. Perform again

The image is stored in the destination image while in transit between the two threads.

Now, you may wonder, why use this template? This is a template to make rapid            
prototyping possible. You just need to set up the compiler and copy over the classes!
There are spaces designated to place things, like your functions and especially your
main code! All you need to do is place your processing code, and it will run forever,
until you exit the program! Another pro of using this template is that it supports
libfreenect, and thus, you can access RGB, infrared and depth maps easily! Also, this
runs off the implementation, developed by my OpenCV and libfreenect installer!

Where do I type up my code?
Your main code goes after "TODO: CODE HERE". There are a bunch of blank lines too.
If you want an action to be performed before the program launches your code, there
is the function, int main()! That is called the bootloader in this template because
it initiates all the important functions of the program and gets it running stabily!
To add something in the program boot process, just place the code within the bootloader
in the order that you want it to execute in! Don't worry! It's executed linear! You
can add functions to functionstoolkit.h and they will be available through composition
under kit.[function]! It is perfect for cleaning up your program up a bit!

How do I set up a new program?
Here's how you do it! Open QT Creator! Create a new application, a QT Console
Application! Name your project and create it like a regular project. Then, close
the project. Open up the project folder and delete main.cpp. Replace it with main.cpp
from this template. Also, copy in the functionstoolkit.h header! Reopen the project.
If it can't find main.cpp, tell it to ignore the problem and remove main.cpp from
the build path. Now, right click on the project in the project explorer and click
on the button, "Add existing files...". Select main.cpp and functionstoolkit.h.
QT Creator will then generate all the makefiles for you and get most of the things
set up. However, you will notice that you get a bunch of compile errors if you
try to build the application. That is because you haven't told the compiler where
the libraries, OpenCV and libfreenect_sync are! We shall fix that next! Thankfully,
OpenCV installs with pkg-config, a utility that generates all the build flags for
us, making it easy to import the libraries! In the project explorer, you will notice
that there is a file, with the .pro file extension! That is the main project folder!
Thankfully, you are in Linux, so getting the compiler set up is a piece of cake!
Navigate to the end of the file, and append, at the end of the file:

LIBS += `pkg-config --libs opencv libfreenect`
LIBS += -lfreenect_sync

Remember, those are BACKQUOTES surrounding pkg-config and you should NEVER ignore
them! When you compile the program, the compiler will run pkg-config. It will
return a bunch of flags, telling the compiler what binaries are available and
where to find them! You can try this yourself! In the terminal, type:

pkg-config --libs opencv
pkg-config --libs libfreenect

Sadly, libfreenect_sync isn't outputted by pkg-config, so we need to import the
library manually. That is why we had to type

LIBS += -lfreenect_sync

Didn't you see how the pkg-config commands return a similar output? That is
because pkg-config just looks up the libraries in a database and gets these
flags automatically.

Say you want to compile a C++ code file, just a single .cpp file with no headers
or other code files. You could actually use pkg-config to do the dirty-work for
you! For example, we will compile main.cpp with libopencv-dev:

main.cpp:
#include <opencv2/highgui/highgui.hpp>
using namespace cv;
int main() {
	CvCapture *cam1 = cvCaptureFromCAM(0);
	while(true) {
		if(cam1) {
			Mat x = cvQueryFrame(cam1);
			imshow("WINDOW", x);
			waitKey(1);
		}
	}
}

To compile:
g++ main.cpp `pkg-config --cflags --libs opencv`

That will compile the code for you and you will be happy!

Now, let's get started with that program!

If you haven't already installed OpenCV under Ubuntu, I have written an
installation script, available at:

https://gist.githubusercontent.com/yash101/10190427/raw/install.sh

To install under Ubuntu/Linux, run the following:

wget https://gist.githubusercontent.com/yash101/10190427/raw/install.sh
chmod +x install.sh
./install.sh

That will download another script and ask for your SUDO password to
authenticate, to run the installation scripts! Afterwards, the
script will clone my GitHub repositories so you have a copy of my
code to learn from. You can either learn from the code, or you may
delete the folder! Have fun!