/*////////////////////////////////////////////////////////////////////////////////////////////////////////
 // Copyright (c) 2002 by Jianxiong Dong
 //
 //  Name
 //
 //   SVMTrain.h -- interface for HeroSVM dynamic link library (DLL)
 //
 //  Exported Functions:
 //
 //   SvmInit   -- set the training parameters and allocate the memory dynamically
 //   SvmTrain  -- Train support vector machine 
 //   SvmSaveSummary -- Save some useful training information into a file 
 //                     after training is finished
 //   SvmSaveResult  -- Save training results into a file
 //   SvmClean       -- Free dynamically allocated memory
 //
 //  Author
 //
 //   Jianxiong Dong ( jdong@cenparmi.concordia.ca )
 //   Homepage: http://www.cenparmi.concordia.ca/~people/jdong
 //
 //  COPYRIGHT INFORMATION:
 //
 //    This software can be used for research over the world and is free
 //    of charge. Anybody who likes to use it for a commercial purpose 
 //    should get the permission of the author. Note that distributing this
 //    software bundled in with any product is considered to be a 
 //    comercial purpose. 
 //
 //    THE SOFTWARE IS PROVIDED ``AS-IS" AND WITHOUT WARRANTY OF ANY
 //    KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION,
 //    ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
 //    PURPOSE
 //
 //    IN NO EVENT SHALL THE AUTHOR LIABLE FOR ANY SPECIAL, INCIDENTAL, 
 //    INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES 
 //    WHATSOEVER RESULTING FROM LOSS OR USE, DATA OR PROFITS, WHETHER 
 //    OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
 //    LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
 //    THIS SOFTWARE
 //	
 //  Reference:
 //
 //    Jian-xiong Dong, Adam Krzyzak and Ching Y. Suen, A fast SVM training algorithm. 
 //    International workshop on Pattern Recognition with Support Vector Machines.  
 //    S.-W. Lee and A. Verri (Eds.): Springer Lecture Notes in Computer Science  LNCS 2388, 
 //    pp. 53-67, Niagara Falls, Canada, August 10,  2002. 
 //
 ////////////////////////////////////////////////////////////////////////////////////////////////////////
 */

#ifndef __SVMTrain_H
#define __SVMTrain_H

#ifndef WINAPI
#define WINAPI __stdcall
#endif 

#ifndef DllExport
#define DllExport   __declspec( dllexport) 
#endif 

/* prototype for kernel function */
typedef float (*KernelFunc)(float* vector1, float* vector2, int dim);

extern "C" {


/*//////////////////////////////////////////////////////////////////////////////
//		SvmInit
// 
//  Synopsis: 
//     This function sets the SVM training parameters and allocate the memory
//     
//  Paramters:
//    
//   nDim [in]              --- Dimension of the input feature vector
//   nWorkingSetSize [in]   --- Size of working set  
//   nTrainingSetSize [in]  --- Number of training samples
//   kernel_Para1 [in]      --- Parameters of non user-specified kernel
//   kernel_Para2 [in]      --- Parameters of non user-specified kernel
//   kernel_Para3 [in]      --- Parameters of non user-specified kernel
//   nKernelType  [in]      --- Kernel type
//   C            [in]      --- Upper bound of alpha in SVM
//   UserKer      [in]      --- User-specified kernel function pointer when the value of 
//                              nKernelType is 4;
//   nApplicationType [in]  --- Application type (console or window program ) for the output of 
//                              error message
//  Return:
//   
//   If succeed, return 0; otherwise -1
//
//  Note that user can use its own kernel function by specifying the value of 
//  nKernelType (4) and passing kernel function pointer; or use some classical 
//  positive kernels: RBF, Polynomial, Linear.
//
///////////////////////////////////////////////////////////////////////////////////
*/

/*
Let a = kernel_Para1, b = kernel_Para2, c = kernel_Para3, 

RBF         : exp(-||x1-x2||^2/(2*c))
Polynomial  : (x1 * x2 + b)/c)^a
Linear      : ( x1 * x2 + b)/c

where x1 and x2 are vectors in R^nDim.

nKernelType:
  1:  RBF kernel (radial basis function) 
  2:  Polynomial kernel
  3:  Linear kernel
  4:  User-specified kernel

nApplicationType:

  0: console application
  1: window application

*/

	DllExport int WINAPI SvmInit(int nDim, int nWorkingSetSize, int nTrainingSetSize,
			      float kernel_Para1, float kernel_Para2, float kernel_Para3, 
			      unsigned short int nKernelType, float C, KernelFunc UserKer,
				  int nApplcationType);



/*///////////////////////////////////////////////////////////////////////////////////////
//
//	 SvmTrain
//
//  Synopsis:
//    Train support vector machine
//	 	
//  Paramters:
//
//   szDataFilePathName [in]       --- a pointer to data filename
//   szTargetFilePathName [in]     --- a pointer to target data filename. The target value is 
//                                     1.0 or -1.0
//  Return:
//   If succeed, return 0; otherwise -1
//
/////////////////////////////////////////////////////////////////////////////////////////
*/

/*
	data structure of file szDataFilePathName: input feature vectors are sequentially stored 

	input vector 1
	input vector 2
	...
	input vector n


    data structure of file szTargetFilePathName: the correspoinding target value of the input 
	     feature vectors in the above file szDataFilePathName are sequentially stored

        target value of input vector 1 
	target value of input vector 2
	...
	target value of input vector n
*/

	DllExport int WINAPI SvmTrain(char* szDataFilePathName, char* szTargetFilePathName);




/*/////////////////////////////////////////////////////////////////////////////////////////
//   
//   SvmSaveSummary
//
// Synopsis:
//
//	Save some useful training information into a file after training is finished
//
// Parameters:
//	
//  szSummaryFilePathName [in] -- a pointer to summary filename
//  nClass                [in] -- identity number of each class
//
// Returns:
//  
//  If succeed, return 0; otherwise -1 
//
//
// Note that : see the userguide to know the detailed output information
//
///////////////////////////////////////////////////////////////////////////////////////////
*/

	DllExport int WINAPI SvmSaveSummary(char* szSummaryFilePathName, int nClass);


/*//////////////////////////////////////////////////////////////////////////////////////////
//	
//	SvmSaveResult
//
//  Synopsis:
//	
//   Save training results into a file
//
//  Paramters:
//		
//  szSvFilePathName -- a pointer to data file where support vectors, training and optimized
//                      parameters are stored
//                      
//  szSvIndexFilePathName -- index file for the support vector 
//	
//  Returns:
//
//   If succeed, return 0; otherwise -1
//
//
//  Note that: see the user-guilde to know the detailed information
//
///////////////////////////////////////////////////////////////////////////////////////////
*/

	DllExport int WINAPI SvmSaveResult(char* szSvFilePathName, char* szSvIndexFilePathName);



/*///////////////////////////////////////////////////////////////////////////////////////////
//	
//	SvmClean
//
//  Synopsis:
//   
//   Free dynamically allocated memory
//	
//  Paramters:
//   
//   NONE
//
//
//  Returns:
//
//	 NONE
//
/////////////////////////////////////////////////////////////////////////////////////////////
*/
	DllExport void WINAPI SvmClean( ); 
};

#endif /* __SVMTrain_H */