Visual Object Tracking

Classic/VPC環境で利用できます。

オブジェクト(物体)の基本情報と姿勢推定の結果を照会します。

事前段階

ARC eye VOT APIを使用するための事前段階は次の通りです。

1. オブジェクト(物体)の作成

コンソールでオブジェクト(物体)を作成します。詳細は、ARC eyeご利用ガイドをご参照ください。

2. APIのデプロイ

オブジェクト(物体)を作成すると、NAVERクラウドプラットフォームコンソールの ARC eye > Visual Object Tracking > API メニューに待機状態の APIが作成されます。その APIを選択してデプロイします。完了状態でデプロイが完了すると、ARC eye VOT APIを使用できます。
デプロイ方法の詳細は、ARC eyeご利用ガイドをご参照ください。

リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

メソッド	URI
POST	InvokeURL

リクエストヘッダ

ARC eye APIで共通して使用されるヘッダの詳細は、ARC eyeのリクエストヘッダをご参照ください。

リクエストボディ

リクエストボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`image`	File	Required	物体検出実行対象の RGB画像画像ファイルの拡張子: jpg、png
`uuid`	String	Required	画像を撮影したデバイスの固有 ID UUID形式
`timestamp`	Number	Required	画像の開始時間(ミリ秒) Unix Timestamp形式
`intrinsic`	String	Required	姿勢推定に使用されたカメラ intrinsicパラメータ
`distort`	String	Required	姿勢推定に使用されたカメラ distortionパラメータ
`gravity`	String	Optional	姿勢推定に使用された重力方向入力しないと`extrinsic`で計算した値を使用
`extrinsic`	String	Required	姿勢推定に使用されたカメラと座標系間の位置と方向(回転と移動)
`videoid`	String	Optional	VOTクライアントが認識した映像 ID
`imgid`	String	Optional	VOTクライアントが認識した画像 ID
`keyframeid`	String	Optional	VOTクライアントが認識したキーフレーム ID

リクエスト例

リクエストのサンプルコードは次の通りです。

curl --location --request POST '{InvokeURL}' \
--header 'X-ARCEYE-SECRET: {SecretKey}' \
--header 'Content-Type: multipart/form-data' \
--form 'image=@object.jpg \
--form 'uuid=a4315b63-2d64-11ef-becb-005056a70a22' \
--form 'timestamp=1718709558076' \
--form 'intrinsic=1524.3942260742188,0.0,539.0464782714844,0.0,1524.3942260742188,950.2188720703125,0.0,0.0,1.0' \
--form 'distort=0.0,0.0,0.0,0.0,0.0' \
--form 'extrinsic=-0.5501050024473961,-0.03056710354932507,-0.834535882070361,-0.2494854635652485-0.42819610313094764,0.8682865385146257,0.25045275861479593,-0.16543658916848714,0.7169606569023306,,0.495120328016226,-0.4907374830184501,0.189104661569504620.0,0.0,0.0,1.0'

レスポンス

レスポンス形式を説明します。

レスポンスボディ(成功)

照会に成功した場合のレスポンスボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`result`	String	-	レスポンス結果 `SUCCESS` \| `FAILURE` \| `ERROR` `SUCCESS`: 成功 `FAILURE`: 失敗 `ERROR`: エラー
`version`	String	-	ARC eye VOT APIデプロイバージョン
`projectid`	String	-	姿勢推定を行ったプロジェクト ID
`recvtime`	Number	-	Poser(姿勢推定)が Detector(物体検出)リクエストを受信した時点(ミリ秒) Unix Timestamp形式
`timestamp`	Number	-	リクエスト時に使用された画像の作成時間(ミリ秒) Unix Timestamp形式
`uuid`	String	-	リクエスト時に使用されたデバイスの固有 ID UUID形式
`status`	Number	-	検出の状態コード
`message`	String	-	検出状態メッセージ
`objects`	Array	-	姿勢推定に使用された物体情報
`flpose`	Array	-	対象の物体を利用して計算されたユーザー姿勢

`objects`

objectsの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`bbox2d`	Array(4,2)	-	姿勢推定のために提供された Detectorの検出 ROI(Region of Interest) 画像上の物体の境界を表す2Dバウンディングボックス座標
`conf_thresh`	Number	-	検出された物体の信頼度のしきい値 0に近いほど信頼度が低く、1に近いほど信頼度が高い
`corners2d`	Array(9,2)	-	3D object bounding boxに対応する2D画像座標
`corners3d`	Array(9,3)	-	3D空間で(0,0)を中心とした3D object bounding boxの座標
`distort`	Array(5)	-	姿勢推定に使用されたカメラレンズの歪み情報
`extrinsic`	Array(4,4)	-	姿勢推定に使用されたカメラと座標系間の位置と方向(回転と移動)を表す座標
`global_pose`	Array(4,4)	-	グローバル座標系における物体の位置と方向を表す座標
`global_prob`	Number	-	グローバル姿勢推定の信頼度 0に近いほど信頼度が低く、1に近いほど信頼度が高い
`intrinsic`	Array(3,3)	-	姿勢推定に使用したカメラの焦点距離(focal length)、光心(optical center)などの内部特性を表す座標
`message`	String	-	物体の姿勢推定状態情報
`obj_prob`	Number	-	物体検出の信頼度 0に近いほど信頼度が低く、1に近いほど信頼度が高い
`objid`	String	-	姿勢推定に使用された物体 ID
`pose`	Array(4,4)	-	物体の位置と方向座標
`poserid`	String	-	姿勢推定を行った映像 ID(`videoid`または`objectid`と同じ)
`projectid`	String	-	物体が属するプロジェクト ID
`sim_prob`	Number	-	物体とモデル間の類似信頼度 0に近いほど信頼度が低く、1に近いほど信頼度が高い
`size`	Array(3)	-	物体のサイズ情報順に width、height、depth
`status`	boolean	-	物体の姿勢推定の状態 `True` \| `False` `True`: 姿勢推定成功 `False`: 姿勢推定失敗
`type`	String	-	物体のタイプ

