Face-Detector

Face-Detector es un componente web construido con StencilJs que permite la detección de rostros en entradas de video e imagen. Puede operar en modo cámara de video o carga de archivos, ofreciendo capacidades robustas para aplicaciones web.

Si deseas ver la documentación dentro de npm visita este link: Face-Detector npm. La version mostrada a continuación es 1.2.0-dev.15.

Objetivo

Proporcionar una herramienta esencial para el desarrollo web, ofreciendo capacidades de detección de rostros adaptadas para diversas aplicaciones.

Instalación

Antes de comenzar, asegúrese de tener instalado Node.js y npm en su máquina. Estas herramientas son necesarias para instalar y administrar las dependencias del proyecto.

Node.js: Asegúrate de tener Node.js instalado en tu sistema. Puedes descargarlo e instalarlo desde aquí.

node --version

npm: npm (Node Package Manager) generalmente se instala junto con Node.js. Verifica la instalación de npm con el siguiente comando:

npm -v

Una vez confirmado lo anterior, instala el paquete utilizando npm:

npm i @jaak.ai/[email protected]

Este paquete necesita dependencias de biblioteca, si es necesario, puede instalar las dependencias manualmente usando este comando:

npm install @jaak.ai/video-camera @jaak.ai/file-uploader

Código Muestra

<face-detector
  config={{
    width: '640px',
    height: '480px',
    enableMicrophone: true,
    mode: 'video-camera',
    placeholder: 'Upload your document',
    buttonText: 'Upload',
    documentAccept: 'image/*',
    description: 'Please upload an image file.',
    size: 2048
  }}
  onStatus={(event) => handleStatusChange(event.detail)}
  onComponentError={(event) => handleComponentError(event.detail)}
  onFileResult={(event) => handleFileResult(event.detail)}
></face-detector>

Configuración

El componente puede ser configurado con múltiples opciones para adaptarse a las necesidades específicas de su aplicación. Las propiedades incluyen dimensiones del elemento de vídeo, habilitación del micrófono, modo de operación, configuraciones para la entrada de archivo, tamaño máximo del archivo, duración del vídeo, entre otros:

Property	Type	Description
width	string	Ancho del elemento de video. Valor por defecto: `500px`.
height	string	Alto del elemento de video. Valor por defecto: `400px`.
enableMicrophone	boolean	Indica si el micrófono debe estar habilitado. Valor por defecto: `false`.
mode	string	Modo operativo, ya sea `video-camera` o `upload-file`. Valor por defecto: `upload-file`.
placeholder	string	Texto del marcador de posición para la entrada de archivo.
buttonText	string	Texto mostrado en el botón de carga.
documentAccept	string	Especifica los tipos de archivos que pueden ser cargados.
description	string	Descripción mostrada cerca de la entrada de archivo.
size	number	Tamaño máximo permitido del archivo en kilobytes. Valor por defecto: `5000`.
videoDuration	number	Duración de la grabación de video en segundos. Valor por defecto: `4`.
video	MediaTrackConstrains	Duración de la grabación de vídeo en segundos.
cameraSource	string	Especifica qué cámara usar para la captura de video cuando hay múltiples fuentes disponibles, como `user` (cámara frontal) o `environment` (cámara trasera).
videoFormat	string	Define la resolución de video preferida y el formato de velocidad de fotogramas, como `1920x1080@30` para video 1080p a 30 cuadros por segundo.
autoRecorder	boolean	Si el sistema detecta una cara en el modo de cámara de video, grabará un video (`videoDuration`).
hideFaceTracker	boolean	Oculta la forma de monitoreo que se superpone en la cara encontrada durante la transmisión de video. Valor por defecto: `false`.
disableFaceDetection	boolean	Desactive el sistema de detección de rostros, el componente no busca rostros durante el video. Valor por defecto: `false`.
progressiveAutoRecorder	boolean	El componente no deja de grabar videos después de la primera grabación. ⚠️Aviso: deberá cerrar el ciclo de vida manualmente. Valor por defecto: `false`.
muteFaceDetectionMessages	boolean	Deshabilitar el envió de mensajes de detección de rostros durante la transmisión de video. Valor por defecto: `false`.
hideTimer	boolean	El indicador de grabación no se mostrará durante el proceso. Valor por defecto: `false`.
timerStyles	TimerStyles	Definir los estilos del indicador de grabación durante el proceso.
faceTrackerStyles	FaceTrackerStyles	Definir los estilos de la figura en el rostro encontrado por el sistema de detección.
offlineModel	boolean	Cargar el sistema de detección de rostros sin realizar solicitudes de Internet (almacenamiento local).

