MediaPipeとは・使い方｜Pythonで手・顔・姿勢推定と旧API移行

MediaPipe を使う流れは、どのタスクでもほぼ同じです。画像を RGB の mp.Image にして、モデルを読み込んだタスクに渡し、返ってきた点の座標を使います。

flowchart TD
    A[カメラ・動画・画像] --> B[OpenCVで読む<br>色の順はBGR]
    B --> C[RGBに変換して<br>mp.Imageにする]
    M[モデル .task] --> D
    C --> D[Tasks API<br>HandLandmarkerなど]
    D --> E[ランドマーク<br>x・y・zの点]
    E --> F[描画・角度・判定]

よく調べられることの答えを先にまとめます。

確認環境：Ubuntu 24.04.5 LTS（Intel Xeon 2.10GHz・2 vCPU。ほかの作業と同居したマシン）の上で、Python 3.12.3 の venv に mediapipe 1.2.0（2026年10月27日公開の版）を pip で入れ、import・mp.Image の作成・各タスクの初期化・エラーの文言・描画の関数を実行しました。容量を抑えるため、依存の opencv-contrib-python 5.0.0.93 は opencv-python-headless 4.11.0.86 に入れ替えています（numpy 2.5.4）。Tasks API 用のモデル（.task）は、この環境から storage.googleapis.com への接続が拒否された（HTTP 403）ため取得できず、Tasks API の検出結果とモデルの一覧は Google の公式ドキュメントで確かめました。実際の検出は、PyPI から入れた mediapipe 0.10.21（旧 Solutions。モデルが同梱されている最後の系統）で行い、入力には OpenCV で描いた自作の合成画像（顔・開いた手・全身の図。実在の人の写真は使っていません）を使いました。カメラはこの環境に無いため、動画は自作の mp4 と、画像を少しずつずらしたフレームで代わりにしています。処理時間は、1回目を除いた10回の中央値です。図は mermaid 11.16.0 で描画を確かめています（確認日 2026年10月29日）。

MediaPipeとは（何ができるか・仕組み）

この節では、MediaPipe が何をするライブラリで、どんな部品からできているかが分かります。

MediaPipe は、Google が公開している機械学習の部品集で、画像・動画・音声・テキストを、学習済みのモデルで処理するためのライブラリです。いちばん使われているのは画像の認識で、カメラに映った手の関節21点、顔の478点、体の33点といった「ランドマーク（目印の点）」の座標を、GPU が無くても動く速さで求められます。Android・Web（JavaScript）・Python・iOS で同じタスクを使えるのが特徴です。ライセンスは Apache 2.0（PyPI の表示）です。

公式の説明では、MediaPipe Solutions は次の4つでできています。

ランドマークと「検出」の違い

MediaPipe の結果には、大きく2種類あります。

• 検出（Detection）：「どこに顔があるか」を四角い枠（バウンディングボックス）で返します。顔検出（Face Detector）や物体検出がこれです。
• ランドマーク（Landmark）：手の指先・肘・目尻など、決まった部位の点の座標を返します。手（Hand Landmarker）・顔（Face Landmarker）・姿勢（Pose Landmarker）がこれで、「姿勢推定」は体のランドマークを求めることを指します。

どちらも、中では「まず対象のおおよその場所を見つけるモデル」と「その範囲を切り出して細かい点を求めるモデル」の2段で動きます。手なら手のひらの検出→21点、姿勢なら人の検出→33点です。動画では、前のフレームの位置を使って1段目を省く（トラッキング）ため、静止画より速くなります。この差は後の節で実測しています。モデルの中身（ニューラルネットワーク）の仕組みは、関連記事「ニューラルネットワークとは｜仕組み・学習・AttentionをNumPyで実演」で扱っています。

なお、MediaPipe の顔のタスクは「顔がどこにあるか・どんな形か」を求めるもので、「誰の顔か」を見分ける顔認証の機能はありません。

MediaPipeでできること（タスク一覧と対応環境）

この節では、MediaPipe の画像系のタスクで何が分かるか、Python で使えるか、以前の Solutions では何という名前だったかが分かります。

画像系のタスクは11種類あり、公式の対応表では全部が Python に対応しています。以前の Solutions の名前で書かれた記事やコードを読むときは、右の列で対応を確かめます。

このほか、音声の分類（audio）、テキストの分類・言語の判定（text）も Python から使えます。1.2.0 の mediapipe.tasks.python.vision を実際に読み込むと、上の表のクラスがすべて入っていました（HolisticLandmarker も含む）。

