Hướng dẫn nhận dạng cử chỉ dành cho web

Tác vụ Trình nhận dạng cử chỉ của MediaPipe cho phép bạn nhận dạng cử chỉ tay theo thời gian thực, đồng thời cung cấp kết quả nhận dạng cử chỉ tay và các điểm đánh dấu trên bàn tay của những bàn tay được phát hiện. Hướng dẫn này cho bạn biết cách sử dụng Trình nhận dạng cử chỉ cho các ứng dụng web và JavaScript.

Bạn có thể xem tác vụ này hoạt động bằng cách xem bản minh hoạ. Để biết thêm thông tin về các chức năng, mô hình và lựa chọn cấu hình của tác vụ này, hãy xem phần Tổng quan.

Ví dụ về mã

Mã ví dụ cho Trình nhận dạng cử chỉ cung cấp một cách triển khai hoàn chỉnh cho tác vụ này bằng JavaScript để bạn tham khảo. Đoạn mã này giúp bạn kiểm thử tác vụ này và bắt đầu xây dựng ứng dụng nhận dạng cử chỉ của riêng mình. Bạn có thể xem, chạy và chỉnh sửa ví dụ về Trình nhận dạng cử chỉ chỉ bằng trình duyệt web.

Thiết lập

Phần này mô tả các bước chính để thiết lập môi trường phát triển, đặc biệt là để sử dụng Trình nhận dạng cử chỉ. Để biết thông tin chung về cách thiết lập môi trường phát triển web và JavaScript, bao gồm cả các yêu cầu về phiên bản nền tảng, hãy xem Hướng dẫn thiết lập cho web.

Gói JavaScript

Mã Trình nhận dạng cử chỉ có trong gói @mediapipe/tasks-vision NPM của MediaPipe. Bạn có thể tìm và tải các thư viện này xuống bằng cách làm theo hướng dẫn trong Hướng dẫn thiết lập nền tảng.

Bạn có thể cài đặt các gói cần thiết thông qua NPM bằng lệnh sau:

npm install @mediapipe/tasks-vision

Nếu bạn muốn nhập mã tác vụ thông qua dịch vụ mạng phân phối nội dung (CDN), hãy thêm mã sau vào thẻ <head> trong tệp HTML:

<!-- You can replace JSDeliver with another CDN if you prefer to -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.mjs"
    crossorigin="anonymous"></script>
</head>

Mô hình

Tác vụ Trình nhận dạng cử chỉ MediaPipe yêu cầu một mô hình đã được huấn luyện và tương thích với tác vụ này. Để biết thêm thông tin về các mô hình đã huấn luyện hiện có cho Trình nhận dạng cử chỉ, hãy xem phần Mô hình trong phần tổng quan về tác vụ.

Chọn và tải mô hình xuống, sau đó lưu trữ mô hình trong thư mục dự án của bạn:

<dev-project-root>/app/shared/models/

Tạo việc cần làm

Dùng một trong các hàm createFrom...() của Trình nhận dạng cử chỉ để chuẩn bị tác vụ chạy suy luận. Sử dụng hàm createFromModelPath() với đường dẫn tương đối hoặc tuyệt đối đến tệp mô hình đã huấn luyện. Nếu mô hình của bạn đã được tải vào bộ nhớ, bạn có thể sử dụng phương thức createFromModelBuffer().

Ví dụ về mã bên dưới minh hoạ cách sử dụng hàm createFromOptions() để thiết lập tác vụ. Hàm createFromOptions cho phép bạn tuỳ chỉnh Trình nhận dạng cử chỉ bằng các lựa chọn cấu hình. Để biết thêm thông tin về các lựa chọn cấu hình, hãy xem phần Các lựa chọn cấu hình.

Đoạn mã sau đây minh hoạ cách tạo và định cấu hình tác vụ bằng các lựa chọn tuỳ chỉnh:

// Create task for image file processing:
const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm "
);
const gestureRecognizer = await GestureRecognizer.createFromOptions(vision, {
  baseOptions: {
    modelAssetPath: "https://storage.googleapis.com/mediapipe-tasks/gesture_recognizer/gesture_recognizer.task"
  },
  numHands: 2
});

Các lựa chọn về cấu hình

Tác vụ này có các lựa chọn cấu hình sau đây cho các ứng dụng web:

Tên tuỳ chọn Mô tả Phạm vi giá trị Giá trị mặc định
runningMode Đặt chế độ chạy cho tác vụ. Có 2 chế độ:

HÌNH ẢNH: Chế độ dành cho các đầu vào là hình ảnh đơn.

