PRC_GetRecognizedEntry*

C Specification

#include <nitro/prc.h>

fx32 PRC_GetRecognizedEntry(
PRCPrototypeEntry**         resultEntry,
void*                       buffer,
const PRCInputPattern*      input,
const PRCPrototypeDB*       protoDB );

fx32 PRC_GetRecognizedEntryEx(
PRCPrototypeEntry**         resultEntry,
void*                       buffer,
const PRCInputPattern*      input,
const PRCPrototypeDB*       protoDB,
u32                         kindMask,
const PRCRecognizeParam*    param );

int PRC_GetRecognizedEntries(
PRCPrototypeEntry**         resultEntries,
fx32*                       resultScores,
int                         numRanking,
void*                       buffer,
const PRCInputPattern*      input,
const PRCPrototypeDB*       protoDB );

int PRC_GetRecognizedEntriesEx(
PRCPrototypeEntry**         resultEntries,
fx32*                       resultScores,
int                         numRanking,
void*                       buffer,
const PRCInputPattern*      input,
const PRCPrototypeDB*       protoDB,
u32                         kindMask,
const PRCRecognizeParam*    param );

Arguments

resultEntry Pointer for receiving the PRCPrototypeEntry* recognition results.
buffer Pointer to the memory region used by the recognition algorithm.
input Input pattern data to be recognized.
protoDB Sample DB.
kindMask Bit field specification of the pattern type that is used to qualify match targets.
param Other parameter values that are dependent on the recognition algorithm (use NULL as the default).
resultEntries Pointer to the array that receives the PRCPrototypeEntry* recognition results.
resultScores Pointer to the array that receives the recognition result score.
numRanking Specifies up to what rank of the recognition results will be accepted.

Return Values

PRC_GetRecognizedEntry and PRC_GetRecognizedEntryEx return the recognition result score as a fx32 type.

PRC_GetRecognizedEntries and PRC_GetRecognizedEntriesEx return how many of the sample DB patterns are matching targets.

Description

Performs pattern recognition. This function matches the PRCInputPattern type input pattern and each entry in the PRCPrototypeDB type sample DB and returns those that have high scores.

When matching, the logical AND is taken of kind for each sample DB entry in protoDB and the value of kindMask. If the result is non-0, the entry will be targeted for matching. Specifying PRC_KIND_ALL in kindMask will select all kinds. If the enabled flag is FALSE, the DB entry will not be targeted for matching, even if the kind values match.

PRC_GetRecognizedEntry and PRC_GetRecognizedEntryEx return a pointer to the sample DB entry that has the highest score in *resultEntry. If no recognition was achieved, NULL will be returned to *resultEntry.

PRC_GetRecognizedEntries and PRC_GetRecognizedEntriesEx return pointers to high scoring sample DB entries scores above numRanking, in descending order according to score in resultEntries[]. It returns the numerical value of each score in resultScores[]. If the number of matching target sample DB entries does not reach numRanking, NULL will be assigned to the unfilled regions of resultEntries[].

Note that depending on the selected recognition algorithm and the complexity of the input pattern, depending on the number and complexity of the sample DB entries, and depending on other conditions, the cost of this process can become extremely high. Based on the fact that multiple frames will be involved in recognition, we recommend that this function run on a thread other than the main process. For a sample implementation see prc/characterRecognition-1 in the demos.

Use buffer to specify the memory region that the recognition algorithm will use. First obtain the amount of memory required using PRC_GetRecognitionBufferSize* and allocate at least that amount.

Scores are returned as an fx32. The range will be 0 <= range <= FX32_ONE.

Higher scores indicate a recognition result that has a closer resemblance to the pattern. Calling PRC_GetRecognizedEntry, PRC_GetRecognizedEntries, is the same as calling PRC_GetRecognizedEntryEx, PRC_GetRecognizedEntriesEx with kindMask set to PRC_KIND_ALL, and param set to NULL.

For details on recognition algorithms see docs/TechnicalNotes/AboutPatternRecognition.pdf.

See Also

PRC_GetRecognitionBufferSize*, PRCRecognizeParam, PRC_Init, PRC_InitPrototypeDB*, PRC_InitInputPattern*, PRC_GetEntryCode, PRC_GetEntryData

Revision History

02/18/2005 Revised file name of reference document
06/23/2004 Initial Version