以前の Solutions のうち、Box Tracking・Objectron・KNIFT・AutoFlip などは後継が無いまま、2023年3月1日でサポートが終わっています（公式の「Legacy solutions」の記載）。

MediaPipeのインストール（pip・Pythonの版・OS）

この節では、MediaPipe を Python に入れる手順と、入るものの大きさ、対応する Python・OS が分かります。

venv（仮想環境）を作り、python -m pip install mediapipe で入れます。公式の Python 向けページは「Python 3.9 以降」「pip 20.3 以降」としています。

python -m venv .venv
source .venv/bin/activate
python -m pip install mediapipe
python -c "import mediapipe as mp; print(mp.__version__)"

Successfully installed absl-py-2.5.1 certifi-2026.10.23 cffi-2.1.1 contourpy-1.4.0 cycler-0.12.1 flatbuffers-25.12.19 fonttools-4.68.0 kiwisolver-1.5.1 matplotlib-3.11.2 mediapipe-1.2.0 numpy-2.5.4 opencv-contrib-python-5.0.0.93 packaging-26.3 pillow-13.0.0 pycparser-3.12 pyparsing-3.3.3 python-dateutil-3.0.0 six-1.17.0 sounddevice-0.5.6 tzdata-2026.6
1.2.0

venv の作り方と、有効にできないときの直し方は関連記事「Python venvの使い方｜作成・有効化コマンド早見表と有効化できない時の直し方」で扱っています。

入るものの大きさ（実測）

venv 全体で 483MB になり、いちばん大きいのは MediaPipe 本体ではなく、依存の opencv-contrib-python（206MB）でした。

1.2.0 では、import mediapipe の時点で描画用のモジュールが読み込まれ、その中で cv2 と matplotlib が import されます。手元で sys.modules を見ると、import mediapipe だけで両方が読み込まれていました。import にかかった時間は5回で 598〜696ms で、そのうち numpy・cv2・matplotlib だけで約480ms でした。

容量を抑えたい場合、opencv-contrib-python を opencv-python-headless（画面表示の機能を除いた版）に入れ替えても、import・画像の作成・描画は動きました。ただし pip は依存が足りないと警告します。

$ pip check
mediapipe 1.2.0 requires opencv-contrib-python, which is not installed.

pip の版の指定や requirements.txt の書き方は、関連記事「pipコマンド一覧｜installのバージョン指定とrequirements.txt」で扱っています。

対応する Python と OS（PyPI で確認）

1.x の wheel は Python の版を問わない形（py3-none）で配られ、PyPI の分類は Python 3.9〜3.14 です。Intel Mac 向けの wheel は 0.10.21（2025年2月6日公開）が最後です。

合う wheel が無い環境では、pip は次のように止まります。Python 3.13 で 0.10.21 を指定したときの原文です（3.13 向けの wheel が無いため、選べる版に 0.10.30 以降だけが並びます）。

ERROR: Could not find a version that satisfies the requirement mediapipe==0.10.21 (from versions: 0.10.30, 0.10.31, 0.10.32, 0.10.33, 0.10.35, 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0)
ERROR: No matching distribution found for mediapipe==0.10.21

Intel Mac（macosx_11_0_x86_64）＋Python 3.13 を指定して取得しようとすると、(from versions: none) となり、どの版も選べませんでした。Intel Mac で使うなら、Python 3.12 以下＋0.10.21 という組み合わせになります。

旧Solutions（mp.solutions）とTasks APIの違い

この節では、mp.solutions を使うコードが動かなくなった理由と、Tasks API への書き換え方が分かります。

以前の書き方 mp.solutions.hands などは、0.10.30 以降の pip の配布物に入っていません。ネットで多く見かけるコードをそのまま 1.2.0 で動かすと、次のエラーになります。

$ python -c "import mediapipe as mp; mp.solutions.hands"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
AttributeError: module 'mediapipe' has no attribute 'solutions'

1.2.0 の mediapipe の直下にあったのは Image・ImageFormat・tasks の3つだけでした。PyPI の wheel の中身（ファイルの一覧）を版ごとに数えると、違いがはっきりします。

書き換え対応表（手・姿勢・顔）

0.10.21 に固定して以前のコードを動かす判断

以前のコードを今すぐ動かす必要があるだけなら、Python 3.12 以下で pip install mediapipe==0.10.21 とする方法があります。手元でも、0.10.21 の mp.solutions は動き、この記事の検出の実物はこの版で取りました。ただし次の制約があります。

