ZumiAI API 개요

이 문서는 ZumiAI 라이브러리의 모든 주요 메서드를 요약하여 보여줍니다. ZumiAI와 상호작용하는 데 필요한 핵심 기능들을 한눈에 파악할 수 있도록 분류되어 있습니다.

주미 AI 설치 방법

주미 AI를 사용하기 위한 설치는 두 가지 방식으로 나뉩니다. 사용 목적에 맞게 선택하여 설치해 주세요.

1. 🔌 기본 설치 (동글 버전)

이 방법은 주미와 함께 제공되는 USB 동글을 사용하는 가장 기본적인 설치 방식입니다.

권장 파이썬 버전: 3.9 이상
장점: 설치와 연결이 매우 빠르고 간편합니다. 코딩에 집중하고 싶을 때 적합합니다.
단점: 카메라 스트리밍을 통한 고급 기능은 사용할 수 없습니다.

pip install zumi-ai

2. 🌐 고급 설치 (스트리밍 및 비전 기능 지원)

이 방법은 주미와 IP 주소를 직접 입력하여 연결하며, 카메라 스트리밍을 통한 AI 비전 기능을 사용할 수 있는 고급 설치 방식입니다.

권장 파이썬 버전: 3.12.3 이상의 3.12.x 모든 버전 (3.13은 현재 지원되지 않습니다)
장점: 주미의 카메라 영상을 실시간 스트리밍하여 강력한 AI 기능을 활용할 수 있습니다.
단점: 설치해야 할 추가 라이브러리가 많아 설치 시간이 오래 걸릴 수 있습니다.

pip install zumi-ai[pro]

🌐 카메라 스트리밍 버전을 위한 준비물

무선 공유기 (2.4GHz 필수): Zumi와 PC가 같은 네트워크에 연결되도록 하는 필수 장비입니다.
안정적인 Wi-Fi 연결: Zumi와 PC 모두 공유기에 안정적으로 연결되어야 스트리밍이 끊기지 않습니다.

⚠️ **참고:** 주변에 무선 장비가 많거나 신호가 복잡한 환경에서는 간섭으로 인해 연결이 불안정해지거나 스트리밍 품질이 떨어질 수 있습니다.

※ 지원 여부 안내

함수별 지원 여부는 연결 방식에 따른 동작 가능 여부를 나타냅니다.
🔌 동글 연결 : USB 동글을 사용하여 Zumi AI에 연결한 경우
🌐 IP 연결 : 사용자가 IP 주소를 직접 입력하여 Zumi AI에 연결한 경우

일부 함수는 특정 연결 방식에서만 동작합니다. 각 함수 설명의 지원 정보를 참고하세요.

기본 연결 방식
Zumi AI를 사용하기 위한 기본적인 연결 방법은 아래와 같습니다.
이 코드를 통해 Zumi AI 객체를 초기화하고 연결을 설정할 수 있습니다.

from zumi_AI.zumi_AI import *
zumiAI = ZumiAI()
zumiAI.connect()

1) 연결 제어

✅ 동글 연결 지원 | ✅ IP 연결 지원

`connect`([connection_info])	주미 AI를 연결합니다.
`disconnect`()	주미 AI의 연결을 종료합니다.

2) 주행 및 움직임 제어

✅ 동글 연결 지원 | ✅ IP 연결 지원

