nepython/reality-fork

Reality Fork: física a partir de vídeo

Reality Fork rastrea un objeto en movimiento fotograma a fotograma (Meta SAM 3.1), ajusta una ley de movimiento con barras de error, y puede "bifurcar" el movimiento bajo condiciones físicas cambiadas.

Cuándo usarlo

El usuario tiene un vídeo (o un identificador de clip de muestra) y quiere: gravedad, velocidad inicial o ángulo, arrastre del aire, cuánto rebota una pelota, la longitud o periodo de un péndulo, aceleración en una pendiente, o "¿cómo se vería esto en la Luna?". También cuando el código necesita constantes reales medidas a partir de metraje.

Cómo invocarlo

Reemplace <DIR> con la carpeta de reality-fork (la que contiene mcp/).

Herramientas MCP (si el servidor reality-fork está conectado):

• list_clips - identificadores de clip e indicación de si cada uno está analizado.
• analyze_video({path | clip_id, question?, live?}) - titular, respuesta, ley, mediciones con sigma, supuestos, confianza.
• fork_motion({clip_id, g?, drag?, e?}) - re-simulación: resumen, eventos de aterrizaje/rebote, trayectoria cada 0.1 s en metros.
• export_measurements({clip_id}) - JSON de la ley ajustada, parámetros, sigmas, escala, rango de fotogramas, fps.
• braking_fork({clip_id, hazard_distance_m = 20, speed_kmh?, react_s = 1.5, decel = 7}) - para un clip de un coche cruzando el encuadre: ¿se detiene si alguien se interpone a esa distancia?, ¿por cuántos metros?, ¿o a qué velocidad impacta? Tanto la velocidad medida (con su barra de error) como speed_kmh si se proporciona.
• speed_survey({clip_ids, limit_kmh = 30}) - muchos clips de coches analizados: cada velocidad en km/h con sigma, la media, la velocidad del percentil 85 con su incertidumbre, la proporción por encima del límite, y un resumen simple. Los clips no vehiculares o no analizados se listan como omitidos, con el motivo.

Shell (mismas herramientas, JSON en salida estándar; utilícese si MCP no está disponible):

node <DIR>/mcp/cli.mjs list
node <DIR>/mcp/cli.mjs analyze <ruta-al-video|clip_id> --question "¿cuánto vale g?"
node <DIR>/mcp/cli.mjs fork <clip_id> --g 1.62        # o --g moon, --drag none, --e 0.8
node <DIR>/mcp/cli.mjs export <clip_id>
node <DIR>/mcp/cli.mjs brake <clip_id> --distance 20 --speed 30   # también --react 1.5 --decel 7
node <DIR>/mcp/cli.mjs survey <clip_id> <clip_id> ... --limit 30

Flujo típico: analyze, luego export para obtener números, opcionalmente fork. Inserte los valores exportados en el código del usuario, con sus sigmas como tolerancias.

Coches: frenado y estudios de velocidad

Use braking_fork cuando la pregunta sea sobre seguridad en una calle ("¿se detendría el coche si un niño se interpusiera 20 m adelante?", "¿qué diferencia hace 30 km/h?") y speed_survey cuando alguien necesite la velocidad del tráfico para un ayuntamiento o una escuela: los ayuntamientos actúan según la velocidad del percentil 85, la velocidad por debajo de la cual circula el 85 % de los conductores, no el promedio. Ambos necesitan clips ya analizados con un ajuste de velocidad constante de algo que se mueve lateralmente a través del encuadre a más de 2 m/s. Siempre indique los supuestos mencionados junto con la respuesta: 1.5 s de tiempo de percepción-reacción y frenada fuerte a 7 m/s² sobre asfalto seco son cifras típicas, no mediciones; cambie react_s y decel para un conductor cansado o una carretera mojada. La velocidad de cada clip depende de la escala (el tamaño de un objeto conocido, como la longitud de un coche), así que menciónelo, y con menos de unos 20 clips considere el percentil 85 como una guía aproximada.

Interpretación de los números

• Cada valor tiene un error de 1 sigma. sigma en las mediciones de analyze_video ya incluye la incertidumbre de escala; en export_measurements use sigma_total para afirmaciones del mundo real y sigma_fit para ruido del ajuste únicamente.
• Aproximadamente el 68 % de las repeticiones deberían caer dentro de 1 sigma, el 95 % dentro de 2. Si un resultado está dentro de 2 sigma de un valor conocido (g de la Tierra = 9.81), concuerda; no sobreinterprete una diferencia del 3 % cuando sigma es del 6 %.
• Verifique confidence y assumptions. Diga "medido 10.0 +/- 0.7 m/s^2", nunca un número desnudo.
• Los resultados de fork son simulaciones a partir de la ley ajustada, no nuevas mediciones. Los tiempos están en segundos desde el inicio de la trayectoria, las posiciones en metros desde el punto de inicio del ajuste, x a la derecha, y hacia arriba.

Límites honestos

• Cámara fija; sin panorámica ni zoom.
• Movimiento aproximadamente en un plano frente a la cámara (sin cambios fuertes de profundidad).
• La escala proviene de un objeto de tamaño conocido en el mismo plano (una pelota de tenis, una persona); una suposición de tamaño incorrecta escala cada longitud y velocidad.
• Clips cortos: se usan como máximo 20 s. El vídeo está normalizado a H.264; el tiempo de fotograma es el del reloj.
• Un nuevo análisis (live=true) invoca los modelos de Meta, cuesta algunos céntimos de crédito API, y solo se ejecuta si el proceso se inició con RF_ALLOW_LIVE=1. De lo contrario, solo están disponibles los clips ya analizados. Nunca lo active sin el consentimiento del usuario.