Saltar a contenido

📖 Manual de Uso - Sistema EPPA

Evaluación Posturográfica de Pie Automatizada

Versión: 1.0 Fecha: Octubre 2025 Institución: Lab15 - UCA

📋 Tabla de Contenidos

  1. Introducción
  2. Requisitos del Sistema
  3. Instalación y Configuración
  4. Inicio del Sistema
  5. Flujo de Trabajo Completo
  6. Guía Paso a Paso
  7. Interpretación de Resultados
  8. Solución de Problemas
  9. Preguntas Frecuentes

📖 Introducción

El Sistema EPPA (Evaluación Posturográfica de Pie Automatizada) es una herramienta de análisis biomecánico que permite evaluar la postura corporal a través de 4 vistas diferentes:

  • Vista Anterior (Plano Frontal)
  • Vista Posterior (Plano Dorsal)
  • Vista Lateral Derecha (Perfil Derecho)
  • Vista Lateral Izquierda (Perfil Izquierdo)

El sistema calcula 19 métricas posturales validadas matemáticamente con MATLAB, proporcionando un análisis completo y preciso.

💻 Requisitos del Sistema

Hardware

  • Procesador: Intel Core i5 o superior
  • RAM: 8 GB mínimo (16 GB recomendado)
  • Disco: 2 GB de espacio libre
  • Monitor: Resolución mínima 1920x1080

Software

  • Sistema Operativo: macOS, Windows 10/11, o Linux
  • Python: 3.13 o superior
  • Node.js: 18.x o superior
  • Navegador: Chrome, Firefox, o Safari (última versión)

Equipamiento Fotográfico

  • Cámara digital de al menos 12 MP
  • Trípode
  • Fondo neutro (pared blanca/clara)
  • Iluminación uniforme
  • Grilla de calibración de 10 cm x 10 cm

🔧 Instalación y Configuración

1. Clonar el Repositorio

git clone https://github.com/tu-usuario/orthoposture.git
cd orthoposture

2. Instalar Dependencias Python

# Crear entorno virtual
python3 -m venv venv

# Activar entorno virtual
source venv/bin/activate  # En macOS/Linux
# o
venv\Scripts\activate  # En Windows

# Instalar dependencias
pip install -r python/requirements.txt

3. Instalar Dependencias Frontend

npm install

4. Configurar Variables de Entorno

Crear archivo .env.local en la raíz del proyecto: 

NEXT_PUBLIC_API_URL=http://localhost:8000

🚀 Inicio del Sistema

Paso 1: Iniciar el Backend API

En una terminal: 

./start-api.sh

O manualmente: 

source venv/bin/activate
cd python
python api.py

Verificar: Deberías ver el mensaje: 

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Acceder a la documentación interactiva: http://localhost:8000/docs

Paso 2: Iniciar el Frontend

En otra terminal: 

npm run dev

Acceder a la aplicación: http://localhost:9002

🔄 Flujo de Trabajo Completo

graph TD
    A[Inicio] --> B[Preparar Paciente]
    B --> C[Tomar Fotografías 4 Vistas]
    C --> D[Capturar Marcadores]
    D --> E[Analizar Vista Anterior]
    E --> F[Analizar Vista Posterior]
    F --> G[Analizar Vista Lateral Derecha]
    G --> H[Analizar Vista Lateral Izquierda]
    H --> I[Exportar Resultados]
    I --> J[Fin]

Resumen del Proceso:

  1. Preparación del paciente
  2. Captura fotográfica (4 vistas)
  3. Marcación de puntos anatómicos
  4. Calibración (Factor de Conversión)
  5. Análisis con API Python
  6. Exportación de resultados (CSV + Capturas)

📝 Guía Paso a Paso

FASE 1: Preparación del Paciente

Vestimenta Requerida

  • Ropa ajustada o traje de baño
  • Puntos anatómicos visibles
  • Sin zapatos (descalzo)
  • Cabello recogido si es largo

