ViDRA-V1

ViDRA-V1 is a research-grade scaffold for vision-only human driving data collection and analysis in Euro Truck Simulator 2 (ETS2). The project is split into a low-latency live capture path and an offline analysis path so gameplay capture stays lightweight while alignment, segmentation, feature extraction, and artifact generation happen after the session ends.

Support Matrix

• Live capture: Windows only
• Offline alignment / segmentation / features / analysis: cross-platform Python
• Tested Python: 3.10+

Live capture uses Win32 APIs for process monitoring, window discovery, keyboard polling, and Windows Startup integration. If you import or run live-capture commands on a non-Windows system, ViDRA-V1 now fails with a clear runtime error instead of crashing at import time.

Quick Start

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e .[research]
python -m unittest discover -s tests
vidra --help

If you prefer not to install the package, the repository also works directly from the checkout because sitecustomize.py adds src/ to sys.path automatically for local runs. The checkout also includes a top-level vidra_v1/ shim so python -m vidra_v1 ... works from a clean clone without setting PYTHONPATH.

Project Layout

<PROJECT_ROOT>/
+-- configs/
+-- datasets/
+-- paper_artifacts/
+-- runtime/
+-- sessions/
+-- src/vidra_v1/
+-- tests/
`-- vidra_v1/

Runtime Split

Live during gameplay:

1. Session metadata
2. Window/frame capture
3. Keyboard polling and HCEL encoding
4. Timestamped capture record writing
5. Service/session live logging

Offline after gameplay:

1. Alignment
2. Event segmentation
3. Feature extraction
4. Behavioral analysis
5. Dataset export and paper artifacts

Installation Modes

Recommended:

python -m pip install -e .[research]
vidra --help

Direct-from-repo fallback:

python -m vidra_v1 --help

Configure ETS2

Set the ETS2 executable path in:

• configs/game_config.json

Example placeholder:

{
  "game_executable_path": "<ETS2_EXE_PATH>",
  "process_name": "eurotrucks2.exe",
  "poll_interval_s": 1.0
}

Capture parameters live in:

• configs/capture.json
• configs/auto_capture.json
• configs/overlay_config.json

Common Commands

Initialize a manual session:

vidra init-session --session-id ets2_2026_03_21_001 --driver-id driver_a --controller-type keyboard --experiment-tag v1_baseline

Run the always-on capture service:

vidra auto-service --driver-id driver_a --controller-type keyboard --experiment-tag v1_auto

Install Windows autostart for the capture service:

vidra install-autostart --driver-id driver_a --controller-type keyboard --experiment-tag v1_auto --start-now

Check the current runtime state:

vidra status

Run a session integrity check:

vidra validate-session --session-id <SESSION_ID>

Write a dataset manifest for a session:

vidra write-manifest --session-id <SESSION_ID>

Run the offline pipeline for a session:

vidra run-post --session-id <SESSION_ID>

What Gets Logged

During live capture, ViDRA-V1 writes:

• frame images under sessions/<SESSION_ID>/raw/frames/
• atomic capture records under sessions/<SESSION_ID>/raw/records/capture_records.jsonl
• raw key transitions under sessions/<SESSION_ID>/raw/controls/key_events.jsonl
• per-session live state under sessions/<SESSION_ID>/live_status.json
• per-session runtime events under sessions/<SESSION_ID>/runtime_events.jsonl
• global service events under runtime/service_events.jsonl
• global session history under runtime/session_history.jsonl
• dataset manifests under sessions/<SESSION_ID>/dataset_manifest.json and runtime/dataset_manifests.jsonl
• experiment records under sessions/<SESSION_ID>/experiments/ and runtime/experiments.jsonl
• validation reports under sessions/<SESSION_ID>/validation_report.json

Testing

The repository test suite should run from a clean clone with:

python -m unittest discover -s tests

For editable-install validation:

python -m pip install -e .
python -m unittest discover -s tests

Notes

• Live capture currently stores sampled frames plus control logs; it does not write an .mp4 video.
• Live overlays work best in borderless/windowed ETS2. Exclusive fullscreen can hide Windows topmost overlays behind the game.