nnshaperecognizer.h

An open source handwriting recongnition package!!!

        string m_MDTFileOpenMode;

	DynamicTimeWarping<LTKShapeFeaturePtr, float> m_dtwObj;

    public:

        /** @name Constructors and Destructor */
        //@{

        NNShapeRecognizer(const LTKControlInfo& controlInfo);

        /**
         * Destructor
         */
        ~NNShapeRecognizer();

        //@}

        /**
         * This method initializes the NN shape recognizer
         * <p>
         * Semantics
         *   - Set the project name in NNShapeRecognizer::headerInfo with the parameter passed.<br>
         *		m_headerInfo[PROJNAME] = strProjectName;
         *
         *   -  Initialize NNShapeRecognizer::m_nnCfgFilePath <br>
         *		m_nnCfgFilePath = NNShapeRecognizer::m_lipiRootPath + LTKMacros::PROJECTS_PATH_STRING +
         *					 strProjectName + LTKMacros::PROFILE_PATH_STRING + strProfileName +
         *					 LTKInc::SEPARATOR + LTKInc::NN + LTKInc::CONFIGFILEEXT;
         *
         *   -  Initializes NNShapeRecognizer::m_nnMDTFilePath <br>
         *		m_nnMDTFilePath = NNShapeRecognizer::m_lipiRootPath + LTKMacros::PROJECTS_PATH_STRING +
         *					   strProjectName + LTKMacros::PROFILE_PATH_STRING + strProfileName +
         *					   LTKInc::SEPARATOR + LTKInc::NN + LTKInc::DATFILEEXT;
         *
         *   - Initializes NNShapeRecognizer::m_projectTypeDynamic with the value returned from LTKShapeRecoUtil::isProjectDynamic
         *
         *   - Initialize the preprocessor using LTKShapeRecoUtil::initializePreprocessor and assign
         *      default values for
         *           -# Normalised size
         *           -# Threshold size
         *           -# Aspect ratio
         *           -# Dot threshold
         *
         *   - Initialize the recognizers instance variables with the values given in classifier config file.
         *
         * </p>
         * @param strProjectName : string : Holds the name of the Project
         * @param strProfileName : string : Holds the name of the Profile
         *
         * @return int : LTKInc::SUCCESS		if initialization done successfully
         *				errorValues if initialization has some errors
         *
         * @exception LTKErrorList::ECONFIG_FILE_OPEN			Could not open project.cfg
         * @exception LTKErrorList::EINVALID_NUM_OF_SHAPES		Negative value for number of shapes
         * @exception LTKErrorList::ELOAD_PREPROC_DLL			Could not load preprocessor DLL
         * @exception LTKErrorList::EDLL_FUNC_ADDRESS_CREATE	Could not map createPreprocInst
         * @exception LTKErrorList::EDLL_FUNC_ADDRESS_DELETE	Could not map destroyPreprocInst
         */

        /**
         * This method calls the train method of the NN classifier.
         *
         */
        int train(const string& trainingInputFilePath,
                const string& mdtHeaderFilePath, 
                const string &comment,const string &dataset, 
                const string &trainFileType=INK_FILE) ;

        /**
         * This method loads the Training Data of the NN classifier.
         * @param
         * @return LTKInc::SUCCESS : if the model data was loaded successfully
         * @exception
         */
        int loadModelData();

        /**
         * This method unloads all the training data
         * @param none
         * @return LTKInc::SUCCESS : if the model data was unloaded successfully
         * @exception none
         */
        int unloadModelData();

        /**
         * This method sets the device context for the recognition
         *
         * @param deviceInfo The parameter to be set
         * @return
         * @exception
         */
        int setDeviceContext(const LTKCaptureDevice& deviceInfo);

        /**
         * Populates a vector of LTKShapeRecoResult consisting of top classes with their confidences.
         *
         * Semantics
         *
         *	- Validate the input arguments
         *	- Extract the features from traceGroup
         *	- If the distance method (m_prototypeDistance) is Euclidean (EUCLIDEAN_DISTANCE),
         *		populate the distIndexPairVector with the distance of the test sample to all the
         samples in the prototype set
         *	- If the distance method is DTW, compute the DTW distance of the test sample to the
         samples in the prototype set which passed the Euclidean filter. Populate the
         distIndexPairVector
         *	- Sort the distIndexPairVector based on the distances in ascending order
         *	- Compute the confidences of the classes appearing in distIndexPairVector, call computeConfidence()
         *	- Check if the first element of resultVector has confidence less than m_rejectThreshold, if so,
         empty the resultVector (reject the sample), log and return.
         *	- If the confThreshold value was specified by the user (not equal to -1),
         delete the entries from resultVector with confidence values less than confThreshold.
         *	- If the numChoices value was specified by the user (not equal to -1),
         update the resultVector with top numChoices entries, delete the other values.
         *
         * @param traceGroup The co-ordinates of the shape which is to be recognized
         * @param screenContext Contains information about the input field like whether it is boxed input
         *                 or continuous writing
         * @param subSetOfClasses A subset of the entire class space which is to be used for
         *                        recognizing the input shape.
         * @param confThreshold Classes with confidence below this threshold are not returned,
         *			valid range of confThreshold: (0,1)
         * @param numOfChoices Number of top choices to be returned in the result structure
         * @param resultVector The result of recognition
         *
         * @return SUCCESS: resultVector populated successfully
         *         FAILURE: return ErrorCode
         * @exception none
         */
        int recognize(const LTKTraceGroup& traceGroup, 
                const LTKScreenContext& screenContext,
                const vector<int>& subSetOfClasses, 
                float confThreshold,
                int  numChoices, 
                vector<LTKShapeRecoResult>& outResultVector);
        /**
         * This method add Class
         *
         * Semantics
         *
         *	- Check if project is Dynamic, if not return ErrorCode
         *	- Calculate Features
         *	- Update PrototypeSet
         *	- Update MDTFile
         *	- return shapeID of new class added
         *
         * @param sampleTraceGroup : LTKTraceGroup : Holds TraceGroup of sample to Add
         * @param shapeID		: int : Holds shapeID of new Class
         *                         shapeID = m_prototypeSet.at(prototypeSetSize-1).getClassID()+1
         *
         * @return SUCCESS:Shape Class added successfully
         *         FAILURE: return ErrorCode
         * @exception none
         */

        int addClass(const LTKTraceGroup& sampleTraceGroup, int& shapeID);

		/**
		* This method add Sample Class for adapt
		*
		* Semantics
		*
		*	- Check if project is Dynamic, if not return ErrorCode
		*	- Calculate Features
		*	- Update PrototypeSet
		*	- Update MDTFile
		*	- return shapeID of new class added
		*
		* @param sampleTraceGroup : LTKTraceGroup : Holds TraceGroup of sample to Add
		* @param shapeID		: int : Holds shapeID of new Class
		*                         shapeID = m_prototypeSet.at(prototypeSetSize-1).getClassID()+1
		*
		* @return SUCCESS:Shape Class added successfully
		*         FAILURE: return ErrorCode
		* @exception none
		*/
		int addSample(const LTKTraceGroup& sampleTraceGroup, int shapeID);

        /**
         * This method delete Class
         *
         * Semantics
         *
         *	- Check if shapeID is valid, if not return error code
         *	- Check if project is Dynamic, if not return ErrorCode
         *	- Update PrototypeSet
         *	- Update MDTFile
         *
         * @param shapeID		: int : Holds shapeID of Shape to be deleted
         *
         * @return SUCCESS: Shape Class deleted successfully
         *         FAILURE: return ErrorCode
         * @exception none
         */
        int deleteClass(int shapeID);

        /**
         * This method converts features to TraceGroup
         *
         * Semantics
         *
         *	- Check if shapeID is valid, if not return error code
         *	- Check if project is Dynamic, if not return ErrorCode
         *	- Update PrototypeSet
         *	- Update MDTFile
         *
         * @param shapeID		: int : Holds shapeID
         * @param numberOfTraceGroups : int : Maximum number of Trace Groups to populate
         * @param outTraceGroups : vector<LTKTraceGroup> : TraceGroup
         *
         * @return SUCCESS: TraceGroup is populated successfully
         *         FAILURE: return ErrorCode
         * @exception none
         */
        int getTraceGroups(int shapeID, int numberOfTraceGroups, vector<LTKTraceGroup> &outTraceGroups);

		/**
         * This function does the recognition function required for training phase (called from trainLVQ)
         * The input parameter are the incharacter, which is compared with the existing
         * set of prototypes and then the matched code vector and along with its index (and also the shape id) is returned
         * @param incharacter is the character which we are trying to recognise.
         * @param returnshapeID is the value of the matched character which is returned, codeCharacter is the matched prototype (code vector) vector, and codeVecIndex is the matched prototype (code vector) index
         */
        int trainRecognize(LTKShapeSample& inShapeSample, LTKShapeSample& bestShapeSample, int& codeVecIndex);

    private:
        /**
         * This function is the train method using Clustering prototype selection technique.
         *
         *
         * 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
         *		- NNShapeRecognizer::trainFromFeatureFile() if inFileType = LTKMacros ::FEATURE_FILE
         *
         *	- Update the headerInfo with algorithm version and name using NNShapeRecognizer::updateHeaderWithAlgoInfo() method
         *
         *	- 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 trainClustering(const string& trainingInputFilePath, 
                const string& mdtHeaderFilePath, 
                const string& trainFileType);


        /**
         * This method do the map between the module name and function names from the cfg file
         *
         * Semantics
         *
         *	- Read the Preprocess Sequence from the nn.cfg
         *
         *	- Split the sequence into tokens with delimiter LTKMacros::DELEMITER_SEQUENCE using LTKStringUtil::tokenizeString
         *
         *	- Split each token with delimiter LTKMacrosDELEMITER_FUNC using LTKStringUtil::tokenizeString
         *		to get the Module name and Function name
         *
         *	- Store the Module name and the Function name into a structure
         *
         *
         * @param none
         * @return LTKInc::SUCCESS		: if functions are successfully mapped,
         * @return errorCodes	: if contains any errors
         * @exception none
         */
        int mapPreprocFunctions();

        /**
         * This method will assign default values to the members
         *
         * Semantics
         *
         *	- Assign Default values to all the data members
         *
         *
         * @param  none
         *
         * @return none
         */
        void assignDefaultValues();

        /** Reads the NN.cfg and initializes the instance variable of the classifier with the user defined
         * values.
         *
         * Semantics
         *
         *	- Open the nn.cfg using LTKConfigFileReader
         *
         *	- Incase of file open failure (nn.cfg), default values of the classifier parameters are used.
         *
         *	- The valid values of the classifier parameters are cached in to the class data members.
         *        LTKConfigFileReader::getConfigValue is used to get the value fora key defined in the config file
         *
         *	- Exception is thrown if the user has specified an invalid valid for a parameter
         *
         *
         * @param  none
         * @return SUCCESS   : If the Config file read successfully
         * @return errorCode : If it contains some errors
         * @exception LTKErrorList::ECONFIG_FILE_RANGE			The config file variable is not within the correct range
         */
        int readClassifierConfig();

        /**
         * This function serves as wrapper function to the Dtw distance computation function
         * (for use by clustering prototype selection)
         * @param train This is an input parameter and corresponds to the training character.
         * @param test This is an input parameter and corresponds to the testing character.
         */
        int computeDTWDistance(const LTKShapeSample& inFirstShapeSampleFeatures,
                               const LTKShapeSample& inSecondShapeSampleFeatures, 
                               float& outDTWDistance);




        /**
         * This function computes the eucildean distance between the two points.
         * @param train X and Y coordinate of the first point.
         * @param test X and Y coordinate of the second point.
         */

        /*int computeEuclideanDistance(const LTKShapeSample& inFirstShapeSampleFeatures,
                const LTKShapeSample& inSecondShapeSampleFeatures, 
                float& outEuclideanDistance);*/

	    int computeEuclideanDistance(const LTKShapeSample& inFirstShapeSampleFeatures,
                                     const LTKShapeSample& inSecondShapeSampleFeatures, 
                                     float& outEuclideanDistance);

	int calculateMedian(const int2DVector& clusteringResult, 
        	const float2DVector& distanceMatrix, vector<int>& outMedianIndexVec);



        /**
         * This method creates a custom feature extractor instance and stores it's address in
         * NNShapeRecognizer::m_ltkFE. The local distance function pointer is also initialized.
         *
         * Semantics
         *
         *
         *	- Intialize the NNShapeRecognizer::m_ptrFeatureExtractor with address of the feature extractor instance created
         *        using LTKShapeFeatureExtractorFactory::createFeatureExtractor
         *
         *	- Cache the address of  LTKShapeFeatureExtractor::getLocalDistance() in an instance variable
         *
         * @param none
         *
         * @return 0 on LTKInc::SUCCESS and 1 on LTKInc::FAILURE
         *
         * @exception none
         */
        int initializeFeatureExtractorInstance(const LTKControlInfo& controlInfo);

        /**
         * This method trains the classifier from the train list file whose path is passed as paramater.
         *
         * Semantics
         *
         *	- Open the trainListFile for reading.
         *
         *	- Open the mdt file for writing.
         *
         *	- Write header information to the mdt file
         *		- NNShapeRecognizer::m_numShapes
         *		- NNShapeRecognizer::m_traceDimension
         *		- NNShapeRecognizer::m_flexibilityIndex
         *
         *	- Get a valid line from the train list file
         *		- Skip commented lines
         *		- Skip lines where number_of_tokens != 2
         *		- Throw error LTKErrorList::EINITSHAPE_NONZERO, if the first shape in the list file is not zero
         *		- Throw error LTKErrorList::EINVALID_ORDER_LISTFILE if the shapes are not in sequential order
         *
         *	- For every valid line get the ShapeSample from the ink file using NNShapeRecognizer::getShapeSampleFromInkFile
         *		- Read ink from UNIPEN  ink file