Posicionamiento

  1. Vista Anterior:
  2. Paciente de frente a la cámara
  3. Pies separados al ancho de hombros
  4. Brazos a los costados

  5. Mirada al frente

  6. Vista Posterior:

  7. Paciente de espaldas a la cámara
  8. Misma posición de pies

  9. Brazos relajados

  10. Vista Lateral Derecha:

  11. Paciente de lado derecho a la cámara
  12. Pies juntos

  13. Brazos a los costados

  14. Vista Lateral Izquierda:

  15. Paciente de lado izquierdo a la cámara
  16. Misma posición

Configuración de Cámara

  • Distancia: 2-3 metros del paciente
  • Altura: A nivel del ombligo del paciente
  • Formato: JPG o PNG
  • Resolución: Mínimo 1920x1080 px
  • Grilla de calibración: Colocar en el campo visual (10 cm x 10 cm)

FASE 2: Captura de Marcadores Anatómicos

2.1 Acceder a la Captura de Marcadores

  1. Abrir http://localhost:9002/marker-capture
  2. Verás la interfaz de captura multi-vista

2.2 Cargar Imágenes y Marcar Puntos

Para cada vista:

  1. Seleccionar Vista en el dropdown superior:
  2. Vista Anterior
  3. Vista Posterior
  4. Vista Lateral Derecha

  5. Vista Lateral Izquierda

  6. Cargar Imagen:

  7. Click en "Seleccionar Imagen"
  8. Elegir la foto correspondiente

  9. La imagen se mostrará en el canvas

  10. Seleccionar Marcador:

  11. Usar el dropdown de marcadores
  12. Seleccionar el punto anatómico a marcar

  13. Ejemplo: "Eminencia Frontal Media"

  14. Marcar Punto:

  15. Click en la ubicación exacta del punto anatómico en la imagen
  16. El punto se marcará con un círculo rojo y etiqueta

  17. Aparecerá en la tabla inferior

  18. Repetir para todos los marcadores de la vista

2.3 Marcadores por Vista

Vista Anterior (17 marcadores): - Eminencia Frontal Media - Espina Nasal - Punto Mentoniano - Tragus Izq. y Der. - Punto Acromion Izq. y Der. - Escotadura Esternal - Apéndice Xifoides - Ombligo - Punto Sínfisis Pubiana - Espina Iliaca Anterosuperior Izq. y Der. - Centro Rótula Izq. y Der. - TAT Izq. y Der.

Vista Posterior (20 marcadores): - Lóbulo Izq. y Der. - Puntos de Omóplato (4 puntos) - Cervical 7 - Torácica 3, 7, 12 - Lumbar 5 - Espinas Ilíacas Posterosuperiores e Inferiores - Aquiles Izq. y Der. - Calcáneo Izq. y Der.

Vista Lateral Derecha (14 marcadores): - Tragus Der. - Apex Cervical Der. - Punto Acromion Der. - Punto Epicóndilo Der. - Base 3er Metacarpiano Der. - Apex Lumbar Der. - Espinas Ilíacas (3 puntos) - Trocánter Mayor Der. - Tubérculo Cóndilo Externo Der. - Borde anterior de Maléolo Der.

Vista Lateral Izquierda (14 marcadores): - Mismos puntos que derecha, lado izquierdo

2.4 Exportar Marcadores

  1. Una vez marcados todos los puntos de las 4 vistas:
  2. Click en "Exportar Marcadores a Archivo (.txt)"
  3. Se descargará marcadores_[fecha].txt

  4. ¡IMPORTANTE! Guardar este archivo para usar en el análisis

  5. Tabla Consolidada:

  6. Muestra todos los marcadores de todas las vistas
  7. Puedes borrar puntos individuales si es necesario
  8. Botón "Borrar Todos" para reiniciar

FASE 3: Análisis Vista Anterior

3.1 Acceder al Análisis

  • Click en "Vista Anterior" desde la página principal
  • O navegar a: http://localhost:9002/analysis/anterior

3.2 Cargar Datos

  1. Cargar Imagen:
  2. Sección "Carga de Imagen"
  3. Click "Seleccionar Imagen"

  4. Cargar foto vista anterior

  5. Importar Marcadores:

  6. Sección "Importar Marcadores"
  7. Click "Seleccionar archivo"
  8. Cargar el archivo marcadores_[fecha].txt exportado anteriormente
  9. Verificar: Toast verde confirma importación exitosa

