nnshaperecognizer.h

An open source handwriting recongnition package!!!

         *		- Skip if the trace group is empty
         *		- Pre process the trace group read from the ink file
         *		- Extract features
         *
         *	- Push all the ShapeSamples corresponding to a shape into a vector of ShapeSample ShapeSamplesVec.
         *
         *	- When all the ShapeSamples corresponding to a Shape have been collected, cluster them using NNShapeRecognizer::performClustering
         *
         *	- performClustering results in vector of clustered ShapeSamples.
         *
         *	- Append these clustered vector<ShapeSample> to the mdt file.
         *
         *
         * @param listFilePath : string : Holds the path for train list file
         * @param trainSet : ShapeSampleVector: Holds the ShapeSample for all shapes, used for LVQ only
         *
         * @return none
         *
         * @exception LTKErrorList::EFILE_OPEN_ERROR		: Error in Opening a file (may be mdt file or list file)
         * @exception LTKErrorList::EINVALID_NUM_OF_SHAPES : Invalid value for number of shapes
         * @exception LTKErrorList::EINVALID_ORDER_LISTFILE: Invalid order of shapeId in List file
         * @exception LTKErrorList::EINITSHAPE_NONZERO		: Initial shapeId must not be zero
         */
        int trainFromListFile(const string& listFilePath, vector<LTKShapeSample>* trainSet=NULL);

        /**
         * This method will get the ShapeSample by giving the ink file path as input
         *
         * Semantics
         *
         *	- Call the LTKShapeRecoUtil::readInkFromFile() method (Utility Method) to read the ink file
         *	   By reading this file, an inTraceGroup was generated
         *
         *	- Preprocess the inTraceGroup and get the preprocessed trace group
         *	   LTKTraceGroup preprocessedTraceGroup
         *
         *	- Extract features from the preprocessed trace group to get the ShapeSamples.
         *
         *
         * @param path		: string : The path for Ink file
         * @param ShapeSample : ShapeSample : The ShapeSample generated after feature extraction
         *
         * @return SUCCESS : If the ShapeSample was got successfully
         * @return FAILURE : Empty traces group detected for current shape
         *
         * @exception LTKErrorList::EINKFILE_EMPTY			: Ink file is empty
         * @exception LTKErrorList::EINK_FILE_OPEN			: Unable to open unipen ink file
         * @exception LTKErrorList::EINKFILE_CORRUPTED		: Incorrect or corrupted unipen ink file.
         * @exception LTKErrorList::EEMPTY_TRACE			: Number of points in the trace is zero
         * @exception LTKErrorList::EEMPTY_TRACE_GROUP		: Number of traces in the trace group is zero
         */
        int getShapeFeatureFromInkFile(const string& inkFilePath, 
                vector<LTKShapeFeaturePtr>& shapeFeatureVec);

        /**
         * This method will do Custering for the given ShapeSamples
         *
         * Semantics
         *
         *	- If the NNShapeRecognizer::m_prototypeReductionFactor is -1 means Automatic clustering could be done
         *
         *	- If the NNShapeRecognizer::m_prototypeReductionFactor is 0 means No clustering was needed
         *
         *	- Otherwise clustering is needed based on the value of NNShapeRecognizer::m_prototypeReductionFactor
         *
         *	- Calculate Median if NNShapeRecognizer::m_prototypeReductionFactor is not equal to zero
         *
         *
         * @param ShapeSamplesVec : ShapeSampleVector : Holds all the ShapeSample for a single class
         * @param resultVector		: ShapeSampleVector : Holds all the ShapeSample after clustering
         * @param sampleCount	: int				 : Holds the number of shapes for a sample
         *
         * @return none
         * @exception none
         */
        int performClustering(const vector<LTKShapeSample> & shapeSamplesVec, 
                vector<LTKShapeSample>& outClusteredShapeSampleVec);

        /**
         * This method will Update the Header information for the MDT file
         *
         * Semantics
         *
         *	- Copy the version number to a string
         *
         *	- Update the version info and algoName to NNShapeRecognizer::m_headerInfo, which specifies the
         *	   header information for MDT file
         *
         *
         * @param none
         *
         * @return none

         * @exception none
         */
        void updateHeaderWithAlgoInfo();

        int preprocess (const LTKTraceGroup& inTraceGroup, LTKTraceGroup& outPreprocessedTraceGroup);

        /**
         * This method will writes training results to the mdt file
         *
         * Semantics
         *
         *	- If the feature representation was float then
         *		- Iterate through the shape model
         *		- Write the feature Dimension
         *		- Write the feature vector size
         *		- Write all the feature vector
         *		- Write the class ID
         *
         *	- If the feature representation was custom then
         *		- Iterate through the shape model
         *		- Write the feature Size
         *		- Call the writeFeatureVector() to write all the feature vector
         *		- Write the class ID
         *
         *
         * @param resultVector 		: ShapeSampleVector : A vector of ShapeSamples created as a result of training
         *		 mdtFileHandle 	: ofstream	       : Specifies the outut stream
         *
         * @return none
         *
         * @exception none
         */

        int appendPrototypesToMDTFile(const vector<LTKShapeSample>& prototypeVec, ofstream & mdtFileHandle);

        static bool sortDist(const NeighborInfo& x, const NeighborInfo& y);

        static int getDistance(const LTKShapeFeaturePtr& f1,const LTKShapeFeaturePtr& f2, float& distance);

        int getShapeSampleFromString(const string& inString, LTKShapeSample& outShapeSample);

        int mapFeatureExtractor();

        int deleteFeatureExtractorInstance();
        /**
         * This method extracts shape features from given TraceGroup
         *
         * Semantics
         *
         *	- PreProcess tracegroup
         *	- Extract Features
         *
         * @param inTraceGroup	: LTKTraceGroup : Holds TraceGroup of sample
         *
         * @return SUCCESS:  if shapeFeatures is populated successfully
         *         FAILURE:  return ErrorCode
         * @exception none
         */

        int extractFeatVecFromTraceGroup(const LTKTraceGroup& traceGroup, 
                vector<LTKShapeFeaturePtr>& featureVec);

        /**
         * This method create MDTFile
         *
         * Semantics
         *
         *
         * @param None
         *
         * @return None
         *
         * @exception none
         */
        int writePrototypeSetToMDTFile();

        /**
         * This method adds Sample To Prototype
         *
         * Semantics
         *
         *	- Add data in ascending order to ShapeID
         *	-
         *
         * @param shapeSampleFeatures	: LTKShapeSample : Holds features of sample to be added to PrototypeSet
         *
         * @return SUCCESS:  if shapeSampleFeatures is populated successfully
         *         FAILURE:  return ErrorCode
         * @exception none
         */
        int insertSampleToPrototypeSet(const LTKShapeSample &shapeSampleFeatures);

        /**
         * This method computes the confidences of test sample belonging to various classes
         *
         * Semantics
         *
         *	- Compute the confidence based on the values of m_nearestNeighbors and m_adaptiveKNN
         *	- Populate the resultVector
         *	- Sort the resultVector
         *	-
         *
         * @param distIndexPairVector : vector<struct NeighborInfo>: Holds the samples, classIDs and distances to the test sample
         * @param resultVector	: vector<LTKShapeRecoResult> : Holds the classIDs and the respective confidences
         *
         * @return SUCCESS: resultVector populated
         *         FAILURE: return ErrorCode
         * @exception none
         */

        int computeConfidence();

        /**
         * The comparison function object of STL's sort() method, overloaded for class LTKShapeRecoResult, used to sort the vector of LTKShapeRecoResult based on the member variable confidence
         *
         * Semantics
         *
         *	- Check if the first object's confidence value is greater than the second object's confidence value
         *	- Return true or false
         *	-
         *
         * @param x : LTKShapeRecoResult : First object for comparison
         * @param y : LTKShapeRecoResult : Second object for comparison
         *
         * @return true: If x.confidence > y.confidence
         *         false: If x.confidence <= y.confidence
         * @exception none
         */
        static bool sortResultByConfidence(const LTKShapeRecoResult& x, const LTKShapeRecoResult& y);

        /**
         * The comparison function object of STL's max_element() method, overloaded for the map<int, int>, used to retrieve the maximum of the value field (second element) of map
         *
         * Semantics
         *
         *	- Check if the first object's second value is greater than the second object's second value
         *	- Return true or false
         *	-
         *
         * @param lhs : map<int, int>::value_type : First object for comparison
         * @param rhs : map<int, int>::value_type : Second object for comparison
         *
         * @return true: If lhs.second > rhs.second
         *         false: If lhs.second <= rhs.second
         * @exception none
         */

        static bool compareMap( const map<int, int>::value_type& lhs, const map<int, int>::value_type& rhs );

        /** This method is used to initialize the PreProcessor
         *
         * Semantics
         *
         * 	- Load the preprocessor DLL using LTKLoadDLL().
         *
         * 	- Get the proc address for creating and deleting the preprocessor instance.
         *
         * 	- Create preprocessor instance.
         *
         * 	- Start the logging for the preprocessor module.
         *	
         * @param  preprocDLLPath : string : Holds the Path of the Preprocessor DLL, 
         * @param  errorStatus    : int    : Holds SUCCESS or Error Values, if occurs
         * @return preprocessor instance
         *
         * @exception	ELOAD_PREPROC_DLL			Could not load preprocessor DLL
         * @exception	EDLL_FUNC_ADDRESS_CREATE	Could not map createPreprocInst
         * @exception	EDLL_FUNC_ADDRESS_DELETE	Could not map destroyPreprocInst
         */
        int initializePreprocessor(const LTKControlInfo& controlInfo,
                LTKPreprocessorInterface** preprocInstance);


        /** This method is used to deletes the PreProcessor instance
         *
         * Semantics
         *
         * 	- Call deleteLTKPreprocInst from the preproc.dll.
         *
         * 	- Unload the preprocessor DLL.
         *
         * @param  ptrPreprocInstance : Holds the pointer to the LTKPreprocessorInterface 
         * @return none
         * @exception none
         */

        int deletePreprocessor();

        /** This method is used to Unloads the preprocessor DLL.
         *
         * Semantics
         *
         * 	- If m_libHandler != NULL, unload the DLL
         *		LTKUnloadDLL(m_libHandler);
         *		m_libHandler = NULL;
         *	
         * @param none
         * @return none
         * @exception none
         */
        int unloadPreprocessorDLL();

		/**
         * This function is the train method using LVQ
         *
         * Semantics
         *
         *	- Note the start time for time calculations.
         *
         *	- Create an instance of the feature extractor using NNShapeRecognizer::initializeFeatureExtractorInstance() method
         *
         *	- Call train method depending on the inFileType
         *		-	NNShapeRecognizer::trainFromListFile if inFileType() = LTKMacros::INK_FILE
         *		-	tNNShapeRecognizer::rainFromFeatureFile if inFileType() = LTKMacros::FEATURE_FILE
         *
         *	NOTE :
         *		The NNShapeRecognizer::trainFromListFile populates the following data structures
         *
         *		-	NNShapeRecognizer::m_prototypeSet : Vector of clustered ShapeSample and
         *		-	trainSet : vector of unclustered ShapeSample.
         *
         *	- Process the prototype set using NNShapeRecognizer::processPrototypeSetForLVQ()
         *
         *	- Update the headerInfo with algorithm version and name using NNShapeRecognizer::updateHeaderWithAlgoInfo()
         *
         *	- Calculate the checksum.
         *
         *	- Note the finish time for time calculations.
         *
         *
         * @param inputFilePath :string : Path of trainListFile / featureFile
         * @param strModelDataHeaderInfoFile : string : Holds the Header information of Model Data File
         * @param inFileType : string : Possible values ink / featureFile
         *
         * @return LTKInc::SUCCESS	: if the training done successfully
         * @return errorCode : if it contains some errors
         */
        int trainLVQ(const string& inputFilePath,
                const string& mdtHeaderFilePath, 
                const string& inFileType);

		/**
         * This function is used to compute the learning parameter that is used in Learning Vector Quantization  (called from trainLVQ)
         * The input parameters are the iteration number, number of iterations, and the start value of the learning parameter (alpha)
         * the function returns the value of the learning parameter (linearly decreasing)
         */
        float linearAlpha(long iter, long length, double& initialAlpha, 
                double lastAlpha,int correctDecision);

        /**
         * This function does the reshaping of prototype vector (called from trainLVQ)
         * The input parameters are the code vector, data vector (learning example in the context of LVQ), and alpha (learning parameter)
         * @param bestcodeVec is the character which we are trying to morph
         * the function modifies the character bestcodeVec
         */
        int morphVector(const LTKShapeSample& dataShapeSample,
                double talpha, LTKShapeSample& bestShapeSample);

        int processPrototypeSetForLVQ(vector<LTKShapeSample>& trainSet);

		int validatePreprocParameters(stringStringMap& headerSequence);

	      /**< @brief LVQ Iteration Scale
         *	<p>
         *
         *	DEFAULT:  LTKPreprocDefaults::NN_DEF_LVQITERATIONSCALE
         *	</p>
         */
        int m_LVQIterationScale;

        /**< @brief LVQ Initial Alpha
         *	<p>
         *
         *	DEFAULT:  LTKPreprocDefaults::NN_DEF_LVQINITIALALPHA
         *	</p>
         */
        double m_LVQInitialAlpha;

		/**< @brief LVQ Distance Measure
         *	<p>
         *
         *	DEFAULT:  LTKPreprocDefaults::NN_DEF_LVQDISTANCEMEASURE
         *	</p>
         */
        string m_LVQDistanceMeasure;

        /**< @brief Pointer to LTKOSUtil interface
         *	<p>
         *
         *	</p>
         */
        LTKOSUtil*  m_OSUtilPtr;

};


#endif