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

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

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 3 years ago

Was this helpful?