WIL-PDL Reference ( C++ ) 1.0.1
Typedefs | Enumerations | Functions
PredictionDLL

AI 推論ツール ( C++ 版 ) More...

Typedefs

typedef VOID * H_MODEL
 モデルハンドル More...
 

Enumerations

enum  MODEL_CATEGORY { UNKNOWN = -1 , CLASSIFICATION = 0 , ANOMALY_DETECTION , MULTI_VIEW_CNN }
 モデルの種別 More...
 

Functions

INT fnPDL_check_license ()
 ライセンス確認 More...
 
H_MODEL * fnPDL_create_handle ()
 モデルハンドルの生成 More...
 
INT fnPDL_load_model (const CHAR *filename, H_MODEL hmodel)
 モデルの読み込み More...
 
INT fnPDL_get_this_version (INT *major_version, INT *minor_version, INT *build_no, INT *revision)
 WIL-PDL のバージョンの取得 More...
 
INT fnPDL_get_required_version (const H_MODEL hmodel, INT *major_version, INT *minor_version, INT *build_no, INT *revision)
 モデルの要求するバージョンの取得 More...
 
INT fnPDL_check_version (const H_MODEL hmodel)
 モデルの要求するバージョンの確認 More...
 
INT fnPDL_get_model_category (const H_MODEL hmodel, MODEL_CATEGORY *model_category)
 モデルの種別の取得 More...
 
INT fnPDL_get_input_image_size (const H_MODEL hmodel, INT *channels, INT *width, INT *height)
 モデルパラメータの取得 More...
 
INT fnPDL_get_how_many_views (const H_MODEL hmodel, INT *num_views)
 モデルパラメータの取得 More...
 
INT fnPDL_cls_get_label_num (const H_MODEL hmodel, INT *label_num)
 画像分類ラベル数の取得 More...
 
INT fnPDL_cls_get_label_name (const H_MODEL hmodel, const INT label_index, const size_t buff_size, char *label_name_buff, size_t *len_label_name)
 画像分類ラベル名称の取得 More...
 
INT fnPDL_predict (const H_MODEL hmodel, const FHANDLE hsrc, FLOAT **scores, size_t *num_scores)
 推論の実行 More...
 
INT fnPDL_predict_multi_images (const H_MODEL hmodel, const INT num_images, FHANDLE *hsrcs, FLOAT **scores, size_t *num_scores)
 推論の実行 ( MVCNN ) More...
 
INT fnPDL_postproc_cls (const H_MODEL hmodel, const FLOAT *scores, const size_t num_scores, UINT *top_score_index, FLOAT *top_score_value)
 推論結果の加工 ( 画像分類, MVCNN ) More...
 
INT fnPDL_postproc_ad (const H_MODEL hmodel, const FLOAT *anomaly_data, const size_t num_scores, const FLOAT threshold, BOOL *is_anomaly, FHANDLE *hmap, FLOAT *max_anomaly)
 推論結果の加工 ( アノマリー検出 ) More...
 
VOID fnPDL_dispose (H_MODEL hmodel)
 モデルハンドルの解放 More...
 

Detailed Description

AI 推論ツール ( C++ 版 )

Typedef Documentation

◆ H_MODEL

typedef VOID* H_MODEL

モデルハンドル

推論に使用するモデルを管理するハンドルです

Enumeration Type Documentation

◆ MODEL_CATEGORY

enum MODEL_CATEGORY

モデルの種別

モデルの種別を表す列挙体です
種別によって対応する推論関数 ( fnPDL_predict(), fnPDL_predict_multi_images() )、後処理の関数 ( fnPDL_postproc_cls(), fnPDL_postproc_ad() ) が異なりますので、モデル読み込み後に確認することができます

See also
fnPDL_get_model_category()
Enumerator
UNKNOWN 

未知の種別

CLASSIFICATION 

画像分類

ANOMALY_DETECTION 

アノマリー検出

MULTI_VIEW_CNN 

MVCNN

Function Documentation

◆ fnPDL_check_license()

