reamde.txt

Gaussian Mixture Algorithm

/***************************************************************************
 *   Copyright (C) 2008 by Cyril Poulet   *
 *   [e-mail]   *
 *
 * 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.
 *     * Redistribution under a license not approved by the Open Source
 *       Initiative (http://www.opensource.org) must display the
 *       following acknowledgement in all advertising material:
 *        This product includes software developed at the Courant
 *        Institute of Mathematical Sciences (http://cims.nyu.edu).
 *     * The names of the authors may not be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED ``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 AUTHORS 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.
 ***************************************************************************/

INSTALLATION

1. Libraries to install:

apt-get install libqt4-core
apt-get install libqt4-debug
apt-get install libqt4-dev
apt-get install libqt4-gui

You'll need libeblearn as well. To configure its path, edit libeblearn_gui.pro and set the following:
INCLUDEPATH += app \
	"path/to/the/lib's/include"
LIBS +=  -L"path/to/the/lib" -leblearn


2. Configuring your project:
	i) add the qt4 file to the include paths of your compiler (usually found in "/usr/include/qt4"), as well as qt4/QtGui 
and qt4/QtCore
	ii) add  "eblearn_gui" to the libraries of your linker
	iii) add " #include "libeblearn_gui.h" " to your main file
	
3. the GUI
	i) How it works
	Every GUI looks the same because it is based on the class ebbox. Basically it's a box with three buttons : the 
left one opens or closes the container under the box, the "print" prints according to the options you choosed, and 
the button with the title opens property dialog.
	If you use th Idx_Gui or the state_idx_Gui, the box under will contain the displayer widget. For more complex 
GUIs, it will contain the boxes of the basic elements of your object. 
	
	
	ii) creating GUIs: examples
	Creating the GUIs is very easy. it supports all kind of Idxs or state_Idxs apart from those with 0 dimension
	
idx_Gui :

	 Idx<type> *in = new Idx<type>(10, 28, 100);
	 Idx_Gui* test = new Idx_Gui((void*)in, TYPE, "my title");
	
@param type here can be double, float, intg or ubyte
@param TYPE is the corresponding item of the enum idx_type: DOUBLE, FLOAT, INTG or UBYTE


state_idx_Gui:

    state_idx *in = new state_idx(10, 28, 3);
	state_Idx_GUI* test = new state_Idx_GUI(in, "my title");
	
If you need then to set some display options (idx_Guis and state_idx_GUIs only), you can use the setvmin, 
setvmax and setvisible functions


For more complex objects, you'll have 2 possibilities. for example with a linear module :
	linear_module_GUI* test = new linear_module_GUI(module, in, out, "mytitle");     
creates a gui for a linear module with state_Idx_GUIs for in and out, plus some boxes for specific features of the 
module

	linear_module_GUI* test = new linear_module_GUI(module, "mytitle");
	test->add_box(new state_Idx_GUI(in, "in title"));
	test->add_box(new state_Idx_GUI(out, "out title"));
creates a gui for a linear module only with boxes for specific features of the module, then add the GUIs for in and 
out.

More generally, add_box(ebbox*) will allow you to make customized GUIs for complex modules. Example:
	ebbox* my_module = new ebbox(0, "my complex module");
	my_module->add_box(new state_Idx_GUI(in, "in));
	my_module->add_box(new linear_module_GUI(module, "linear module"));
	...
	
		iii) main structure
	The main structure must have the following structure :
	
	int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
	
	// Your code here
	
    return a.exec();
}

the QApplication::exec() function launches a infinite loop of event handling.
Nothing will be displayed before exec() is reached, and the application won't get out of the infinite loop before
the GUIs created are closed.
You can move the exec() up in the code of the main() (Be careful : it HAS to be in the main() ), but be aware that
the rest of your code below the exec() won't be reached before the GUIs are closed !
Still exec() can be used several time in the same main(). Therefore if you want to refresh the display without 
multithreading, one way would be :

	a.exec()
	
	somecomputations()  // won't be executed while the GUI is still open
	mygui->refreshdisplay();
	a.exec();
	
	...
	
When calling the exec the 2nd time, it has kept in memory what was displayed, so the GUI will reopen in the state
it was when you called it, only with a refreshed display.


	iiii) multi-thread use : examples
If you want to debug your application, multi-thread is probably not a good idea, and I would recommand the 
solution explained above, wich is to call exec() every time you need a GUI, then kill it to let the rest of the main 
go on.

If you want to release your application, then you'll have to put your computation (ie everything that is not related 
to the GUI) in a second thread and send signals to the GUI to refresh its display.
You should then use the following structures (as an example): 


class my_thread: public QThread
{
	Q_OBJECT
	
public:
	my_thread(Idx<ubyte>* idx, QMutex* mutex = NULL);
	~my_thread(){delete myidx; delete mymutex;};
	
	void run();

signals:
	void refreshdisplay();
	
private:
	Idx<ubyte>* myidx;
	QMutex* mymutex;
};

my_thread::my_thread(Idx<ubyte>* idx, QMutex* mutex):
	QThread(),
	myidx(idx),
	mymutex(mutex)
	{
		start();
	}



void my_thread::run()
{
	int i = 0;
	int j = 0;
	while(true){
		some_operation_on_idx_protected_with_mutex();
		emit refreshdisplay();
		i+=50;
		j+=50;
	}
}

int main(int argc, char *argv[])
{
	// this is the main structure you'll have to use when using the GUI
    QApplication a(argc, argv);
    
    QMutex* mymutex = new QMutex();
    
	Idx<ubyte> left(1, 1);
	CPPUNIT_ASSERT(load_matrix<ubyte>(left, "data/norb/plane_left.mat") == true);

	// creates the GUI using the mutex to protect it when calculating the images
	Idx_Gui* myIdx = new Idx_Gui((void*)&left, UBYTE, "test", 0, mymutex);
	myIdx->setvmin(0);
	myIdx->setvmax(255);

	// creates the computational thread
	my_thread* compute_thread = new my_thread(&left, mymutex);
	// connect the signal refreshdisplay() from your computational thread to the refreshdisplay() slot of your GUI
	QApplication::connect(compute_thread, SIGNAL(refreshdisplay()), myIdx, SLOT(refreshdisplay()));
	
    return a.exec();;
}

Don't forget to protect the access to the object display when you're modifying it in the computational
thread !!
Since the QThread uses the Q_OBJECT macro, you'll need qmake to compile your project.
Here is what your .pro should have at least:

DEPENDPATH += . \
    include \
    src \
    "$(HOME)/workspace/libeblearn/include" \
    "$(HOME)/workspace/libeblearn_gui/include"
INCLUDEPATH += . \
    include \
    "$(HOME)/workspace/libeblearn/include" \
    "$(HOME)/workspace/libeblearn_gui/include"
LIBS += -L"$(HOME)/workspace/libeblearn/Debug" \
    -leblearn \
    -L"$(HOME)/workspace/libeblearn_gui" \
    -leblearn_gui \
CONFIG += thread

You may also need to create a symbolic link to libeblearn_gui.so.1 :
	cd /usr/lib
	sudo ln -s /path/to/the/libeblearn_gui/directory/libeblearn_gui.so.1 libeblearn_gui.so.1