손 추적

카메라 영상에서 손을 실시간으로 추적하여 21개 키 포인트(손가락 관절) 좌표를 제공합니다. 왼손·오른손 판별, 손가락 펴짐 상태, 제스처 인식을 포함합니다.

명령

명령	설명
손 감지	손이 감지되었는지 확인합니다.
키 포인트 좌표	지정한 키 포인트의 X, Y, Z 좌표를 기록합니다.
왼손/오른손 판별	감지된 손이 왼손인지 오른손인지 기록합니다.
손가락 상태	지정한 손가락이 펴졌는지 접혔는지 기록합니다.
영역내 손 여부	손이 감지 영역 안에 있는지 확인합니다.
영역내 키 포인트 여부	지정한 키 포인트가 감지 영역 안에 있는지 확인합니다.
키 포인트 간 거리	두 키 포인트 사이의 픽셀 거리를 기록합니다.
모든 키 포인트 읽기	21개 키 포인트의 좌표를 JSON 으로 기록합니다.
제스처 인식	21개 키 포인트의 배치로 손 제스처(예: 주먹, 브이, 엄지 들기)를 분류하여 이름과 ID 를 기록합니다.

설정

항목	설명
신뢰도 (%)	0~100, 기본값 50.
키 포인트	좌표를 읽거나 영역 안 여부를 확인할 키 포인트입니다. 21종 중에서 선택합니다.
키 포인트1 / 키 포인트2	거리를 계산할 두 키 포인트입니다.
손가락	상태를 확인할 손가락입니다. 엄지, 검지, 중지, 약지, 새끼 중에서 선택합니다.
감지 영역	공통 사항 참고.

출력 변수

항목	타입	값
감지 여부	디지털	손 감지, 키 포인트 좌표, 영역내 손 여부, 영역내 키 포인트 여부의 결과.
키 포인트 X / 키 포인트 Y / 키 포인트 Z	숫자	지정한 키 포인트의 좌표. X, Y 는 픽셀 좌표이고 Z 는 모델이 추정한 깊이 방향의 값입니다.
손 구분 값	숫자	왼손 0, 오른손 1, 구분할 수 없으면 -1.
손 구분 텍스트	텍스트	`left` 또는 `right`, 구분할 수 없으면 빈 문자열.
거리 (픽셀)	숫자	두 키 포인트 사이의 거리.
감지 여부	디지털	키 포인트 간 거리 명령에서 두 키 포인트가 모두 감지되어 거리를 계산했으면 참.
손가락 상태	숫자	접힘 0, 펴짐 1, 감지할 수 없으면 -1.
출력 (JSON 텍스트)	텍스트	21개 키 포인트의 배열.
제스처 이름	텍스트	인식된 제스처의 영문 이름. 미감지 시 `none`.
제스처 ID	숫자	제스처 번호. 미감지 시 -1.

JSON 출력

키 포인트마다 id, name, x, y, z를 담은 배열입니다. 아래는 일부만 보인 예시입니다.

[
  { "id": 0, "name": "wrist", "x": 320, "y": 350, "z": 0 },
  { "id": 4, "name": "thumb_tip", "x": 280, "y": 310, "z": -15 },
  { "id": 8, "name": "index_tip", "x": 310, "y": 260, "z": -25 },
  { "id": 12, "name": "middle_tip", "x": 330, "y": 255, "z": -22 }
]

키 포인트 21종

ID	JSON 이름	화면 표시
0	wrist	손목
1	thumb_cmc	엄지 손목관절
2	thumb_mcp	엄지 뿌리관절
3	thumb_ip	엄지 첫번째 관절
4	thumb_tip	엄지 끝
5	index_mcp	검지 뿌리관절
6	index_pip	검지 첫번째 관절
7	index_dip	검지 두번째 관절
8	index_tip	검지 끝
9	middle_mcp	중지 뿌리관절
10	middle_pip	중지 첫번째 관절
11	middle_dip	중지 두번째 관절
12	middle_tip	중지 끝
13	ring_mcp	약지 뿌리관절
14	ring_pip	약지 첫번째 관절
15	ring_dip	약지 두번째 관절
16	ring_tip	약지 끝
17	pinky_mcp	새끼 뿌리관절
18	pinky_pip	새끼 첫번째 관절
19	pinky_dip	새끼 두번째 관절
20	pinky_tip	새끼 끝

제스처 33종과 ID

제스처 ID 는 아래 표의 번호이고 제스처 이름은 영문 이름입니다.

ID	이름	뜻
0	call	전화 제스처(엄지와 새끼손가락 펴기)
1	dislike	싫어요(엄지 아래로)
2	fist	주먹
3	four	숫자 4(엄지 접기)
4	grabbing	잡기
5	grip	쥐기
6	hand_heart	손가락 하트(엄지와 검지)
7	hand_heart2	손가락 하트(다른 형태)
8	holy	합장
9	like	좋아요(엄지 위로)
10	little_finger	새끼손가락 펴기
11	middle_finger	가운뎃손가락 펴기
12	mute	조용히(검지를 입에)
13	ok	OK 사인(엄지와 검지로 원)
14	one	숫자 1(검지 펴기)
15	palm	손바닥 펴기
16	peace	브이
17	peace_inverted	뒤집힌 브이
18	point	가리키기(검지)
19	rock	락(검지와 새끼손가락)
20	stop	정지(손바닥 앞으로)
21	stop_inverted	뒤집힌 정지
22	take_picture	사진 찍기
23	three	숫자 3
24	three2	숫자 3(다른 형태)
25	three3	숫자 3(세 번째 형태)
26	three_gun	손가락 총(세 손가락)
27	thumb_index	엄지와 검지 펴기
28	thumb_index2	엄지와 검지 펴기(다른 형태)
29	timeout	타임아웃(T 자)
30	two_up	숫자 2(두 손가락 위로)
31	two_up_inverted	뒤집힌 숫자 2
32	xsign	X 사인(두 검지 교차)