`stop`()	주미의 모든 움직임을 즉시 멈춥니다.
`control_motor`([dirL, speedL, dirR, speedR])	모터를 작동합니다.
`control_motor_time`([dirL, speedL, dirR, ...])	일정한 시간 동안 모터를 제어합니다.
`forward_dist`([speed, dist])	지정된 거리만큼 주미를 전진시킵니다.
`reverse_dist`([speed, dist])	지정된 거리만큼 주미를 후진시킵니다.
`send_move_dist`([speed, dist, dir])	지정된 거리만큼 주미에게 이동하도록 명령을 전송합니다.
`forward_dist_quick`([dist])	빠르게 지정된 거리만큼 주미를 전진시킵니다.
`reverse_dist_quick`([dist])	빠르게 지정된 거리만큼 주미를 후진시킵니다.
`send_move_dist_quick`([dist, dir])	빠르게 주미에게 지정된 거리만큼 이동하도록 명령을 전송합니다.
`left_turn`([speed, deg])	왼쪽으로 지정된 각도만큼 주미를 회전시키는 명령을 전송합니다.
`right_turn`([speed, deg])	오른쪽으로 지정된 각도만큼 주미를 회전시키는 명령을 전송합니다.
`send_turn`([speed, deg, dir])	지정된 각도만큼 주미를 회전시키는 명령을 전송합니다.
`left_turn_quick`([deg])	빠르게 왼쪽으로 지정된 각도만큼 주미를 회전시키는 명령을 전송합니다.
`right_turn_quick`([deg])	빠르게 오른쪽으로 지정된 각도만큼 주미를 회전시키는 명령을 전송합니다.
`send_turn_quick`([deg, dir])	빠르게 지정된 각도만큼 주미를 회전시키는 명령을 전송합니다.
`forward_infinite`([speed])	지정된 속도로 주미가 계속 전진하도록 명령합니다.
`reverse_infinite`([speed])	지정된 속도로 주미가 계속 후진하도록 명령합니다.
`move_infinite`([speed, dir])	지정된 속도와 방향으로 주미가 계속 이동하도록 명령합니다.
`linefollower_distance`([speed, dist])	라인을 따라 지정된 거리만큼 주미가 이동하도록 명령합니다.
`linefollower_infinite`([speed])	라인을 따라 지정된 속도로 계속 주미가 이동하도록 명령합니다.
`linefollower`([speed, senBL, senBR, senBC, time])	라인 감지 센서를 이용하여 라인을 따라 주미가 이동하도록 명령합니다.
`go_sensor`([speed, senL, senR])	전방 센서에 무언가가 감지될 때까지 주미가 직진합니다.
`set_calibration_motors`()	주미의 모터를 보정하여 정확한 움직임을 수행할 수 있도록 합니다.

3) 감정 및 소리

✅ 동글 연결 지원 | ✅ IP 연결 지원

`change_emotion`([set])	주미의 표정을 변경합니다.
`play_sound`([sound])	주미에서 지정된 사운드를 재생합니다.
`led_control`([r, g, b])	주미의 LED 색상을 변경합니다.
`led_pattern`([pattern, time])	주미의 LED에 다양한 패턴 효과를 적용합니다.

4) 화면 제어

✅ 동글 연결 지원 | ✅ IP 연결 지원

`change_screen`([screen_type])	주미의 디스플레이 화면을 전환합니다.
`display_text`(text[, newline])	주어진 문자열을 디스플레이에 출력합니다.
`display_text_add`(text[, newline])	현재 디스플레이에 기존 텍스트에 이어서 새로운 텍스트를 출력합니다.
`display_text_clear`()	디스플레이에 표시된 모든 텍스트를 지웁니다.
`display_text_pos`([pos_x, pos_y])	텍스트의 위치를 지정합니다.
`display_text_set`([color, size])	텍스트의 색상과 크기를 설정합니다.

5) 기타 센서 및 시스템 정보

✅ 동글 연결 지원 | ✅ IP 연결 지원

`get_IR_sensor_all`()	주미의 모든 적외선(IR) 센서 값을 가져옵니다.
`get_IR_sensor_front`()	주미의 전방 적외선(IR) 센서 값들을 가져옵니다.
`get_IR_sensor_bottom`()	주미의 하단 적외선(IR) 센서 값들을 가져옵니다.
`get_battery`()	주미의 현재 배터리 잔량을 퍼센트(%) 값으로 가져옵니다.
`get_button`()	주미에 있는 4개의 버튼 중 현재 눌린 버튼의 값을 가져옵니다.