3.3 Calibración

Calibrar Grilla (Factor de Conversión - FC):

  1. En la sección "Calibración de Grilla":
  2. Click en "Calibrar Grilla (2 puntos)"

  3. El modo de calibración se activa (botón verde)

  4. Marcar 2 puntos en la grilla de calibración:

  5. Click en un extremo de la grilla (ej: esquina superior izquierda)
  6. Click en el extremo opuesto (ej: esquina inferior derecha)

  7. Una línea amarilla conectará los puntos

  8. El sistema calculará automáticamente el Factor de Conversión (FC)

  9. Se mostrará el valor: ej. "FC = 0.107021"
  10. Este factor convierte píxeles a centímetros

3.4 Líneas de Referencia (LRV)

Establecer Línea de Referencia Vertical:

  1. Sección "Rectas de Referencia":
  2. Click "Dibujar Rectas de Referencia (4 puntos)"

  3. Modo activado (botón verde)

  4. Marcar 4 puntos en orden:

  5. Puntos 1-2: Línea horizontal (ej: suelo)

  6. Puntos 3-4: Línea vertical (ej: línea media corporal)

  7. Se dibujarán:

  8. Línea horizontal (azul)
  9. Línea vertical (roja) - esta es la LRV
  10. Se guardará la coordenada X de la LRV

3.5 Mediciones de Superficie (Opcional)

Medir distancias entre puntos:

  1. Seleccionar tipo de medición:
  2. Distancia entre cóndilos femorales
  3. Distancia entre gemelos

  4. Distancia entre maléolos

  5. Click "Tomar Medida de Superficie"

  6. Marcar 2 puntos (izquierdo y derecho)
  7. Se calcula y muestra la distancia en cm

3.6 Análisis con API Python

🐍 Análisis Completo (Recomendado):

  1. Verificar que tienes:
  2. ✅ Imagen cargada
  3. ✅ Marcadores importados
  4. ✅ FC calibrado

  5. ✅ LRV establecida

  6. En la sección "Resultados del Análisis":

  7. Click en el botón verde: "🐍 Análisis Completo con API Python"

  8. El sistema:

  9. Enviará los datos al backend Python
  10. Ejecutará cálculos validados MATLAB

  11. Mostrará los resultados en la tabla

  12. Resultados - Vista Anterior (8 métricas):

  13. Ángulo de inclinación cabeza
  14. Distancias desde LRV (eminencia frontal, espina nasal, punto mentoniano)
  15. Ángulo de inclinación tronco
  16. Ángulo de inclinación pelvis
  17. Q-angle derecho e izquierdo

Análisis Individuales por Región (Alternativo):

También puedes realizar análisis parciales: - "Analizar Cérvico-Cefálica" - "Analizar Tronco-Columna" - "Analizar Escapular-Miembro Superior" - "Analizar Pélvica-Miembro Inferior"

Estos usan cálculos TypeScript locales (menos precisos que la API).

3.7 Exportar Resultados

Exportar a CSV: 1. Click "Exportar Resultados a CSV" 2. Se descarga: resultados_analisis_anterior_[fecha].csv 3. Abre en Excel/Google Sheets

Captura de Pantalla: 1. Click "📸 Capturar Pantalla" 2. Se descarga: analisis_anterior_[fecha].png 3. Incluye imagen + marcadores + resultados

FASE 4: Análisis Vista Posterior

4.1 Acceder al Análisis

  • Click en "Vista Posterior" desde la página principal
  • O navegar a: http://localhost:9002/analysis/posterior

4.2 Proceso Similar a Vista Anterior

  1. Cargar Imagen vista posterior
  2. Importar Marcadores (mismo archivo .txt)
  3. Calibrar Grilla (FC)
  4. Establecer LRV

4.3 Opción Especial: Estimar Puntos Poplíteos

Si no marcaste los puntos poplíteos (detrás de las rodillas):

  1. Marcar checkbox: "Estimar puntos poplíteos automáticamente"
  2. El sistema calculará geométricamente estos puntos basándose en Aquiles y Calcáneo

