HandDetection

HandDetection (손 찾기)

카메라 영상에서 손과 손가락 관절을 찾아 위치 좌표를 제공하는 손 찾기 AI 확장 모듈입니다.

인스턴스 선언

hand_detection = HandDetection(0)

이름	구분	설명	범위 / 종류	기본값
index	드롭다운 옵션	인스턴스 번호 (0부터 시작)	0 이상 정수	0

함수

device

손 찾기에 사용할 카메라 장치를 선택합니다. 카메라 이름(문자열), 인덱스, 또는 Camera 객체를 전달할 수 있습니다.

매개변수

이름	구분	설명	범위 / 종류	기본값
unit	드롭다운 옵션	카메라 지정 값	카메라 라벨(str) / 인덱스(int) / Camera 객체	-

예제

hand_detection = HandDetection(0)

hand_detection.device('')

---

load_model

손 찾기 모델을 로드합니다. wait 가 True 이면 모델 로드가 완료될 때까지 최대 15초 동안 기다립니다.

매개변수

이름	구분	설명	범위 / 종류	기본값
wait	체크박스	로드 완료 대기 여부	True / False	True

예제

hand_detection = HandDetection(0)

hand_detection.load_model(wait=True)

---

max_hands

동시에 인식할 손의 최대 개수를 설정합니다.

매개변수

이름	구분	설명	범위 / 종류	기본값
unit	드롭다운 옵션	손 개수	한 손('one'), 두 손('both')	-

예제

hand_detection = HandDetection(0)

hand_detection.max_hands('one')
hand_detection.max_hands('both')

---

detect_once

손을 한 번만 인식합니다.

매개변수: 없음

예제

hand_detection = HandDetection(0)

hand_detection.detect_once()

---

detect_continuous

손을 연속적으로 인식하기 시작합니다.

매개변수: 없음

예제

hand_detection = HandDetection(0)

hand_detection.detect_continuous()

---

stop

연속 손 인식을 정지합니다.

매개변수: 없음

예제

hand_detection = HandDetection(0)

hand_detection.stop()

---

display

손 인식 결과를 카메라 화면에 표시할지 여부를 설정합니다.

매개변수

이름	구분	설명	범위 / 종류	기본값
on	드롭다운 옵션	표시 ON / OFF	표시(True/1), 숨기기(False/0)	True

예제

hand_detection = HandDetection(0)

hand_detection.display(True)
hand_detection.display(False)

---

hand

지정한 손의 손바닥/손목 위치 또는 손 전체 사각형 정보를 반환합니다.

매개변수

이름	구분	설명	범위 / 종류	기본값
side	드롭다운 옵션	손 방향	왼손('left'), 오른손('right')	-
unit	드롭다운 옵션	손 부위	손바닥('palm'), 손목('wrist'), 손 전체('hand')	-
pos	드롭다운 옵션	좌표/크기 종류	x, y, min_x, max_x, min_y, max_y, width, height, area	-

반환값 — 지정한 좌표/크기 값 (정수)

예제

hand_detection = HandDetection(0)

hand_detection.hand('left', 'palm', 'x')
hand_detection.hand('right', 'wrist', 'y')
hand_detection.hand('left', 'hand', 'min_x')
hand_detection.hand('right', 'palm', 'width')

---

finger

지정한 손가락 관절의 좌표를 반환합니다.

매개변수

이름	구분	설명	범위 / 종류	기본값
side	드롭다운 옵션	손 방향	왼손('left'), 오른손('right')	-
unit	드롭다운 옵션	손가락	엄지('thumb'), 검지('index'), 중지('middle'), 약지('ring'), 새끼('pinky')	-
joint	드롭다운 옵션	관절 위치	첫 마디('first'), 둘째 마디('second'), 셋째 마디('third'), 끝('last')	-
pos	드롭다운 옵션	좌표 종류	x, y	-

반환값 — 지정한 좌표 값 (정수)

예제

hand_detection = HandDetection(0)

hand_detection.finger('left', 'index', 'first', 'x')
hand_detection.finger('right', 'thumb', 'last', 'y')

---

get_distance

손 또는 손가락 관절 두 부위 사이의 거리를 반환합니다. 부위는 문자열로 지정합니다 (손: 'side_unit', 손가락 관절: 'side_unit_joint'). type 을 생략하면 직선 거리를 반환합니다.

매개변수

이름	구분	설명	범위 / 종류	기본값
unit1	입력값 (문자열)	첫 번째 부위	손: 'side_unit' (예: 'left_palm'), 손가락 관절: 'side_unit_joint' (예: 'right_index_first'). side=left/right, 손 unit=palm/wrist/hand, 손가락 unit=thumb/index/middle/ring/pinky, joint=first/second/third/last	-
unit2	입력값 (문자열)	두 번째 부위	손: 'side_unit' (예: 'right_palm'), 손가락 관절: 'side_unit_joint' (예: 'left_thumb_last')	-
type	드롭다운 옵션	거리 종류	직선 거리(생략 또는 None), 수평 거리('horizontal'), 수직 거리('vertical')	None

반환값 — 두 부위 사이의 거리 (정수 또는 실수)

예제

hand_detection = HandDetection(0)

# 손 ↔ 손
hand_detection.get_distance('left_palm', 'right_palm')

# 손 ↔ 손가락 관절
hand_detection.get_distance('left_palm', 'right_index_first')

# 손가락 관절 ↔ 손가락 관절
hand_detection.get_distance('left_thumb_last', 'right_index_last')

---

model_state

손 찾기 모델의 로드 상태를 정수로 반환합니다.

매개변수: 없음

반환값 — 모델 로드 상태 (정수, 로드 완료 시 2)

예제

hand_detection = HandDetection(0)

hand_detection.model_state()

---

detected

현재 손이 감지되었는지 여부를 반환합니다.

매개변수: 없음

반환값 — 손이 감지되었으면 True, 아니면 False (bool)

예제

hand_detection = HandDetection(0)

if hand_detection.detected():
    print("손을 찾았습니다")

---