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ỉ MediaPipe cho phép bạn nhận dạng cử chỉ của tay theo thời gian thực, đồng thời cung cấp kết quả nhận dạng cử chỉ tay cũng như điểm mốc trên tay của các tay đã phát hiện. Các hướng dẫn này chỉ cho bạn cách sử dụng Trình nhận dạng cử chỉ dành cho các ứng dụng web và JavaScript.

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

Ví dụ về mã

Mã mẫu cho Trình nhận dạng cử chỉ cung cấp cách triển khai đầy đủ tác vụ này trong JavaScript để bạn tham khảo. 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 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ề 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ó sẵn trong gói CNP của MediaPipe @mediapipe/tasks-vision. 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 phần Hướng dẫn thiết lập của nền tảng.

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

npm install @mediapipe/tasks-vision

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

Mẫu

Tác vụ Trình nhận dạng cử chỉ MediaPipe cần có một mô hình đã qua huấn luyện 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 tổng quan về tác vụ.

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

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

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

Sử dụng một trong các hàm createFrom...() của Trình nhận dạng cử chỉ để chuẩn bị nhiệm vụ chạy dự đoán. Sử dụng hàm 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ạ cách sử dụng hàm createFromOptions() để thiết lập nhiệm vụ. Hàm createFromOptions cho phép bạn tuỳ chỉnh Trình nhận dạng cử chỉ bằng các tuỳ 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 Lựa 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á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 cho Ứng dụng web:

Tên lựa chọn	Nội dung mô tả	Khoảng giá trị	Giá trị mặc định
`runningMode`	Đặt chế độ chạy cho tác vụ. Có hai chế độ: IMAGE: Chế độ nhập một hình ảnh. VIDEO: Chế độ dành cho các khung hình đã giải mã của video hoặc trên một luồng phát trực tiếp dữ liệu đầu vào, chẳng hạn như từ máy ảnh.	{`IMAGE, VIDEO`}	`IMAGE`
`num_hands`	`GestureRecognizer` có thể phát hiện số lượng tay tối đa.	`Any integer > 0`	`1`
`min_hand_detection_confidence`	Điểm số tin cậy tối thiểu để tính năng phát hiệ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 về điểm số có mặt kim trong mô hình phát hiện điểm mốc trên kim đồng hồ. Ở 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ự có mặt của tay trong mô hình điểm mốc trên tay thấp hơn ngưỡng này, thì điểm số này 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 kim nhẹ sẽ được dùng để xác định vị trí của(các) kim nhằm phát hiện điểm mốc tiếp theo.	`0.0 - 1.0`	`0.5`
`min_tracking_confidence`	Điểm số tin cậy tối thiểu để theo dõi tay được coi là thành công. Đây là ngưỡng IoU hộp giới hạn giữa các kim trong khung hiện tại và khung cuối cùng. Ở chế độ Video và chế độ Luồng của Trình nhận dạng cử chỉ, nếu quá trình theo dõi không thành công thì Trình nhận dạng cử chỉ sẽ kích hoạt tính năng phát hiện tay. 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ó. Số kết quả tối đa: số lượng tối đa các kết quả phân loại có điểm cao nhất cần trả về. Nếu < 0, hàm sẽ trả về tất cả kết quả hiện có. Ngưỡng điểm: điểm số mà kết quả bị từ chối dưới dạng điểm số. Nếu đặt là 0, hàm sẽ trả về tất cả kết quả hiện có. Danh sách cho phép của danh mục: danh sách cho phép của các tên danh mục. Nếu không trố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 bằng danh sách từ chối. Danh sách từ chối danh mục: danh sách từ chối chứa tên danh mục. Nếu không trống, 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 bằng 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 đượ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 đượ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ó. Số kết quả tối đa: số lượng tối đa các kết quả phân loại có điểm cao nhất cần trả về. Nếu < 0, hàm sẽ trả về tất cả kết quả hiện có. Ngưỡng điểm: điểm số mà kết quả bị từ chối dưới dạng điểm số. Nếu đặt là 0, hàm sẽ trả về tất cả kết quả hiện có. Danh sách cho phép của danh mục: danh sách cho phép của các tên danh mục. Nếu không trố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 bằng danh sách từ chối. Danh sách từ chối danh mục: danh sách từ chối chứa tên danh mục. Nếu không trống, 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 bằng 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 đượ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 đượ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 ở mọi định dạng mà trình duyệt máy chủ hỗ trợ. Tác vụ này cũng xử lý trước việc nhập dữ liệu, bao gồm 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ể sử dụng API để nhanh chóng xử lý 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ỉ diễn ra 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 dự đoán. Tác vụ này sẽ xử lý dữ liệu, cố gắng nhận dạng các cử chỉ của tay, 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 phương thức recognize() và recognizeForVideo() của Trình nhận dạng cử chỉ sẽ chạy đồng bộ và chặn luồng giao diện người dùng. Nếu bạn nhận ra các cử chỉ trong khung video từ máy ảnh của thiết bị, thì mỗi hoạt động 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 trình thực thi web để chạy phương thức recognize() và recognizeForVideo() trên một luồng khác.

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

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

Sau đây là ví dụ về dữ liệu đầu ra của nhiệm 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 của một kim phát hiện.

Tay thuận

Tay thuận biểu thị việc tay được phát hiện là tay trái hay tay phải.
Cử chỉ

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

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

Các mốc 21 kim cũng được trình bày theo toạ độ trên thế giới. Mỗi điểm mốc bao gồm x, y và z, biểu thị các toạ độ 3D thực tế tính bằng mét với 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 đầy đủ hơn việc tạo một tác vụ của Trình nhận dạng cử chỉ, hãy xem ví dụ về mã.