レスポンスボディ(失敗)

照会に失敗した場合のレスポンスボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`result`	String	-	レスポンス結果 `SUCCESS` \| `FAILURE` \| `ERROR` `SUCCESS`: 成功 `FAILURE`: 失敗 `ERROR`: エラー
`running_time`	Object	-	処理時間情報
`running_time.processing`	Number	-	処理時間(ミリ秒)
`timestamp`	Number	-	リクエスト時に使用された画像の作成時間(ミリ秒) Unix Timestamp形式
`version`	String	-	ARC eye VOT APIデプロイバージョン
`candidate_obj_id`	Number	-	候補の物体 ID 値が0の場合、候補の物体がないことを意味

レスポンスステータスコード

ARC eye VOT APIで共通して使用されるレスポンスステータスコードの詳細は、ARC eyeのレスポンスステータスコードをご参照ください。

レスポンス例

レスポンスのサンプルコードは次の通りです。

成功

照会に成功した場合のレスポンスのサンプルコードは次の通りです。

{
    "result": "SUCCESS",
    "version": "3.0.0-1",
    "projectid": "123",
    "recvtime": 1712213062.4720848,
    "timestamp": 1712213062.2513185,
    "uuid": "933ec42646f8",
    "status": 0,
    "message": "VOT_DETECTOR_SUCCESS",
    "objects": [
        {
            "bbox2d": [[677.0, 1472.0], [1466.0, 1472.0], [1466.0, 2861.0], [677.0, 2861.0]],
            "conf_thresh": 0.3,
            "corners2d": [[1048, 2119], [746, 2513], [726, 1473], [715, 2864], [686, 1564], [1297, 2500], [1335, 1477], [1408, 2842], [1472, 1568]],
            "corners3d": [[0.0, 0.0, 0.0],
                [-0.29031120781734804, -0.5381274223327637, -0.3174518426978675],
                [-0.29031120781734804, 0.5381274223327637, -0.3174518426978675],
                [-0.29031120781734804, -0.5381274223327637, 0.3174518426978675],
                [-0.29031120781734804, 0.5381274223327637, 0.3174518426978675],
                [0.29031120781734804, -0.5381274223327637, -0.3174518426978675],
                [0.29031120781734804, 0.5381274223327637, -0.3174518426978675],
                [0.29031120781734804, -0.5381274223327637, 0.3174518426978675],
                [0.29031120781734804, 0.5381274223327637, 0.3174518426978675]],
            "distort": [0.0, 0.0, 0.0, 0.0, 0.0],
            "extrinsic": [[-0.2429226121477801, -0.2506293885132776, 0.9371091260471003, 0.0],
                [-0.009911837278829036, 0.9666372782061301, 0.2559572774195017, 0.0],
                [-0.9699950309094669, 0.05288933725909484, -0.23730225033748942, 0.0],
                [0.012476532015234023, 0.021933435026800476, 0.024992155870001847, 1.0]],
            "global_pose": [[1.0, 0.0, 0.0, 0.0],
                [0.0, 1.0, 0.0, 0.0],
                [0.0, 0.0, 1.0, 0.0],
                [0.0, 0.0, 0.0, 1.0]],
            "global_prob": 1.0,
            "intrinsic": [[2834.314, 0.0, 1093.1019], [0.0, 2834.314, 1933.7009], [0.0, 0.0, 1.0]],
            "message": "VOT_OBJECT_POSE_SUCCESS",
            "obj_prob": 1.0,
            "objid": "rookie",
            "pose": [[0.9968414902687073, 0.014719659462571144, 0.0780409649014473, -0.03976171463727951],
                [-0.006204552017152309, -0.9652349948883057, 0.26131001114845276, 0.16608235239982605],
                [0.07917426526546478, -0.2609688639640808, -0.9620949625968933, 2.5332860946655273],
                [0.0, 0.0, 0.0, 1.0]],
            "poserid": "14dfc56c-a640-4281-9e95-aa49b61d51bd",
            "projectid": "b385865f-67f3-4341-aca5-166d20df952b",
            "sim_prob": 0.9999999255277782,
            "size": [0.5806224156346961, 1.0762548446655273, 0.634903685395735],
            "status": True,
            "type": "normal"
        }
    ]
    "flpose": [[0.9999973932548811, -0.001259764878431, -0.0019043308258140002, 5.813885266846625], ....], 
}

失敗

照会に失敗した場合のレスポンスのサンプルコードは次の通りです。

{
  "result": "FAILURE",
  "running_time": {
    "processing": 2
  },
  "timestamp": 1718709558076,
  "version": "3.0.0-1",
  "candidate_obj_id": 0
}

参考

API呼び出しに失敗した場合のレスポンスボディとレスポンスのサンプルコードは、ARC eyeの概要をご参照ください。