VIDEO: Chế độ cho các khung hình đã giải mã của một video hoặc trên một sự kiện phát trực tiếp của dữ liệu đầu vào, chẳng hạn như từ camera.		 {IMAGE, VIDEO} IMAGE
num_hands GestureRecognizer có thể phát hiện tối đa số lượng bàn tay. Any integer > 0 1
min_hand_detection_confidence Điểm tin cậy tối thiểu để quá trình phát hiện bàn tay được coi là thành công trong mô hình phát hiện lòng bàn tay. 0.0 - 1.0 0.5
min_hand_presence_confidence Điểm số tin cậy tối thiểu của điểm số hiện diện của bàn tay trong mô hình phát hiện điểm đánh dấu bàn tay. Ở chế độ Video và chế độ Phát trực tiếp của Gesture Recognizer, nếu điểm số độ tin cậy về sự hiện diện của bàn tay từ mô hình điểm đánh dấu bàn tay thấp hơn ngưỡng này, thì mô hình phát hiện lòng bàn tay sẽ được kích hoạt. Nếu không, một thuật toán theo dõi cử động của tay đơn giản sẽ được dùng để xác định vị trí của(các) bàn tay nhằm phát hiện các điểm mốc tiếp theo. 0.0 - 1.0 0.5
min_tracking_confidence Điểm tin cậy tối thiểu để tính năng theo dõi cử động của tay được coi là thành công. Đây là ngưỡng IoU của khung giới hạn giữa các bàn tay trong khung hình hiện tại và khung hình cuối cùng. Ở chế độ Video và chế độ Phát trực tiếp của Trình nhận dạng cử chỉ, nếu quá trình theo dõi không thành công, Trình nhận dạng cử chỉ sẽ kích hoạt tính năng phát hiện bàn tay. Nếu không, quá trình phát hiện bàn tay sẽ bị bỏ qua. 0.0 - 1.0 0.5
canned_gestures_classifier_options Các lựa chọn để định cấu hình hành vi của trình phân loại cử chỉ được tạo sẵn. Các cử chỉ soạn sẵn là ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"]
  • Ngôn ngữ của tên hiển thị: ngôn ngữ dùng cho tên hiển thị được chỉ định thông qua Siêu dữ liệu mô hình TFLite (nếu có).
  • Số kết quả tối đa: số lượng kết quả phân loại được tính điểm cao nhất tối đa cần trả về. Nếu < 0, tất cả kết quả có sẵn sẽ được trả về.
  • Ngưỡng điểm: điểm mà kết quả sẽ bị từ chối nếu thấp hơn. Nếu bạn đặt giá trị này thành 0, tất cả kết quả có sẵn sẽ được trả về.
  • Danh sách cho phép danh mục: danh sách cho phép tên danh mục. Nếu không trống, những kết quả phân loại có danh mục không nằm trong tập hợp này sẽ bị lọc ra. Loại trừ lẫn nhau với danh sách từ chối.
  • Danh sách từ chối danh mục: danh sách từ chối tên danh mục. Nếu không trống, các kết quả phân loại có danh mục trong tập hợp này sẽ bị lọc ra. Loại trừ lẫn nhau với danh sách cho phép.
    		•
    • Ngôn ngữ của tên hiển thị: any string
    • Số kết quả tối đa: any integer
    • Ngưỡng điểm: 0.0-1.0
    • Danh sách cho phép danh mục: vector of strings
    • Danh sách từ chối theo danh mục: vector of strings
    • Ngôn ngữ của tên hiển thị: "en"
    • Số kết quả tối đa: -1
    • Ngưỡng điểm: 0
    • Danh sách cho phép đối với danh mục: trống
    • Danh sách từ chối đối với danh mục: trống
    custom_gestures_classifier_options Các lựa chọn để định cấu hình hành vi của trình phân loại cử chỉ tuỳ chỉnh.
  • Ngôn ngữ của tên hiển thị: ngôn ngữ dùng cho tên hiển thị được chỉ định thông qua Siêu dữ liệu mô hình TFLite (nếu có).
  • Số kết quả tối đa: số lượng kết quả phân loại được tính điểm cao nhất tối đa cần trả về. Nếu < 0, tất cả kết quả có sẵn sẽ được trả về.
  • Ngưỡng điểm: điểm mà kết quả sẽ bị từ chối nếu thấp hơn. Nếu bạn đặt giá trị này thành 0, tất cả kết quả có sẵn sẽ được trả về.
  • Danh sách cho phép danh mục: danh sách cho phép tên danh mục. Nếu không trống, những kết quả phân loại có danh mục không nằm trong tập hợp này sẽ bị lọc ra. Loại trừ lẫn nhau với danh sách từ chối.
  • Danh sách từ chối danh mục: danh sách từ chối tên danh mục. Nếu không trống, các kết quả phân loại có danh mục trong tập hợp này sẽ bị lọc ra. Loại trừ lẫn nhau với danh sách cho phép.
    		•
    • Ngôn ngữ của tên hiển thị: any string
    • Số kết quả tối đa: any integer
    • Ngưỡng điểm: 0.0-1.0
    • Danh sách cho phép danh mục: vector of strings
    • Danh sách từ chối theo danh mục: vector of strings
    • Ngôn ngữ của tên hiển thị: "en"
    • Số kết quả tối đa: -1
    • Ngưỡng điểm: 0
    • Danh sách cho phép đối với danh mục: trống
    • Danh sách từ chối đối với danh mục: trống

    Chuẩn bị dữ liệu

    Gesture Recognizer có thể nhận dạng cử chỉ trong hình ảnh ở mọi định dạng mà trình duyệt lưu trữ hỗ trợ. Tác vụ này cũng xử lý việc tiền xử lý dữ liệu đầu vào, bao gồm cả việc đổi kích thước, xoay và chuẩn hoá giá trị. Để nhận dạng cử chỉ trong video, bạn có thể dùng API này để xử lý nhanh từng khung hình một, sử dụng dấu thời gian của khung hình để xác định thời điểm cử chỉ xuất hiện trong video.

    Chạy tác vụ

    Trình nhận dạng cử chỉ sử dụng các phương thức recognize() (với chế độ chạy 'image') và recognizeForVideo() (với chế độ chạy 'video') để kích hoạt suy luận. Tác vụ này xử lý dữ liệu, cố gắng nhận dạng cử chỉ tay rồi báo cáo kết quả.

    Đoạn mã sau đây minh hoạ cách thực thi quy trình xử lý bằng mô hình tác vụ:

    Hình ảnh

    const image = document.getElementById("image") as HTMLImageElement;
