Arquitectura del Repositorio

El proyecto HeadGazeLib, desarrollado para el seguimiento de cabeza y estimación de mirada, se organiza siugiendo una estructura modular estánddar en Python. A continuación, se detalla una representación de su jerarquía de directorios, la cual puede variar según la versión del repositorio:

HeadGazeLib-Workspace/
├── documentation/      # Manuales de API y guías de desarrollo
├── demos/              # Scripts de demostración interactiva
│   ├── real_time_tracking.py
│   └── offline_analysis.py
├── src/                # Código fuente del motor principal
│   ├── engine/         # Algoritmos de estimación de pose y mirada
│   │   ├── pose_calculator.py
│   │   └── gaze_tracker.py
│   └── helpers/        # Utilidades y calibración de sensores
│       └── sensor_calibration.py
├── dependencies.txt    # Requisitos del entorno virtual
├── install.sh          # Script de construcción
└── unit_tests/         # Suite de pruebas automatizadas

Los módulos dentro de src/engine/ albergan la lógica matemática y de inferencia para procesar los fotogramas, mientras que src/helpers/ provee funciones auxiliares críticas como la calibración de la cámara. El archivo dependencies.txt es fundamental para preparar el entorno antes de cualquier ejecución.

Punto de Entrada y Ejecución

Para interactuar con las capacidades del núcleo, los desarrolladores suelen utilizar los scripts ubicados en el directorio de demostraciones. En lugar de depender únicamente de la línea de comandos, un punto de entrada típico implementa la instanciación directa de las clases principales para procesar el flujo de video.

import sys
from src.engine.gaze_tracker import GazeTracker
from src.helpers.sensor_calibration import Calibrator

def iniciar_sistema(id_camara=0, umbral_confianza=0.85):
    # Inicializar módulo de calibración
    calibrador = Calibrator(resolucion=(1920, 1080))
    
    # Configurar motor de seguimiento visual
    tracker = GazeTracker(
        fuente_video=id_camara,
        confianza_minima=umbral_confianza
    )
    
    try:
        tracker.ejecutar_bucle_principal()
    except KeyboardInterrupt:
        print("Sistema de seguimiento detenido manualmente.")
    finally:
        tracker.liberar_recursos()

if __name__ == "__main__":
    iniciar_sistema(id_camara=1)

Este script demuestra cómo acoplar la calibración inicial con el motor de seguimiento, permitiendo capturar interrupciones del sistema para un cierre seguro de los recursos de hardware.

Gestión de Configuraciones

El diseño original de HeadGazeLib no incorpora archivos de configuración externos centralizados (como YAML o INI). Las variables de entorno, identificadores de hardware y rutas a modelos preentrenados se inyectan directamente como agrumentos en las funciones. Sin embargo, para entornos de producción, es altamente recomendable encapsular esta lógica mediante un gestor de configuración basado en JSON.

import json
from src.engine.gaze_tracker import GazeTracker

def cargar_configuracion(ruta_archivo):
    with open(ruta_archivo, 'r') as archivo:
        return json.load(archivo)

# Implementación de configuración externa
config = cargar_configuracion('ajustes_sistema.json')
motor = GazeTracker(
    fuente_video=config.get('camera_id', 0),
    ruta_modelo=config.get('model_path', './default_model.h5'),
    fps_objetivo=config.get('target_fps', 30)
)

Al delegar los parámetros a un archivo externo, se facilita el despliegue en múltiples dispositivos sin necesidad de modificar el código base de la biblioteca.