INT fnPDL_check_license ( )

ライセンス確認

deep learning 関連のオプションライブラリを使用するためのライセンスのチェックを行います

Return values
F_ERR_NONE正常終了
F_ERR_NO_LICENSEライセンスエラー、または未初期化エラー
See also
fnPDL_load_model()

◆ fnPDL_check_version()

INT fnPDL_check_version ( const H_MODEL  hmodel)

モデルの要求するバージョンの確認

読み込み済みのモデルハンドルが要求する WIL-PDL のバージョンを確認します。

Parameters
[in]hmodel読み込んだモデルのハンドル
Return values
F_ERR_NONE正常終了
F_ERR_INVALID_OBJECT未初期化のモデルハンドルが渡された
F_ERR_UNSUPPORTEDモデルの要求するバージョンを WIL-PDL のバージョンが満たさない
See also
fnPDL_load_model()

◆ fnPDL_cls_get_label_name()

INT fnPDL_cls_get_label_name ( const H_MODEL  hmodel,
const INT  label_index,
const size_t  buff_size,
char *  label_name_buff,
size_t *  len_label_name 
)

画像分類ラベル名称の取得

label_index に対応する画像分類の学習時に設定した各ラベルの名称を取得します。

ラベル名称は、事前に確保されたバッファ領域 label_name_buff の先頭から書き込みます。書き込んだ文字数は len_label_name で返されます。確保したバッファサイズは buff_size で入力してください。

また、本関数は頻繁に ( 例えば推論を実行するたびに ) 呼び出されることは想定されておらず高速化されていませんので、モデル読み込みなどの初期化時に一度だけ呼び出しておくような使い方を推奨いたします。 推論を実行する前にラベルの個数を取得するためには fnPDL_cls_get_label_num() が使用できます

Parameters
[in]hmodel読み込んだモデルのハンドル
[in]label_index名称を取得したいラベルのインデックス
[in]buff_sizelabel_name_buff として事前に確保したバッファサイズ
[out]label_name_buff取得したラベル名称が先頭から書き込まれます
[out]len_label_nameラベル名称の文字数
Return values
F_ERR_NONE正常終了
F_ERR_INVALID_INDEXlabel_index がラベル一覧の配列の範囲外 ( 負の場合、ラベル個数以上の場合 )
F_ERR_BUFFER_OVERFLOWlabel_name_buff のバッファサイズがラベル名称の文字数以下
F_ERR_UNKNOWNバッファへの文字列の書き込みに失敗した
F_ERR_INVALID_OBJECT未初期化のモデルハンドルが渡された
See also
fnPDL_load_model(), fnPDL_cls_get_label_num()

◆ fnPDL_cls_get_label_num()

INT fnPDL_cls_get_label_num ( const H_MODEL  hmodel,
INT *  label_num 
)

画像分類ラベル数の取得

画像分類の学習時に設定したラベルの個数を取得します。 本関数で取得される個数は、推論時に返されるスコア配列の長さ ( fnPDL_predict() の num_scores ) に一致します。 事前にラベルの名称を取得する場合などに使用します。