• Python 3.13 以降では入りません（上の pip のエラー）。
• 依存に numpy<2・protobuf<5・jax・jaxlib があり、新しいライブラリと同じ venv に入れるとぶつかりやすくなります。
• 同梱されていないモデル（姿勢の lite と heavy）は、初回に storage.googleapis.com から自動でダウンロードされます。オフラインや社内のプロキシの下では、ここで止まります（エラーの節に原文）。
• 公式のサポートは終わっており、不具合が直る見込みはありません。

新しく書くコードは Tasks API で書き、以前のコードは上の対応表で少しずつ置き換えるのが安全です。

Tasks APIの使い方（モデル・Options・実行モード）

この節では、Tasks API の共通の書き方（5手順）と、モデルの取得先、3つの実行モードの違いが分かります。

どのタスクも「モデルのパス → Options → create_from_options → mp.Image → detect」の順で書きます。クラス名の「Hand」を「Pose」「Face」に替えれば、ほぼ同じ形で使えます。

1. 1モデルを置くhand_landmarker.task などを公式のページから取得する
2. 2BaseOptions にパスを書くpython.BaseOptions(model_asset_path="...")
3. 3タスクの Options を作る実行モード・検出する数・しきい値
4. 4create_from_options でタスクを作るwith 文で使うと最後に閉じられる
5. 5mp.Image を渡して結果を受け取るdetect・detect_for_video・detect_async

モデルファイルの一覧（公式）

モデルは各タスクの公式ページの「Models」に載っており、次の形の URL で配られています（いずれも float16）。

https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/latest/hand_landmarker.task
https://storage.googleapis.com/mediapipe-models/pose_landmarker/pose_landmarker_lite/float16/latest/pose_landmarker_lite.task
https://storage.googleapis.com/mediapipe-models/face_detector/blaze_face_short_range/float16/latest/blaze_face_short_range.tflite
https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/latest/face_landmarker.task

この環境では、上の URL への接続がプロキシに拒否され（curl: (56) CONNECT tunnel failed, response 403）、モデルを取得できませんでした。社内のネットワークで同じことが起きたら、ブラウザで取得したファイルを置くか、取得先を許可してもらいます。

3つの実行モード

VIDEO と LIVE_STREAM では、フレームごとにミリ秒のタイムスタンプを渡します。値は前のフレームより大きくなければなりません。実行モードとコールバックの組み合わせが合わないと、モデルを読む前に次のエラーになりました（1.2.0 の原文）。

ValueError: The vision task is in live stream mode, a user-defined result callback must be provided.
ValueError: The vision task is in image or video mode, a user-defined result callback should not be provided.

mp.Image の作り方

入力はファイルからも、NumPy の配列からも作れます。

import mediapipe as mp
import numpy as np

image = mp.Image.create_from_file("hand.png")          # ファイルから（RGBで読まれる）
rgb = np.zeros((480, 640, 3), np.uint8)                 # 高さ・幅・3チャンネル
image = mp.Image(image_format=mp.ImageFormat.SRGB, data=rgb)
print(image.width, image.height, image.channels)       # 640 480 3

1.2.0 の ImageFormat には SRGB・SRGBA・GRAY8・GRAY16・SRGB48・SRGBA64・VEC32F1・VEC32F2・VEC32F4 がありました。640×480 の配列からの作成は1枚 0.06〜0.07ms で、処理全体から見ればほぼ無視できる時間です。配列の作り方・形の変え方は関連記事「NumPyの使い方 基本一覧｜配列の作成・演算・形状変更」で扱っています。

手の検出（Hand Landmarker）の使い方と21点

この節では、手のランドマークを求めるコードと、結果の読み方、左右の判定の注意が分かります。

HandLandmarker は、手のひらを見つけたあと、手首・指の関節・指先の21点の座標を返します。公式の Python ガイドの形に沿ったコードです。

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

base_options = python.BaseOptions(model_asset_path="hand_landmarker.task")
options = vision.HandLandmarkerOptions(base_options=base_options, num_hands=2)

with vision.HandLandmarker.create_from_options(options) as landmarker:
    image = mp.Image.create_from_file("hand.png")
    result = landmarker.detect(image)

for i, hand in enumerate(result.hand_landmarks):
    label = result.handedness[i][0].category_name   # Left / Right
    tip = hand[8]                                   # 人差し指の先
    print(label, round(tip.x, 3), round(tip.y, 3), round(tip.z, 3))