4.4 Análisis con API Python

  1. Click en "🐍 Análisis Completo con API Python"

  2. Resultados - Vista Posterior (7 métricas):

  3. Ángulo calcáneo izquierdo y derecho
  4. Balance coronal C7, T7, L5
  5. Ángulo de inclinación pelvis

  6. Ángulo de inclinación cabeza

  7. Análisis por Regiones:

  8. Cérvico-Cefálica
  9. Tronco-Columna
  10. Pélvica
  11. Pie-Tobillo

4.5 Exportar Resultados

  • CSV: resultados_analisis_posterior_[fecha].csv
  • Imagen: analisis_posterior_[fecha].png

FASE 5: Análisis Vista Lateral Derecha

5.1 Acceder al Análisis

  • Click en "Vista Lateral Derecha" desde la página principal
  • O navegar a: http://localhost:9002/analysis/lateral-derecha

5.2 Proceso de Análisis

  1. Cargar Imagen perfil derecho
  2. Importar Marcadores (mismo archivo .txt)
  3. Calibrar Grilla (FC)
  4. Establecer LRV

Nota: No hay mediciones de superficie en vistas laterales

5.3 Análisis con API Python

  1. Click en "🐍 Análisis Completo con API Python"

  2. El sistema usa side='right' automáticamente

  3. Resultados - Vista Lateral Derecha (4 métricas):

  4. Ángulo cabeza con horizontal
  5. Ángulo tronco con vertical
  6. Ángulo del codo

  7. Ángulo de la rodilla

  8. Análisis por Regiones:

  9. Cérvico-Cefálica
  10. Tronco-Columna
  11. Miembro Superior
  12. Miembro Inferior

5.4 Exportar Resultados

  • CSV: resultados_analisis_lateral_derecha_[fecha].csv
  • Imagen: analisis_lateral_derecha_[fecha].png

FASE 6: Análisis Vista Lateral Izquierda

6.1 Proceso Idéntico a Vista Lateral Derecha

  1. Acceder a: http://localhost:9002/analysis/lateral-izquierda
  2. Cargar imagen perfil izquierdo
  3. Importar marcadores
  4. Calibrar y establecer LRV
  5. Click "🐍 Análisis Completo con API Python"
  6. Usa side='left' automáticamente

6.2 Resultados (4 métricas idénticas)

  • Ángulo cabeza con horizontal
  • Ángulo tronco con vertical
  • Ángulo del codo
  • Ángulo de la rodilla

6.3 Exportar Resultados

  • CSV: resultados_analisis_lateral_izquierda_[fecha].csv
  • Imagen: analisis_lateral_izquierda_[fecha].png

📊 Interpretación de Resultados

Vista Anterior

Métrica Valor Normal Interpretación
Ángulo cabeza -2° a +2° >2°: inclinación derecha
<-2°: inclinación izquierda
Ángulo tronco -2° a +2° Similar a cabeza
Ángulo pelvis -2° a +2° Similar a cabeza
Q-angle derecho 10-15° <10°: disminuido
>15°: aumentado
Q-angle izquierdo 10-15° <10°: disminuido
>15°: aumentado
Dist. desde LRV Variable Positivo: derecha de LRV
Negativo: izquierda de LRV

Vista Posterior

Métrica Valor Normal Interpretación
Ángulo calcáneo -5° a +5° >5°: valgo
<-5°: varo
Balance coronal -1 cm a +1 cm >1 cm: desviación derecha
<-1 cm: desviación izquierda
Ángulo pelvis -2° a +2° >2°: derecha
<-2°: izquierda
Ángulo cabeza -2° a +2° >2°: derecha
<-2°: izquierda

Vistas Laterales

Métrica Valor Normal Interpretación
Ángulo cabeza horizontal 40-50° <40°: disminuido (anteriorización)
>50°: aumentado (posteriorización)
Ángulo tronco vertical 0-5° <0°: inclinación anterior
>5°: inclinación posterior
Ángulo codo 170-180° <170°: flexión
>180°: hiperextensión
Ángulo rodilla 170-180° <170°: flexión
>180°: hiperextensión