6) 키보드 인터럽트 제어

✅ 동글 연결 지원 | ✅ IP 연결 지원

`key_press_set`(key_str, callback_func)	사용자 키보드의 특정 키가 눌렸을 때 실행될 콜백 함수를 등록합니다.
`key_press_start`()	등록된 키보드 인터럽트 리스너를 시작합니다.
`key_press_stop`()	실행 중인 외부 키보드 인터럽트 리스너를 중지합니다.

7) 기본 카메라 인식 기능

✅ 동글 연결 지원 | ❌ IP 연결 미지원

`set_zumi_face_detection`([enable])	주미의 내장 얼굴 감지 기능을 켜거나 끕니다.
`set_zumi_cat_detection`([enable])	주미의 내장 고양이 감지 기능을 켜거나 끕니다.
`set_zumi_color_detection`([enable])	주미의 내장 색상 감지 기능을 켜거나 끕니다.
`set_zumi_marker_detection`([enable])	주미의 내장 마커 감지 기능을 켜거나 끕니다.
`is_zumi_face_detected`()	주미의 내장 얼굴 감지 기능을 통해 얼굴이 감지되었는지 확인합니다.
`get_zumi_face_center`()	주미의 내장 얼굴 감지 기능을 통해 감지된 얼굴의 중심 좌표를 가져옵니다.
`is_zumi_cat_detected`()	주미의 내장 고양이 감지 기능을 통해 고양이가 감지되었는지 확인합니다.
`get_zumi_cat_center`()	주미의 내장 고양이 감지 기능을 통해 감지된 고양이의 중심 좌표를 가져옵니다.
`get_zumi_color_id`()	주미의 내장 색상 감지 기능을 통해 현재 감지된 색상의 ID를 가져옵니다.
`get_zumi_color_center`()	주미의 내장 색상 감지 기능을 통해 감지된 색상 영역의 중심 좌표를 가져옵니다.
`get_zumi_marker_id`()	주미의 내장 마커 감지 기능을 통해 현재 감지된 마커의 ID를 가져옵니다.
`get_zumi_marker_center`()	주미의 내장 마커 감지 기능을 통해 감지된 마커의 중심 좌표를 가져옵니다.

8) 카메라 스트리밍

❌ 동글 연결 미지원 | ✅ IP 연결 지원

`camera_stream_start`()	주미가 카메라 영상 스트리밍을 시작합니다.
`camera_LR_Flip`(flag)	주미의 카메라 영상 스트리밍 화면을 좌우로 뒤집습니다.
`sensor_start`()	주미의 다양한 센서에서 데이터를 읽는 기능을 시작합니다.
`sensor_visible`(flag)	스트리밍 카메라 영상에서 주미의 센서 값들을 실시간으로 표시합니다.
`frame_rate_visible`(flag)	스트리밍 카메라 영상의 프레임 속도(FPS) 정보를 표시합니다.

9) 얼굴 인식

❌ 동글 연결 미지원 | ✅ IP 연결 지원