const gestureRecognitionResult = gestureRecognizer.recognize(image);

    Video

    await gestureRecognizer.setOptions({ runningMode: "video" });

let lastVideoTime = -1;
function renderLoop(): void {
  const video = document.getElementById("video");

  if (video.currentTime !== lastVideoTime) {
    const gestureRecognitionResult = gestureRecognizer.recognizeForVideo(video);
    processResult(gestureRecognitionResult);
    lastVideoTime = video.currentTime;
  }

  requestAnimationFrame(() => {
    renderLoop();
  });
}

    Các lệnh gọi đến phương thức Gesture Recognizer recognize() và recognizeForVideo() chạy đồng bộ và chặn luồng giao diện người dùng. Nếu bạn nhận dạng cử chỉ trong khung hình video từ camera của thiết bị, thì mỗi lần nhận dạng sẽ chặn luồng chính. Bạn có thể ngăn chặn điều này bằng cách triển khai các worker trên web để chạy các phương thức recognize() và recognizeForVideo() trên một luồng khác.

    Để biết cách triển khai đầy đủ hơn về việc chạy một tác vụ Trình nhận dạng cử chỉ, hãy xem ví dụ.

    Xử lý và hiển thị kết quả

    Trình nhận dạng cử chỉ tạo một đối tượng kết quả phát hiện cử chỉ cho mỗi lần chạy nhận dạng. Đối tượng kết quả chứa các điểm đánh dấu bàn tay theo toạ độ hình ảnh, các điểm đánh dấu bàn tay theo toạ độ thế giới, tính thuận tay(tay trái/tay phải) và các danh mục cử chỉ tay của những bàn tay được phát hiện.

    Sau đây là ví dụ về dữ liệu đầu ra của tác vụ này:

    GestureRecognizerResult kết quả chứa 4 thành phần và mỗi thành phần là một mảng, trong đó mỗi phần tử chứa kết quả phát hiện của một bàn tay được phát hiện.

    • Tay thuận

      Thuận tay cho biết bàn tay được phát hiện là tay trái hay tay phải.

    • Cử chỉ

      Các danh mục cử chỉ được nhận dạng của bàn tay được phát hiện.

    • Địa danh

      Có 21 điểm đánh dấu trên bàn tay, mỗi điểm bao gồm các toạ độ x, y và z. Toạ độ x và y được chuẩn hoá thành [0.0, 1.0] theo chiều rộng và chiều cao của hình ảnh, tương ứng. Toạ độ z biểu thị độ sâu của điểm mốc, với độ sâu ở cổ tay là gốc. Giá trị càng nhỏ thì điểm đánh dấu càng gần camera. Độ lớn của z sử dụng gần như cùng một thang đo với x.

    • Điểm mốc Thế giới

      21 điểm đánh dấu trên bàn tay cũng được trình bày theo toạ độ thế giới. Mỗi điểm mốc bao gồm x, y và z, biểu thị toạ độ 3D trong thế giới thực tính bằng mét với gốc tại tâm hình học của bàn tay.

    GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : -3.41E-7
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
    ... (21 landmarks for a hand)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
    ... (21 world landmarks for a hand)

    Hình ảnh sau đây minh hoạ kết quả của tác vụ:

    Bàn tay giơ ngón tay cái lên, có cấu trúc xương bàn tay được lập bản đồ

    Để biết cách triển khai đầy đủ hơn về việc tạo một tác vụ Trình nhận dạng cử chỉ, hãy xem ví dụ.