# PRC_GetRecognizedEntry*

## 構文

      #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 );

## 引数

resultEntry | 認識結果の`PRCPrototypeEntry*`を受け取るポインタ
buffer | 認識アルゴリズムで使用されるメモリ領域へのポインタ
input | 認識する入力パターンデータ
protoDB | 見本DB
kindMask | マッチング対象を限定するための図形種のビットフィールド指定
param | 認識アルゴリズム依存のその他のパラメータ値　（NULL でデフォルト値を使用）

resultEntries | 認識結果の`PRCPrototypeEntry*`を受け取る配列へのポインタ
resultScores | 認識結果のスコアを受け取る配列へのポインタ
numRanking | 認識結果の何位までを受け取るかの指定

## 返り値

`PRC_GetRecognizedEntry`, `PRC_GetRecognizedEntryEx` は認識結果のスコアを`fx32`型で返します。

`PRC_GetRecognizedEntries`, `PRC_GetRecognizedEntriesEx` は見本DBの中の何パターンがマッチング対象になったかを返します。

## 説明

図形認識を実際に行うAPIです。`PRCInputPattern`型の入力パターンデータと`PRCPrototypeDB`型の見本DBの各エントリとのマッチングを行い、スコアの高かったものを返します。

マッチング処理中に、`protoDB` 中の各見本DBエントリの `kind` 値と`kindMask` 値との AND がとられ、結果が非0であればそのエントリをマッチングの対象とします。`kindMask` に `PRC_KIND_ALL` を指定すると全種類を選択します。なお、`enabled` フラグが偽の見本DBエントリは `kind` 値が合致していてもマッチング対象にはなりません。

`PRC_GetRecognizedEntry`, `PRC_GetRecognizedEntryEx` はもっともスコアの高かった見本DBエントリへのポインタを `*resultEntry` に返します。認識できなかった場合は`*resultEntry` に `NULL` が代入されて返ります。

`PRC_GetRecognizedEntries`, `PRC_GetRecognizedEntriesEx` はスコアの上位 `numRanking` 位までの見本DBエントリへのポインタをスコアの降順に `resultEntries[]` に返し、それぞれのスコアの数値を`resultScores[]` に返します。マッチング対象の見本DBエントリの数が `numRanking` に満たなかった場合は、`resultEntries[]` の足りない部分に `NULL` が代入されます。

選択した認識アルゴリズムと入力パターンの複雑さ、見本DBのエントリ数・複雑さなどの条件により、非常に高コストの処理となりますので注意してください。認識には複数フレームかかることを前提として、メインの処理とは別のスレッド上でこのAPIを実行することを推奨します。実装例としてデモの下の prc/characterRecognition-1 をご参照ください。

認識アルゴリズムが使用するメモリ領域を `buffer` で指定します。必要なメモリ量をあらかじめ`PRC_GetRecognitionBufferSize*()`で取得し、それ以上のメモリ領域を確保しておいてください。

fx32 型で返ってくるスコア値は実際には 0 以上 FX32_ONE 以下の範囲に収まっています。スコアが大きいほど認識結果のパターンとの類似度が高くなります。

`PRC_GetRecognizedEntry, PRC_GetRecognizedEntries` は、それぞれ `kindMask` に `PRC_KIND_ALL`、`param` に `NULL` を設定した `PRC_GetRecognizedEntryEx, PRC_GetRecognizedEntriesEx` の呼び出しと同等です。

認識のアルゴリズムの詳細に関しては、docs/TechnicalNotes/AboutPatternRecognition.pdf を参照してください。

## 参照

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

## 履歴

2005/02/18 解説ドキュメントのファイル名を修正
2004/06/23 初版