結果（HandLandmarkerResult）の中身は、1.2.0 で調べると handedness・hand_landmarks・hand_world_landmarks の3つでした。点（NormalizedLandmark）は x・y・z・visibility・presence・name を持ちます。

• x・y：画像の幅・高さを1とした位置（0〜1）。ピクセルにするには幅・高さを掛けます。
• z：手首を基準にした奥行き。値が小さいほどカメラに近い。
• hand_world_landmarks：画像の大きさに左右されない3次元の座標。

21点の番号

自作の画像で動かした結果

Tasks API のモデルは取得できなかったため、同じ「手のひら検出＋21点」の構成を持つ 0.10.21 の Solutions で、OpenCV で描いた開いた手の図（640×480）を処理しました。

import cv2
import mediapipe as mp   # 0.10.21

img = cv2.cvtColor(cv2.imread("hand.png"), cv2.COLOR_BGR2RGB)
with mp.solutions.hands.Hands(static_image_mode=True, max_num_hands=2) as hands:
    r = hands.process(img)
h = r.multi_handedness[0].classification[0]
lm = r.multi_hand_landmarks[0].landmark
print(h.label, round(h.score, 3), len(lm))
print("wrist", round(lm[0].x, 3), round(lm[0].y, 3), "index_tip", round(lm[8].x, 3), round(lm[8].y, 3), round(lm[8].z, 3))

Right 0.878 21
wrist 0.487 0.832 index_tip 0.69 0.195 -0.167

線で描いただけの手でも21点がそろい、点を描き戻すと指の関節の位置に重なりました。人差し指の先の z が -0.167 と、手首より手前と判定されています。

左右（handedness）は鏡に映った前提

公式のドキュメント（Solutions の Hands）は、左右の判定は「入力が左右反転された画像（自撮りのカメラ）である」前提で、そうでなければアプリ側で左右を入れ替えるよう説明しています。同じ画像を cv2.flip(img, 1) で左右反転すると、判定が入れ替わりました。

背面のカメラや、反転していない動画を使うときは、表示の左右と判定の左右が逆になることがあります。必要なら判定を入れ替えるか、入力を反転してから渡します。なお、この結果は肌の色だけで描いた図の場合で、色の情報を失うと検出できませんでした。実際の写真では結果が変わることがあります。

Options の既定値（公式）は、num_hands が1、min_hand_detection_confidence・min_hand_presence_confidence・min_tracking_confidence がいずれも0.5です。1.2.0 の HandLandmarkerOptions の引数を調べても同じ値でした。

顔検出と顔ランドマーク（Face Detector・Face Landmarker）

この節では、顔の枠だけを求める Face Detector と、顔の形を478点で求める Face Landmarker の使い分けが分かります。

「顔があるか・どこか」だけなら Face Detector、目・口の形や表情まで必要なら Face Landmarker を使います。

from mediapipe.tasks import python
from mediapipe.tasks.python import vision
import mediapipe as mp

options = vision.FaceDetectorOptions(
    base_options=python.BaseOptions(model_asset_path="blaze_face_short_range.tflite"),
    min_detection_confidence=0.5)
with vision.FaceDetector.create_from_options(options) as detector:
    result = detector.detect(mp.Image.create_from_file("face.png"))
for d in result.detections:
    b = d.bounding_box                     # ピクセル単位
    print(d.categories[0].score, b.origin_x, b.origin_y, b.width, b.height, len(d.keypoints))

Tasks API の枠（BoundingBox）は origin_x・origin_y・width・height のピクセル単位で、6点（NormalizedKeypoint）は 0〜1 の座標です。以前の Solutions の枠は 0〜1 の比率（relative_bounding_box）だったので、書き換えのときに単位が変わる点に注意します。

自作の画像で動かした結果（0.10.21）

顔だけを大きく描いた画像（face.png）と、全身の図の中に小さな顔がある画像（body.png）で、近距離用と遠距離用のモデルを比べました。

大きな顔は近距離用、小さな顔は遠距離用のほうがスコアが高く、モデルの説明（近距離＝自撮り、遠距離＝背面のカメラ）のとおりの差が出ました。face.png の枠は比率で x 0.325・y 0.339・幅 0.369・高さ 0.492、点は6つでした。refine を有効にした FaceMesh は虹彩の点を含む478点で、Tasks API の Face Landmarker と同じ点の数です。

OpenCV の顔検出（Haar）との比較

