Skip to content

ArmandoMedina/SimGhostInputs

BranchesTags

Repository files navigation

👻 SimGhostInputs

Estado tests Ko-fi License: AGPL-3.0

📋 Brief de Producto · 🗺️ Roadmap · 📝 Changelog · 🤝 Contribuir

HUD preview

Note

v2.0.0 — Auditoría integral, remediación crítica y retiro de Streamlit. El motor CLI, la interfaz gráfica nativa (fantasma-ng, NiceGUI + pywebview) y el flujo de video con HUD (fantasma compose) están validados con telemetría y grabaciones reales en AMS2 (4 circuitos, múltiples clases). setup.ps1 probado en instalación limpia de Windows 11. 212 tests verdes. La UI Streamlit fue retirada en v2.0.0; la única interfaz es fantasma-ng. Importadores adicionales (iRacing, ACC, rF2) y features avanzadas van en versiones siguientes.

Compara tus inputs contra una vuelta de referencia, por distancia, no por tiempo.

SimGhostInputs es una herramienta abierta para sim racers que quieren estudiar su conducción con datos claros, visuales y accionables. Convierte telemetrías exportadas desde distintas fuentes —CSV, Excel, MoTeC u otros formatos compatibles— en un formato común que permite comparar una vuelta del piloto contra una vuelta de referencia.

El objetivo no es distribuir vueltas de referencia pagadas, privadas o de terceros. Cada usuario carga sus propios archivos de telemetría y se asegura de tener derecho a usarlos. El software solamente proporciona el motor de conversión, normalización, comparación y visualización.

Si una herramienta ayuda a la comunidad a mejorar, las mejoras de esa herramienta también deben volver a la comunidad.

Por eso el código se publica bajo AGPL-3.0-or-later: puedes usar, estudiar, modificar y compartir el software (incluso comercialmente), pero si distribuyes una versión modificada o la ofreces como servicio en red, debes publicar tu código fuente bajo la misma licencia.

Qué hace

  • Interfaz gráfica local (fantasma-ng): 5 pasos en ventana de escritorio nativa (NiceGUI + pywebview), sin hosting. Flujos predefinidos: solo análisis, solo overlay, o video completo con HUD. Tus datos nunca salen de tu máquina. Disponible también como instalador doble-clic (sin necesitar Python).
  • Importa telemetría desde CSV exportado de MoTeC i2 (y el mismo formato en .xlsx), o CSV genérico con mapeo de columnas.
  • Separa las vueltas de un outing (por beacons, número de vuelta o reinicio de distancia) y elige la más rápida.
  • Normaliza todo a un formato interno estándar: distancia de vuelta con metro 0 en meta, remuestreo configurable (5 m por defecto).
  • Detecta curvas e hitos automáticamente: frenada, turn-in, release, ápex (V-Min), gas, gas 100%, G lateral máxima, pendiente.
  • Compara piloto vs referencia por distancia: delta de tiempo continuo, Δ V-Min, Δ metro de frenada, tiempo perdido por curva.
  • Calcula indicadores de desgaste de goma: índice de deslizamiento (slip rueda vs velocidad real), activaciones de ABS/TCS por curva, temperatura media de gomas y combustible consumido.
  • Genera reporte en Markdown + CSVs de salida listos para graficar.
  • Genera packs de Pace Notes para CrewChief (fantasma pacenotes): tonos por hito de curva (frenada, ápex, gas) para escuchar referencias durante la siguiente vuelta.
  • Overlay HUD animado con canal alfa (VP9/WebM): velocímetro, gas/freno con color por ABS/TCS, delta continuo, marcha y distancia. Render paralelo en todos los cores.
  • Sincronía automática video/telemetría (--auto-sync): correlación cruzada del audio del motor (150–500 Hz) contra RPM/velocidad. Detecta el offset en ~30 s con precisión ~0.5 s. Valida la correlación (z-score ≥ 3σ) y verifica que no haya pausas de juego en el audio de la vuelta.
  • Composición del video final con NVENC automático si hay GPU NVIDIA disponible (3.7× más rápido que CPU en RTX 2060). El output es un clip recortado exactamente a la duración de la vuelta — sin re-codificar toda la sesión.

