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

Với nhiệm vụ Trình nhận dạng cử chỉ MediaPipe, bạn có thể nhận dạng các cử chỉ của tay theo thời gian thực và cung cấp kết quả cử chỉ tay được nhận dạng và các mốc nhận dạng bàn tay của đã phát hiện thấy bàn tay nào. Các hướng dẫn sau chỉ cho bạn cách sử dụng Trình nhận dạng cử chỉ cho ứng dụng web và JavaScript.

Bạn có thể xem công việc này trong thực tế bằng cách xem bản minh hoạ. Để biết thêm thông tin về tính năng, kiểu máy và các lựa chọn cấu hình của nhiệm vụ nà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 cách triển khai hoàn chỉnh việc này trong JavaScript để bạn tham khảo. Mã này giúp bạn kiểm thử công việc này và bắt đầu xây dựng ứng dụng nhận dạng cử chỉ của riêng bạn. Bạn có thể xem, chạy và chỉnh sửa mã 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ụ thể để sử dụng Trình nhận dạng cử chỉ. Để biết thông tin chung về thiết lập môi trường phát triển web và JavaScript, bao gồm 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ã Nhận dạng cử chỉ có trên MediaPipe @mediapipe/tasks-vision Gói Trạng thái đã hiển thị 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 nền tảng Hướng dẫn thiết lập.

Bạn có thể cài đặt các gói bắt buộc thông qua kháng nghị bằng lệnh sau:

npm install @mediapipe/tasks-vision

Nếu bạn muốn nhập mã tác vụ qua 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.js"
    crossorigin="anonymous"></script>
</head>

Mẫu

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

Chọn và tải mô hình xuống rồi lưu trữ mô hình đó trong thư mục dự án:

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

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

Sử dụng một trong các chức năng createFrom...() của Trình nhận dạng cử chỉ để chuẩn bị tác vụ để chạy các dự đoán. Sử dụng createFromModelPath() có đườ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 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ạ việc sử dụng hàm createFromOptions() để thiết lập việc cần làm. Hàm createFromOptions cho phép bạn tuỳ chỉnh Trình nhận dạng cử chỉ với các lựa chọn cấu hình. Để biết thêm thông tin về cấu hình hãy xem phần Tuỳ chọn cấu hình.

Mã sau đây minh hoạ cách tạo và định cấu hình tác vụ bằng công cụ tuỳ chỉnh tùy chọn:

// 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 ứng dụng web:

Tên lựa chọn Mô tả Khoảng giá trị Giá trị mặc định
runningMode Thiết lập chế độ chạy cho tác vụ. Có hai chế độ:

HÌNH ẢNH: Chế độ cho đầu vào một hình ảnh.