OpenCV に入っている Haar 特徴の顔検出（haarcascade_frontalface_default.xml）でも、同じ2枚で顔を1件ずつ見つけました。時間は face.png で 40.2ms、body.png で 47.2ms で、MediaPipe の近距離用（2.2ms）より1桁遅い結果でした。Haar は点（目・鼻の位置）を返さないため、顔の向きや表情を扱うなら MediaPipe が向いています。

顔の画像は、人によっては個人情報にあたります。社内のシステムで扱うときは、保存するか・座標だけ残すか・誰が見られるかを先に決めておきます。

姿勢推定（Pose Landmarker）の使い方と33点

この節では、体の33点を求めるコード、点の番号、関節の角度の求め方、モデルの選び方が分かります。

PoseLandmarker は、人を見つけたあと、顔（0〜10）・上半身（11〜22）・下半身（23〜32）の33点を返します。運動のフォームの確認、姿勢の記録、ジェスチャーの操作などに使われます。

from mediapipe.tasks import python
from mediapipe.tasks.python import vision
import mediapipe as mp

options = vision.PoseLandmarkerOptions(
    base_options=python.BaseOptions(model_asset_path="pose_landmarker_lite.task"),
    running_mode=vision.RunningMode.IMAGE,
    num_poses=1,
    output_segmentation_masks=False)
with vision.PoseLandmarker.create_from_options(options) as landmarker:
    result = landmarker.detect(mp.Image.create_from_file("body.png"))
if result.pose_landmarks:
    nose = result.pose_landmarks[0][0]
    print(len(result.pose_landmarks[0]), nose.x, nose.y, nose.visibility)

自作の全身の図で動かした結果（0.10.21・model_complexity=1）

body.png: landmarks=33 med=32.9ms nose=(0.501,0.135) vis=1.000 Lwrist=(0.727,0.508) vis=0.950 world=True
face.png: none med=11.7ms
blank.png: none med=10.5ms

全身の図では33点がそろい、点を描き戻すと肩・肘・膝・足首の位置に重なりました。顔だけの画像と何も無い画像では、人が見つからず結果は空でした。「LEFT（左）」は写っている人から見た左で、正面を向いた人の左手首は画像の右側（x 0.727）に出ます。

関節の角度を求める

3点の座標から角度を求めれば、肘や膝の曲がり具合を数値にできます。正規化座標のままでは縦横比がずれるので、先にピクセルに直します。

import numpy as np

def angle(a, b, c):
    """b を頂点とした角度（度）"""
    ba, bc = a - b, c - b
    cos = np.dot(ba, bc) / (np.linalg.norm(ba) * np.linalg.norm(bc))
    return np.degrees(np.arccos(np.clip(cos, -1.0, 1.0)))

h, w = 640, 480
lm = result.pose_landmarks[0]            # 0.10.21 では results.pose_landmarks.landmark
p = lambda i: np.array([lm[i].x * w, lm[i].y * h])
print(round(angle(p(11), p(13), p(15)), 1))   # 左肩・左肘・左手首

LEFT_SHOULDER 300 166 1.0
LEFT_ELBOW 330 249 0.985
LEFT_WRIST 349 324 0.95
173.4

腕をほぼまっすぐ下ろした図なので、左肘の角度は173.4度でした。visibility（見えている確からしさ）が低い点は、隠れていたり画面の外だったりするので、角度の計算から外すと安定します。

lite・full・heavy の選び方

モデルは lite（軽い）・full・heavy（重いが精度が高い）の3つで、入力の大きさは同じです（公式）。以前の Solutions の model_complexity は 0＝lite、1＝full、2＝heavy にあたります。0.10.21 の pip の配布物には full だけが入っており、lite と heavy は初回に自動でダウンロードされる作りでした。まず lite でカメラの速さを確かめ、精度が足りなければ full、heavy へ上げます。

OpenCVとの組み合わせ（カメラ・動画・BGRとRGB）

この節では、OpenCV で読んだカメラ・動画を MediaPipe に渡す書き方と、色の順・タイムスタンプ・描画の注意が分かります。

OpenCV の cv2.imread や VideoCapture が返す画像は BGR の順です。MediaPipe は RGB を前提にしているので、渡す前に必ず変換します。

BGR pixel [36, 118, 196] -> RGB [196, 118, 36]

この変換を忘れても、エラーは出ません。手の節の表のとおり、手の図を BGR のまま渡すと検出が0件になりました。「エラーは出ないのに何も検出されない」ときは、まず色の順を疑います。

