JCV属性分析SDK マニュアル (Java for Android）

目次

改訂履歴 2

1 概要 2

1.1 導入前準備 2

1.2 SDK説明 2

2 SDKインテグレーション 3

2.1 “AndroidManifest.xml”ファイル設定 3

2.2 SDKの導入 3

2.3 SDKの初期化 4

2.4 SDKのリリース 4

2.5 SDK初期化に関する詳細パラメータの説明 5

2.6 SDK設定 5

3 APIの説明 8

3.1 offer 8

3.2 setConfig 8

3.3 currentTrackingFace 9

3.4 facesOfPastTimeRange 9

3.5 currentTrackingBody 9

4 タイプの説明 10

4.1 TrackingFace 10

4.2 Face Attribute 10

4.3 Face 10

4.4 TrackingBody 11

4.5 BodyAttribute 11

4.5 コードテーブル 12

5 難読化コード 13

6 FAQ 14

改訂履歴

バージョン	改訂日	改訂箇所
V2.0.0	2019-12-3	First release of GE (Global Edition).
V2.0.1	2019-12-18	Delete InsightFaceAttribute.
V2.0.2	2019-12-23	Fix minor issues.

1. 概要

1.1 導入前準備

SDKパッケージ中にはSDKインテグレーション用“aar”ファイルとサンプルプログラムが含まれております、ご確認ください。

1.2 SDK説明

JCV属性分析SDKはオフライン店舗における、顧客の行動分析の提供をコンセプトに開発されたSDKです。オフライン店舗において、顧客の行動分析情報を提供することで、購買体験を最適化し、顧客へ提供する情報の精度およびパーソナルサービスの効率向上を実現します。

2. SDKインテグレーション

2.1 “AndroidManifest.xml”ファイル設定

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.CAMERA"/>

2.2 SDKの導入

1 SDKの“aar”ファイルを“module”下にある“libs”フォルダに入れてください。

2 導入するSDKの“module“下にある”build.gradle“を次ように変更する。

android {
    ...
    repositories {
        flatDir {
            dirs 'libs' // 「aar」ディレクトリ
        }
    }
}
dependencies {
    ...
    //insight sdk
    implementation(name: 'ST SenseInsight Android service SDK -GE V2.0.2', ext: 'aar')
    implementation 'com.squareup.retrofit2:retrofit:2.4.0'
}

2.3 SDKの初期化

SDKParams params = SDKParams.builder()
    .context(this.getApplicationContext())
    .licensePath("dev_license.lic")// ライセンスファイルパス：「assets」または「sdcard」
    .businessConfigPath(businessPath)
    .build();
InsightSDK.init(params, new SDKInitCallback() {
    @Override
    public void success() {
        Log.i("TAG", "insight sdk init success !");
    }

    @Override
    public void failed(int code, String msg) {
        Log.i("TAG", "insight sdk init failed : code " + code + "msg" + msg);
    }
});

2.4 SDKのリリース

InsightSDK.release();

2.5 SDK初期化に関する詳細パラメータの説明

//オプショナルパラメータ
HashMap<String, String> modelsConfig = new HashMap<>();
modelsConfig.put(SDKModels.KEY_FACE_ALIGN,
    "M_Align_occlusion_106_1.16.4.model");
modelsConfig.put(SDKModels.KEY_FACE_ATTRIBUTE,
    "M_Attribute_Face_Advertisement_3.5.0.model");
modelsConfig.put(SDKModels.KEY_FACE_DETECT,
    "MM_ObjectFlow_Face_SenseInsight_Common_BGR_1.0.1.model");
modelsConfig.put(SDKModels.KEY_FACE_VERIFY,
    "M_Verify_VehicleFace_Common_2.47.0.model");
modelsConfig.put(SDKModels.KEY_HEAD_POSE,
    "M_Align_CalcPose_Ann_106_2.4.0.model");
modelsConfig.put(SDKModels.KEY_BODY_DETECT, 
    "M_Detect_Body_Hunter_1.5.0.model");
modelsConfig.put(SDKModels.KEY_BODY_ALIGN,
    "M_Detect_Body_Keypoints_5.0.17.model");
modelsConfig.put(SDKModels.KEY_BODY_ATTRIBUTE,
    "M_Attribute_Body_Fir_1.1.0.model");
SDKModelConfig sdkModelConfig = SDKModelConfig.builder()
    .modelDirPath("model")// 「assets」 または 「sdcard」 パス
    .modelsConfig(modelsConfig)
    .build();

2.6 SDK設定

#
# SDK機能スイッチ (0の場合: 起動しない 1の場合: 起動する)
#
# 顔属性取得の有効化 (defaults:1)
function_switch_face_attribute=1
# 注視機能の有効化 (defaults: 1)
function_switch_face_watch = 1
# 顔イメージクロップ機能の有効化(defaults:1)
function_switch_face_image_crop=1
#  統計用の顔認証を用いたユーザマージ機能の有効化 (デフォルト:1)
function_switch_face_recognition=1
# 統計用の身体検出とトラキング機能の有効化 (デフォルト:0)
# 「function_switch_body_track」を「１」に設定した時のみ、
# 「function_switch_body_attribution」および
# 「function_switch_body_image_crop」が「1」に設定可能です。
function_switch_body_track=0
# 身体属性取得の有効化 (デフォルト:０)
# 「function_switch_body_track」を「１」に設定した場合のみ、
# このアイテムは「1」に設定可能です。
function_switch_body_attribute=0
#身体イメージクロップ機能の有効化(デフォルト：0)
#「function_switch_body_track」を「１」に設定した場合のみ、
# このアイテムは「1」に設定可能です。
function_switch_body_image_crop=0
#
# 注視機能設定
# 「function_switch_face_watch」を「１」に設定した場合、
# SDK顔注視設定中のアイテムは有効である。
# function_switch_face_watch is set to 1.
#
# 水平方向の注視範囲の注視におけるネガティブ値
key_parameter_negative_yaw=-20
# 水平方向の注視範囲の注視におけるポジティブ値
key_parameter_positive_yaw=20
# 垂直方向の注視範囲におけるネガティブ値
key_parameter_negative_pitch=-10
# 垂直方向の注視範囲におけるポジティブ値
key_parameter_positive_pitch=30
#
# SDK key パラメータ設定
#
#0: 顔属性を一定期間毎の呼び出しを実行しない
#1: 顔属性を一定期間毎の呼び出しを実行する (デフォルト: 0)
#このパラメータが「1」に設定された場合、
# 「key_parameter_face_attribution_times」が無効になり、
# 「key_parameter_face_attribution_period」が有効になる。
key_parameter_timed_face_attribute=0
# 顔属性を呼び出す間隔時間。単位：ms（デフォルト：1000）、有効範囲：[1000, 60000]
key_parameter_face_attribute_period=1000
#顔クオリティスコアの最小値。
#1ユーザの顔トラックのおける顔イメージクオリティがこの値以上である場合
#のみ、顔属性または顔照合が呼び出されるか、イメージがトリミングされる。（デフォルト：0.3）有効範囲：[0.1, 0.5]
key_parameter_min_face_quality=0.3
#顔クオリティスコアの増加値。1ユーザの顔トラックにおいて、前のイメージクオリティスコアより一定量以上
#増加したクオリティスコアを持つ新しいイメージに対し、再度、顔属性/顔照合が呼び出されるか
#顔イメージがトリミングされる（デフォルト：0.2）有効範囲：[0.1, 0.5]
key_parameter_incremental_face_quality=0.2
# 身体クオリティスコアの最小値。1つの身体トラックのおける身体イメージクオリティがこの値以上である
# 場合のみ、身体属性が呼び出される、またはイメージがトリミングされる。（デフォルト：0.3）有効範囲：[0.1, 0.5]
key_parameter_min_body_quality=0.3
# 身体クオリティスコアの増加値。1ユーザの身体トラックにおいて、前のイメージクオリティスコアより一定量
# 以上増加したクオリティスコアを持つ新しいイメージに対し、再度、身体属性/身体照合が呼び出されるか
# 顔イメージがトリミングされる（デフォルト：0.2）有効範囲：[0.1, 0.5]
key_parameter_incremental_body_quality=0.2
# 同一人物の複数顔を統計のためにマージする時間の範囲。単位：min、有効範囲：[1 , 86400]
key_parameter_face_merge_time_range=5
# 顔認証類似スコアの閾値、有効範囲：[0, 1]
key_parameter_face_similarity_threshold=0.6

3. APIの説明

3.1 offer

InsightSDK.service().offer();

3.2 setConfig

// SKDを初期化した後、操作途中に、初期化せずパラメータのアップデートを行えます。

// カメラプレビューの幅と高さの設定。

InsightSDK.config().setPreviewSize(cameraPreviewWidth, cameraPreviewHeight);

//デバッグモードの設定。デバッグモードでは、より詳細なログが利用可能

InsightSDK.config().setDebugMode(true);

// SDK Keyパラメータの設定。

SDKConfig build = SDKConfig.builder()
    .timedFaceAttribute(1)// 顔属性を一定期間毎の呼び出しを実行する
    .faceAttributionPeriod(1000)// 顔属性呼び出すの時間間隔。
    .faceMergeTimeRange(5) // 単位: min //１ユーザに対して、複数顔トラックした際に統計情報作成の際にマージする時間範囲
    .incrementalFaceQuality(0.2f)// 1ユーザの顔トラックにおいて、前のイメージクオリティスコアより
        //一定量以上増加したクオリティスコアを持つ新しいイメージに対し、再度、顔属性/顔照合が
        //呼び出されるか顔イメージがトリミングされる
    .incrementalBodyQuality(0.2f)// 1ユーザの身体トラックにおいて、前のイメージクオリティスコアより一定量以上増加したクオリティスコアを持つ新しいイメージに対し、再度、身体属性/身体照合が呼び出されるか顔イメージがトリミングされる（デフォルト：0.2）
    .minBodyQuality(0.3f)// 1つの身体トラックのおける身体イメージクオリティがこの値以上である
        //場合のみ、身体属性が呼び出される、またはイメージがトリミングされる。
    .minFaceQuality(0.3f)// 1つの身体トラックのおける身体イメージクオリティがこの値以上である
        //場合のみ、身体属性が呼び出される、またはイメージがトリミングされる。
     .build();

InsightSDK.config().setSDKKeyParameterConfig(build);
InsightSDK.config().enableFaceAttribute(true);
InsightSDK.config().enableFaceWatch(true);
InsightSDK.config().enableFaceImageCrop(true);
InsightSDK.config().enableFaceRecognition(true);
InsightSDK.config().enableBodyTrack(true);
InsightSDK.config().enableBodyAttribute(true);
InsightSDK.config().enableBodyImageCrop(true);

3.3 currentTrackingFace

//現在の顔情報を取得。
List<TrackingFace> trackingFaces =InsightSDK.service().currentTrackingFace();

3.4 facesOfPastTimeRange

// 過去一定の時間範囲内の顔情報（ユーザマージ済み）を取得。
// The following forms are equivalent for calling.

long now = System.currentTimeMillis();
List<Face> faces = InsightSDK.service().facesOfPastTimeRange(now - 3000, now);

List<Face> faces = InsightSDK.service().facesOfPastTimeRange(3000);

3.5 currentTrackingBody

//現在の身体情報を取得
List<TrackingBody> trackingBodies = InsightSDK.service().currentTrackingBody();

4. タイプの説明

4.1 TrackingFace

フィールド名	フィールド種類	フィールド説明
trackingFaceId	int	Face track id（ユーザマージ前）
faceId	int	Face id（ユーザマージ後）
enter	long	チェックイン時刻
leave	long	チェックアウト時刻
gender	String	性別（M：男性；F：女性）
age	int	年齢
quality	float	顔認識クオリティスコア（0-1）
faceRect	Rect	顔検知時のフレーム
watchTime	long	注視時間（ms）
expression	String	表情
glasses	int	メガネ（0：利用せず；1：メガネ；2：サングラス；-1：不明）
mask	int	マスク（0：no；1：yes；-1：不明）
smileScore	int	笑顔スコア
charmScore	int	魅力スコア
faceFeature	byte[]	顔の特徴量
faceImage	StImage	クロップされた顔画像
faceImageQuality	float	クロップされた顔画像のクオリティスコア
beard	int	ひげ（0：no；1：yes；-1：不明）
associateBodyTrackID	int	関連付けられたbody id

4.2 Face Attribute

フィールド名	フィールド説明	属性タグ	属性説明
expression	顔表情	others	その他
		happy	喜ぶ
		calm	穏やか

4.3 Face

フィールド名	フィールド種類	フィールド説明
faceId	int	face id（顔のユニークID）
gender	String	性別（M：男性；F：女性）
age	int	年齢
faceImage	StImage	クロップされた顔画像
watchTime	long	注視時間（ms）
otherEmotionTime	long	「喜び」と「穏やか」以外が検知された時間（ms）
calmEmotionTime	long	「穏やか」が検知された時間
happyEmotionTime	long	「喜び」が検知された時間
glasses	int	メガネ（0：利用せず；1：メガネ；2：サングラス；-1：不明）
mask	int	マスク（0：マスク着用せず；1：マスク着用）
charmScore	int	魅力スコア
facefeature	byte[]	顔の特徴量
faceImageQuality	float	クロップされた顔画像のクオリティスコア
beard	int	ひげ（0：no；1：yes；-1：不明）

4.4 TrackingBody

フィールド名	フィールド種類	フィールド説明
trackId	int	身体トラックId
bodyQuality	float	身体クオリティ（0-1）
bodyRect	StRect	身体検知時のフレーム
associatedFaceTrackID	int	関連付けられたface id （-1：マッチする顔がない）
attribute	BodyAttribute	身体属性情報
age	String	年齢（成人、高齢者、児童）
gender	String	性別（M：男性；F：女性）
bodyImage	StImage	クロップされた身体画像

4.5 BodyAttribute

フィールド名	フィールド種類	フィールド説明
UpperClothing	String	上着の種類（半袖、長袖）
LowerClothing	String	パンツの種類（長ズボン、短パン、スカート）
UpperMode	String	上着の模様（単色、ストライプ、Design、Joint、Lattic）
LowerMode	String	パンツの模様（単色、ストライプ、Design、Joint、Lattic）
UpperType	String	上着のスタイル（ロングコート、ジャケット、Tシャツ、スポーツウェア、ダウン、シャツ、ドレス、スーツ）
UpperColor	String	上着の色（黒色、白色、灰色、赤色、黄色、青色、緑色、紫色）
LowerColor	String	パンツの色（黒色、白色、灰色、赤色、黄色、青色、緑色、紫色）
Age	String	年齢層（成人、高齢者、児童）
gender	String	性別（M：男性；F：女性）

4.5 コードテーブル

コード	説明
100	CODE_OK
101	reinit sdk
103	running error
104	params illegal
201	algorithm no detect face
202	algorithm sdk release
203	algorithm no feature
204	algorithm unknown img format
205	algorithm img decode failed
206	algorithm img size illegal
207	algorithm params illegal
208	algorithm pls_enable face recognition
210	algorithm st exception

5. 難読化コード

プロジェクトの難読化設定：次のように“proguard-rules.pro”内にコードを追加してください：

######insight sdk########
-keep class com.sensetime.** {*;}

########retrofit#######
#retrofit2 Obfuscation
-keepattributes Signature, InnerClasses, EnclosingMethod
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface <1>

# OkHttp3
-dontwarn javax.annotation.**
-keepnames class okhttp3.internal.publicsuffix.PublicSuffixDatabase
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn okhttp3.internal.platform.ConscryptPlatform

# Okio
-dontwarn org.codehaus.mojo.animal_sniffer.*

########Insight-Gson##########
-keepattributes Signature
-keepattributes *Annotation*
-keep class sun.misc.Unsafe { *; }
-keep class com.sensetime.insight.gson.** {*;}

6. FAQ

1. なぜAPI”currentTrackingFace“実行時に、顔データを取得できないのでしょうか？

A: データの取得が失敗した場合、SDKが正常に初期化したかをチェックしてください。

その後、デバイスとの接続モジュールをチェックし、最後に、カメラが正しい向きであることをチェックする。

1. インタ－フェース”currentTrackingFace”を同時に複数のスレッドに呼びだすことが可能でしょうか？

A: こちらのインターフェースはシングルスレッドのみの対応となります。

1. リリースした後のSDKの再初期化は可能でしょうか？

A: 再初期化は実行可能です。

1. インターフェース“currentTrackingface”から取得した顔属性は空である場合があります。

A: 属性を抽出する際、SDKは認識した顔のクオリティを基づいて判断します。

クオリティを満たさない場合は、属性を取得できない場合があります。

高いクオリティスコアの顔情報を取得できる場合のみ、属性を取得することが出来ます。

1. インターフェース“currentTrackingFace”を呼び出頻度およびシチュエーションについて教えて下さい。

A: 以下の例がインターフェースを呼び出し頻度となります。　

- 1. チルドスレッドは30msごとに呼び出し、取得データはスクリーンに表示させる。
- 2. カルセールしている間、1秒ごとに顔データを取得する際に呼び出す。
- 3. 1つイベント（例えば、1つの購入イベント）が発生した時、カレントスクリーン前の顔データを取得するために呼び出す。

EOF