/* @doc * * @module ARTHWR_API.h : The ScanSoft Handwriting Recognition Engine Header File | * * Contains definitions, and prototypes for an interface for ScanSoft's simpliWrite handwriting recognition capabilities. * * (c)2005 ScanSoft Inc. All Rights Reserved. * */ #ifndef _ARTHWR_API_H_ #define _ARTHWR_API_H_ #if defined(_WIN32_WCE) #include #else /* Type definitions */ #define BYTE unsigned char #define WORD unsigned short #define DWORD unsigned long #endif #define MAX_RESULTS 5 #define MAX_N_BEST 4 /* max number of recognition options for a symbol */ #define MAX_STROKES_IN_MODEL 6 #define MAX_POINTS_IN_STROKE 22 #define MAX_POINTS_IN_MODEL (MAX_STROKES_IN_MODEL * MAX_POINTS_IN_STROKE) #ifndef min #define min(a,b) (((a) < (b)) ? (a) : (b)) #endif #define CODE_BACKSPACE_GESTURE 0x08 #define CODE_CR_GESTURE 0x0D /* code for carrige return gesture*/ #define CODE_SPACE_GESTURE 0x20 #define CODE_TAB_GESTURE 0x09 /* const char HWRAllModelsIndex = -1; */ /* Enumerations */ /* @enum ART_RETURN_STATUS */ typedef enum { ART_STATUS_OK = 1, /* @emem No error occured */ ART_STATUS_NO_RESULTS_AVAILABLE = 2,/* @emem No recognition results are available after end of stroke call */ ART_STATUS_INCOMPLETE_RESULTS = 3, /* @emem Intermediate recognition results are available after end of stroke call */ ART_STATUS_FINAL_RESULTS = 4, /* @emem Final recognition results are available after end of stroke call */ ART_STATUS_NO_DICT = -1, /* @emem No dictionary assigned */ ART_STATUS_INVALID_DICT = -2, /* @emem Dictionary assigned has wrong format */ ART_STATUS_NO_ENOUGH_RAM = -3, /* @emem Not enough dynamic memory assigned */ ART_STATUS_UNKNOWN = -4, /* @emem Unspecified error occurred */ ART_STATUS_MEMORY_NOT_SUFFICIENT = -5, /* @emem Error occurred in memory allocation for training */ ART_STATUS_LIB_CORRUPT = -6, /* @emem Library of trained models is corrupt */ ART_STATUS_LIB_NOT_INITIALIZED = -7, /* @emem Library of trained models was not initialized */ ART_STATUS_LIB_WRITE_FAILURE = -8, /* @emem Training was unsuccessful because writing to the library file failed */ ART_STATUS_LIB_READ_FAILURE = -9, /* @emem Error occured while opening or reading the library file */ ART_STATUS_TRAIN_CONFLICT = -10, /* @emem Training failed due to a conflicting model of a different symbol in the library */ ART_STATUS_TRAIN_TOO_MANY_STROKES = -11, /* @emem Training failed due to an attempt to train a symbol with too many strokes */ ART_STATUS_TRAIN_CODE_NOT_ALLOWED = -12, /* @emem Training failed due to an attempt to train an unsupported character in the current language group */ ART_STATUS_TRAIN_NO_STROKES = -13, /* @emem Training failed due to an attempt to train a symbol with no strokes */ ART_STATUS_LIBRARY_CODE_NOT_AVAILABLE = -14 /* @emem If a symbol code is not supported by the recognizer or does not have any specific library models (for example accented characters) */ } ART_RETURN_STATUS; /* @enum ART_RecognitionMode */ typedef enum { EUpperMode, /* @emem Recognizes letters (both upper and lower) the recogniton results are returned as upper case. Also recognizes punctuation marks ! @ & - ' , . ? */ ELowerMode, /* @emem Recognizes letters (both upper and lower) the recogniton results are returned as lower case. Also recognizes punctuation marks ! @ & - ' , . ? */ ENumericMode, /* @emem Recognizes digits and punctuation marks - , . */ EPuncMode /* @emem Recognizes a large variety of punctuation marks and symbols */ }ART_RecognitionMode; /* Structures */ /* @struct ART_HWRData | Describes the HWR structure */ typedef struct { char *pInternalLanguageDict;/* @field The pointer to the language specific HWR dictionary */ void* pHwr; /* @field The pointer to the RAM for HWR engine internal usage */ DWORD iHwrLen; /* @field The length of the RAM referred to by pHwr */ }ART_HWRData; /* @struct ART_WritingAreaInfo | Represents the writing area information used by the host application */ typedef struct { WORD maxX; /* @field Specifies the the maximal x value of the writing area */ WORD maxY; /* @field Specifies the the maximal y value of the writing area */ WORD minX; /* @field Specifies the the minimal x value of the writing area */ WORD minY; /* @field Specifies the the minimal y value of the writing area */ }ART_WritingAreaInfo; /* @struct ART_Point | Represents the point (x,y coordinates) fed to the recognizer */ typedef struct { short x; /* @field Specifies the x-coordinate. */ short y; /* @field Specifies the y-coordinate. */ }ART_Point; /* @struct ART_RecResult | Represents one recognition result */ typedef struct { WORD Code; /* @field The recognition results */ short Score; /* @field The score of the recognition result */ }ART_RecResult; /* @struct ART_RecNBest | Represents the n-best recognition result data */ typedef struct { ART_RecResult Res[MAX_N_BEST]; /* @field Array that will contain the recognition results */ short NumStrokes; /* @field Represents the number of strokes recognized in the resulting character */ int NumRes; /* @field Indicates the number of recognition results */ }ART_RecNBest; /* @struct ART_RecResults | Represents the recognition results data */ typedef struct { ART_RecNBest Res[MAX_RESULTS]; /* @field Array that contains n-best results for each recognition */ int NumRes; /* @field Indicates the number of recognition results */ }ART_RecResults; /* @struct ART_TrainConflictInfo | Holds information about training conflicts */ typedef struct { WORD ConflictSymbol; /* @field The code of the conflicting symbol */ WORD isUserModel; /* @field Indication for the type of the conflicting model - a user or internal library model */ }ART_TrainConflictInfo; /* @struct ART_CharactersTrainedInfo | Holds information of trained characters */ typedef struct { WORD *Characters; /* @field The list of trained characters (unicode code) */ WORD nCharacters; /* @field The number of trained characters */ }ART_CharactersTrainedInfo; /* @struct ART_ModelPoints | Holds the trained model information */ typedef struct { BYTE nPoints; /* @field The number of points for the trained model including the end of stroke points */ ART_Point points[MAX_POINTS_IN_MODEL]; /* @field the points for the trained model. End of each stroke is defined as point (-1,-1). */ }ART_ModelPoints; /* Language definitions */ #define ARTHWR_LANG_ENGLISH 0x00000000 #define ARTHWR_LANG_FRENCH 0x00000001 #define ARTHWR_LANG_GERMAN 0x00000002 #define ARTHWR_LANG_ITALIAN 0x00000004 #define ARTHWR_LANG_PORTUGUESE 0x00000008 #define ARTHWR_LANG_SPANISH 0x00000010 #define ARTHWR_LANG_DUTCH 0x00000020 #define ARTHWR_LANG_FINNISH 0x00000040 #define ARTHWR_LANG_DANISH 0x00000080 #define ARTHWR_LANG_SWEDISH 0x00000100 #define ARTHWR_LANG_NORWEGIAN 0x00000200 #define ARTHWR_LANG_POLISH 0x00000400 #define ARTHWR_LANG_HUNGARIAN 0x00000800 #define ARTHWR_LANG_CZECH 0x00001000 #define ARTHWR_LANG_SLOVAK 0x00002000 #define ARTHWR_LANG_LATVIAN 0x00004000 #define ARTHWR_LANG_LITHUANIAN 0x00008000 #define ARTHWR_LANG_ICELANDIC 0x00010000 #define ARTHWR_LANG_TURKISH 0x00020000 #define ARTHWR_LANG_CROATIAN 0x00040000 #define ARTHWR_LANG_SLOVENE 0x00080000 #define ARTHWR_LANG_ESTONIAN 0x00100000 #define ARTHWR_LANG_ROMANIAN 0x00200000 #define ARTHWR_LANG_SERBIAN 0x00400000 #define ARTHWR_LANG_RUSSIAN 0x01000000 #define ARTHWR_LANG_BULGARIAN 0x02000000 #define ARTHWR_LANG_UKRAINIAN 0x04000000 #define ARTHWR_LANG_KAZAKH 0x08000000 #define ARTHWR_LANG_GREEK 0x10000000 #define ARTHWR_LANG_MACEDONIAN 0x20000000 #define ARTHWR_LANG_IRISH 0x40000000 /********************************************************************************** * @func Retrieves the amount of RAM needed to be allocated by the host application for the recognizer. * * @parm WORD | maxModels | Indicates the maximal number of symbols that can be trained by the recognizer * * @rdesc If successful returns the amount of memory in bytes to be allocated for the recognizer, otherwise zero is returned. * * @normal ***********************************************************************************/ DWORD ARTHWRGetRamSize(WORD maxModels); /********************************************************************************** * @func Initializes the engine. This function should be called after has been allocated. * * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm WORD | maxModels | Indicates the maximal number of symbols that can be trained by the recognizer * * @comm This function assumes that pData is initialized with allocated memory * in pHwr, pInternalDict contains a pointer to the memory read from the dictionary file, this memory must not be changed during the lifetime of * the recognizer, iHwrLen should indicate the size of the memory allocated for pHwr. * * @rdesc Success/error code: * @flag ART_STATUS_OK | If initialization was successful * @flag ART_STATUS_NO_ENOUGH_RAM | If dynamic memory assigned was not enough * @flag ART_STATUS_INVALID_DICT | Dictionary has wrong format * @flag ART_STATUS_UNKNOWN | If an error occured * * @normal ***********************************************************************************/ ART_RETURN_STATUS ARTHWRInit(ART_HWRData *pData,WORD maxModels); /********************************************************************************** * @func Sets the writing area of the host application (needs to * be called after a call to ARTHWRInit and then only if the writing area has changed). * * @parm ART_HWRData * | pData | Pointer to the recognizer data * @parm ART_WritingAreaInfo | writingArea | The writing area data to set * * @rdesc Success/error code: * @flag ART_STATUS_OK | Success * @flag ART_STATUS_UNKNOWN | Error * * @normal ***********************************************************************************/ ART_RETURN_STATUS ARTHWRSetInputBoxSize(ART_HWRData *pData, ART_WritingAreaInfo writingArea); /********************************************************************************** * @func Closes the handwriting recognizer * * @parm ART_HWRData *| pData | Pointer to the recognizer data * * @rdesc Success/error code: * @flag ART_STATUS_OK | Success * @flag ART_STATUS_UNKNOWN | Error * * @normal ***********************************************************************************/ ART_RETURN_STATUS ARTHWREnd(ART_HWRData *pData); /********************************************************************************** * @func Sets the language for recognition * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm DWORD | language | Value of the language ( e.g. ARTHWR_LANG_ENGLISH) * * @rdesc Success/error code: * @flag ART_STATUS_OK | Success * @flag ART_STATUS_UNKNOWN | Error * * @normal ***********************************************************************************/ ART_RETURN_STATUS ARTHWRSetLanguage(ART_HWRData *pData, DWORD language); /********************************************************************************** * @func Gets the current language in the recognizer * * @parm ART_HWRData * | pData | Pointer to the recognizer data * * @rdesc The value of the language currently set * * @normal ***********************************************************************************/ DWORD ARTHWRGetLanguage(ART_HWRData *pData); /********************************************************************************** * @func Sets a new recognition mode letters(upper/lower), punctuation, numeric * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm ART_RecognitionMode | recMode | New recognition mode * * @rdesc Success/error code: * @flag ART_STATUS_OK | Success * @flag ART_STATUS_UNKNOWN | Error * * @normal ***********************************************************************************/ ART_RETURN_STATUS ARTHWRSetRecognitionMode(ART_HWRData* pData, ART_RecognitionMode recMode); /********************************************************************************** * @func Gets the current recognition mode * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @rdesc Current recognition mode * @flag | Letters - recognition results are in uppercase * @flag | Letters - recognition results are in lowercase * @flag | Numbers * @flag | Punctuation marks * * @normal ***********************************************************************************/ ART_RecognitionMode ARTHWRGetRecognitionMode (ART_HWRData *pData); /********************************************************************************** * @func Sets the current intermediate state * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm BYTE | intermediateOn | New intermediate state ( 0 - off , 1 - on ) * * @rdesc Success/error code: * @flag ART_STATUS_OK | Success * @flag ART_STATUS_UNKNOWN | Error * * @normal ***********************************************************************************/ ART_RETURN_STATUS ARTHWRSetIntermediate (ART_HWRData *pData, BYTE intermediateOn); /********************************************************************************** * @func Gets the current recognition state * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @rdesc Current intermediate state * @flag 0 | Intermediate results in-active * @flag 1 | Intermediate results active * * @normal ***********************************************************************************/ BYTE ARTHWRGetIntermediate (ART_HWRData *pData); /********************************************************************************** * Function name: ARTHWRAddPoint * ARTHWRAddPoint function adds a point written by the user to the recognizer * * Parameters: * pData: Pointer to the recognizer data * point: The point written, the recognizer assumes cartesian coordinates * with (0,0) being the buttom left corner. * * Return: * Success: ART_STATUS_OK * Error: ART_STATUS_UNKNOWN ***********************************************************************************/ ART_RETURN_STATUS ARTHWRAddPoint(ART_HWRData *pData, ART_Point point); /********************************************************************************** * @func Notifies the recognizer that the stroke has ended, meaning that * all the points that have been input since the previous call constitute a stroke. * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm ART_RecResults | pResults | Pointer to a structure that will contain the recognition results * * @rdesc The return value will indicate if the results are final or intermediate, or if no results are available. If the results are final the host application * should clear the ink of the writing area * @flag ART_STATUS_NO_RESULTS_AVAILABLE | No results are available, or while training * @flag ART_STATUS_INCOMPLETE_RESULTS | Only intermediate results are available * @flag ART_STATUS_FINAL_RESULTS | Final results are available * @flag ART_STATUS_TRAIN_TOO_MANY_STROKES | While training, this error will be returned to indicate that the user has written too many strokes (more than 4). * @flag ART_STATUS_UNKNOWN | An error occured * * @normal ***********************************************************************************/ ART_RETURN_STATUS ARTHWREndOfStroke(ART_HWRData *pData, ART_RecResults *pResults); /********************************************************************************** * @func This function is called by the host application on a timeout event, that is, when a certain amount of time has elapsed since a pen-up event, * and recogniton results should be retrieved. After calling this function the writing area should be cleared. * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm ART_RecResults | pResults | Pointer to a structure that will contain the recognition results * * @rdesc Indicates if results are available or not * @flag ART_STATUS_NO_RESULTS_AVAILABLE | No results are available, or while training. * @flag ART_STATUS_FINAL_RESULTS | Final results are available * * @normal ***********************************************************************************/ ART_RETURN_STATUS ARTHWRRecognizeData(ART_HWRData *pData, ART_RecResults *pResults); /********************************************************************************** * @func Resets the recognizer in case the recogniton or training process should be aborted * * @parm ART_HWRData *| pData | Pointer to the recognizer data * * @rdesc Success/error code: * @flag ART_STATUS_OK | Success * @flag ART_STATUS_UNKNOWN | Error * * @normal ***********************************************************************************/ ART_RETURN_STATUS ARTHWRResetData(ART_HWRData *pData); /********************************************************************************** * @func Retrieves the recognizer version * * @parm int * | version | Pointer to the version, upon return will contain the recognizer version * * @rdesc Success/error code: * @flag ART_STATUS_OK | Success * @flag ART_STATUS_UNKNOWN | Error * * @normal ***********************************************************************************/ ART_RETURN_STATUS ARTHWRGetRecognizerVersion(int *version); /********************************************************************************** * @func Retrieves the recognizer brand (in this case the return value will always be "simpliWrite") * * @rdesc A char* containing the recognizer brand * * @normal ***********************************************************************************/ char * ARTHWRGetRecognizerBrand(void); /********************************************************************************** * @func Retrieves the version of the dictionary currently in use * * @parm ART_HWRData *| pData | Pointer to the recognizer data * * @rdesc A char* of length 6, containing the dictionary version. * * @normal ***********************************************************************************/ char * ARTHWRGetDictVersion(ART_HWRData* pData); /********************************************************************************** * * @func Starts a training session for one symbol * * @parm ART_HWRData *| pData | Pointer to the recognizer data * * @rdesc Success/error code: * @flag ART_STATUS_OK | Success * @flag ART_STATUS_LIB_NOT_INITIALIZED | If a user library was not loaded * @flag ART_STATUS_UNKNOWN | If the function failed to start a training session * * @comm Once this function has been called, all the points that are fed into the recognizer * are used for the training of one symbol until the If the function failed: * @flag ART_STATUS_LIB_NOT_INITIALIZED | If a user library was not loaded * @flag ART_STATUS_UNKNOWN | If the function failed for any other reason. * * @normal * ***********************************************************************************/ int ARTHWRNumberOfTrainedSymbols(ART_HWRData *pData); /********************************************************************************** * * @func Gets the list of trained symbols * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm ART_CharactersTrainedInfo * | symbols | Pointer to structure that will hold the list trained symbols. * * * @rdesc If the function was succesful - it returns a positive number indicating the * number of trained symbols in the library. * If the function failed, the following error codes are returned: * * @flag ART_STATUS_LIB_NOT_INITIALIZED | If a user library was not loaded * @flag ART_STATUS_UNKNOWN | If the function failed for any other reason. * * @comm The host application should allocate space for the list of trained characters * (Characters element of ). The size of this list should be * determined by the host application (will be referred to as MAX_MODELS) and should be the maximum number of models that can be trained. * This size should be indicated by nCharacters element of . * If the maximum size of the array is too small, only the first MAX_MODELS symbols will be returned. * If the function was succesful, it returns the actual number of trained symbols * in the library. This number may be bigger than the size of the array of symbols, * if the maximum size of the array is not sufficient to hold all trained symbols. * Each data item in the array is the Unicode of one trained symbol. * * @normal * ***********************************************************************************/ int ARTHWRTrainedSymbols(ART_HWRData *pData,ART_CharactersTrainedInfo* symbols); /********************************************************************************** * * @func Gets the number of models trained for a specific symbol * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm WORD | symbolCode | a symbol code * * @rdesc If the function was successful - the number of trained models for the * input code (may be 0) * If the function failed: * @flag ART_STATUS_LIB_NOT_INITIALIZED | If a user library was not loaded * @flag ART_STATUS_TRAIN_CODE_NOT_ALLOWED | If symbolCode is not supported by the recognizer * @flag ART_STATUS_UNKNOWN | If the function failed for a reason other than those described above * * @comm The symbol code should be a Unicode of a symbol that is supported * by the recognizer, or ART_STATUS_TRAIN_CODE_NOT_ALLOWED will be returned. * * @normal * ***********************************************************************************/ int ARTHWRNumberOfTrainedModels(ART_HWRData *pData,WORD symbolCode); /********************************************************************************** * * @func Get the list of strokes and points for drawing a trained model * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm WORD | symbolCode | a symbol code * @parm WORD | index | A serial index of the required model - starts from 0 * @parm * | pStrokes | An array that holds the strokes and points of the model * @parm element of structure, which is an array of all the model points. * An end of stroke is indicated by a (-1,-1) point. The number of points in the model, including the end of stroke (-1,-1) points are indicated * in element of pStrokes. The model's points are returned in element of . * * The model points are scaled to the size of the writing area info given to the function. * * @normal * ***********************************************************************************/ ART_RETURN_STATUS ARTHWRTrainedModelPoints(ART_HWRData *pData,WORD symbolCode, WORD index, ART_ModelPoints *pStrokes, ART_WritingAreaInfo info); /********************************************************************************** * * @func Deletes a trained model from the library * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm WORD | symbolCode | a symbol code * @parm BYTE | index | A serial index of the required model. * * @rdesc Success/error code: * @flag ART_STATUS_OK | If there is no error * @flag ART_STATUS_LIB_NOT_INITIALIZED | If a user library was not loaded * @flag ART_STATUS_LIB_WRITE_FAILURE | If there was a failure writing the library file to disk * @flag ART_STATUS_UNKNOWN | If the function failed for a reason other than those described above * * @comm In order to delete all the models for the symbol code, the value of index should be set to -1 (HWRAllModelsIndex) * * @normal * ***********************************************************************************/ ART_RETURN_STATUS ARTHWRDeleteTrainedModel(ART_HWRData *pData,WORD symbolCode, char index); /********************************************************************************** * * @func Loads a new library of trained models * * @parm ART_HWRData *| pData | Pointer to the recognizer data * @parm char* | libPath | The path and file name of the library * * @rdesc Success/error code: * @flag ART_STATUS_OK | If there is no error * @flag ART_STATUS_LIB_READ_FAILURE | If there was a failure during the opening or reading of the library file * @flag ART_STATUS_LIB_CORRUPT | If the library file is corrupted * @flag ART_STATUS_UNKNOWN | If the function failed for a reason other than those described above * * @comm The library of trained models is saved to the file specified in libPath. * If the path or the file does not exist a new library file is created. * * @normal * ***********************************************************************************/ ART_RETURN_STATUS ARTHWRSetLibrary(ART_HWRData *pData,char* libPath); #endif /*_ARTHWR_API_H_*/