動画ファイルを VIDEO モードで処理する

import cv2
import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

options = vision.PoseLandmarkerOptions(
    base_options=python.BaseOptions(model_asset_path="pose_landmarker_lite.task"),
    running_mode=vision.RunningMode.VIDEO)

cap = cv2.VideoCapture("input.mp4")
fps = cap.get(cv2.CAP_PROP_FPS)
with vision.PoseLandmarker.create_from_options(options) as landmarker:
    i = 0
    while True:
        ok, frame = cap.read()
        if not ok:
            break
        rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
        mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=rgb)
        result = landmarker.detect_for_video(mp_image, int(i * 1000 / fps))
        i += 1
cap.release()

自作の 30fps・60フレームの mp4 で、このループの前半（読み込み→変換→mp.Image）を 1.2.0 で動かしました。

fps 30.0 frames 60
read 60 frames; cvtColor 0.093 ms/frame; mp.Image 0.541 ms/frame
timestamps(ms) first5 [0, 33, 66, 100, 133] last 1966

色の変換は1フレーム 0.09ms、mp.Image の作成は 0.54ms で、推論（手で約20ms）に比べれば小さな時間です。タイムスタンプは i * 1000 / fps で 0・33・66・100… と増えていきます。同じ値を2回渡したり、逆戻りさせたりしないようにします。

カメラを LIVE_STREAM モードで処理する

import time
import cv2
import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

def on_result(result, output_image, timestamp_ms):
    print(timestamp_ms, len(result.hand_landmarks))

options = vision.HandLandmarkerOptions(
    base_options=python.BaseOptions(model_asset_path="hand_landmarker.task"),
    running_mode=vision.RunningMode.LIVE_STREAM,
    result_callback=on_result)

with vision.HandLandmarker.create_from_options(options) as landmarker:
    cap = cv2.VideoCapture(0)
    while cap.isOpened():
        ok, frame = cap.read()
        if not ok:
            break
        frame = cv2.flip(frame, 1)                       # 自撮りの向きにそろえる
        rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
        landmarker.detect_async(mp.Image(image_format=mp.ImageFormat.SRGB, data=rgb),
                                int(time.monotonic() * 1000))
    cap.release()

LIVE_STREAM では、結果は別のスレッドからコールバックに届きます。画面に描くときは、コールバックで結果を変数にしまい、メインのループで描くと扱いやすくなります。この環境にはカメラが無いため、このコードは公式の Python ガイドの形に沿って書いたもので、カメラでは動かしていません。

点を画像に描く（1.2.0 の drawing_utils）

1.2.0 にも描画の関数があり、Tasks API の結果（点のリスト）をそのまま渡せます。手元では、自分で作った21点を描かせて動作を確かめました（1回 0.58ms）。

from mediapipe.tasks.python.vision import drawing_utils, HandLandmarksConnections

for hand in result.hand_landmarks:
    drawing_utils.draw_landmarks(frame, hand, HandLandmarksConnections.HAND_CONNECTIONS)
cv2.imwrite("out.png", frame)        # frame は OpenCV の BGR の画像

エラーにならない落とし穴（実測）

• 1BGR のまま渡さないエラーは出ず、手の図の検出が0件になった。cv2.cvtColor で RGB にする
• 2透過 PNG（4チャンネル）を SRGB で渡さない1.2.0 はエラーにせず受け取り、2画素目が [255, 10, 20] と色がずれた。SRGBA を指定するか、3チャンネルに変換する
• 3mp.Image は変数に入れてから使うmp.Image(...).numpy_view() と1行で書くと、3回とも [45, 121, 70] などでたらめな値になった。変数に入れれば正しい値
• 4cv2.imread の戻り値を確かめるパスが違うと None が返り、次の行で AttributeError になる。if img is None で止める

画像のサイズ変更や形式の変換を先に済ませたい場合は、関連記事「Python Pillowで画像処理｜リサイズ・トリミング・形式変換のコード集」で扱っています。Pillow で開いた画像は RGB なので、np.asarray(img.convert("RGB")) をそのまま mp.Image に渡せます。

MediaPipeの処理時間の実測（CPUだけで何ms？）

この節では、GPU の無い2コアの環境で、顔・手・姿勢の処理に1枚あたり何 ms かかったかが分かります。

何も無い画像で速いのは、1段目の検出で対象が見つからず、2段目（点を求めるモデル）を動かさないためです。手の lite は full より約3割速く、スコアは 0.533 と低めでした。

