soma-screen-monitor

v1.3.0

Published

6 months ago

SOMA - Screen OCR Monitor Application - Monitor de cambios en pantalla con interfaz TUI interactiva y soporte para múltiples regiones

0High
0Medium
0Low

aesoftwaregroup

screen monitor ocr tesseract automation tui terminal

SOMA - Screen OCR Monitor Application

Monitor de cambios en pantalla con interfaz TUI interactiva

Desarrollado por AE Software Group

Características

Interfaz TUI (Terminal User Interface) moderna y navegable
Arte ASCII personalizado con diseño profesional
Navegación por teclado con flechas y atajos configurables
Detección OCR de cambios en regiones específicas de la pantalla
🆕 Soporte para múltiples regiones - Monitorea hasta 2 puntos diferentes simultáneamente
Notificaciones del sistema y alertas de sonido
Configuración persistente guardada en JSON
Atajos de teclado personalizables (F5, F6, F7)
Modo de sonido configurable (una vez o continuo)

Instalación

Requisitos Previos

Node.js v18.0.0 o superior
npm (incluido con Node.js)

Instala SOMA globalmente para usarlo desde cualquier terminal:

npm install -g soma-screen-monitor

Luego simplemente ejecuta:

soma

Uso

Iniciar la aplicación

soma

Navegación

Menú Principal

Usa las flechas ↑↓ para navegar entre las opciones:

🎯 Gestionar Regiones de Pantalla - Configura hasta 2 regiones a monitorear
⚙️ Configuraciones - Ajusta los parámetros del monitor
▶️ Iniciar Monitoreo (F6) - Comienza a detectar cambios
⏸️ Detener Monitoreo (F7) - Pausa la detección
❌ Salir - Cierra la aplicación

Presiona Enter para seleccionar una opción.

Menú de Gestión de Regiones (Nuevo en v1.3.0)

Ahora puedes configurar y monitorear hasta 2 regiones diferentes simultáneamente:

➕ Agregar/Editar Región 1 - Configura el primer punto de monitoreo
➕ Agregar/Editar Región 2 - Configura el segundo punto de monitoreo
🗑️ Eliminar Región 1 - Elimina la configuración de la región 1
🗑️ Eliminar Región 2 - Elimina la configuración de la región 2
← Volver al Menú Principal - Regresa al menú principal

Ejemplo de uso:

Puedes monitorear un contador de vida y un contador de munición al mismo tiempo
O vigilar dos indicadores diferentes en una aplicación
Cada región se detecta independientemente con su propia alerta

Atajos de Teclado Globales

F5 - Abrir menú de gestión de regiones (desde cualquier pantalla)
F6 - Iniciar monitoreo (desde cualquier pantalla)
F7 - Detener monitoreo (desde cualquier pantalla)
Ctrl+C - Salir de la aplicación

Configuración

Seleccionar Regiones de Pantalla

Nuevo en v1.3.0: SOMA ahora permite monitorear hasta 2 regiones diferentes simultáneamente. Cada región se configura de forma independiente usando cualquiera de los 3 métodos disponibles:

📸 Método 1: Screenshot + Medición (Recomendado)

El más fácil y preciso:

Selecciona la opción "Seleccionar Región de Pantalla" del menú
Elige el método 1
Se tomará un screenshot automático y se abrirá con tu visor de imágenes
Usa el visor para medir la región:
- Windows: Paint (Ver > Regla) o la app Fotos
- Mac: Preview (Tools > Show Inspector)
- Linux: GIMP o cualquier visor con regla
Anota las coordenadas:
- X, Y: Posición de la esquina superior izquierda
- Width, Height: Ancho y alto del rectángulo
Ingresa los valores en el prompt

Explicación de coordenadas:

(0,0) ┌─────────────────────→ X (horizontal)
  │   │
  │   │    Tu número está aquí: (450, 320)
  │   │    ┌────────┐
  ↓   │    │ 123.45 │  ← Width: 180px, Height: 40px
  Y   │    └────────┘
      │
 (vertical)

🖱️ Método 2: Dos Clics en Pantalla (Windows/Linux)

Para usuarios avanzados:

Selecciona el método 2
Haz clic en la esquina superior izquierda de la región
Haz clic en la esquina inferior derecha
El script calcula las coordenadas automáticamente