Códigos de Color en Diagnósticos

  • 🟢 Verde (neutro/normal): Dentro de rangos normales
  • 🟡 Amarillo: Valores limítrofes
  • 🔴 Rojo: Fuera de rangos normales

🔧 Solución de Problemas

Problema 1: API no inicia

Error: Address already in use

Solución: 

# Verificar proceso en puerto 8000
lsof -ti:8000

# Matar proceso
kill -9 $(lsof -ti:8000)

# Reiniciar API
./start-api.sh

Problema 2: Error CORS en navegador

Error: CORS policy: No 'Access-Control-Allow-Origin' header

Verificar: 1. API está corriendo: http://localhost:8000/health 2. Frontend en puerto correcto: http://localhost:9002 3. Archivo .env.local existe y tiene: 

NEXT_PUBLIC_API_URL=http://localhost:8000

Solución: 

# Reiniciar ambos servicios
# Terminal 1
./start-api.sh

# Terminal 2
npm run dev

Problema 3: Marcadores no se importan

Error: No se encontraron marcadores para esta vista

Causas comunes: 1. Archivo .txt mal formateado 2. Nombres de marcadores no coinciden 3. Vista incorrecta seleccionada

Solución: 1. Verificar formato del archivo .txt: 

'Eminencia Frontal Media'    'A' 495.5315    501.4900
2. Verificar vista: 'A'=Anterior, 'P'=Posterior, 'D'=Derecha, 'I'=Izquierda 3. Re-exportar marcadores desde captura

Problema 4: Factor de Conversión incorrecto

Error: Valores de distancia irreales

Verificar: 1. Grilla de calibración visible en imagen 2. Dos puntos marcados correctamente (esquinas opuestas) 3. Grilla es de 10 cm x 10 cm

Solución: 1. Borrar calibración actual 2. Volver a calibrar con puntos precisos 3. Verificar FC resultante (típicamente 0.05 - 0.15)

Problema 5: Análisis API falla

Error: Failed to fetch /api/analyze/anterior: Missing required markers

Causas: - Faltan marcadores requeridos - Marcadores mal nombrados - FC o LRV no calibrados

Solución: 1. Verificar todos los marcadores están presentes en la tabla 2. Verificar FC y LRV están calibrados (valores numéricos mostrados) 3. Revisar consola del navegador (F12) para detalles

Problema 6: Imagen no carga

Error: Imagen no aparece en canvas

Solución: 1. Verificar formato: JPG, PNG, o WEBP 2. Tamaño máximo: 10 MB 3. Permisos de archivo: lectura habilitada 4. Refrescar página (F5)

❓ Preguntas Frecuentes

General

P: ¿Necesito conexión a internet? R: No. El sistema funciona completamente offline (localhost). Solo necesitas conexión para la instalación inicial.

P: ¿Los datos se guardan automáticamente? R: Los marcadores y calibraciones se guardan en sessionStorage del navegador. Al cerrar el navegador se pierden. Importante: Exporta siempre los marcadores a .txt y los resultados a CSV.

P: ¿Puedo analizar múltiples pacientes? R: Sí. Exporta los resultados de cada paciente y limpia la sesión antes del siguiente. Usa "Borrar Todos" en captura de marcadores.

P: ¿Cuánto tiempo toma el análisis completo? R: Aproximadamente: - Captura de fotos: 10-15 minutos - Marcación de puntos: 20-30 minutos - Análisis 4 vistas: 10-15 minutos - Total: 40-60 minutos por paciente

Técnicas

P: ¿Qué precisión tienen los cálculos? R: Los cálculos Python tienen precisión de 15 dígitos decimales, con diferencia máxima de 1.42e-13 respecto a MATLAB. Esto es equivalencia matemática total.

P: ¿Puedo modificar los rangos normales? R: Los rangos están definidos en el código. Para modificarlos, edita los archivos de análisis (requiere conocimientos de TypeScript).

P: ¿Dónde están los cálculos MATLAB originales? R: En el directorio matlab/, archivos *.m. Los cálculos Python en python/calculations*.py son equivalentes matemáticos.

P: ¿Qué son los tests de validación? R: 39 tests automáticos que verifican que los cálculos Python sean idénticos a MATLAB. Ejecutar con: pytest tests/ -v