動画では追跡で半分以下になる

手の図を1フレームに3ピクセルずつ横に動かした60フレームを、静止画として毎回検出する設定と、追跡を使う設定で比べました。

追跡では2フレーム目以降の手のひら検出が省かれ、19.8ms から 8.8ms に縮みました。Tasks API では VIDEO・LIVE_STREAM モードがこの追跡にあたり、公式も「遅延を減らすために追跡を使う」と説明しています。30fps（1フレーム33ms）に間に合わせたいなら、動画には IMAGE ではなく VIDEO を使います。

公式が載せている Pixel 6 での値は、手（full）が CPU 17.12ms・GPU 12.27ms、顔検出（近距離）が CPU 2.94ms・GPU 7.41ms です。小さなモデルでは GPU のほうが遅いこともある、という点も参考になります。手元の値は、ほかの作業と同居した2コアのマシンでの値で、マシンや画像によって変わります。

MediaPipeのよくあるエラーと直し方

この節では、MediaPipe で出たエラーの原文と、その原因・直し方が分かります。

多いのは「モデルのパス」「入力の形と色」「実行モードの組み合わせ」の3つです。原文はすべて手元で出たものです。

以前の Solutions でモデルの自動ダウンロードが止まる

0.10.21 で姿勢の model_complexity=0 か 2 を指定すると、同梱されていないモデルを storage.googleapis.com の mediapipe-assets から取得しにいきます。この環境では、プロキシに拒否されて次のように止まりました。回線が無い環境では、末尾の文言が名前解決の失敗などに変わります。

Downloading model to /…/site-packages/mediapipe/modules/pose_landmark/pose_landmark_lite.tflite
URLError: <urlopen error Tunnel connection failed: 403 Forbidden>

社内のネットワークで使うなら、接続できる環境で一度取得したファイルを同じ場所に置くか、同梱されている model_complexity=1 を使います。

pip で入らない・ぶつかる

• No matching distribution found for mediapipe：その Python・OS 向けの wheel がありません。Intel Mac、32ビットの Python、3.13 以降での 0.10.21 指定で起きます。python -VV で版とビット数を確かめます。
• OpenCV が2種類入っている：opencv-python と opencv-contrib-python と opencv-python-headless は、どれも同じ cv2 という名前で入ります。複数入れると、後から入れたものが上書きし、消すと共有のファイルまで消えることがあります。venv を分け、1種類だけにします。

判断表：MediaPipeのAPI・モデル・版の選び方

この節では、作りたいものに合わせて、どの API・モデル・版を選ぶかが分かります。

MediaPipe と OpenCV の違い

よく一緒に名前が出ますが、役割が違います。OpenCV は画像を読む・変換する・描く・カメラを扱う道具箱で、MediaPipe は学習済みのモデルで「手・顔・体がどこにあるか」を求める部品です。実際のプログラムでは、OpenCV でカメラから読み、MediaPipe で点を求め、OpenCV で描いて表示する、という分担になります。OpenCV にも顔検出（Haar・DNN）はありますが、手の21点や体の33点を直接返す機能は標準では持っていません。

よくある質問

Q. MediaPipeとは何ですか？ A. Google が公開しているオープンソースのライブラリで、画像・動画から手・顔・体のランドマーク（点の座標）や物体を、学習済みのモデルで求めます。Python・Android・iOS・Web で使え、ライセンスは Apache 2.0 です。

Q. MediaPipe は無料で、商用でも使えますか？ A. ライブラリは Apache 2.0 で配られており、無料です。商用で使うときは、ライブラリのライセンスに加えて、使うモデルごとのモデルカード（公式ページからリンクされている説明書）の条件も確かめます。

Q. mp.solutions が使えません。 A. 0.10.30 以降の pip の配布物に Solutions は入っていません。AttributeError: module 'mediapipe' has no attribute 'solutions' が出たら、Tasks API に書き換えます。急ぐときは Python 3.12 以下で mediapipe==0.10.21 に固定すると、以前のコードがそのまま動きました。

Q. MediaPipe はどの Python の版で使えますか？ A. 1.2.0 の PyPI の分類は Python 3.9〜3.14 です。以前の 0.10.21 は 3.9〜3.12 だけで、3.13 では入りません。

Q. モデルファイル（.task）はどこにありますか？ A. 各タスクの公式ページの「Models」の節にダウンロードのリンクがあります。pip では入らないので、取得してコードの model_asset_path に書きます。