Parameters
[in]hmodel読み込んだモデルのハンドル
[out]label_num学習時に設定したラベルの個数
Return values
F_ERR_NONE正常終了`
F_ERR_INVALID_OBJECT未初期化のモデルハンドルが渡された
See also
fnPDL_load_model(), fnPDL_cls_get_label_name()

◆ fnPDL_create_handle()

H_MODEL * fnPDL_create_handle ( )

モデルハンドルの生成

モデルハンドルを生成します。ライセンスエラーの場合は NULL を返します。

Returns
モデルハンドル
See also
fnPDL_check_license()

◆ fnPDL_dispose()

VOID fnPDL_dispose ( H_MODEL  hmodel)

モデルハンドルの解放

読み込まれているモデルのリソースを解放します。解放後は NULL ハンドルとなります。

Parameters
[in]hmodel解放したいモデルのハンドル
See also
fnPDL_load_model()

◆ fnPDL_get_how_many_views()

INT fnPDL_get_how_many_views ( const H_MODEL  hmodel,
INT *  num_views 
)

モデルパラメータの取得

読み込み済みのモデルハンドルが期待する視点数 ( 入力画像の枚数 ) を取得します。 画像分類とアノマリー検出では常に 1 が返され、MVCNN では学習時に設定した視点数が返されます。

Parameters
[in]hmodel読み込んだモデルのハンドル
[out]num_views期待する視点数 ( 入力画像の枚数 )
Return values
F_ERR_NONE正常終了
F_ERR_INVALID_OBJECT未初期化のモデルハンドルが渡された
See also
fnPDL_load_model()

◆ fnPDL_get_input_image_size()

INT fnPDL_get_input_image_size ( const H_MODEL  hmodel,
INT *  channels,
INT *  width,
INT *  height 
)

モデルパラメータの取得

読み込み済みのモデルハンドルが期待する入力画像のチャネル数、幅、高さを取得します。

Parameters
[in]hmodel読み込んだモデルのハンドル
[out]channels,width,height期待する入力画像のチャネル数、幅、高さ
Return values
F_ERR_NONE正常終了
F_ERR_INVALID_OBJECT未初期化のモデルハンドルが渡された
See also
fnPDL_load_model()

◆ fnPDL_get_model_category()

INT fnPDL_get_model_category ( const H_MODEL  hmodel,
MODEL_CATEGORY *  model_category 
)

モデルの種別の取得

読み込み済みのモデルハンドルの種別を取得します。

種別によって対応する推論関数 ( fnPDL_predict(), fnPDL_predict_multi_images() )、後処理の関数 ( fnPDL_postproc_cls(), fnPDL_postproc_ad() ) が異なりますので、本関数で確認することが可能です。

Parameters
[in]hmodel読み込んだモデルのハンドル
[out]model_categoryモデルの種別
Return values
F_ERR_NONE正常終了
F_ERR_INVALID_OBJECT未初期化のモデルハンドルが渡された
See also
fnPDL_load_model()

◆ fnPDL_get_required_version()

INT fnPDL_get_required_version ( const H_MODEL  hmodel,
INT *  major_version,
INT *  minor_version,
INT *  build_no,
INT *  revision 
)

モデルの要求するバージョンの取得

読み込み済みのモデルハンドルが要求する WIL-PDL のバージョンを確認します。

Parameters
[in]hmodel読み込んだモデルのハンドル
[out]major_version読み込んだモデルが要求するメジャーバージョン
[out]minor_version読み込んだモデルが要求するマイナーバージョン
[out]build_no読み込んだモデルが要求するビルド番号
[out]revision読み込んだモデルが要求するリビジョン ( 機能には関係無いため必要条件ではありません )
Return values
F_ERR_NONE正常終了
F_ERR_INVALID_OBJECT未初期化のモデルハンドルが渡された
See also
fnPDL_load_model(), fnPDL_get_this_version(), fnPDL_check_version()

◆ fnPDL_get_this_version()

INT fnPDL_get_this_version ( INT *  major_version,
INT *  minor_version,
INT *  build_no,
INT *  revision 
)

WIL-PDL のバージョンの取得

現在実行している WIL-PDL のバージョンを確認します。

Parameters
[out]major_versionメジャーバージョン
[out]minor_versionマイナーバージョン
[out]build_noビルド番号
[out]revisionリビジョン
Return values
F_ERR_NONE正常終了
See also
fnPDL_load_model(), fnPDL_get_required_version(), fnPDL_check_version()

◆ fnPDL_load_model()

INT fnPDL_load_model ( const CHAR *  filename,
H_MODEL  hmodel 
)

モデルの読み込み

ファイル名で指定されたモデルを読み込みます。AI 開発ツールでインライン用に変換されたモデルを受け付けます。

Parameters
[in]filename読み込むモデルのファイル名 ( フルパス又は相対パス、拡張子は .wilpdl )
[out]hmodel読み込んだモデルのハンドル ( 読み込みに失敗したときには NULL が返されます )
Return values
F_ERR_NONE正常終了
F_ERR_FILE_IOモデルファイルのアクセスエラー ( 拡張子の不一致を含む )
F_ERR_NOMEMORYメモリ確保の失敗
F_ERR_INVALID_OBJECTその他の失敗
F_ERR_NO_LICENSEライセンスエラー、または未初期化エラー
See also
fnPDL_check_license(), fnPDL_create_handle()

◆ fnPDL_postproc_ad()

INT fnPDL_postproc_ad ( const H_MODEL  hmodel,
const FLOAT *  anomaly_data,
const size_t  num_scores,
const FLOAT  threshold,
BOOL *  is_anomaly,
FHANDLE *  hmap,
FLOAT *  max_anomaly 
)

推論結果の加工 ( アノマリー検出 )

fnPDL_predict() または fnPDL_predict_multi_images() で得られた結果に対して、アノマリー検出における後処理を行います。

引数に NULL を与えることで計算をスキップします。以下の 3 つが全て NULL の場合は F_ERR_INVALID_PARAM を返します。

  • threshold に NULL を与えたとき : is_anomaly の判定をスキップします
  • hmap に NULL を与えたとき : hmap の計算をスキップします
  • max_anomaly に NULL を与えたとき: max_anomaly の検出をスキップします

また、hmap は推論画像と幅、大きさの一致したチャネル数が 1 の画像である必要があります。

  • 画像型が UC8 のとき: 画像内の異常度の最大値が 255 となるように自動的に正規化を行います
  • 画像型が BIN のとき: threshold 以上の異常度反応があった領域を 1、それ未満の領域を 0 とする二値画像を取得します。threshold が NULL の場合には F_ERR_INVALID_PARAM となります
Parameters
[in]hmodel読み込んだモデルのハンドル ( 読み込みに失敗したときには NULL が返されます )
[in]anomaly_data推論結果データ
[in]num_scores推論結果データの配列長
[in]threshold異常度の閾値 ( 画像単位での異常度がこの値より大きいときに異常と判定します )
[out]is_anomaly異常判定結果、異常と判定したときに true を返します ( threshold に NULL 指定時は判定をスキップします )
[out]hmap異常度マップ画像 ( NULL 指定時は計算をスキップします )
[out]max_anomaly画像内での最大異常度、この値を画像単位での異常度として is_anomaly の判定に使用します ( NULL 指定時は計算をスキップします )
Return values
F_ERR_NONE正常終了
F_ERR_INVALID_OBJECT不正なモデルハンドルが渡された
F_ERR_INVALID_IMAGE異常度マップ画像のサイズが一致しない (
See also
fnPDL_get_model_param )
Return values
F_ERR_INVALID_PARAM不正なパラメータが渡された ( threshold, hmap, max_anomaly が全ての計算をスキップするパラメータのとき )
F_ERR_NOMEMORYメモリ確保に失敗した
F_ERR_NO_LICENSEライセンスエラー、または未初期化エラー
See also
fnPDL_load_model(), fnPDL_predict()
Attention
異常度マップは主に可視化のための機能のため、厳密に異常度の最大値を保持していない場合があります。 このため、hamp の画像型を BIN として threshold の値に max_anomaly の値を入力したときに、1 となる画素が 1 つでない場合 ( 0 個の場合 ) があります。 このような設定値となることは稀であり、本来取得したい異常領域は最大異常度を与える画素の周辺と考えられます。 評価用画像に対する出力を確認しながら、意図した領域を取得できる threshold の値に調整するようお願いします

◆ fnPDL_postproc_cls()

INT fnPDL_postproc_cls ( const H_MODEL  hmodel,
const FLOAT *  scores,
const size_t  num_scores,
UINT *  top_score_index,
FLOAT *  top_score_value 
)

推論結果の加工 ( 画像分類, MVCNN )

fnPDL_predict() または fnPDL_predict_multi_images() で得られた結果に対して、画像分類における後処理を行います。 スコア配列から分類結果として次のものを

  • スコア最大のクラスのインデックス: 分類結果を表します。ラベル名称が必要な場合には fnPDL_cls_get_label_name() などで取得しておいたラベル名称と照合します
  • 最大スコア : 分類結果に対応するスコアを表します。
Parameters
[in]hmodel読み込んだモデルのハンドル ( 読み込みに失敗したときには NULL が返されます )
[in]scores推論結果データ
[in]num_scores推論結果データの配列長
[out]top_class_indexスコア最大のクラスのインデックス ( 分類結果 )
[out]top_class_score最大スコア
Return values
F_ERR_NONE正常終了
F_ERR_INVALID_OBJECT不正なモデルハンドルが渡された、または num_scores がゼロ以下、スコア最大値が負 ( scores が不正 )
F_ERR_NO_LICENSEライセンスエラー、または未初期化エラー
See also
fnPDL_load_model(), fnPDL_predict(), fnPDL_cls_get_label_num(), fnPDL_cls_get_label_name()

◆ fnPDL_predict()

INT fnPDL_predict ( const H_MODEL  hmodel,
const FHANDLE  hsrc,
FLOAT **  scores,
size_t *  num_scores 
)

推論の実行

読み込み済みのモデルハンドルを使用して入力画像に対する推論を行い、推論結果のスコア配列を scores から出力します。
この関数は画像分類とアノマリー検出のモデルの推論に使用します。MVCNN のモデルの推論には fnPDL_predict_multi_images() をご利用ください。

スコア配列 scores は内部確保されます。関数へのエントリー時 *scores は NULL である必要があります。使用し終えたメモリは、fnOAL_free() で解放してください。
事前確保済みのメモリを使用することもできます。その際には、確保した配列長 ( float としての配列長 ) を num_scores から入力します。 入力された配列長が必要なサイズに一致しないときには F_ERR_INVALID_PARAM のエラーコードを返します。 事前確保済みのメモリを使用するシナリオとしては、同じモデルハンドルで推論する際に初回の推論で内部確保されたメモリを 2 回目以降に使い回すことを想定しています。

得られたスコア配列は次の後処理に利用することが可能です。

  • 画像分類の推論結果として、スコア最大値の分類先を取得する際には fnPDL_postproc_cls() をご利用ください
  • アノマリー検出の推論結果として、異常度マップ画像の算出、最大異常度の計算と閾値に基づく判定を取得する際には fnPDL_postproc_ad() をご利用ください

推論対象の画像は、幅と高さが fnPDL_get_input_image_size() で取得されるパラメータに一致していることが必要です。 また、チャネル数と画像型は以下の組み合わせである必要があります。

  • 画像型が UC8 のとき、チャネル数は 1 又は 3 ( 1 のときには各チャネルで同じ画素値を持つ 3ch 画像に内部で変換して処理を行います ）
  • 画像型が RGBTRIPLE 又は　RGBQUAD のとき、チャネル数は 1
Parameters
[in]hmodel読み込んだモデルのハンドル
[in]hsrc推論対象の画像
[in/out]scores 各クラスのスコアのリスト ( 関数へのエントリー時 *scores は NULL であることが必要、または事前確保済みのメモリを使用する場合には num_scores に float としての配列長を入力 )
[in/out]num_scores スコアのリストの長さ
Return values
F_ERR_NONE正常終了
F_ERR_INVALID_OBJECT不正なモデルハンドルが渡された ( 読み込まれていない、または種別が画像分類・アノマリー検出以外 )
F_ERR_INVALID_PARAMスコア配列に事前確保済みメモリが渡されたが num_scores で渡された float としての配列長が必要なサイズに一致しない
F_ERR_INVALID_IMAGE不正な入力画像が渡された ( チャネル数、幅、高さ、画像型 )
F_ERR_NOMEMORYメモリ確保に失敗した
F_ERR_NO_LICENSEライセンスエラー、または未初期化エラー
See also
fnPDL_load_model(), fnPDL_postproc_cls(), fnPDL_postproc_ad(), fnPDL_get_input_image_size(), fnPDL_predict_multi_images()

◆ fnPDL_predict_multi_images()

INT fnPDL_predict_multi_images ( const H_MODEL  hmodel,
const INT  num_images,
FHANDLE *  hsrcs,
FLOAT **  scores,
size_t *  num_scores 
)

推論の実行 ( MVCNN )

読み込み済みのモデルハンドルを使用して複数枚の入力画像に対する推論を行い、推論結果のスコア配列を scores から出力します。
この関数は主に MVCNN のモデルの推論に使用します。

スコア配列 scores は内部確保されます。関数へのエントリー時 *scores は NULL である必要があります。使用し終えたメモリは、fnOAL_free() で解放してください。
事前確保済みのメモリを使用することもできます。その際には、確保した配列長 ( float としての配列長 ) を num_scores から入力します。 入力された配列長が必要なサイズに一致しないときには F_ERR_INVALID_PARAM のエラーコードを返します。 事前確保済みのメモリを使用するシナリオとしては、同じモデルハンドルで推論する際に初回の推論で内部確保されたメモリを 2 回目以降に使い回すことを想定しています。

MVCNN のモデルの推論では、任意の枚数の画像を配列として入力することができます。 このとき、画像枚数は num_images にて指定し、その値はモデルの視点数に一致している必要があります。
画像分類とアノマリー検出のモデルの推論にも使用することが可能ですが、num_images は 1 である必要があり、先頭の画像のみを参照して、 fnPDL_predict() を呼び出します。

得られたスコア配列は次の後処理に利用することが可能です。

  • 画像分類、MVCNN の推論結果として、スコア最大値の分類先を取得する際には fnPDL_postproc_cls() をご利用ください
  • アノマリー検出の推論結果として、異常度マップ画像の算出、最大異常度の計算と閾値に基づく判定を取得する際には fnPDL_postproc_ad() をご利用ください

推論対象の画像は、幅と高さが fnPDL_get_input_image_size() で取得されるパラメータに一致していることが必要です。また、チャネル数と画像型は以下の組み合わせである必要があります。

  • 画像型が UC8 のとき、チャネル数は 1 又は 3 ( 1 のときには各チャネルで同じ画素値を持つ 3ch 画像に内部で変換して処理を行います ）
  • 画像型が RGBTRIPLE 又は　RGBQUAD のとき、チャネル数は 1
Parameters
[in]hmodel読み込んだモデルのハンドル ( 読み込みに失敗したときには NULL が返されます )
[in]nun_images推論対象画像の枚数
[in]hsrcs推論対象画像の配列の先頭アドレス
[out]scores各クラスのスコアのリスト
[out]num_scoresスコアのリストの長さ
Return values
F_ERR_NONE正常終了
F_ERR_INVALID_OBJECT不正なモデルハンドルが渡された ( 読み込まれていない、または種別がは画像分類・アノマリー検出・MVCNN 以外 )
F_ERR_INVALID_PARAMスコア配列に事前確保済みメモリが渡されたが num_scores で渡された float としての配列長が必要なサイズに一致しない
F_ERR_INVALID_PARAM不正なパラメータが渡された ( num_images がモデルの視点数に一致しない )
F_ERR_INVALID_IMAGE不正な入力画像が渡された ( チャネル数、幅、高さ、画像型 )
F_ERR_NOMEMORYメモリ確保に失敗した
F_ERR_NO_LICENSEライセンスエラー、または未初期化エラー
See also
fnPDL_load_model(), fnPDL_postproc_cls(), fnPDL_postproc_ad(), fnPDL_get_input_image_size(), fnPDL_get_how_many_views(), fnPDL_predict()
Documentation copyright © 2008 FAST Corporation. https://www.fast-corp.co.jp/
Generated on Sun Jan 15 2023 13:40:43 for WIL-PDL Reference ( C++ ) 1.0.1 by Doxygen 1.9.5.