freehands-architecture

# FreeHands — Arquitectura del Proyecto Proyecto de control del PC sin manos: **gaze tracking + gestos de mano + comandos de voz**. PyQt6 + MediaPipe FaceMesh + pyautogui. ## 📁 Estructura del proyecto ``` src/freehands/ ├── __main__.py # Entry point: freehands CLI ├── main.py # run_system() — orquestador principal ├── config.py # Constantes globales (FPS, dwell, thresholds) ├── gaze/ │ ├── __init__.py # Exporta GazeTracker, GazeRegressor, DeadZoneClamper │ ├── tracker.py # GazeTracker — MediaPipe FaceMesh → GazeFeatures (6-d) │ ├── calibration.py # GazeRegressor — ridge regression → coordenadas pantalla │ ├── dead_zones.py # DeadZoneClamper — recorte de bordes de pantalla │ └── head_pose.py # HeadPose — estimación 6DoF desde FaceMesh landmarks ├── gestures/ │ ├── hand_tracker.py # MediaPipe Hands → gesture classification │ ├── face_tracker.py # Expresiones faciales (AUs) │ └── stabilizer.py # Debounce + stability frames para gestos ├── fusion/ │ ├── fusion.py # MultimodalFusion — estado, dwell, bindings │ ├── state_machine.py # StateMachine — IDLE → ACTIVE → CONFIRMING → COOLDOWN │ └── channel_priority.py # Priorización dinámica: gesto vs voz cuando compiten ├── actions/ │ └── dispatcher.py # ActionDispatcher — pyautogui (click, scroll, zoom...) ├── voice/ │ ├── whisper_listener.py # Faster-Whisper ASR → acciones de voz │ └── continuous_dictation.py # Transcripción continua con feedback visual ├── plugins/ │ ├── base.py # FreeHandsPlugin base class — 7 pipeline hooks │ ├── loader.py # PluginLoader — discovery, priority, lifecycle │ └── example_cursor_trail.py # Ejemplo: trail de cursor ├── profiles/ │ ├── store.py # Profile (Pydantic) — JSON persistence, migration │ └── __init__.py # Gestos, bindings, thresholds por defecto ├── capture/ │ ├── camera.py # OpenCV webcam capture │ └── __init__.py └── ui/ ├── overlay.py # GazeOverlay — widget PyQt6 transparente ├── theme.py # Estilos CSS (azul #1E5BFF + naranja #FF7A1A) ├── calibration_game.py # Juego de calibración 9 puntos └── camera_selector.py # Selector de cámara tests/ ├── test_dead_zones.py # Tests dead zones ├── test_fusion.py # Tests multimodal fusion ├── test_state_machine.py # Tests state machine ├── test_profiles.py # Tests profiles ├── test_hand_tracker.py # Tests hand tracker ├── test_stabilizer.py # Tests gesture stabilizer ├── test_voice_commands.py # Tests voice commands └── test_head_pose.py # Tests head pose estimation ``` ## 🔄 Flujo de datos principal ``` Camera ──frame──▶ GazeTracker ──GazeFeatures──▶ GazeRegressor ──cursor (x,y) │ DeadZoneClamper ──cursor_clamped │ FineAimPointer ──cursor_smooth │ HandTracker ──gesture──▶ GestureStabilizer ──confirmed_gesture │ ┌─────────────────────────┘ ▼ MultimodalFusion (state machine + dwell + bindings) │ ▼ FusionResult {cursor_xy, state, dwell, fired_action} │ ▼ PluginPipeline (hooks: on_gaze, on_action, ...) │ ▼ ActionDispatcher ──pyautogui events ``` ## 🔑 Conceptos clave ### GazeFeatures (6-dimensional) Vector compacto extraído por frame: - `l_rel[0:2]` — iris izquierdo normalizado por ancho/alto ojo izq - `r_rel[0:2]` — iris derecho normalizado por ancho/alto ojo der - `head[0:2]` — proxy de pose de cabeza (nariz vs centro ojos) ### State Machine Estados: `IDLE → ACTIVE → CONFIRMING → COOLDOWN → ACTIVE` - **IDLE**: sistema pausado (palma abierta → resume) - **ACTIVE**: esperando mirada estable - **CONFIRMING**: mirada estable durante dwell_time_ms - **COOLDOWN**: tras acción, cooldown de COOLDOWN_MS_AFTER_ACTION ### Palm-scroll Gestos de scroll por palma (palm_scroll_up/down) son **instantáneos** — bypass del state machine, disparan directamente scroll_up/scroll_down. ### Dead Zones Recorte de coordenadas del cursor para que no alcance bordes extremos de pantalla. Por defecto 5% de margen en cada lado, mínimo 40px. ### Channel Priority (priorización dinámica) Cuando gesto y voz proponen acciones diferentes en el mismo frame, `decide_channel_priority()` resuelve el conflicto: 1. **Comandos de sistema** (volume, screenshot, show_desktop) → voz siempre gana 2. **Mismas acciones** en ambos → gesto gana (modalidad primaria) 3. **Acciones diferentes no-sistema** → gesto gana (tiene contexto espacial) - `voice_should_bypass_fusion()` identifica acciones que no pasan por el state machine. - Ver `references/channel-priority-pattern.md` para detalles completos. ### Head Pose (6DoF coarse displacement) El módulo `gaze/head_pose.py` estima rotación de cabeza (yaw, pitch, roll) desde landmarks de FaceMesh: - **Yaw**: vector nariz-ojo en plano XZ con `arctan2` - **Pitch**: eje frente-mentón relativo a línea horizontal ojo - **Roll**: inclinación lateral - Se aplica como desplazamiento "coarse" en la capa de fusión, complementando el pointer "fine" de gaze - Dead zone por defecto: ±5° para evitar jitter en pose neutral - Ver `references/head-pose-estimation-pattern.md` para patrón completo. ### Control de volumen por posición Y de mano Módulo `gestures/volume_control.py` — detector de volumen basado en la posición vertical del centroid de la mano en el frame. Es un **gesto de posición de zona**, distinto de palm-scroll (motion-based) y expresiones faciales (state-based): - **Zona superior** (Y < 0.35) → `volume_up` - **Zona inferior** (Y > 0.65) → `volume_down` - **Zona neutra** (0.35 ≤ Y ≤ 0.65) → sin acción - Usa centroid (promedio 21 landmarks) en lugar de muñeca sola → más estable - Cooldown de 15 frames (~0.5s) para evitar disparos continuos - Se ejecuta directamente vía `dispatcher.execute()`, sin pasar por gesture bindings - Ver `references/volume-control-pattern.md` para patrón completo. ### Fusión bimanual (HandFusion) Módulo `gestures/hand_fusion.py` — asigna roles complementarios cuando ambas manos están visibles: - **Mano derecha** → offset de cursor fino (±10px basado en posición relativa al centro) - **Mano izquierda** → scroll vertical (barrido) + zoom (pinch open/close) - Con una sola mano visible → no-op, comportamiento normal - Se integra en `tick()` después de `volume_control`, antes de `fusion.step_and_voice()` - Ver `references/bimanual-fusion-pattern.md` para patrón completo de integración. ### Integración de widgets UI overlay (patrón radial-menu) Para añadir un nuevo widget PyQt6 overlay al pipeline principal: 1. **Crear el módulo** en `ui/` con clase principal heredando de `QtWidgets.QWidget` 2. **Configurar flags Qt**: `FramelessWindowHint | WindowStaysOnTopHint | Tool` + `WA_TranslucentBackground` + `WA_TransparentForMouseEvents` 3. **Exportar en `ui/__init__.py`** para acceso desde `main.py` 4. **Integrar en `main.py`**: - Importar la clase + constantes necesarias (ej: `MENU_OPEN_DURATION_MS`) - Instanciar en `run_system()` con variables de estado (hold frames, gesture tracking) - Conectar señales con `pyqtSignal` → función de callback en scope de `run_system` - En el loop `tick()`: - `nonlocal` variables de estado del menú - Detectar trigger (ej: palm-hold sostenido) - Llamar `widget.update_dwell(cursor_xy)` si visible - Llamar `widget.close()` en transición a IDLE 5. **Verificar sintaxis** con `ast.parse()` antes de commit 6. **Commit + push** a ambos repos (FreeHands + Mastermind plan) Ver `references/radial-menu-integration.md` para ejemplo completo. ### Patrón para widgets que siguen al cursor (magnifier overlay) Algunos widgets no se abren/cierran con gestos sino que siguen al cursor de mirada de forma continua. Patrón diferente al de radial-menu: 1. **Crear el módulo** en `ui/` con clase principal que capture la pantalla (`QScreen.grabWindow`) y la escale. 2. **Método `update_cursor(cursor)`**: si cursor es None → hide; si no → show + update. 3. **Timer de refresh** interno (~80ms) para recapturar la pantalla sin depender del tick principal. 4. **Integrar en `main.py`**: - Instanciar con `zoom_factor` y `radius` configurables. - Variable de estado `magnifier_visible` (bool) declarada en `nonlocal` en `tick()`. - En `handle_voice_action()`: interceptar comandos como `"zoom_in"`/`"zoom_out"` ANTES de llegar al dispatcher, para repurposarlos como toggle del widget en lugar de `Ctrl++`/`Ctrl--`. - En el loop `tick()`: si `magnifier_visible`, llamar `magnifier.update_cursor(result.cursor_xy)`; si no y widget visible, llamar `update_cursor(None)`. - En `State.IDLE`: cerrar el widget y resetear `magnifier_visible = False`. 5. **Importante**: usar `overlay.flash_action()` para feedback visual, NO `magnifier.flash_action()` (el magnifier no tiene ese método). 6. **Verificar balance de braces/parens/brackets** con Python tras los cambios en main.py. Ver `references/magnifier-overlay-pattern.md` para patrón completo. ### Teclado virtual dual layout por ojos (Keyboard-Typing-with-Eyes) Teclado dividido en mitades izquierda/derecha; se muestra solo la mitad donde está el cursor de mirada. Reduce el espacio de búsqueda a la mitad. - Clase `LayoutSide` (enum: BOTH, LEFT, RIGHT) - Cada tecla marcada con `is_left_key: bool` - `get_visible_keys()` filtra dinámicamente - `update_layout_side(cursor_x)` detecta lado del cursor - `process_blink(blink)` soporta blink-to-select - Signal `layout_changed` para audio feedback - Ver `references/dual-layout-keyboard-pattern.md` para patrón completo. ### Detección de intención multimodal (gaze dwell + voz) Patrón para activar funcionalidades de dictado por voz mediante **detección multimodal**: el usuario debe mirar una región de texto (dwell) Y decir un comando de voz. Esto evita activaciones accidentales y da control preciso sobre dónde se inserta el texto dictado. - Clase `DictationIntentDetector` en `voice/dictation_intent.py` - Estado: `idle → gazing → ready → activate → reset` - Dwell configurable (default 500ms), debounce configurable (default 300ms) - Feedback visual: anillo pulsante naranja + badge "🎙 DICTANDO" - Integrado en `main.py` tick loop, independiente de `gaze_text_sel` - Ver `references/multimodal-dictation-intent-pattern.md` para patrón completo. ### Perfiles (Pydantic) - `gesture_bindings`: dict → mapea gesture_name → action_name - `gesture_thresholds`: dict → stability_frames + confidence_min por gesture - Migraciones automáticas en `load_profile()` para compatibilidad con versiones anteriores ### Sistema de Plugins (mejora #16) Arquitectura extensible para inyectar lógica custom en cada etapa del pipeline: ``` Camera → [on_frame] → Gaze → [on_gaze] → Filter → [on_filter] → Gesture → [on_gesture] → Fusion → [on_fusion] → Action → [on_action] → Overlay → [on_overlay] ``` **API principal:** - `FreeHandsPlugin` — clase base con 7 hooks (todos opcionales, passthrough por defecto) - `PluginContext` — dataclass con frame, cursor, gesture, action, blink, metadata - `PluginLoader` — descubrimiento automático desde directorio, registro manual, orden por priority - `plugins_dir` en Profile para configurar ruta de plugins **Patrón para crear un plugin:** ```python from freehands.plugins import FreeHandsPlugin, PluginContext class MiPlugin(FreeHandsPlugin): name = "mi_plugin" version = "1.0.0" description = "Descripción" priority = 50 # menor = ejecuta antes def on_gaze(self, cursor, ctx): # Modificar cursor antes de llegar a fusion return modified_cursor def on_action(self, action, ctx): # Interceptar acción antes de dispatch return suppressed_or_modified_action ``` **Reglas:** - Hooks no implementados se saltan silenciosamente (no override) - Excepciones en hooks se capturan y loguean, no rompen el pipeline - `ctx.metadata` es un dict compartido entre todos los plugins del frame - `loader.run_all(ctx)` modifica el contexto en-place, se aplica al main loop Ver `references/plugin-system-pattern.md` para API completa y ejemplos. ### Calibración con Gaussian Process (auto-calibración continua) Módulo adicional `gaze/calibration.py` que añade un modelo GP alongside el Ridge regression: - `GPGazeModel` — modelo serializable (kernel RBF/Matern, lengthscale, noise_level, training data sliding window) - `GPGazeRegressor` — predictor con Kalman smoothing, API idéntica a `GazeRegressor` - `fit_gp_model()` — entrena GP desde samples de calibración - `update_gp_model()` — añade muestras y reentrena con ventana deslizante (max 200 samples) - Auto-calibración en `main.py`: durante uso normal en estado ACTIVE, cuando cursor es estable (<15px movimiento) y confianza >0.7, se recopilan muestras implícitas - Reentrenamiento cada 30 frames, guardado al perfil cada 5 min - Ver `references/gp-auto-calibration-pattern.md` para patrón completo. ## 🛠️ Patrón para añadir un nuevo módulo Cuando se añade una funcionalidad nueva a FreeHands: 1. **Crear el módulo** en el subdirectorio correspondiente (`gaze/`, `gestures/`, `fusion/`, `voice/`, `ui/`, `actions/`) 2. **Exportar en `__init__.py`** del subdirectorio 3. **Integrar en `main.py`**: - Importar la nueva clase/módulo - Instanciar en `run_system()` con los parámetros adecuados - Aplicar en el loop `tick()` en el punto correcto del pipeline 4. **Añadir tests** en `tests/test_{modulo}.py` 5. **Actualizar perfil** si hay nuevas configuraciones (`profiles/store.py`) 6. **Verificar sintaxis** antes de commit: `python3 -c "import py_compile; py_compile.compile('path/to/file.py', doraise=True)"` 7. **Commit + push**: `git add -A && git commit -m "9009: mejora #N: descripción" && git push` ### Patrón para detector de intención multimodal (gaze + voz) Cuando la mejora requiere activar una funcionalidad por **mirada + voz simultáneamente**: 1. **Crear detector** en `voice/` con estado: `idle → gazing → ready → activate → reset` 2. **Hit-test** contra regiones de texto (coordenadas relativas al centro del overlay) 3. **Dwell configurable** + debounce para evitar falsos positivos por glitches de MediaPipe 4. **Integrar en main.py tick()**: actualizar detector con regiones, check voice commands si `ready_to_activate` 5. **Feedback visual** en overlay: anillo pulsante cuando `ready`, badge cuando activo 6. **Consume el estado** con `consume_ready()` para evitar activaciones repetidas ## 📐 Convenciones de código - `from __future__ import annotations` en todos los archivos - Dataclasses con `frozen=True` para configuraciones inmutables - Type hints en todos los parámetros y retornos - Docstrings en inglés, comentarios en castellano - Líneas máx: 100 caracteres (ruff config) - Tests: nombre `test_{funcionalidad}.py`, funciones `test_{descripción}()` - No usar `pytest` como dependencia — los tests pueden correr sin él (import directo) ## 📚 Referencias | Archivo | Descripción | |---------|-------------| | `references/channel-priority-pattern.md` | Priorización dinámica de canales: reglas de prioridad gesto vs voz | | `references/audio-feedback-pattern.md` | Patrón para añadir feedback auditivo (beeps) en gestos y voz | | `references/dead-zones-pattern.md` | Patrón para dead zones en bordes de pantalla | | `references/blink-detection-ear.md` | Detección de parpadeo via Eye Aspect Ratio (EAR) — mejora #5 | | `references/external-gesture-profiles.md` | Perfiles de gestos externos JSON: carga, merge, pitfall de `_repair_essential_bindings` | | `references/asr-backend-pattern.md` | Patrón para añadir nuevos backends ASR (Vosk, whisper.cpp, etc.) a VoiceListener | | `references/radial-menu-integration.md` | Patrón para integrar widgets overlay PyQt6 (radial menu, OSD) en el pipeline principal | | `references/dual-layout-keyboard-pattern.md` | Teclado virtual dual-layout: split izq/der basado en posición del cursor, blink-to-select | | `references/overlay-enhancement-pattern.md` | Patrón para mejorar GazeOverlay: halo radial, pens cosméticos, soporte multi-monitor | | `references/plugin-system-pattern.md` | API completa del sistema de plugins: FreeHandsPlugin, PluginContext, PluginLoader, hooks, ejemplos | | `references/head-pose-estimation-pattern.md` | Estimación 6DoF head pose desde FaceMesh: algoritmo yaw/pitch/roll, dead zones, coarse displacement | | `references/volume-control-pattern.md` | Control de volumen por posición Y de mano: gesto de posición de zona, cooldown, centroid vs muñeca | | `references/multimodal-dictation-intent-pattern.md` | Detección de intención multimodal: gaze dwell en región de texto + comando de voz para activar dictado sin falsos positivos | | `references/air-scroll-pattern.md` | Air-scroll / swipe: detección de barrido vertical con cualquier pose de mano, umbral de desplazamiento |