`face_detector_init`([face_recognize_threshold])	스트리밍되는 카메라 영상에서 얼굴 인식 기능을 초기화합니다.
`face_detector_start`()	스트리밍되는 카메라 영상에서 얼굴 인식 기능을 시작합니다.
`face_detector_stop`()	스트리밍되는 카메라 영상의 얼굴 인식 기능을 중지합니다.
`face_landmark_visible`(flag)	스트리밍되는 카메라 영상에 인식된 얼굴의 주요 랜드마크(특징점)를 표시합니다.
`face_contours_visible`(flag)	스트리밍되는 카메라 영상에 인식된 얼굴의 윤곽선을 표시합니다.
`is_face_detected`([name])	스트리밍되는 카메라 영상에서 특정 이름의 얼굴이 감지되었는지 확인합니다.
`get_face_center`()	스트리밍되는 카메라 영상에서 인식된 첫 번째 얼굴의 중심 좌표를 가져옵니다.
`get_face_size`()	스트리밍되는 카메라 영상에서 인식된 첫 번째 얼굴의 크기를 가져옵니다.
`get_face_landmark`([landmark])	스트리밍되는 카메라 영상에서 인식된 얼굴의 특정 랜드마크(특징점) 중심 좌표를 가져옵니다.
`face_train`(name)	스트리밍되는 카메라 영상에서 새로운 얼굴을 학습시키고 등록합니다.
`delete_face_data`(name)	스트리밍되는 카메라 영상에서 학습된 특정 이름의 얼굴 데이터를 삭제합니다.
`delete_all_Face_data`()	스트리밍되는 카메라 영상에서 학습된 모든 얼굴 데이터를 삭제합니다.
`get_detected_face_result`()	스트리밍되는 카메라 영상에서 인식된 얼굴의 이름과 신뢰도 점수를 가져옵니다.
`get_detected_face_name`()	스트리밍되는 카메라 영상에서 인식된 첫 번째 얼굴의 이름을 가져옵니다.
`get_detected_face_confidence_score`()	스트리밍되는 카메라 영상에서 인식된 첫 번째 얼굴의 신뢰도 점수를 가져옵니다.

10) 마커 인식

❌ 동글 연결 미지원 | ✅ IP 연결 지원

`marker_detector_init`()	스트리밍되는 카메라 영상에서 마커 인식 기능을 초기화합니다.
`marker_detector_start`()	스트리밍되는 카메라 영상에서 마커 인식 기능을 시작합니다.
`marker_detector_stop`()	스트리밍되는 카메라 영상의 마커 인식 기능을 중지합니다.
`is_marker_detected`(id)	스트리밍되는 카메라 영상에서 특정 ID의 마커가 감지되었는지 확인합니다.
`get_marker_id`()	스트리밍되는 카메라 영상에서 인식된 첫 번째 마커의 ID를 가져옵니다.
`get_marker_center`()	스트리밍되는 카메라 영상에서 인식된 첫 번째 마커의 중심 좌표를 가져옵니다.
`get_marker_size`()	스트리밍되는 카메라 영상에서 인식된 첫 번째 마커의 크기를 가져옵니다.

12) 제스처 인식

❌ 동글 연결 미지원 | ✅ IP 연결 지원

`gesture_detector_init`()	스트리밍되는 카메라 영상에서 손 제스처 인식 기능을 초기화합니다.
`gesture_detector_start`()	스트리밍되는 카메라 영상에서 손 제스처 인식 기능을 시작합니다.
`gesture_detector_stop`()	스트리밍되는 카메라 영상의 손 제스처 인식 기능을 중지합니다.
`is_gesture_detected`()	스트리밍되는 카메라 영상에 손이 감지되었는지 확인합니다.
`get_gesture_center`()	스트리밍되는 카메라 영상에서 인식된 손의 중심 좌표를 가져옵니다.
`get_gesture_size`()	스트리밍되는 카메라 영상에서 인식된 손의 크기를 가져옵니다.
`get_gesture_finger`()	스트리밍되는 카메라 영상에서 인식된 손의 각 손가락이 펴져 있는지 접혀 있는지 확인합니다.
`get_gesture_recognize`()	스트리밍되는 카메라 영상에서 인식된 손의 제스처 이름을 가져옵니다.

11) 스케치 인식

❌ 동글 연결 미지원 | ✅ IP 연결 지원