Q. GPU は必要ですか？ A. なくても動きます。この記事の値はすべて GPU の無い2コアの CPU で、顔検出 2.2ms、手 19.9ms、姿勢 32.9ms でした。BaseOptions には CPU・GPU を選ぶ delegate がありますが、公式の Python 向けのセットアップのページには GPU の手順が載っていないため、CPU で間に合う設計にしておくのが無難です。

Q. 手の左右が逆に出ます。 A. 左右の判定は、自撮りのように左右反転された画像を前提にしています。手元でも、同じ画像を反転すると Right が Left に変わりました。背面のカメラや反転していない動画では、入力を cv2.flip(frame, 1) で反転するか、判定を入れ替えます。

Q. エラーは出ないのに何も検出されません。 A. まず、OpenCV の BGR を RGB に変換しているかを確かめます。手元では BGR のまま渡すと検出が0件でした。次に、しきい値（min_..._confidence）を下げる、対象が小さすぎないか（顔なら遠距離用のモデル）を確かめます。

Q. 動画で処理が遅いです。 A. IMAGE モードで毎フレーム検出していないかを見ます。追跡を使う設定（Tasks API の VIDEO・LIVE_STREAM）にすると、手元では1フレーム 19.8ms から 8.8ms に縮みました。姿勢なら lite のモデルに替える、入力を縮小する、も効きます。

Q. Web（JavaScript）でも使えますか？ A. 使えます。公式の対応表では、手・顔・姿勢・ジェスチャーなどの画像系のタスクは Web にも対応しており、同じモデルを使います。ブラウザで試すだけなら MediaPipe Studio でコードを書かずに結果を見られます。

まとめ

• MediaPipe は Google のオープンソースの認識ライブラリ。手21点・顔478点・体33点などのランドマークを、GPU が無くても求められる。
• Python は pip install mediapipe（1.2.0・Python 3.9〜3.14）。venv で約480MB。モデル（.task）は別に取得して model_asset_path に書く。
• mp.solutions は 0.10.30 以降に無い。Tasks API に書き換える（対応表）か、Python 3.12 以下で 0.10.21 に固定する。
• OpenCV の画像は BGR。RGB に変換しないとエラーは出ずに検出0件になった。透過 PNG や一時オブジェクトの numpy_view() も値が壊れる。
• CPU 2コアで顔検出 2.2ms・手 19.9ms・姿勢 32.9ms。動画は追跡（VIDEO・LIVE_STREAM）で手が 8.8ms になった。

次に読むとよい記事です。環境づくりは関連記事「Python venvの使い方｜作成・有効化コマンド早見表と有効化できない時の直し方」と関連記事「pipコマンド一覧｜installのバージョン指定とrequirements.txt」で、結果の座標の計算は関連記事「NumPyの使い方 基本一覧｜配列の作成・演算・形状変更」で扱っています。

参考・出典

確認日はいずれも 2026年10月29日です。

• Google AI Edge「MediaPipe Solutions guide」（タスクの一覧・対応表・Legacy solutions）：https://developers.google.com/edge/mediapipe/solutions/guide
• Google AI Edge「Setup guide for Python」：https://developers.google.com/edge/mediapipe/solutions/setup_python
• Google AI Edge「Hand landmarks detection guide」：https://developers.google.com/edge/mediapipe/solutions/vision/hand_landmarker
• Google AI Edge「Hand landmarks detection guide for Python」：https://developers.google.com/edge/mediapipe/solutions/vision/hand_landmarker/python
• Google AI Edge「Pose landmark detection guide」：https://developers.google.com/edge/mediapipe/solutions/vision/pose_landmarker
• Google AI Edge「Face detection guide」：https://developers.google.com/edge/mediapipe/solutions/vision/face_detector
• Google AI Edge「Face landmark detection guide」：https://developers.google.com/edge/mediapipe/solutions/vision/face_landmarker
• PyPI「mediapipe」（版の一覧・配布ファイル・依存）：https://pypi.org/project/mediapipe/
• GitHub「google-ai-edge/mediapipe」：https://github.com/google-ai-edge/mediapipe
• OpenCV「Color conversions」（cvtColor の変換）：https://docs.opencv.org/4.x/de/d25/imgproc_color_conversions.html
• MediaPipe（GitHub）「docs/solutions/hands.md」（以前の Solutions の Hands。左右の判定・z の説明）：https://github.com/google-ai-edge/mediapipe/blob/master/docs/solutions/hands.md

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。