Guía de detección de puntos de referencia manuales para la Web

La tarea MediaPipe Hand Landmarker te permite detectar los puntos de referencia de las manos en una imagen. En estas instrucciones, se muestra cómo usar el marcador de posición de la mano para apps web y de JavaScript.

Para obtener más información sobre las capacidades, los modelos y las opciones de configuración para completar esta tarea, consulta la Descripción general.

Ejemplo de código

El ejemplo de código de Hand Landmarker brinda una implementación completa de este en JavaScript para tu referencia. Este código te ayuda a probar esta tarea y obtener empezaste a crear tu propia app de detección de puntos de referencia en las manos. Puedes ver, ejecutar y editar el código de ejemplo del marcador de posición manual usando solo el navegador web.

Configuración

En esta sección, se describen los pasos clave para configurar tu entorno de desarrollo específicamente para usar Hand Landmarker. Para obtener información general configurar tu entorno de desarrollo web y de JavaScript, lo que incluye de la versión de la plataforma, consulta la Guía de configuración para la Web.

Paquetes de JavaScript

El código de marcador de posición de la mano está disponible a través de MediaPipe @mediapipe/tasks-vision. NPM. Puedes sigue las instrucciones de la plataforma para encontrar y descargar estas bibliotecas. Guía de configuración.

Puedes instalar los paquetes requeridos a través de NPM con el siguiente comando:

npm install @mediapipe/tasks-vision

Si quieres importar el código de la tarea a través de una red de distribución de contenidos (CDN) agrega el siguiente código en la sección <head> etiqueta en tu archivo 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>

Modelo

Para la tarea MediaPipe Hand Landmarker, se requiere un modelo entrenado compatible con esta tarea. Para obtener más información sobre los modelos entrenados disponibles para Hand Landmarker, consulta la sección Modelos de la descripción general de la tarea.

Selecciona y descarga un modelo y, luego, guárdalo en el directorio de tu proyecto:

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

Crea la tarea

Usa una de las funciones createFrom...() de la marca de posición de la mano para realizar lo siguiente: preparan la tarea para ejecutar inferencias. Usa el createFromModelPath() con una ruta de acceso absoluta o relativa al archivo de modelo entrenado. Si tu modelo ya está cargado en la memoria, puedes usar createFromModelBuffer().

En el siguiente ejemplo de código, se demuestra el uso de la función createFromOptions() para configurar la tarea. La función createFromOptions te permite personalizar la Punto de referencia manual con opciones de configuración. Para obtener más información sobre la configuración consulta Opciones de configuración.

En el siguiente código, se muestra cómo compilar y configurar la tarea con Opciones:

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
    });

Opciones de configuración

Esta tarea tiene las siguientes opciones de configuración para la Web y JavaScript aplicaciones:

Nombre de la opción Descripción Rango de valores Valor predeterminado
runningMode Establece el modo de ejecución de la tarea. Existen dos modos:

IMAGE: Es el modo para entradas de una sola imagen.

VIDEO: el modo para fotogramas decodificados de una o en una transmisión en vivo de datos de entrada, como los de una cámara.		 {IMAGE, VIDEO} IMAGE
numHands La cantidad máxima de manos que detecta el detector de puntos de referencia de la mano. Any integer > 0 1
minHandDetectionConfidence La puntuación de confianza mínima para la detección de la mano considerado exitoso en el modelo de detección de palma. 0.0 - 1.0 0.5
minHandPresenceConfidence La puntuación de confianza mínima para la puntuación de presencia de la mano en la mano de detección de puntos de referencia. En los modos de video y de transmisión en vivo, si la puntuación de confianza de la presencia de la mano del modelo de punto de referencia de la mano es inferior este umbral, Hand Landmarker, se activa el modelo de detección de la palma. De lo contrario, el algoritmo de seguimiento de manos ligeras determina la ubicación de para las detecciones de puntos de referencia posteriores. 0.0 - 1.0 0.5
minTrackingConfidence La puntuación de confianza mínima para que se considere el seguimiento de la mano y exitoso. Este es el umbral de IoU del cuadro delimitador entre manos en el fotograma actual y el último. En los modos Video y Transmisión de El marcador de posición de mano (hand Landmarker) si el seguimiento falla, activa la mano de detección de intrusiones. De lo contrario, omitirá la detección de manos. 0.0 - 1.0 0.5

Preparar los datos

El marcador de posición de la mano puede detectar puntos de referencia de la mano en imágenes de cualquier formato compatible con el navegador del host. La tarea también maneja el procesamiento previo de la entrada de datos, lo que incluye cambio de tamaño, rotación y normalización de valores. Para detectar puntos de referencia en las manos, haz lo siguiente en los videos: puedes usar la API para procesar rápidamente un fotograma a la vez, con la marca de tiempo del fotograma para determinar cuándo aparecen los puntos de referencia de la mano en el video.

Ejecuta la tarea

El Landmarker de la mano usa el detect() (con el modo de ejecución image) y Métodos detectForVideo() (con el modo de ejecución video) para activar para hacer inferencias. La tarea procesa los datos, intenta detectar puntos de referencia en las manos y y, luego, informa los resultados.

Se ejecutan las llamadas al marcador de posición manual de los métodos detect() y detectForVideo(). de forma síncrona y bloquea el subproceso de la interfaz de usuario. Si detectas puntos de referencia en la mano en fotogramas de video desde la cámara de un dispositivo, cada detección bloquea la principal conversación. Para evitar esto, implementa trabajadores web para ejecutar detect(). y detectForVideo() en otro subproceso.

En el siguiente código, se muestra cómo ejecutar el procesamiento con el modelo de tareas:

Imagen

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();
  });
}

Para obtener una implementación más completa de la ejecución de una tarea de Landmarker de la mano, consulta el ejemplo de código de barras.

Cómo controlar y mostrar resultados

El marcador de posición de la mano genera un objeto de resultado del sistema de puntos de referencia de la mano para cada detección cuando se ejecute. El objeto resultante contiene puntos de referencia en coordenadas de imágenes, mano puntos de referencia en coordenadas mundiales y la mano derecha(mano izquierda/derecha) del dispositivo detectado manos.

A continuación, se muestra un ejemplo de los datos de salida de esta tarea:

El resultado HandLandmarkerResult contiene tres componentes. Cada componente es un array en el que cada elemento contiene los siguientes resultados para una sola mano detectada:

  • Mano dominante

    La Mano dominante representa si las manos detectadas son la izquierda o la derecha.

  • Puntos de referencia

    Hay 21 puntos de referencia de la mano, cada uno compuesto por coordenadas x, y y z. El Las coordenadas x y y se normalizan a [0.0, 1.0] por el ancho de la imagen y altura, respectivamente. La coordenada z representa la profundidad del punto de referencia, con y la profundidad en la muñeca es el origen. Cuanto menor sea el valor, más cerca punto de referencia a la cámara. La magnitud de z usa más o menos la misma escala que x

  • Monumentos universales

    Los 21 puntos de referencia de las manos también se presentan en coordenadas mundiales. Cada punto de referencia está compuesto por x, y y z, que representan coordenadas 3D del mundo real en metros con el origen en el centro geométrico de la mano.

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)

En la siguiente imagen, se muestra una visualización del resultado de la tarea:

El código de ejemplo de Hand Landmarker muestra cómo mostrar el resultados que devolvió la tarea, consulta la ejemplo de código