画像

画像（image）は、すべての画像アップロード APIで必須のJSON形式のフィールドです。画像フィールドは、デコードされた画像データと多彩なオプションにより構成されます。それらを利用して、さまざまな利用目的を満たすことができます。検出APIの顔検出動作を除いて、他のすべての画像関連APIでは、同じような機能が提供されています。

📘

モデルについて

このページは、最初の顔モデル「JCV_FACE_K25000」の仕様に基づいています。新しいモデルでは詳細が異なる場合があります。
今後、モデルの詳細を表示するインターフェースをいくつか提供する予定です。

画像要件

入力画像にはいくつかの要件があります。

• 画像ファイルのフォーマットは、JPG、PNG、GIFのいずれかであること（GIF を使用する場合、最初のフレームのみが処理されます）。
• 画像エンコード（Base64）のサイズは、約5MB未満であること(API ゲートウェイでの各リクエストによって制限されます)。
• 顔のサイズ（検出エリアで定義）は、32x32ピクセル以上で、画像全体の幅と高さの10%以上であること。
• 画像は白黒でないこと。

📘

写真ファイルのサイズについて

画像ファイルサイズの選定は、精度と遅延の妥協です。画像ファイルのサイズが大きいほど、顔の品質が高くなり、顔認識の精度が高くなります。一方、画像が大きいほど処理に時間がかかるため、遅延が増大します。

ベストプラクティスとして、顔のサイズが200x200ピクセルを超える高品質、正面の画像を使用することを推奨します。また、デコードする前に、画像をトリミングして200KB未満に圧縮することを推奨します。

画像データ

APIで送信されるすべての画像データは、base64でエンコードする必要があります。AnySeeでは、その機能を提供しません。ご自身のサービスに実装してください。ここでは、base64エンコーディングの2つの簡単な例を提供します。

import base64

# ファイルを読み取り、バイナリをbase64文字列に変換
def base64_encode_file(file_path):
    handle = open(file_path, "rb")
    raw_bytes = handle.read()
    handle.close()
    return base64.b64encode(raw_bytes).decode("utf-8")

$ base64 file_path

📘

画像ファイルの保存について

AnySeeでは、ユーザーがアップロードした画像ファイルまたは画像データは、いかなる状況でもどこにも保存されません。Base64エンコードされた画像データは、検出または特徴抽出後に即破棄されます。調査目的のため画像ファイルが必要な場合は、画像データベースを独自で構築する必要があります。

エンコードされた文字列は、文字列値としてimage.dataフィールドに入れてください。省略したりNullにしたりすると、エラーが発生します。以下は短縮された例です。

{
  "image": {
    "data": "/9j/4AAQSkZJRgAB="
  }
}

エリアと検出

AnySee は、画像内の検出エリアを長方形で絞り込むことができます。areaフィールドに4つの整数値を使用して指定できます。

{
	"area": {
    "top": 0,
    "left": 0,
    "width": 1000,
    "height": 1000
  }
}

このareaフィールドが設定されている場合、顔検出モデルは、長方形の検出エリアと重なっている顔のみ検出・処理します。 顔エリアの定義については、位置を参照してください。

顔検出ロジックは、画像が必要なAPI間でわずかに異なります。顔検出APIは、画像内（エリア指定ある場合は検出エリア内）のすべての顔を検出します。他のAPIは、画像内（エリア指定ある場合は検出エリア内）の最大の顔のみを検出・処理します。

AnySeeには2つの検出モデルがあります。一つの顔のみ検出必要がある「高速モデル」と、複数の顔を検出する必要がある「低速モデル」となります。異なるAPIは、応答時間と検出精度を最適化するため、異なる検出ロジックを使用しています。そのため、位置と角度などの詳細な顔情報にわずかな違いが生じます。

自動回転

🚧

リソースを消費するプロセス

このオペレーションは、標準のリクエストよりも余分なリソースを消費するため、遅延が高くなります。
機能を十分に理解した上でご利用ください。

画像のExif（エクスチェンジャブル・イメージ・ファイル・フォーマット）メタデータに画像の向き情報が含まれている場合があります。通常、OSは画像を表示するときにExif情報に従って自動的に向きを調整するため、画像が縦向きになっていることを誤解されやすいです。これらの画像をそのままエンコードされてサービスに送信されると、多くの場合では、モデルが認識できず、顔が見つからないエラーを返します。まれに、間違った向きの画像がモデルによって受け入れられ、誤って処理される可能性があります。その場合の認識精度は保証できません。