VIDEO: Chế độ cho khung đã giải mã của hoặc sự kiện phát trực tiếp dữ liệu đầu vào, chẳng hạn như từ camera.		 {IMAGE, VIDEO} IMAGE
num_hands Số lượng tay tối đa có thể phát hiện bằng GestureRecognizer. Any integer > 0 1
min_hand_detection_confidence Điểm tin cậy tối thiểu để phát hiện tay được coi là thành công trong mô hình phát hiện tì tay. 0.0 - 1.0 0.5
min_hand_presence_confidence Điểm số tin cậy tối thiểu về điểm số có mặt trên tay mô hình phát hiện mốc. Ở chế độ Video và chế độ phát trực tiếp của Trình nhận dạng cử chỉ, nếu điểm số tự tin về sự hiện diện của bàn tay từ mô hình điểm mốc bàn tay ở bên dưới ngưỡng này, nó sẽ kích hoạt mô hình phát hiện tì tay. Nếu không, một thuật toán theo dõi cử chỉ tay nhẹ được dùng để xác định vị trí của tay để phát hiện 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ử chỉ tay được xem xét thành công. Đây là ngưỡng IoU hộp giới hạn giữa các tay trong khung hiện tại và khung cuối cùng. Ở chế độ Video và chế độ Phát trực tuyến của Trình nhận dạng cử chỉ sẽ kích hoạt tay nếu theo dõi không thành công của bạn. Nếu không, tính năng phát hiện tay sẽ bị bỏ qua. 0.0 - 1.0 0.5
canned_gestures_classifier_options Các tuỳ chọn để định cấu hình hành vi của thuật toán phân loại cử chỉ soạn trước. Các cử chỉ soạn trước 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ó.
  • Kết quả tối đa: số lượng kết quả phân loại có điểm số 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 số: điểm số thấp hơn kết quả bị từ chối. Nếu bạn đặt thành 0, hệ thống sẽ trả về tất cả kết quả có sẵn.
  • Danh mục danh mục cho phép: danh sách cho phép chứa tên danh mục. Nếu không để trống, các 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 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 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 số: 0.0-1.0
    • Danh mục cho phép: vector of strings
    • Danh sách từ chối 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 số: 0
    • Danh mục danh mục cho phép: trống
    • Danh sách từ chối danh mục: trống
    custom_gestures_classifier_options Các tuỳ chọn để định cấu hình hành vi của thuật toán 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ó.
  • Kết quả tối đa: số lượng kết quả phân loại có điểm số 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 số: điểm số thấp hơn kết quả bị từ chối. Nếu bạn đặt thành 0, hệ thống sẽ trả về tất cả kết quả có sẵn.
  • Danh mục danh mục cho phép: danh sách cho phép chứa tên danh mục. Nếu không để trống, các 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 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 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 số: 0.0-1.0
    • Danh mục cho phép: vector of strings
    • Danh sách từ chối 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 số: 0
    • Danh mục danh mục cho phép: trống
    • Danh sách từ chối danh mục: trống

    Chuẩn bị dữ liệu

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

    Chạy tác vụ

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

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

    Bài đăng có 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 các phương thức recognize() và recognizeForVideo() của Trình nhận dạng cử chỉ sẽ chạy một cách đồng bộ và chặn luồng giao diện người dùng. Nếu bạn nhận ra cử chỉ trong khung hình video từ camera của thiết bị, mỗi lần nhận dạng sẽ chặn chuỗi. Bạn có thể ngăn chặn điều này bằng cách triển khai trình thực thi web để chạy Các phương thức recognize() và recognizeForVideo() trên một chuỗi khác.

    Để triển khai hoàn chỉnh hơn khi chạy tác vụ của Trình nhận dạng cử chỉ, hãy xem mã ví dụ.

    Xử lý và hiện 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 chạy nhận dạng. Đối tượng kết quả chứa các điểm mốc bàn tay trong toạ độ hình ảnh, địa danh tay trong toạ độ thế giới, tay thuận(tay trái/phải) và bàn tay các loại cử chỉ của tay được phát hiện.

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

    Kết quả GestureRecognizerResult 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 đã phát hiện.

    • Tay thuận

      Tay thuận cho biết tay trái hay tay phải.

    • Cử chỉ

      Các loại cử chỉ được nhận dạng của tay được phát hiện.

    • Địa danh

      Có 21 điểm mốc kim, mỗi điểm bao gồm các toạ độ x, y và z. Chiến lược phát hành đĩa đơn Toạ độ x và y được chuẩn hoá thành [0, 1, 1] theo chiều rộng của hình ảnh và chiều cao tương ứng. Toạ độ z biểu thị độ sâu của điểm mốc, với độ sâu ở cổ tay là điểm gốc. Giá trị càng nhỏ thì là đến máy ảnh. Độ lớn của z có cùng tỷ lệ với x

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

      Các mốc 21 kim đồng hồ cũng được thể hiện trên toạ độ thế giới. Mỗi mốc bao gồm x, y và z, thể hiện các toạ độ 3D thực tế trong mét có gốc toạ độ ở tâm hình học của kim đồng hồ.

    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)

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

    Để triển khai hoàn chỉnh hơn việc tạo tác vụ Trình nhận dạng cử chỉ, hãy xem mã ví dụ.