Qué NO incluye

Vueltas de referencia pagadas, telemetrías privadas de coaches o proveedores, setups comerciales, bases de datos propietarias. Trae tus propios datos.

Instalación

Primero, consigue el repo. Una instalación limpia de Windows no trae git. Descarga el ZIP desde GitHub (botón verde Code → Download ZIP, o el de la última release), descomprímelo y abre una terminal dentro de la carpeta. Si ya tienes git, git clone también sirve.

Windows (recomendado): ejecuta el script de setup incluido — instala el paquete, las dependencias Python y las herramientas del sistema en un paso:

powershell -ExecutionPolicy Bypass -File setup.ps1
# o con todo incluido (openpyxl + Pillow + matplotlib):
powershell -ExecutionPolicy Bypass -File setup.ps1 -Full
# desatendido (CI / máquina virgen): responde "sí" a todo, sin preguntas:
powershell -ExecutionPolicy Bypass -File setup.ps1 -Yes -SkipSystem

Manual:

pip install -e .                          # núcleo (sin dependencias externas)
pip install -e ".[xlsx]"                  # + leer archivos .xlsx de MoTeC i2
pip install -e ".[overlay]"               # + fantasma overlay (HUD de video)
pip install -e ".[charts]"                # + fantasma compare con gráficas
pip install -e ".[ui-ng]"                 # + fantasma-ng (interfaz gráfica NiceGUI, ventana nativa)
pip install -e ".[sync]"                  # + fantasma compose --auto-sync (detección de offset)
pip install -e ".[voice]"                 # + fantasma pacenotes --mode voice (edge-tts)
pip install -e ".[full]"                  # todo lo anterior
pip install -e ".[test]"                  # + correr la suite de tests (pytest); no lo instala setup.ps1

Dependencias completas

Dependencia Tipo Para qué Cómo instalar
openpyxl Python opcional Leer .xlsx exportados de MoTeC i2 pip install openpyxl
matplotlib Python opcional fantasma overlay — HUD animado; fantasma compare — gráficas ghost pip install matplotlib
Pillow Python opcional fantasma overlay — renderizado de frames auxiliares pip install Pillow
nicegui + pywebview + pandas Python opcional fantasma-ng — interfaz gráfica local (ventana nativa NiceGUI) pip install 'fantasma-inputs[ui-ng]'
scipy Python opcional fantasma compose --auto-sync — detección automática de offset video/telemetría pip install 'fantasma-inputs[sync]'
edge-tts Python opcional fantasma pacenotes --mode voice — frases de voz para CrewChief pip install 'fantasma-inputs[voice]'
ffmpeg Sistema opcional Codificar .webm/.mov con canal alfa y fantasma compose (auto-detecta NVENC si hay GPU NVIDIA) winget install Gyan.FFmpeg
gh (GitHub CLI) Sistema opcional Publicar y gestionar el repositorio en GitHub winget install GitHub.cli

Herramientas recomendadas para el flujo de video

No son dependencias del paquete, pero completan el flujo de análisis con video:

Herramienta Para qué Cómo instalar (Windows)
VLC Previsualizar overlay.webm con alfa antes de editar winget install VideoLAN.VLC
Kdenlive Editor open source (GPL) para superponer el HUD sobre tu grabación winget install KDE.Kdenlive
DaVinci Resolve Alternativa profesional gratuita (no open source) Descarga manual

El setup.ps1 incluido pregunta si instalar VLC y Kdenlive junto con el resto.

Uso rápido

La forma más fácil es la interfaz gráfica: fantasma-ng abre una ventana de escritorio nativa y te guía por 5 pasos (Inicio → Importar → Comparar / Overlay → Componer). No necesitas recordar ningún flag.

Para usar el CLI directamente:

# interfaz gráfica local (ventana nativa NiceGUI)
fantasma-ng

