nepython/reality-fork

Reality Fork: 物理を動画から計測

Reality Forkは、動く物体をフレームごとに追跡し（Meta SAM 3.1）、誤差範囲付きの運動法則をフィッティングし、物理条件を「フォーク」して運動を再シミュレーションします。

使用するタイミング

ユーザーが動画（またはサンプルクリップID）を持っており、次の値を求めている場合に使用します：重力、打ち出し速度または角度、空気抵抗、ボールの反発係数、振り子の長さまたは周期、斜面での加速度、または「これが月でどう見えるか」。また、コードに実際の映像から計測した定数が必要な場合にも使用します。

呼び出し方

<DIR> は reality-fork のチェックアウト先（mcp/ フォルダが入っているディレクトリ）に置き換えてください。

MCP ツール（reality-fork サーバーが接続されている場合）：

• list_clips - クリップIDと、各クリップが解析済みかどうかを表示
• analyze_video({path | clip_id, question?, live?}) - 見出し、回答、物理法則、誤差付き測定値、前提条件、信頼度
• fork_motion({clip_id, g?, drag?, e?}) - 再シミュレーション：要約、着地/バウンドイベント、0.1秒ごとの経路（メートル単位）
• export_measurements({clip_id}) - フィッティングされた物理法則、パラメータ、シグマ、スケール、フレーム範囲、fps のJSON
• braking_fork({clip_id, hazard_distance_m = 20, speed_kmh?, react_s = 1.5, decel = 7}) - 車がフレームを横切るクリップに対し、前方に人が飛び出した場合に停止するか、何メートル手前で停止するか、または衝突時の速度を計算。測定速度（誤差範囲付き）と speed_kmh（指定時）の両方を使用。
• speed_survey({clip_ids, limit_kmh = 30}) - 解析済みの複数の車クリップ：各速度（km/h、シグマ付き）、平均値、85パーセンタイル速度（不確実性付き）、制限速度超過率、平易な要約。非車両または未解析のクリップはスキップされ、理由とともにリスト表示。

シェル（同じツール、JSONを標準出力；MCPが利用できない場合に使用）：

node <DIR>/mcp/cli.mjs list
node <DIR>/mcp/cli.mjs analyze <video-path|clip_id> --question "gはいくつ？"
node <DIR>/mcp/cli.mjs fork <clip_id> --g 1.62        # または --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   # 他に --react 1.5 --decel 7
node <DIR>/mcp/cli.mjs survey <clip_id> <clip_id> ... --limit 30

典型的な流れ：analyze で解析し、export で数値を取得、必要に応じて fork でフォークします。エクスポートされた値をそのシグマを許容誤差としてユーザーのコードに組み込みます。

自動車：制動距離と速度調査

質問が道路の安全に関する場合（「子どもが20m先に飛び出したら車は止まるか？」「時速30km/hの差はどれほどか？」）は braking_fork を使用し、交通の速度を自治体や学校のために調べる必要がある場合は speed_survey を使用します。自治体は平均速度ではなく、85パーセンタイル速度（85%のドライバーがそれを超えない速度）に基づいて行動します。どちらも、フレームを横切って2m/s以上で動く物体を一定速度でフィッティングした解析済みクリップが必要です。回答には必ず記載された前提条件を付け加えてください：1.5秒の知覚-反応時間と乾燥アスファルトでの急制動7m/s²は測定値ではなく標準的な数値です。疲れたドライバーや濡れた道路の場合は react_s と decel を変更してください。各クリップの速度はスケール（車の長さなど既知の物体のサイズ）に依存するため、その旨を伝えてください。クリップが約20未満の場合は、85パーセンタイルはおおまかな目安として扱ってください。

数値の読み方

• すべての値には1シグマ誤差が付いています。analyze_video の測定値における sigma はすでにスケールの不確実性を含んでいます；export_measurements では、現実世界の主張には sigma_total を、フィッティングのみのノイズには sigma_fit を使用してください。
• 約68%の再測定は1シグマ以内に収まり、95%は2シグマ以内に収まるはずです。結果が既知の値（地球のg = 9.81）の2シグマ以内にあれば、一致と見なします。シグマが6%のときに3%の差を過大評価しないでください。
• confidence と assumptions を確認してください。「測定値 10.0 ± 0.7 m/s²」のように報告し、裸の数値だけを伝えないでください。
• フォーク結果はフィッティングされた法則からのシミュレーションであり、新しい測定値ではありません。時間はトラック開始からの秒数、位置はフィッティングの開始点からのメートル単位、xは右、yは上です。

正直な限界

• カメラは固定。パンやズームは不可。
• 運動はおおよそカメラに正対した平面内であること（奥行き方向の強い変化がないこと）。
• スケールは同じ平面内にある既知のサイズの物体（テニスボール、人物）から取得します。サイズの仮定を誤ると、すべての長さと速度がスケーリングされます。
• 短いクリップ：最大20秒まで使用。動画はH.264で正規化。フレームタイミングは時計に基づきます。
• 新しい解析（live=true）はMetaのモデルを呼び出し、APIクレジットを数セント消費します。プロセスが RF_ALLOW_LIVE=1 で開始された場合のみ実行されます。それ以外の場合は、既に解析済みのクリップのみが利用可能です。ユーザーの承諾なしに有効にしないでください。