Visual Object Tracking

Classic/VPC 환경에서 이용 가능합니다.

오브젝트(객체)에 대한 기본 정보와 포즈 추정 결과를 조회합니다.

사전 단계

ARC eye VOT API를 사용하기 위한 사전 단계는 다음과 같습니다.

1. 오브젝트(객체) 생성

콘솔에서 오브젝트(객체)를 생성합니다. 자세한 생성 방법은 ARC eye 사용 가이드를 참조해 주십시오.

2. API 배포

오브젝트(객체)를 생성하면 네이버 클라우드 플랫폼 콘솔의 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	이미지를 촬영한 디바이스의 고유 식별자 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 클라이언트에서 인식된 영상 아이디
`imgid`	String	Optional	VOT 클라이언트에서 인식된 이미지 아이디
`keyframeid`	String	Optional	VOT 클라이언트에서 인식된 키프레임 아이디

요청 예시

요청 예시는 다음과 같습니다.

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	-	포즈 추정을 수행한 프로젝트 아이디
`recvtime`	Number	-	Poser(포즈 추정)가 Detector(오프젝트 검출)의 요청 수신 시점(밀리초) Unix Timestamp 형식
`timestamp`	Number	-	요청 시 사용된 이미지의 생성 시간(밀리초) Unix Timestamp 형식
`uuid`	String	-	요청 시 사용된 디바이스의 고유 식별자 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	-	포즈 추정에 사용된 오브젝트 아이디
`pose`	Array(4,4)	-	오브젝트의 위치 및 방향 좌표
`poserid`	String	-	포즈 추정을 수행한 영상 아이디(`videoid` 또는 `objectid`와 동일)
`projectid`	String	-	오브젝트가 속한 프로젝트 아이디
`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	-	후보 오브젝트 아이디 값이 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 개요를 참조해 주십시오.