# ver las vueltas que contiene un archivo
fantasma laps "mi_export_motec.csv"

# detectar curvas de la vuelta más rápida
fantasma detect "referencia.csv" -o salida/

# comparar tu vuelta contra la referencia
fantasma compare --reference "referencia.csv" --driver "mi_vuelta.csv" -o salida/

# pack de tonos para CrewChief con las 5 curvas donde más pierdes
fantasma pacenotes --corners salida/corners_detected.json --compare salida/corners_compare.csv \
    --top 5 --mode tones --output-dir "%USERPROFILE%\Documents\CrewChiefV4\pace_notes\ams2\nordschleife"

# video HUD transparente para superponer sobre tu grabación
fantasma overlay --reference "referencia.csv" --driver "mi_vuelta.csv" -o salida/

# componer el overlay sobre tu grabación (usa NVENC automáticamente si hay GPU NVIDIA)
fantasma compose --video "grabacion.mp4" --overlay "salida/overlay.webm" -o "resultado.mp4"

# detectar offset automáticamente y componer en un solo paso (requiere scipy)
fantasma compose --video "grabacion.mp4" --overlay "salida/overlay.webm" \
    --auto-sync --driver "mi_vuelta.csv" -o "resultado.mp4"

# preview con overlay + sonidos de Pace Notes mezclados en el audio del video
fantasma compose --video "grabacion.mp4" --overlay "salida/overlay.webm" \
    --driver "mi_vuelta.csv" --pace-notes-dir "salida/pace_notes" -o "preview_pacenotes.mp4"

Salida de compare:

  • report.md — el debrief: dónde pierdes, cuánto y en qué fase de cada curva.
  • delta_map.png — delta acumulado de la vuelta completa con tus mayores pérdidas anotadas.
  • time_loss_bar.png — barras horizontales por curva ordenadas por pérdida (verde = ganas, rojo = pierdes).
  • gg_diagram.png — círculo de fricción: scatter G-lat vs G-long, tú vs referencia. Muestra si estás usando el agarre disponible. Requiere glat/glong en el CSV.
  • full_lap.png — todos los canales (velocidad, gas, freno, volante, marcha, G-lat, G-long, delta) a lo largo de la vuelta completa en un solo PNG.
  • curva_<ID>.png — gráficas ghost por curva (hasta 5 paneles: velocidad / gas / freno / volante / G-lat) de las curvas donde más pierdes.
  • frenada_<ID>.png — zoom en las zonas de frenada: velocidad + freno + G-long con el punto de frenada de referencia vs el tuyo marcado.
  • delta.csv / corners_compare.csv — los datos, listos para graficar otra cosa.

Salida de pacenotes:

  • metadata.json + WAVs ({distancia}_0.wav) listos para usar en Documents\CrewChiefV4\pace_notes\ams2\<pista>\.
  • plan.json — auditoría de qué sonidos eligió u omitió por curva para no saturar al piloto.
  • Por defecto genera un plan inteligente: countdown compacto para frenadas prioritarias, ápex y gas a fondo/inicio de gas solo donde hay espacio. El modo de voz (--mode voice o both) requiere edge-tts y ffmpeg.

Salida de overlay:

  • overlay.webm — video HUD con canal alfa (VP9) sincronizado con el tiempo de tu vuelta. Arrástralo como pista superior en tu editor sobre la grabación real y alinea el segundo 0 con tu cruce de meta. También --format prores (ProRes 4444 .mov para Final Cut / DaVinci) o --format png (frames sueltos).

    El HUD incluye tres paneles (gas / freno / volante) con codificación de color por estado:

    Canal Color piloto Color referencia
    Gas / Freno — normal verde / rojo gris
    Gas / Freno — TCS activo violeta vívido violeta apagado
    Gas / Freno — ABS activo ámbar vívido ámbar apagado
    Volante — carga lateral media (P75–P90 ref) amarillo amarillo apagado
    Volante — carga lateral alta (> P90 ref) naranja naranja apagado

    Los umbrales de G lateral del volante son relativos a la vuelta de referencia: el percentil 75 y 90 del |G-lat| de esa vuelta definen qué es "trabajando" y "al límite" para ese auto y pista, sin necesidad de ajuste manual.

    La franja de datos muestra: GAP acumulado · ΔV en el metro actual · índice de deslizamiento (proxy de desgaste) · activaciones de ABS por segmento · marcha actual (1–6 / N / R) · velocidad en km/h · distancia en metros. Los tres últimos campos son útiles para verificar la sincronía visualmente comparando con el velocímetro y el marcador de marcha del sim.