Eventos

El FaceDetectorComponent emite varios eventos que pueden ser utilizados para responder a cambios de estado, errores y resultados de archivos. Estos incluyen status, componentError, y fileResult:

Event	Description
status	Emitido cuando cambia el estado del componente.
componentError	Emitido cuando ocurre un error en el componente.
fileResult	Emitido con el resultado de la operación del archivo.
faceDetectionMessage	Emitido con los resultados de la detección de rostros y sus detalles de estado y calidad.

Interfaces

FileResult `Interface`

La interfaz FileResult proporciona información detallada sobre el resultado de una operación de archivo:

Propiedad	Tipo	Descripción
base64	string	Cadena codificada en Base64 del contenido del archivo.
type	string	Tipo MIME del archivo (opcional).
name	string	Nombre original del archivo (opcional).
size	number	Tamaño del archivo en bytes (opcional).

FaceDetectionMessage `Interface`

La interfaz FaceDetectionMessage proporciona información detallada sobre el resultado de la operación FaceDetection.

Propiedad	Tipo	Descripción
label	string	Etiqueta que describe el resultado general de la detección de rostros.
details	string	Detalles adicionales sobre el resultado de la detección de rostros.
faceExist	boolean	Indica si se detectó una cara o no.
correctPosition	boolean	Indica si la cara detectada está en la posición correcta según sea necesario.

TimerStyles `Interface`

La interfaz TimerStyles detalla los estilos del indicador de grabación con temporizador:

Propiedad	Tipo	Descripción
color	string	Color del texto del indicador de progreso.
circleColor	string	Color de la parte rellena del círculo de progreso.
circleColorEmpty	string	Color de la parte vacía del círculo de progreso.
circleColorSuccess	string	Color del círculo de progreso cuando la tarea se realiza correctamente.
width	number	Ancho del círculo de progreso en píxeles.
height	number	Altura del círculo de progreso en píxeles.
fontSize	number	Tamaño de fuente del texto del indicador de progreso en píxeles.
posX	number	Posición horizontal del indicador de progreso. Acepta (0 - 100). Valor por defecto: 50.
posY	number	Posición vertical del indicador de progreso. Acepta (0 - 100). Valor por defecto: 50.
strokeWidth	number	Ancho del trazo del círculo de progreso en píxeles.
dashArray	string	Patrón de trazo y guión del círculo de progreso.

FaceTrackerStyles `Interface`

La interfaz detalla los estilos del indicador de seguimiento facial:

Propiedad	Tipo	Descripción
validColor	string	Color opcional utilizado para indicar una detección de rostro válida.
invalidColor	string	Color opcional utilizado para indicar una detección de rostro no válida.

webComponentError `Interface`

La interfaz que detalla cuándo el componente arroja una operación de error:

Propiedad	Tipo	Descripción
label	string	Etiqueta descriptiva que resume el error.
code	string	Código opcional que identifica el tipo de error.
details	any	Datos adicionales opcionales o información sobre el error.

Enum `StatusFaceDetector`

El enum StatusFaceDetector representa los diversos estados que el FaceDetectorComponent puede emitir durante su operación:

Estado	Descripción
NOT_LOADED	Estado inicial antes de que hayan comenzado las operaciones.
LOADING	El componente está cargando los recursos necesarios.
LOADED	Todos los recursos están cargados y el componente está listo para ser usado.
RECORDING	El componente está grabando video actualmente.
ERROR	Ha ocurrido un error en uno de los procesos.
UPLOADING	El componente está subiendo un archivo.
RUNNING	El componente está procesando activamente.
SNAPSHOTTING	El componente está tomando una instantánea.
FINISHED	El componente ha completado todas las tareas de procesamiento y registro.

Métodos

El componente ofrece varios métodos para interactuar con él:

turnOffFaceDetector(): Desactiva el detector de rostros, oculta la forma del modelo y cancela la suscripción al servicio de detección.
switchMode(newMode:video-camera | upload-file): Cambia el modo operativo del componente.
stopComponent(): Detiene las operaciones del componente invocando el método interno stopCore.
restartComponent(): Restablece el componente a su configuración inicial usando resetCore.
getMode(): Retorna el modo actual del componente.
recordVideo(): Inicia la grabación de video basado en la config.videoDuration y lo devuelve en formato Base64.
takeSnapshot(): Toma una instantánea usando el componente de video y lo retorna en formato Base64.
getVideoElement(): Retorna el elemento de video si está disponible en formato Base64.
getStream(): Recupera la transmisión multimedia del componente de la cámara de vídeo.
toggleCamera(): Alterna la cámara de video entre los modos frontal y posterior.
stopVideoStream(): Detiene la transmisión de video desde el componente de la cámara de video.
restartVideoStream(): Reanuda la transmisión de video desde el componente de la cámara de video.
resetFaceDetector(resetHard: boolean): Restablece el detector de rostros a su estado predeterminado y, opcionalmente, realiza un restablecimiento completo.

Ejemplos

Ejemplo HTML and JavaScript

Utilizando node, y una vez que el paquete face-detector se encuentra instalado:

Crea un archivo HTML

Crea un archivo HTML (por ejemplo, index.html). Copia y pega el siguiente código en el archivo:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Ejemplo Face Detector</title>
  	<script type="module" src="https://unpkg.com/@jaak.ai/face-detector"></script>
</head>
<body>
    <!-- Incluir el componente Face Detector -->
    <face-detector id="faceDetector"></face-detector>

    <script type="module">
        // Seleccionar el componente face-detector
        const faceDetector = document.getElementById('faceDetector');

        // Configurar el componente con los ajustes iniciales
        faceDetector.config = {
            width: '640px',
            height: '480px',
            enableMicrophone: false,
            mode: 'video-camera', // o 'upload-file' para modo de carga de archivos
            placeholder: 'Upload your image',
            buttonText: 'Upload File',
            documentAccept: 'image/*',
            description: 'Please upload an image for face detection',
            size: 2048, // Tamaño máximo del archivo en kilobytes
            videoDuration: 5 // Duración en segundos para la grabación de video
        };

        // Manejar el evento de estado
        faceDetector.addEventListener('status', event => {
            console.log('Status event:', event.detail);
            // Puedes actualizar la UI basada en el estado aquí
        });

        // Manejar errores
        faceDetector.addEventListener('componentError', event => {
            console.error('Error event:', event.detail);
            // Mostrar mensajes de error al usuario
        });

        // Manejar resultados de archivos
        faceDetector.addEventListener('fileResult', event => {
            console.log('File result event:', event.detail);
            // Procesar el resultado del archivo, por ejemplo, mostrar la imagen o video
        });

        // Ejemplo de uso de un método del componente para cambiar modos
        function switchToUploadMode() {
            faceDetector.switchMode('upload-file');
        }

        // Agregar más lógica de funcionalidad o interacción según sea necesario
    </script>
</body>
</html>

Despliega el archivo HTML

Usa un servidor web estático para servir el archivo HTML. Por ejemplo, puedes usar live-server:

npm install -g live-server
live-server

Navega a la URL proporcionada por live-server para ver tu página en acción.

ReactJS

Ejemplo ReactJS

Configurar un proyecto React

Si no tienes un proyecto React, crea uno nuevo:

npx create-react-app face-detector-example
cd face-detector-example

Instalar el paquete @jaak.ai/face-detector

npm install @jaak.ai/face-detector

Crear el componente FaceDetector

⚠️ IMPORTANTE si está usando en la configuración(tsconfig) JSX con el valor “jsx-react“, tambien se debe declarar los HTML tags desde el index.ts

declare global {  
	namespace JSX {  
		interface IntrinsicElements {  
			'video-camera-recorder': React.DetailedHTMLProps\<  
				React.HTMLAttributes<HTMLElement>,  
				HTMLElement  
			>;  
		}  
	}  
}