Clínicas

P: ¿Es apto para uso clínico? R: El sistema está validado matemáticamente. Sin embargo, para uso clínico oficial requiere: - Certificación de dispositivo médico - Aprobación regulatoria (FDA, EMA, ANMAT, etc.) - Validación clínica con pacientes - Cumplimiento HIPAA/GDPR para datos

P: ¿Cómo interpreto resultados anormales? R: Los resultados indican desviaciones posturales, no diagnósticos médicos. Requieren interpretación por profesional calificado (médico, kinesiólogo, fisioterapeuta).

P: ¿Puedo comparar análisis en el tiempo? R: Sí. Guarda los CSV de cada sesión y compara manualmente. Una futura versión podría incluir comparación automática.

Exportación

P: ¿En qué formato se exportan los resultados? R: - CSV: Tabla con región, variable, medición, diagnóstico - PNG: Captura de pantalla con imagen + marcadores + resultados

P: ¿Puedo exportar a PDF? R: Actualmente no. Está en la lista de mejoras futuras. Por ahora, puedes: 1. Abrir CSV en Excel 2. Insertar imagen PNG 3. Exportar a PDF desde Excel

P: ¿Los archivos CSV se pueden abrir en Excel? R: Sí, completamente compatibles. Usar "Abrir" o "Importar datos" en Excel.

📞 Soporte y Contacto

Documentación Adicional

  • API Reference: API_REFERENCE.md
  • Estado del Proyecto: PROJECT_STATUS.md
  • Guía de Integración: API_INTEGRATION_COMPLETE.md
  • Validación MATLAB: VALIDATION_SUMMARY.md

Reportar Problemas

  • GitHub Issues: [link al repositorio]
  • Email: [tu-email@ejemplo.com]

Contribuir

El proyecto es de código abierto. Contribuciones bienvenidas: 1. Fork del repositorio 2. Crear branch: git checkout -b feature/nueva-funcionalidad 3. Commit: git commit -m 'Add nueva funcionalidad' 4. Push: git push origin feature/nueva-funcionalidad 5. Crear Pull Request

📜 Licencia y Créditos

Código MATLAB Original: Validado por estadísticos y matemáticos Migración Python: Equivalencia matemática preservada Desarrollo API: FastAPI + Python 3.13 Frontend: Next.js 15 + TypeScript 5 Institución: Lab15 - UCA

🔄 Historial de Versiones

Versión 1.0 (Octubre 2025)

  • ✅ Sistema completo funcional
  • ✅ 4 vistas de análisis con API Python
  • ✅ 19 métricas validadas MATLAB
  • ✅ Captura multi-vista de marcadores
  • ✅ Exportación CSV y capturas PNG
  • ✅ Documentación completa

Próximas Versiones (Roadmap)

  • 📋 v1.1: Exportación PDF de reportes
  • 📊 v1.2: Comparación temporal de análisis
  • 🗄️ v1.3: Base de datos de pacientes
  • 📱 v2.0: Versión móvil/tablet

✅ Checklist de Uso Rápido

Antes de Comenzar

  • [ ] Backend API corriendo (http://localhost:8000)
  • [ ] Frontend corriendo (http://localhost:9002)
  • [ ] Grilla de calibración preparada
  • [ ] Paciente preparado (vestimenta, posición)

Captura de Datos

  • [ ] 4 fotografías tomadas (A, P, D, I)
  • [ ] Marcadores capturados en las 4 vistas
  • [ ] Archivo .txt exportado y guardado

Análisis

  • [ ] Vista Anterior analizada y exportada
  • [ ] Vista Posterior analizada y exportada
  • [ ] Vista Lateral Derecha analizada y exportada
  • [ ] Vista Lateral Izquierda analizada y exportada

Resultados

  • [ ] 4 archivos CSV guardados
  • [ ] 4 capturas PNG guardadas
  • [ ] Resultados interpretados
  • [ ] Informe clínico generado (manual)

¡Éxito en tus análisis posturales! 🎯

Sistema EPPA - Evaluación Posturográfica de Pie Automatizada v1.0 Desarrollado con ❤️ por Lab15 - UCA