`sketch_detector_init`()	스트리밍되는 카메라 영상에서 스케치 인식 기능을 초기화합니다.
`sketch_detector_start`()	스트리밍되는 카메라 영상에서 스케치 인식 기능을 시작합니다.
`sketch_detector_stop`()	스트리밍되는 카메라 영상의 스케치 인식 기능을 중지합니다.
`is_sketch_detected`([name])	스트리밍되는 카메라 영상에서 특정 이름의 스케치가 감지되었는지 확인합니다.
`get_sketch_center`([name])	스트리밍되는 카메라 영상에서 인식된 스케치의 중심 좌표를 가져옵니다.
`get_sketch_size`([name])	스트리밍되는 카메라 영상에서 인식된 스케치의 크기를 가져옵니다.
`sketch_train`([name])	스트리밍되는 카메라 영상에서 새로운 스케치를 학습시키고 등록합니다.
`delete_sketch_data`([name])	스트리밍되는 카메라 영상에서 학습된 특정 이름의 스케치 데이터를 삭제합니다.
`delete_all_sketch_data`()	스트리밍되는 카메라 영상에서 학습된 모든 스케치 데이터를 삭제합니다.
`get_sketch_result`([name])	스트리밍되는 카메라 영상에서 인식된 스케치의 결과(이름과 인식률)를 가져옵니다.
`get_sketch_name`([name])	스트리밍되는 카메라 영상에서 인식된 스케치의 이름을 가져옵니다.
`get_sketch_confidence`([name])	스트리밍되는 카메라 영상에서 인식된 스케치의 신뢰도 점수를 가져옵니다.

13) 객체 인식(신호등, 정지 표지판)

❌ 동글 연결 미지원 | ✅ IP 연결 지원

`object_detector_init`([performance_mode])	스트리밍되는 카메라 영상에서 물체 인식(Object Detection) 기능을 초기화합니다.
`object_detector_start`()	스트리밍되는 카메라 영상에서 물체 인식(Object Detection) 기능을 시작합니다.
`object_detector_stop`()	스트리밍되는 카메라 영상의 물체 인식(Object Detection) 기능을 중지합니다.
`is_obj_detected`(name)	스트리밍되는 카메라 영상에서 특정 이름의 물체가 감지되었는지 확인합니다.
`get_obj_size`(name)	스트리밍되는 카메라 영상에서 특정 이름의 물체(객체) 크기를 가져옵니다.
`get_obj_center`(name)	스트리밍되는 카메라 영상에서 특정 이름의 물체(객체) 중심 좌표를 가져옵니다.
`get_obj_confidence`(name)	스트리밍되는 카메라 영상에서 특정 이름의 물체(객체)에 대한 신뢰도 점수를 가져옵니다.
`get_traffic_light_color`()	스트리밍되는 카메라 영상에서 신호등의 현재 색상을 판별하여 반환합니다.
`object_check_add_obj`([obj_name])	스트리밍되는 카메라 영상에서 물체 인식 목록에 새로운 물체(객체)를 추가합니다.
`object_check_all_add_obj`()	스트리밍되는 카메라 영상에서 물체 인식 목록에 모델이 인식 가능한 모든 물체(객체)를 추가합니다.
`object_check_del_obj`([obj_name])	스트리밍되는 카메라 영상에서 물체 인식 목록에서 특정 물체(객체)를 제거합니다.
`object_check_all_del_obj`()	스트리밍되는 카메라 영상에서 물체 인식 목록에 있는 모든 물체(객체)를 제거합니다.

14) 사용자 학습 모델 (Teachable Machine)

❌ 동글 연결 미지원 | ✅ IP 연결 지원

`teachable_detector_init`([model_path, lable_path])	스트리밍되는 카메라 영상에서 티처블 머신 모델 인식 기능을 초기화합니다.
`teachable_detector_start`()	스트리밍되는 카메라 영상에서 티처블 머신 모델 인식 기능을 시작합니다.
`teachable_detector_stop`()	스트리밍되는 카메라 영상의 티처블 머신 모델 인식 기능을 중지합니다.
`get_teachable_result`()	스트리밍되는 카메라 영상에서 티처블 머신 모델의 예측 결과를 가져옵니다.