Crea un archivo llamado FaceDetector.js dentro de la carpeta src. Copia y pega el siguiente código en FaceDetector.js:

import React, { useState, useEffect } from 'react';
import { defineCustomElements } from '@jaak.ai/face-detector/loader';


const FaceDetector = () => {
    const [status, setStatus] = useState('');
    const [error, setError] = useState(null);
    const [fileResult, setFileResult] = useState(null);

    useEffect(() => {
      defineCustomElements(window);
    }, []);

    const handleStatusChange = (event) => {
        setStatus(event.detail);
    };

    const handleError = (event) => {
        setError(event.detail);
    };

    const handleFileResult = (event) => {
        setFileResult(event.detail);
    };

    return (
        <div>
            <face-detector
                id="faceDetector"
                onStatus={handleStatusChange}
                onComponentError={handleError}
                onFileResult={handleFileResult}
                config={JSON.stringify({
                    width: '640px',
                    height: '480px',
                    enableMicrophone: true,
                    mode: 'video-camera',
                    placeholder: 'Upload your image',
                    buttonText: 'Upload File',
                    documentAccept: 'image/*',
                    description: 'Please upload an image for face detection',
                    size: 2048,
                    videoDuration: 5
                })}
            ></face-detector>

            <div>Status: {status}</div>
            <div>Error: {error && error.label}</div>
            <div>File Result: {fileResult && fileResult.base64}</div>
        </div>
    );
};

export default FaceDetector;

Usa el componente FaceDetector

Abre el archivo src/App.js y modifica el contenido para incluir el componente FaceDetector:

import React from 'react';
import FaceDetector from './FaceDetector';

function App() {
  return (
    <div className="App">
      <FaceDetector />
    </div>
  );
}

export default App;

Iniciar la aplicación de React

npm run start

Abre tu navegador y navega a http://localhost:3000 para ver tu componente en acción.

Angular

Ejemplo Angular

Configurar un proyecto Angular

Si no tienes un proyecto Angular, crea uno nuevo:

ng new face-detector-example
cd face-detector-example

Instalar el paquete @jaak.ai/face-detector package

npm install @jaak.ai/face-detector

Crear el componente FaceDetector

Abre el archivo src/app/app.component.ts y modifícalo con el siguiente contenido:

import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <face-detector
      (status)="handleStatus($event)"
      (componentError)="handleError($event)"
      (fileResult)="handleFileResult($event)"
      [config]="config">
    </face-detector>

    <div>Status: {{ status }}</div>
    <div>Error: {{ error?.details }}</div>
    <div>File Result: {{ fileResult?.base64 }}</div>
  `
})
export class AppComponent implements OnInit {
  status: string;
  error: any;
  fileResult: any;
  config = {
    width: '640px',
    height: '480px',
    enableMicrophone: true,
    mode: 'video-camera',
    placeholder: 'Upload your image',
    buttonText: 'Upload File',
    documentAccept: 'image/*',
    description: 'Please upload an image for face detection',
    size: 2048,
    videoDuration: 5
  };

  ngOnInit(): void {
    // Registro de elementos personalizados o cualquier lógica de inicialización
  }

  handleStatus(event: CustomEvent) {
    this.status = event.detail;
  }

  handleError(event: CustomEvent) {
    this.error = event.detail;
  }

  handleFileResult(event: CustomEvent) {
    this.fileResult = event.detail;
  }
}

Configurar angular.json

Asegúrate de que tu archivo angular.json incluya el script necesario para cargar el componente de Stencil. Agrega lo siguiente bajo la sección de scripts:

"scripts": [
  "node_modules/@jaak.ai/face-detector/dist/face-detector/face-detector.js"
]

Iniciar la aplicación Angular

ng serve

Abre tu navegador y navega a http://localhost:4200 para ver tu componente en acción.

ℹ️ Para obtener más información sobre cómo implementar la detección de rostros en una aplicación React, puedes revisar la sección de Ejemplos en el siguiente enlace: github.com/jaak-ai/face-detector-react-example. Allí encontrarás un proyecto práctico con instrucciones para configurar y ejecutar el ejemplo.