Documentación completa en docs/: guía de usuario · referencia del HUD · formato de datos · glosario · flujo de trabajo · cómo contribuir.

¿Cómo se trabaja en este repo? docs/flujo-de-trabajo.md es la guía del sistema de trabajo: barreras (lint, formato, tests), doc-gate (qué avisa vs qué bloquea), la matriz de roles del §8 de CONTRIBUTING.md, y la capa asistida por IA en .claude/ (hooks de sesión, skill Escribano, orquestación con subagentes).

Demo: descarga sample_60s_nordschleife.mp4 para ver el HUD en acción sobre grabación real (AMS2 · BMW M4 GT3 · Nordschleife).

Nombres de curvas (opcional)

El reporte usa IDs genéricos (C01, C02...) salvo que le des un archivo de curvas:

# 1. genera las curvas de TU referencia
fantasma detect "referencia.csv" -o salida/
# 2. edita salida/corners_detected.json y añade "name" a cada curva
#    (y ajusta "tolerances" si quieres avisos más o menos sensibles)
# 3. úsalo en las comparaciones
fantasma compare --reference referencia.csv --driver mi_vuelta.csv --corners salida/corners_detected.json

Los nombres de curvas y sus metros son datos de la comunidad: comparte tu "track pack" JSON con otros pilotos del mismo circuito.

Cómo capturar telemetría

Sim Estado Ruta recomendada
AMS2 ✅ Probado sim-to-motec (shared memory → .ld) → exportar CSV desde MoTeC i2
ACC / AC / rF2 / LMU ⚙️ Compatible* sim-to-motec → .ld → CSV desde MoTeC i2
iRacing ⚙️ Compatible* sim-to-motec → .ld → CSV desde MoTeC i2
GT7 ⚙️ Compatible* sim-to-motec (UDP → .ld) → CSV desde i2
Otros 🗺️ Manual CSV genérico con --map (ver fantasma compare --help)

*El pipeline vía sim-to-motec → MoTeC i2 → CSV exporta columnas estándar de i2 independientemente del sim. Los canales opcionales (ABS, TCS, G-Forces) dependen de lo que cada sim exponga al logger — si no están presentes, el análisis continúa sin ellos.

En el roadmap: lectura directa de .ld (sin pasar por i2) e iRacing .ibt.

Licencia

AGPL-3.0-or-later. © Colaboradores de SimGhostInputs.

Dependencias de terceros

Todas las dependencias Python del proyecto (openpyxl, matplotlib, Pillow, pandas, scipy, numpy) son MIT o BSD — completamente compatibles con AGPL-3.0 sin restricciones adicionales.

NiceGUI usa Apache 2.0 y pywebview usa BSD-3-Clause — ambas compatibles con AGPL-3.0: código AGPL-3.0 puede usar dependencias Apache 2.0 / BSD, pero no al revés. Los contribuidores que incorporen código de este proyecto en otro proyecto deben respetar el copyleft de AGPL-3.0.

ffmpeg se usa como proceso externo vía subprocess — nunca se linka contra sus bibliotecas. Al no existir linking no existe obra derivada, por lo que las obligaciones de licencia de ffmpeg (LGPL/GPL según el build del sistema) no se extienden al código de SimGhostInputs. ffmpeg debe instalarse por separado y bajo su propia licencia.

About

Compara tus inputs de simracing contra una vuelta de referencia, por distancia.

Resources

Readme
AGPL-3.0 license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages