파이썬으로 배우는
MediaPipe

MediaPipe란 무엇인가

MediaPipe는 구글이 미리 학습시켜 둔 "보는 능력"을 빌려 쓰는 도구 상자입니다.

• 비유하면, 직접 요리하지 않고 완성된 반찬을 사 오는 것과 같습니다. AI에게 수백만 장의 사진을 공부시키는 일은 구글이 이미 끝냈고, 우리는 결과물만 가져다 씁니다.
• 우리가 할 일은 불러서 쓰기입니다. 데이터 수집도, 학습도 필요 없습니다.
• 파이썬, 웹(자바스크립트), 안드로이드 어디서든 같은 모델을 쓸 수 있습니다.
• 무료이고 오픈소스입니다.

MediaPipe로 할 수 있는 일

이번 수업에서는 비전(시각) 기능 가운데 대표적인 두 가지를 직접 다룹니다.

랜드마크: 번호가 달린 점

랜드마크(landmark)는 몸의 중요한 위치마다 찍히는, 번호가 정해진 점입니다.

• 비유하면 지도 위의 핀입니다. "서울역 핀"이 언제나 서울역을 가리키듯, 8번 핀은 언제나 검지 끝을 가리킵니다.
• 번호와 의미는 절대 바뀌지 않습니다. 바뀌는 것은 점의 위치뿐입니다.
• 카메라의 매 장면(프레임)마다 모든 점의 위치가 새로 계산됩니다.
• 그래서 "검지 끝이 어디 있지?"라는 질문은 코드에서 landmarks[8] 한 줄이 됩니다.

좌표 읽는 법: 0~1 비율값

랜드마크의 좌표는 픽셀이 아니라 0에서 1 사이의 비율값으로 옵니다.

• x = 0.5는 "화면 가로의 50% 지점"이라는 뜻입니다. 백분율 표기와 같은 원리입니다.
• 픽셀 위치가 필요하면 화면 크기를 곱합니다: 화면 폭이 640이면 0.5 × 640 = 320픽셀.
• 비율값 덕분에 어떤 해상도의 카메라에서도 같은 코드가 그대로 동작합니다.
• z값도 있습니다: 카메라와의 상대적인 거리(가까울수록 작음)를 나타냅니다.

Tasks API: 세 조각이면 끝

MediaPipe의 최신 사용법(Tasks API)은 전자레인지를 쓰는 순서와 같습니다.

• ① 모델 파일(.task) 준비 — 음식을 넣는다. 손용, 얼굴용 모델 파일이 따로 있습니다.
• ② 옵션 설정 — 시간과 출력을 맞춘다. "손은 몇 개까지?", "표정 수치도 계산할까?" 등을 정합니다.
• ③ detect 호출 — 시작 버튼을 누른다. 프레임을 넣으면 랜드마크가 나옵니다.

options = HandLandmarkerOptions(          # ② 옵션 설정
    base_options=BaseOptions(model_asset_path="hand_landmarker.task"),  # ① 모델 파일
    running_mode=RunningMode.VIDEO,
)
landmarker = HandLandmarker.create_from_options(options)
result = landmarker.detect_for_video(frame, timestamp)   # ③ detect 호출

실행 모드 세 가지

같은 모델도 입력이 무엇이냐에 따라 세 가지 모드 중 하나로 돌립니다.

준비물 점검

설치는 처음 한 번만 하면 됩니다. 필요한 것은 네 가지입니다.

• 윈도우 PC — 학교 실습실 PC면 충분합니다.
• 웹캠 — 노트북 내장 카메라도 좋습니다.
• 파이썬 3.10 ~ 3.12 — 다음 슬라이드에서 설치합니다.
• 인터넷 — 설치할 때, 그리고 첫 실행 때 모델 파일(3~8MB)을 자동으로 내려받을 때 필요합니다.

원클릭 설치: 파이썬 + MediaPipe

아래 파일 하나를 내려받아 실행하면 파이썬 3.12와 MediaPipe를 한 번에 설치할 수 있습니다.

1. 위 버튼으로 install_python_mediapipe.cmd 파일을 내려받습니다.
2. 다운로드한 파일을 더블클릭합니다. 권한 요청 창이 뜨면 예를 누릅니다.
3. 검은 창에서 설치가 끝날 때까지 기다립니다. 마지막에 Done.이 보이면 성공입니다.

파이썬 설치: 체크박스 하나가 핵심

python.org에서 설치할 때, 첫 화면의 체크박스 하나가 가장 중요합니다.

1. python.org/downloads 접속 → 노란 Download Python 3.12 버튼 클릭
2. 내려받은 파일 실행 → 설치 첫 화면 맨 아래를 확인
3. "Add python.exe to PATH" 체크박스 선택
4. Install Now 클릭 → 완료

이미 파이썬이 설치되어 있다면 이 슬라이드는 건너뛰어도 됩니다.

검은 창 첫째 줄: 꾸러미 설치

필요한 꾸러미(패키지) 두 개를 한 줄로 설치합니다.

1. 시작 버튼 → cmd 입력 → Enter (검은 창이 열립니다)
2. 아래 한 줄을 복사해 붙여넣고 Enter

• mediapipe — 오늘의 주인공. 랜드마크를 계산합니다.
• opencv-python — 카메라 영상을 읽고, 점과 글자를 그려 주는 도구입니다.
• 설치에 몇 분 걸릴 수 있습니다. 글자가 주르륵 올라가는 것은 정상입니다.

검은 창 둘째 줄: 설치 확인

설치가 잘 되었는지 한 줄로 확인합니다. 검은 창은 이걸로 끝입니다.

• 0.10.35처럼 버전 번호가 나오면 성공입니다.
• 빨간 오류가 나오면 당황하지 말고 문제 해결 슬라이드를 참고하세요.

코드 실행법: IDLE에서 F5

이제부터 코드는 IDLE에서 실행합니다. 검은 창은 더 이상 필요 없습니다.

1. 시작 버튼 → IDLE 검색 → 실행
2. 메뉴에서 File → New File (새 코드 창이 열립니다)
3. 슬라이드의 예제 코드를 복사해서 붙여넣기
4. Ctrl+S 저장 — 이름은 예: hand_landmarks.py
5. F5 실행 → 카메라 창이 뜨면 성공 → 종료는 ESC

첫 번째 목표

웹캠 속 내 손 위에 21개의 점과 뼈대 선이 실시간으로 그려지고, 화면에 편 손가락 개수가 표시되는 프로그램을 만듭니다.

• 순서는 지도 보기 → 통째로 실행 → 코드 읽기 → 바꿔 보기입니다.
• 코드 전체는 두 슬라이드 뒤에 있고, 복사 한 번으로 실행됩니다.
• 코드의 [수정 지점] 주석에서 설정값과 규칙을 바꿔 볼 수 있습니다.

코드 읽기 ① 설정값과 모델 다운로드

코드 맨 위의 설정값 블록은 프로그램의 손잡이입니다. 몸통을 몰라도 손잡이만 돌리면 동작이 바뀝니다.

• NUM_HANDS, DOT_COLOR, DOT_SIZE... — 전부 대문자로 쓴 변수는 "바꿔도 되는 설정값"이라는 관례입니다.
• 색은 (파랑, 초록, 빨강) 순서입니다. OpenCV의 오래된 관례라 순서가 특이하니 주의하세요.
• download_model() — 모델 파일이 옆에 없으면 인터넷에서 한 번만 받아 저장합니다. 두 번째 실행부터는 바로 시작됩니다.

NUM_HANDS = 1               # [수정 지점] 인식할 손 개수 (1 또는 2)
DOT_COLOR = (0, 255, 0)     # [수정 지점] 점 색깔 (파랑, 초록, 빨강) 각 0~255

def download_model():
    """모델 파일이 없으면 인터넷에서 한 번만 받아 옵니다."""
    if os.path.exists(MODEL_FILE):
        return
    urllib.request.urlretrieve(MODEL_URL, MODEL_FILE)

코드 읽기 ② 카메라 루프

while 반복문 안에서는 매 프레임 같은 다섯 동작이 되풀이됩니다.

1. 읽기 — cap.read()로 카메라에서 사진 한 장을 가져옵니다.
2. 거울 뒤집기 — cv2.flip으로 좌우를 뒤집어 거울처럼 보이게 합니다.
3. 색 순서 변환 — OpenCV는 BGR, MediaPipe는 RGB를 씁니다. 같은 사진을 다른 언어로 번역하는 단계입니다.
4. detect_for_video — 랜드마크 21개를 계산합니다. 시간 도장(타임스탬프)을 함께 넘겨 "이 장면이 몇 번째 시각인지" 알려줍니다.
5. 그리기·표시 — 점, 선, 손가락 개수, FPS를 그려서 창에 보여줍니다.

코드 읽기 ③ 손가락 세는 규칙

count_fingers()는 복잡한 AI가 아니라, 좌표를 비교하는 단순한 규칙입니다.

• 검지~새끼: 손가락 끝(tip)이 가운데 마디(pip)보다 위에 있으면(y가 작으면) "폈다"고 봅니다.
• 엄지: 위아래가 아니라 옆으로 움직이므로, 새끼손가락 쪽에서 얼마나 멀리 있는지(x 거리)로 판단합니다.
• 규칙이 단순한 만큼 손을 기울이면 틀리기도 합니다 — 그래서 여러분이 개선할 여지가 있습니다.

3분 도전

직접 바꿔 봅시다. 저장(Ctrl+S) 후 다시 F5를 누르면 바뀐 코드로 실행됩니다.

두 번째 목표

얼굴 위 478개의 점, 눈동자(홍채) 강조 표시, 표정 수치 게이지, 그리고 시선 방향까지 한 화면에 띄웁니다.

• 좋은 소식: 손 예제와 뼈대가 완전히 같습니다. 설정값 → 모델 다운로드 → 카메라 루프.
• 그래서 이번에는 달라진 부분만 골라서 봅니다.
• 새로 등장하는 개념은 블렌드셰이프(표정 수치)와 홍채 랜드마크 두 가지입니다.

블렌드셰이프: 표정 계기판 52개

블렌드셰이프(blendshape)는 표정 하나하나를 0~1 사이 게이지로 알려주는 52개의 계기판입니다.

• eyeBlinkLeft = 0.9 → "왼눈을 거의 감았다". jawOpen = 0.7 → "입을 꽤 벌렸다".
• 값이 연속적이라서 "감았다/떴다"뿐 아니라 얼마나까지 알 수 있습니다.
• 478개 점의 좌표를 일일이 계산하지 않아도, 표정은 이 계기판만 읽으면 됩니다.
• 대표 계기판: eyeBlinkLeft/Right(눈 감음), jawOpen(입 벌림), mouthSmileLeft/Right(입꼬리), browInnerUp(눈썹 올림)

손 예제와 달라진 곳 네 군데

뼈대는 같으므로, 아래 네 군데만 짚으면 코드 전체를 이해한 것입니다.

• 수정 지점: SHOW_ALL_DOTS(홍채만 보기), IRIS_COLOR, WATCH_BLENDSHAPES(관찰할 계기판 목록), jawOpen 임계값(0.5)

3분 도전

표정과 시선을 조건문의 재료로 써 봅시다.

예제를 고치면 과제가 됩니다

오늘 다룬 두 예제는 그대로 수행 과제의 출발점입니다. 각 아이디어 옆에 고칠 곳을 적어 두었습니다.

플레이그라운드: 코드 없이 ESP32 조종

다음 시간에는 오늘 배운 랜드마크 값을 브라우저에서 노드로 연결해, 얼굴과 손으로 ESP32 보드를 조종합니다.

• 설치 없이 브라우저에서 바로 실행됩니다.
• 오늘 본 값들 — 손가락 개수, 표정 계기판, 시선 — 이 노드의 출력값으로 흘러 다닙니다.
• 조건 노드가 참이 되는 순간, 블루투스나 와이파이로 ESP32에 신호가 날아갑니다.
• 예: "입을 벌리면 LED 켜기", "시선 방향으로 서보 모터 돌리기"

오늘 배운 세 조각

이 세 가지만 기억하면 MediaPipe의 어떤 기능이든 같은 방법으로 쓸 수 있습니다.

• 랜드마크 = 번호가 정해진 점. 좌표는 0~1 비율값이고, y는 아래로 갈수록 커집니다.
• Tasks API = 모델 파일(.task) + 옵션 + detect. 전자레인지 세 단계.
• 커스터마이징 = 코드의 [수정 지점]에서 값을 바꾸고 조건문으로 규칙을 더하는 과정.