間違った向きの画像を入力することを避けるために、画像データを送信するときにautoRotateフィールドをtrueに指定することで、システムは画像を正しい向きで自動的に調整して処理できます。

📘

画像の登録時に自動回転を推奨します

お客様のシステムまたはアプリケーション側が入力画像を制御できないか、画像の前処理機能を持たない場合、自動回転機能を有効にすることを推奨します。特に顔データ追加のAPIを使用する場合は有効です。

レスポンスの詳細

AnySeeは、パワフルな顔認識機能を提供しています。一部のユーザーにとっては、全部の応答本文が冗長だと感じることがあります。また、各認証モジュールの処理に時間がかかり、ユーザー体験に影響します。当社のサービスでは、ユーザーが希望する詳細情報の種類を選択できるため、遅延とレスポンス内容を最適化できます。

returnDetailsフィールドには5つのオプションがあり、すべてが既定falseのブール値です。顔の詳細情報は、対応するフィールドがtrueに設定されている場合にのみ返されます。全部の情報を返す必要がある場合は、次のようにリクエストしてください。

{
	"returnDetails": {
    "position": true,
    "angle": true,
    "landmarks": true,
    "quality": true,
    "attributes": true
	}
}

位置、角度、ランドマーク

顔のアライメントとポーズは、顔特徴量と属性情報の抽出にとって、必要な手順です。位置、角度、ランドマークの3種類の出力は、高度な画像処理に役立ちます。returnDetailsのフィールドでレスポンスの個別指定を設定できます。

位置

positionフィールドには、顔認識の際に顔の位置を指定するエリアの4つの整数値により構成されます。topとleftの値は、左上の座標点のピクセル値となります。widthとheightの値を使用すると、画像内で顔エリア位置の長方形を指定できます。

上記の顔エリアの例から、額や耳など、顔認識のためにすべての顔パーツが必要とされていないことがわかります。逆に、顔エリア内の顔パーツは重要です。顔エリア内の顔パーツの遮蔽などの評価詳細については、品質情報を参照してください。

角度

「ポーズ」または「ヘッドポーズ」とも呼ばれる角度（angle）は、ピッチ（pitch）、ヨー（yaw）、ロール（roll）の名前で、顔が空間直交座標系のxyz軸からどのぐらいずれているかを評価する一連の値です。

これらの3つのパラメータの説明は次のとおりです。

これら3つの軸に加えて、複数の顔の画像内の幾何中心点を簡単に特定するために、2つの追加フィールドcenterXおよびcenterYもレスポンスされます。

ランドマーク

ランドマークは、顔のパーツを位置決めするためのポイントの集合です。各ランドマークポイントには、平面直交座標系の座標ポイントのピクセル値を表す整数のxとyにより構成されます。ランドマークは、AR（拡張現実）で顔に装飾を追加するシーンによく使用されます。AnySeeでは、106ポイントのランドマーク体系を使用しています。

レスポンスで返されるランドマークポイントの順序は、次の表に従います。

📘

左右について

こちらでの「左」と「右」は、画像における目と眉の位置を意味し、個人の視点からのものではありません。

各ランドマークの位置は、こちらの画像例も参照できます。

品質情報

🚧

リソースを消費するプロセス

このオペレーションは、標準のリクエストよりも余分なリソースを消費するため、遅延が高くなります。
機能を十分に理解した上でご利用ください。

品質チェックは、顔を分析して、サイズ、明るさ、鮮明さ、遮蔽の度合いなどの定量情報を返します。より高い認識精度を得るために、顔データを追加する前に品質チェックを実行することを推奨します。

お客様の利用シーンに基づいて許容レベルをテスト・調整を行ってください。次の表は、各項目の詳細と、少々厳しめの基準の参考値について記載しています。

属性情報

🚧

リソースを消費するプロセス

このオペレーションは、標準のリクエストよりも余分なリソースを消費するため、遅延が高くなります。
機能を十分に理解した上でご利用ください。

AnySee は、最新のAIアルゴリズムを利用して有用な顔属性を抽出し、ユーザーが訪問者のデータを分析できるようにします。すべての値は推定値であるため、それらを事実の値として扱わないでください。

ageとemotionsを除いて、すべてのサブ項目には、1つ列挙文字列のvalueフィールドと、0.0から1.0の確実性（certainty）フィールドが含まれます。年齢（age）には3つの項目があり、上限（upperlimit）は年齢予測の最大値です。下限（lowerlimit）は上限から10を引いた値に等しく、推定値（value）は上限から5を引いた値に等しくなります。感情（emotions）フィールドには、8つのサブ項目とそれぞれの確実性（certainty）が含まれます。