2.2.10. 顔特徴抽出

Windows/Linux/Arm_Linux 用のAPIは、以下の解説をご参照ください。

stid_facepro_feature_extraction_create_handle

機能：モデルファイルをロードして、feature_extractionハンドルを作成します。

定義：

STID_SDK_API
stid_result_t
stid_facepro_feature_extraction_create_handle(
    stid_handle_t* out_handle,
    const char *model_filename
);

引数：

• [in] model_filename：モデルファイルの所在パスを入力してください。

• [out] out_handle：初期化されたハンドルです。利用しない場合は、stid_face_feature_destroy_handleを呼び出してリソースを解放する必要があります。

返り値:

• [return]：正常の場合はSTID_OKが表示、エラーになった場合はエラーコードが表示されます。

stid_facepro_feature_extraction_destroy_handle

機能：feature_extractionハンドルを解放できます。

定義：

STID_SDK_API
void
stid_facepro_feature_extraction_destroy_handle(
    stid_handle_t handle
);

引数：

• [in] handle：解放するハンドルを入力します。

返り値：

• [return]：正常の場合はSTID_OKが表示されます（エラーになった場合はエラーコードが表示されます）

stid_facepro_verify_destroy_handle

機能：特徴情報の取得に必要なモデルバージョン番号を取得できます。

定義：

STID_SDK_API
stid_result_t
stid_facepro_feature_extraction_get_version(
    stid_handle_t handle,
    int *out_version
);

引数：

• [in] handle：初期化されたverify_destroyハンドル入力してください。

• [in] out_version：モデルバージョン番号を表示されます。

返り値：

• [return]：正常の場合はSTID_OKが表示、エラーになった場合はエラーコードが表示されます。

stid_facepro_feature_extraction_extract

機能：1フレーム分の画像及び特徴点情報を入力することで、顔の特徴を取得できます。

定義：

STID_SDK_API
stid_result_t
stid_facepro_feature_extraction_extract(
    stid_handle_t handle,
    const stid_image_t* input_image,
    const stid_landmarks_t* input_landmarks,
    char **out_feature
);

引数：

• [in] handle：初期化されたハンドルを表示します。

• [in] input_image：1フレームの画像をロードしてください。画像中の顔向き方向は上下左右の四方向に対応しています。上向き顔画像を利用すると、生体検知パフォーマンスの高い結果が得られます。

• [in] input_landmarks：顔特徴点情報を入力してください。

• [out] out_feature：顔特徴情報が表示されます（APIによるメモリの配分を決めます。APIstid_facepro_feature_release_featureを呼び出してハンドルを解放する必要があります）。

返り値：

• [return]：正常の場合はSTID_OKが表示されます。エラーになった場合はエラーコードが表示されます（顔が検知されなかった場合は、STID_E_NO_FACEが表示されます）。

stid_facepro_feature_release_feature

機能：顔特徴データを解放できます。

定義：

STID_SDK_API
void
stid_facepro_feature_release_feature(
    const char *feature
);

引数：

• [in] feature：解放する顔の特徴情報を入力してください。

stid_facepro_get_feature_length

機能：顔認証に適用しているモデルで抽出したfeature_length情報を取得できます（st_feature_hea der_tの長さ情報を含まない）。

定義：

ST_SDK_API
int stid_facepro_get_feature_length(
    st_handle_t verify_handle
);

引数：

• [In]verify_handle：初期化された顔認証ハンドルを入力してください。

返り値：feature length

stid_facepro_verify_compare_feature

機能：顔を1:1比較することができます。

定義：

ST_SDK_API
st_result_t stid_facepro_verify_compare_feature(
    st_handle_t verify_handle,
    const char *_feature_str1,
    const char *_feature_str2,
    float *score
);

引数：

• [In]verify_handle：初期化済みの顔認証ハンドル

• [in]_feature_str1：1枚目画像中の顔特徴コード

• [in]_feature_str2：2枚目画像中の顔特徴コード

• [Out]score：特徴類似度スコア（スコア範囲：0～1）。2つの顔の類似度はスコアに正比例します。類似度スコアに対してしきい値を低く設定すると、2つの顔が同じ人物と判断する結果が多くなり、しきい値を高くすると同じ人物の2枚の顔写真を異なる人物と判断する場合が増えます。 JCVはしきい値の設定値として「0.8」を推奨します。用途に合わせて、しきい値を調整してください。

返り値：

• [return]：正常の場合はSTID_OKが表示されます（エラーになった場合はエラーコードが表示されます）。

stid_facepro_verify_search_face_from_list

機能：1組の特徴アレイから顔を検索できます（1組のアレイに対して数量制限があるので、最大数を超えないように使用してください）。顔特徴アレイの数量制限は、サービス契約条件によります。

定義：

ST_SDK_API
st_result_t stid_facepro_verify_search_face_from_list(
    st_handle_t verify_handle,
    char *const *list_feature,
    int list_count,
    const char *query,
    unsigned int top_k,
    int *top_idxs,
    float *top_scores,
    unsigned int *result_length
);

引数：

• [In]verify_handle：初期化済みの顔認証ハンドル

• [In]list_feature：顔特徴情報のアレイ

• [In]list_count：顔特徴情報の数（契約時の最大数より小さい数字を入力してください）

• [In]query：検索する顔特徴の情報

• [in]top_k：検索できる顔の最大数

• [out]top_idxs：顔検索結果のインデックスのアレイ（ユーザーで割り当て及び解放を行います）

• [out]top_scores：顔類似度スコアアレイ（ユーザーにより割り当て及び解放を行う） スコア範囲：0～1、類似度はスコアに正比例します。

• [out]result_length：実際に検索された顔の数

返り値：

• [return]：正常の場合はSTID_OKが表示されます（エラーになった場合はエラーコードが表示されます）

stid_facepro_verify_release_feature

機能：顔特徴の保存スペースを解放できます。

注意：

それぞれの顔特徴を使用後、リソースを解放するためにこのAPIを呼び出してください。

定義：

ST_SDK_API
void stid_facepro_verify_release_feature(
    const unsigned char *feature
);

引数：

• [in]feature：取得した顔特徴情報

返り値：ありません。