JCV属性分析SDK マニュアル (Java for Android)
目次
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」を「1」に設定した時のみ、
# 「function_switch_body_attribution」および
# 「function_switch_body_image_crop」が「1」に設定可能です。
function_switch_body_track=0
# 身体属性取得の有効化 (デフォルト:0)
# 「function_switch_body_track」を「1」に設定した場合のみ、
# このアイテムは「1」に設定可能です。
function_switch_body_attribute=0
#身体イメージクロップ機能の有効化(デフォルト:0)
#「function_switch_body_track」を「1」に設定した場合のみ、
# このアイテムは「1」に設定可能です。
function_switch_body_image_crop=0
#
# 注視機能設定
# 「function_switch_face_watch」を「1」に設定した場合、
# 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 //1ユーザに対して、複数顔トラックした際に統計情報作成の際にマージする時間範囲
.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
なぜAPI”currentTrackingFace“実行時に、顔データを取得できないのでしょうか?
A: データの取得が失敗した場合、SDKが正常に初期化したかをチェックしてください。
その後、デバイスとの接続モジュールをチェックし、最後に、カメラが正しい向きであることをチェックする。
インタ-フェース”currentTrackingFace”を同時に複数のスレッドに呼びだすことが可能でしょうか?
A: こちらのインターフェースはシングルスレッドのみの対応となります。
リリースした後のSDKの再初期化は可能でしょうか?
A: 再初期化は実行可能です。
インターフェース“currentTrackingface”から取得した顔属性は空である場合があります。
A: 属性を抽出する際、SDKは認識した顔のクオリティを基づいて判断します。
クオリティを満たさない場合は、属性を取得できない場合があります。
高いクオリティスコアの顔情報を取得できる場合のみ、属性を取得することが出来ます。
インターフェース“currentTrackingFace”を呼び出頻度およびシチュエーションについて教えて下さい。
A: 以下の例がインターフェースを呼び出し頻度となります。
- 1. チルドスレッドは30msごとに呼び出し、取得データはスクリーンに表示させる。
- 2. カルセールしている間、1秒ごとに顔データを取得する際に呼び出す。
- 3. 1つイベント(例えば、1つの購入イベント)が発生した時、カレントスクリーン前の顔データを取得するために呼び出す。
EOF
Last updated
Was this helpful?