Tier 1: RIDM title, usage, requirements, walking config, drop internal ledger field

README.md

@@ -9,7 +9,7 @@ tags:
 - counter-strike-2
 ---
 
-# IDM: inverse dynamics models for camera motion
+# Reka Inverse Dynamics Model (RIDM)
 
 Two models predict camera motion (W/A/S/D/Shift, yaw, pitch) from video.
 Both trained on Counter-Strike 2 renders.
@@ -26,12 +26,30 @@ Both trained on Counter-Strike 2 renders.
 † The number comes from a write-up and has no run log yet.
 
 ```text
-idm-hf/
-  flow/   model.safetensors  config.json  inference.py  README.md
+Reka-Inverse-Dynamics-Model/
+  README.md  LICENSE  NOTICE  requirements.txt
+  flow/   model.safetensors  config.json  config_walking.json  inference.py  README.md
   pixel/  model.safetensors  config.json  inference.py  README.md
 ```
 
-Each folder runs alone: `python inference.py clip.mp4`.
+## Which model to use
+
+Use the flow model for real video. The pixel model gives no clear signal on real footage.
+Its card says so. Use the pixel model for Counter-Strike 2 footage only.
+
+## Use
+
+```bash
+pip install -r requirements.txt
+hf download RekaAI/Reka-Inverse-Dynamics-Model --local-dir ridm
+python ridm/flow/inference.py clip.mp4 --stride 17
+```
+
+- The script prints JSON. Each window has `key_probabilities`, `keys_pressed`, `yaw_deg` and `pitch_deg`.
+- Default settings match game footage. For walking video, run
+  `python ridm/flow/inference.py clip.mp4 --config ridm/flow/config_walking.json --stride 49`.
+- Each folder runs alone. See `flow/README.md` and `pixel/README.md` for details.
+- Tested with Python 3.12 and the versions in `requirements.txt`. Newer versions are untested.
 
 Status: preliminary release. The scores marked † are unconfirmed.
 
@@ -40,3 +58,8 @@ Status: preliminary release. The scores marked † are unconfirmed.
 - The weights and the code in this repository use the Apache License 2.0. See `LICENSE`.
 - RAFT-small weights use the BSD-3 license. They come from torchvision and are not in this repository. See `NOTICE`.
 - The models trained on Counter-Strike 2 gameplay captures. This repository holds no game assets, no clips and no training data.
+
+## Contact and citation
+
+- Questions and problems: open a discussion on this repository.
+- To cite, name this repository: Reka AI, Reka Inverse Dynamics Model (RIDM), Hugging Face, `RekaAI/Reka-Inverse-Dynamics-Model`.

flow/README.md

@@ -43,7 +43,8 @@ Yaw and pitch are signed. The sign is a classifier. The size comes from a log-ma
 | File | Content |
 |---|---|
 | `model.safetensors` | FlowTransformer weights only. No optimizer state. Float32. |
-| `config.json` | Architecture, thresholds, frame count, frame gap. |
+| `config.json` | Architecture, thresholds, frame count, frame gap 4. |
+| `config_walking.json` | The same, with frame gap 12, for walking-speed video. |
 | `inference.py` | Standalone script. No internal imports. |
 
 ## Results
@@ -64,8 +65,10 @@ Yaw and pitch are signed. The sign is a classifier. The size comes from a log-ma
 - The model trained on Counter-Strike 2 renders only.
 - The default frame gap is 4 source frames, tuned on game footage. Other gaps change the result.
 - Real walking is slower than game movement. On walking-tour video a gap of 12 gave a strong forward signal.
-  The gap comes from `frame_gap` in `config.json`. Copy the file, set the value, and pass it with `--config`.
-  Use `--stride` to match the new window length: (num_frames - 1) * frame_gap + 1 source frames.
+  `config_walking.json` is `config.json` with `frame_gap` 12. Run it with
+  `python inference.py clip.mp4 --config config_walking.json --stride 49`.
+  The window is (num_frames - 1) * frame_gap + 1 = 49 source frames, so `--stride 49` gives no overlap.
+  The key thresholds were tuned at gap 4. They are not tuned again for gap 12.
 - The gap embedding accepts values from 0 to 63.
 - Yaw and pitch are per window, not per frame.
 

flow/config.json

@@ -2,8 +2,20 @@
   "model_type": "idm-flow-transformer",
   "name": "flow_transformer_phase5_v4",
   "num_keys": 5,
-  "key_order": ["W", "A", "S", "D", "Shift"],
-  "key_thresholds": {"W": 0.54, "A": 0.40, "S": 0.54, "D": 0.70, "Shift": 0.20},
+  "key_order": [
+    "W",
+    "A",
+    "S",
+    "D",
+    "Shift"
+  ],
+  "key_thresholds": {
+    "W": 0.54,
+    "A": 0.4,
+    "S": 0.54,
+    "D": 0.7,
+    "Shift": 0.2
+  },
   "thresholds_tuned_at_num_frames": 5,
   "token_dim": 192,
   "num_layers": 4,
@@ -19,5 +31,8 @@
   "frame_gap": 4,
   "flow_backbone": "torchvision.models.optical_flow.raft_small (Raft_Small_Weights.DEFAULT, frozen, not in this repo)",
   "num_parameters": 1795337,
-  "training_checkpoint": {"epoch": 10, "best_val_loss": 0.8741227431995112, "run_ledger_status": "CANDIDATE"}
+  "training_checkpoint": {
+    "epoch": 10,
+    "best_val_loss": 0.8741227431995112
+  }
 }

flow/config_walking.json

@@ -0,0 +1,38 @@
+{
+  "model_type": "idm-flow-transformer",
+  "name": "flow_transformer_phase5_v4_gap12",
+  "num_keys": 5,
+  "key_order": [
+    "W",
+    "A",
+    "S",
+    "D",
+    "Shift"
+  ],
+  "key_thresholds": {
+    "W": 0.54,
+    "A": 0.4,
+    "S": 0.54,
+    "D": 0.7,
+    "Shift": 0.2
+  },
+  "thresholds_tuned_at_num_frames": 5,
+  "token_dim": 192,
+  "num_layers": 4,
+  "num_heads": 4,
+  "ffn_dim": 512,
+  "head_hidden": 256,
+  "dropout": 0.1,
+  "num_flow_frames": 9,
+  "patch_grid": 8,
+  "rotation_head_type": "sign_magnitude",
+  "resolution": 128,
+  "num_frames": 5,
+  "frame_gap": 12,
+  "flow_backbone": "torchvision.models.optical_flow.raft_small (Raft_Small_Weights.DEFAULT, frozen, not in this repo)",
+  "num_parameters": 1795337,
+  "training_checkpoint": {
+    "epoch": 10,
+    "best_val_loss": 0.8741227431995112
+  }
+}

requirements.txt

@@ -0,0 +1,6 @@
+torch==2.14.0
+torchvision==0.29.0
+av==19.0.0
+opencv-python==5.0.0
+safetensors==0.8.0
+numpy==2.5.3