HandsMachines es una solución de software de código abierto diseñada para facilitar el aprendizaje y la práctica de la Lengua de Señas Americana (ASL) a través de técnicas avanzadas de visión artificial y aprendizaje automático (Machine Learning). La plataforma permite la detección de gestos en tiempo real, proporcionando retroalimentación inmediata al usuario y permitiendo la personalización del modelo de IA según las características físicas individuales de cada mano.
- Arquitectura del Sistema
- Tecnologías Utilizadas
- Requisitos del Sistema
- Instalación y Configuración
- Uso y Modos de Juego
- Sistema de Calibración Personalizada
- Estructura del Proyecto
- Contribuciones
- Bugs Conocidos
- Licencia
El sistema sigue una arquitectura de cliente-servidor desacoplada para optimizar el rendimiento y la experiencia del usuario (UX).
El frontend se encarga de la captura de video y el procesamiento inicial de visión artificial mediante MediaPipe Hands, extrayendo 21 puntos de referencia (landmarks) tridimensionales. Estos datos son normalizados y transmitidos en tiempo real al servidor mediante una arquitectura de servicios REST para su clasificación.
El backend, desarrollado con FastAPI, actúa como el motor central de inteligencia. Utiliza el modelo original entrenado en Python (Random Forest) para realizar inferencias de alta precisión sobre los landmarks recibidos. Esta centralización elimina las discrepancias de formato y fallos de ejecución asociados a la conversión de modelos entre entornos. Además, gestiona la persistencia en MongoDB y el ciclo de vida del entrenamiento personalizado.
- React 19 & Vite: Framework de interfaz y entorno de desarrollo.
- MediaPipe Hands: Extracción de puntos de referencia de la mano.
- Axios: Comunicación persistente con la API de predicción del backend.
- Tailwind CSS: Estilización de componentes y diseño responsivo.
- Lucide React: Biblioteca de iconografía vectorial.
- FastAPI: Framwork web asíncrono de alto rendimiento.
- MongoDB: Base de datos NoSQL para almacenamiento de usuarios y estadísticas.
- Scikit-Learn: Entrenamiento del modelo Random Forest.
- Skl2onnx: Conversión de modelos para compatibilidad con el frontend.
- Uvicorn: Servidor ASGI para despliegue del backend.
- Sistemas Operativos: Windows 10/11, macOS, o distribuciones Linux recientes.
- Hardware: Cámara web (720p recomendada) y al menos 4GB de RAM.
- Software:
- Python 3.10 o superior.
- Node.js 18 (LTS) o superior.
- MongoDB (Instancia local o Atlas).
- Navegue al directorio del backend:
cd backend - Cree y active un entorno virtual:
python -m venv venv source venv/bin/activate # En Windows: venv\Scripts\activate
- Instale las dependencias necesarias:
pip install -r requirements.txt
- Inicie el servidor:
python main.py
- Navegue al directorio del frontend:
cd frontend - Instale las dependencias de Node:
npm install
- Inicie el servidor de desarrollo:
npm run dev
Al iniciar la aplicación, el usuario puede elegir entre practicar letras individuales o palabras completas.
- Modo Letras: La IA propone una letra aleatoria y el usuario debe realizar la seña correspondiente.
- Modo Palabras: El usuario debe deletrear progresivamente los caracteres de una palabra mostrada en pantalla.
Se incluye un esqueleto de mano 3D que muestra la pose ideal para cada letra. Este componente es interactivo y gira continuamente para facilitar la comprensión espacial de la seña.
La variabilidad anatómica y las condiciones de entorno son factores críticos en el reconocimiento de señas. HandsMachines incorpora un flujo de calibración dinámico que permite adaptar el modelo a cada usuario:
- Interfaz Integrada: El usuario accede al modal de calibración donde dispone de una vista previa de cámara en tiempo real junto con indicadores de detección de la IA.
- Captura de Muestras: Se recolectan puntos de referencia directamente desde el flujo de video, normalizándolos y almacenándolos en el dataset del usuario (
user_collected.csv). - Entrenamiento Especializado: Al completar la captura de al menos dos letras distintas, el sistema permite ejecutar el reentrenamiento del modelo.
- Priorización de Datos: El script de entrenamiento prioriza los datos recolectados por el usuario, eliminando el sesgo de los datos sintéticos base y garantizando una precisión superior en condiciones reales.
- Sincronización Automática: El backend recarga el modelo reentrenado de forma inmediata, permitiendo al usuario retomar el juego con su perfil personalizado sin necesidad de reinicios.
A continuación se detalla la organización de los directorios y la función de los archivos principales para facilitar el mantenimiento y la escalabilidad del sistema.
backend/: Código fuente, modelos y lógica del servidor FastAPI.frontend/: Aplicación de cliente SPA desarrollada con React y Vite.README.md: Documentación principal del proyecto (este archivo).CHANGELOG.md: Registro histórico de versiones y cambios técnicos.
app/: Núcleo de la aplicación.api/routes/: Controladores de API organizados por dominio (auth, prediction, classroom).models/: Esquemas de datos Pydantic para validación y tipado.services/: Capa de servicios y lógica de negocio (ML, DB, Auth).
dataset/: Repositorio de datos para el entrenamiento de la IA.asl_landmarks.csv: Dataset base con muestras sintéticas.user_collected.csv: Capturas personalizadas generadas por el usuario.
ml/: Recursos de Aprendizaje Automático.training/: Scripts de entrenamiento, balanceo de datos y exportación ONNX.model/: Artefactos finales de la IA (.pkl y .onnx).
main.py: Punto de entrada del servidor y configuración de FastAPI.requirements.txt: Dependencias de Python.
public/: Assets estáticos y modelos ONNX para el navegador.src/: Código fuente de la aplicación React.components/: Componentes modulares (cámara, lógica de juego, componentes de UI).hooks/: Ganchos de React (MediaPipe, estados del juego, sonidos).pages/: Vistas de alto nivel y configuración de rutas.services/: Clientes para API e Inferencia local ONNX.types/: Declaraciones de TypeScript globales.utils/: Utilidades matemáticas y normalización de landmarks.
vite.config.ts: Configuración de construcción para Vite.package.json: Manifiesto de dependencias de Node.js.
Este es un proyecto Open Source y valoramos enormemente las contribuciones de la comunidad. Si desea colaborar:
- Realice un fork del repositorio.
- Cree una rama para su mejora o corrección:
git checkout -b feature/nueva-funcionalidad. - Asegúrese de seguir los estandares de codificación existentes.
- Envíe un Pull Request con una descripción detallada de los cambios.
- Iluminación Deficiente: En condiciones de luz baja, el modelo MediaPipe puede perder el seguimiento de los puntos de referencia, reduciendo la precisión.
- Similitud Visual: Ciertas letras con topologías muy parecidas (como la 'S' y la 'A') pueden requerir un mayor número de muestras durante la calibración para diferenciarse correctamente.
Este proyecto se distribuye bajo la licencia Apache License 2.0. Para más información, consulte el archivo LICENSE incluido en la raíz de este repositorio.