Hướng dẫn phát hiện mốc trên tay cho web

Nhiệm vụ MediaPipe Hand chunger cho phép bạn phát hiện các điểm mốc của bàn tay trong một hình ảnh. Các hướng dẫn này chỉ cho bạn cách sử dụng Cột mốc cầm tay cho các ứng dụng web và JavaScript.

Để 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 Bàn tay địa điểm cung cấp cách triển khai đầy đủ của tác vụ này trong JavaScript để bạn tham khảo. Mã này giúp bạn kiểm thử nhiệm vụ này và bắt đầu xây dựng ứng dụng phát hiện điểm mốc gắn trên tay của riêng mình. Bạn có thể xem, chạy và chỉnh sửa mã ví dụ về Bàn tay của Người đánh dấu 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 dành riêng cho việc sử dụng Cột mốc được viết trên tay. Để 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ã HandMốc giới thiệu có sẵn thông qua gói MediaPipe @mediapipe/tasks-vision CNTT. 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ụ của 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ụ MediaPipe Hand Accesser 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 Bàn tay được đánh dấu, hãy xem phần Mô hình tổng quan về tác vụ.

Chọn và tải một mô hình xuống, sau đó 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 Bàn tay để 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ụ. Chức năng createFromOptions cho phép bạn tuỳ chỉnh Khung giao diện tay với 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:

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "hand_landmarker.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 dành cho ứng dụng Web và JavaScript:

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`
`numHands`	Số lượng tay tối đa mà trình phát hiện mốc Tay phát hiện được.	`Any integer > 0`	`1`
`minHandDetectionConfidence`	Đ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`
`minHandPresenceConfidence`	Điểm số tin cậy tối thiểu cho điểm số về sự hiện diện của tay trong mô hình phát hiện điểm mốc kim loại. Ở chế độ Video và chế độ Phát trực tiếp, nếu điểm số tin cậy của sự hiện diện kim đồng hồ từ mô hình điểm mốc kim loại thấp hơn ngưỡng này, thì Tay mốc sẽ kích hoạt mô hình phát hiện lòng bàn tay. Nếu không, thuật toán theo dõi kim nhẹ sẽ xác định vị trí của(các) kim để phát hiện điểm mốc tiếp theo.	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	Đ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ế độ Phát trực tiếp của Cổng đánh dấu tay, nếu theo dõi không thành công, Tay Cột mốc sẽ kích hoạt tính năng phát hiện tay. Nếu không, tính năng này sẽ bỏ qua tính năng phát hiện tay.	`0.0 - 1.0`	`0.5`

Chuẩn bị dữ liệu

Bàn tay có thể phát hiện các mốc trên bàn tay trong hình ảnh ở bất kỳ định dạng nào được 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ị. Để phát hiện điểm mốc trên tay trong video, bạn có thể sử dụng API để nhanh chóng xử lý từng khung hình một bằng cách sử dụng dấu thời gian của khung hình để xác định thời điểm điểm mốc trên tay xuất hiện trong video.

Chạy tác vụ

Cổng mốc cầm tay sử dụng các phương thức detect() (với chế độ đang chạy image) và detectForVideo() (với chế độ đang chạy video) để kích hoạt dự đoán. Nhiệm vụ này sẽ xử lý dữ liệu, cố gắng phát hiện các điểm mốc trên bàn tay, sau đó báo cáo kết quả.

Các lệnh gọi đến phương thức detect() và detectForVideo() của Tay Cột mốc sẽ chạy đồng bộ và chặn luồng giao diện người dùng. Nếu bạn phát hiện điểm mốc trên bàn tay trong khung hình video qua máy ảnh của thiết bị, thì mỗi lượt phát hiện 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 detect() và detectForVideo() trên một luồng khác.

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 handLandmarkerResult = handLandmarker.detect(image);

Video

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

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

  if (video.currentTime !== lastVideoTime) {
    const detections = handLandmarker.detectForVideo(video);
    processResults(detections);
    lastVideoTime = video.currentTime;
  }

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

Để triển khai đầy đủ hơn việc chạy một tác vụ có mốc phát hiện dấu tay, hãy xem ví dụ về mã.

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

Tay mốc có thể tạo một đối tượng kết quả của điểm mốc làm thủ công cho mỗi lần chạy phát hiện. Đối tượng kết quả chứa các mốc kim trong toạ độ hình ảnh, điểm mốc kim trên toạ độ thế giới và tỷ lệ thuận tay(tay trái/phải) của tay được phát hiện.

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

Đầu ra HandLandmarkerResult chứa 3 thành phần. Mỗi thành phần là một mảng, trong đó mỗi phần tử chứa các kết quả sau đây cho một kim được 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.
Đị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ồ.

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  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ụ:

Mã ví dụ về Cột mốc số tay minh hoạ cách hiển thị kết quả trả về từ tác vụ, hãy xem ví dụ về mã