Requisitos:

Windows: PowerShell (incluido por defecto)
Linux: xdotool instalado (sudo apt install xdotool)

⌨️ Método 3: Ingresar Coordenadas Manualmente

Si ya conoces los valores exactos, simplemente ingrésalos:

X: Píxeles desde el borde izquierdo
Y: Píxeles desde el borde superior
Ancho: Ancho de la región en píxeles
Alto: Alto de la región en píxeles

Panel de Configuraciones

Dentro del menú de Configuraciones puedes ajustar:

🖥️ Monitor/Pantalla

Todas - Captura todas las pantallas fusionadas (por defecto)
Monitor 0, 1, 2... - Selecciona un monitor específico

SOMA detecta automáticamente todos tus monitores y te permite elegir cuál monitorear. Útil si tienes múltiples pantallas y quieres monitorear solo una.

🔊 Modo de Sonido

once - Reproduce el sonido una sola vez al detectar cambio
continuous - Reproduce el sonido continuamente mientras haya cambio

🔍 Modo OCR

Configura el motor de reconocimiento de texto según el tipo de número que monitoreas:

single - Optimizado para un solo dígito (0-9)
- Ideal para contadores que muestran números individuales
- Máxima precisión en la detección de 0-9
- Recomendado cuando necesitas detectar cambios de 0→1, 5→6, etc.
multi - Para varios dígitos juntos (10, 11, 123, etc.)
- Detecta números de múltiples cifras
- Funciona bien con contadores de 2 o más dígitos
- Ejemplo: 10→11, 123→124
auto - Detección automática
- Úsalo como último recurso si los otros modos no funcionan
- Tesseract decide automáticamente cómo interpretar la región

💡 Recomendación: Si tu contador muestra un solo dígito (0-9), usa modo single y ajusta la región para capturar solo ese número. Si muestra números de 2+ dígitos (10, 11, 123...), usa modo multi.

🔔 MessageBox Emergente

ON - Muestra ventana emergente al detectar cambio
OFF - Solo sonido sin ventana emergente

⏱️ Intervalo de Verificación

Define cada cuántos segundos se verifica la región (recomendado: 1-3s)

🎮 Atajos de Teclado

Visualiza los atajos configurados (funcionalidad de edición próximamente)

📊 Modo Verbose

ON - Muestra logs detallados de cada verificación con tiempo de procesamiento
OFF - Solo muestra cambios detectados

🐛 Modo Debug (Guardar Screenshots)

ON - Guarda screenshots de cada captura en ~/.soma/debug/
- full_screenshot_[timestamp].png - Pantalla completa
- Region_1_1_raw_crop_[timestamp].png - Región 1 sin procesar
- Region_1_2_processed_ocr_[timestamp].png - Región 1 procesada para OCR
- Region_2_1_raw_crop_[timestamp].png - Región 2 sin procesar (si está configurada)
- Region_2_2_processed_ocr_[timestamp].png - Región 2 procesada para OCR (si está configurada)
OFF - No guarda screenshots (recomendado para uso normal)

Archivo de Configuración

La configuración se guarda automáticamente en:

Windows: C:\Users\[TuUsuario]\.soma\config.json
Linux/Mac: ~/.soma/config.json

Ejemplo de configuración:

{
  "regions": [
    {
      "x": 100,
      "y": 100,
      "width": 200,
      "height": 50,
      "name": "Región 1"
    },
    {
      "x": 500,
      "y": 300,
      "width": 180,
      "height": 40,
      "name": "Región 2"
    }
  ],
  "checkInterval": 5,
  "soundMode": "once",
  "showNotification": true,
  "showMessageBox": true,
  "verbose": true,
  "debugMode": false,
  "screen": "all",
  "ocrMode": "single",
  "shortcuts": {
    "start": "F6",
    "stop": "F7",
    "selectRegion": "F5"
  }
}

Nota: Si tienes una configuración antigua con region (singular), se migrará automáticamente a regions (array) la primera vez que ejecutes la aplicación.

Opciones de configuración:

screen:
- "all" - Todas las pantallas (por defecto)
- 0 - Monitor principal
- 1 - Segundo monitor
- 2 - Tercer monitor, etc.
ocrMode:
- "single" - Un solo dígito (0-9)
- "multi" - Múltiples dígitos (10, 11, 123, etc.)
- "auto" - Detección automática
soundMode:
- "once" - Sonido una vez
- "continuous" - Sonido continuo

Puedes editar este archivo manualmente si lo prefieres.

Flujo de Trabajo Típico

Ejecuta soma (o npm start en desarrollo)
Configura las regiones a monitorear:
- Presiona F5 o selecciona "Gestionar Regiones de Pantalla"
- Configura Región 1 (obligatorio)
- Opcionalmente configura Región 2 para monitoreo simultáneo
Ajusta configuraciones si es necesario (modo OCR, intervalo, etc.)
Inicia el monitoreo (F6)
El script detectará automáticamente cuando los números en esas regiones cambien
Las alertas mostrarán qué región cambió: "CAMBIO DETECTADO EN Región 1!"
Detén el monitoreo cuando termines (F7)

Solución de Problemas

El OCR no detecta correctamente

Para números de un solo dígito (0-9):

Configura el modo OCR:
- Ve a Configuraciones → 🔍 Modo OCR → Cambia a single
Ajusta la región:
- Presiona F5 para reseleccionar región
- Reduce la altura a ~40-50 píxeles
- Asegúrate de capturar SOLO UN DÍGITO, no dos números
- Minimiza el espacio vacío alrededor del número
Activa Debug para verificar:
- Configuraciones → 🐛 Modo Debug → ON
- Revisa la imagen 2_processed_ocr_[timestamp].png en ~/.soma/debug/
- Debe mostrar un solo dígito grande y claro

Para números de múltiples dígitos (10+):

Cambia Modo OCR a multi
Ajusta la región para incluir todos los dígitos juntos

General:

Verifica que el contraste sea bueno (texto oscuro sobre fondo claro)
Activa Modo Verbose para ver logs detallados del OCR
Si nada funciona, prueba modo auto

No se reproduce el sonido

En Windows, verifica que exista el archivo C:\Windows\Media\notify.wav
El sonido es opcional, la aplicación seguirá funcionando sin él
Las notificaciones del sistema seguirán apareciendo

Error "Cannot find module"

npm install

Asegúrate de instalar todas las dependencias.

El intervalo es muy rápido/lento

Accede a Configuraciones > Intervalo de Verificación
Ajusta según tus necesidades (recomendado: 3-10 segundos)

Estructura del Proyecto

SOMA/
├── monitor.mjs        # Aplicación principal
├── config.json        # Configuración persistente
├── package.json       # Dependencias y metadatos
├── README.md          # Este archivo
└── Script.md          # Script original (referencia)

Tecnologías Utilizadas

Node.js - Runtime de JavaScript
screenshot-desktop - Captura de pantalla multiplataforma
Tesseract.js - Motor OCR basado en Tesseract
node-notifier - Notificaciones del sistema nativas
ANSI Escape Codes - Interfaz TUI colorida

Historial de Versiones

v1.3.0 (Actual)

✅ Soporte para múltiples regiones - Monitorea hasta 2 puntos simultáneamente
✅ Nuevo menú de gestión de regiones
✅ Alertas específicas por región
✅ Migración automática desde configuraciones antiguas
✅ Mejoras en el modo debug para múltiples regiones

v1.2.0

Modo OCR mejorado (single/multi/auto)
Selector de pantalla/monitor
Modo debug con screenshots
MessageBox emergente configurable

v1.0.0

Lanzamiento inicial
Interfaz TUI
Detección OCR básica

Próximas Mejoras

[ ] Editor visual de región con overlay en pantalla
[ ] Historial de cambios detectados
[ ] Exportación de datos a CSV/JSON
[ ] Soporte para más de 2 regiones simultáneas
[ ] Filtros de detección (solo incrementos, solo decrementos, etc.)
[ ] Integración con webhooks y APIs
[ ] Modo headless para automatización

Licencia

Este software es propietario y confidencial. No está permitido copiar, modificar, distribuir o usar este software sin autorización expresa de AE Software Group.

Soporte

Para reportar bugs o sugerir mejoras, contacta con AE Software Group.

¡Gracias por usar SOMA! 🚀