Skip to content

Carla Data Recorder Instructions

Setup

  • “Run the latest SightLab installer, selecting both K-Lite Codec Pack and Extra Libraries when prompted.
    Alternatively, you can manually install K-Lite Codec Pack if missing.”
  • SRanipal - Search in Steam for "Vive Console for SteamVR" or use this link.
  • Unzip and place Carla Data Recorder on each machine. Download it here.
  • To view the data files recommended to install "WPS Office", which is a free spreadsheet reader.

How to Run
Setup Hardware: Make sure hardware/headset are connected, boundary is set and controllers are on (if using controllers)
Run 1_EYE_TRACKER_TEST_RUN_FIRST.py on the Simulation Rig. Agree to the SRAnipal pop-up. You will then see a white room and can verify the green gaze point is moving with your eyes.
Launch Carla
Launch Carla_Data_Recorder.py
Select recording length (seconds). You can end early by closing the window or pressing Space.
When the gray recording window appears, click it once to bring it into focus, then press Spacebar to start recording.
Put on the headset and run Carla. A mirrored window will show a live gaze point
Finish & save: When the timer ends you’ll hear a beep. Data goes to the /data folder. Close the recorder window.
GUI View a replay with visualizations by launching the Carla_Data_Recorder_Replay.py file and choose your session.
Use the scrubber in the replay to scrub through the playback. This will show a gaze point overlay by default.
Press the Data button to open the data files (click on date and time folder and view trial_data to see raw data)
Note: if using Biopac, press the 1 and the 2 keys to sync with the Acqknowledge server.

Replay Controls (Highlights)

  • Toggle overlays: scan path, fixations, dwell spheres, heatmap

  • Follow camera: keep this on

  • Scrub: hotkeys B/N or C/V to step; drag slider to set time (video frame jumps follow hotkeys)

  • Record gaze video: 4 start / 5 stop → saves to /replay_recordings

  • Restart Playback: Press r to restart the playback

  • Hide Menu: Press the period "." key to hide the side menu

What Gets Recorded

See here for full list.

Eye/Gaze

  • Combined & per‑eye gaze origin/rotation; gaze point overlay
  • Fixations & counts
  • Saccades (state, amplitude, velocity, peak/avg stats)
  • (Experimental) AI‑derived View Counts & Dwell

Physiology (when available)

  • Biopac AcqKnowledge Physiological Data (when connected to Biopac) (i.e. heart rate, EDA, ECG, EEG, FNIRs, Respiration)
  • Facial expressions (with face tracker)
  • Biopac AcqKnowledge markers & sync; AcqKnowledge playback can be driven by the SightLab Replay slider (6.02+)

Events & Timing

  • Custom flags, interaction triggers, timestamps (trial‑relative & UNIX).

Configuration Settings

# ----- Biopac & Network Sync -----
BIOPAC_ON = True                    # Communicate with Biopac Acqknowledge
LOCK_TRANSPORT = True                # Lock the transport
NETWORK_SYNC_KEY = 't'               # Key to send event marker to Acqknowledge
NETWORK_SYNC_EVENT = 'triggerPress'  # Event trigger for marker
USE_NETWORK_EVENT = False            # Send network event to external app
NETWORK_START = False      # if True, use a network event to start (instead of START_END_SESSION_KEY)
# Network host/port and JSON event names (must match Unity/Unreal sender)
NETWORK_HOST = 'localhost'
NETWORK_PORT = 4950
NETWORK_START_EVENT_NAME = 'start_trial'

# ----- Data Recording -----
RECORD_VIDEO = True                  # Enable video recording
RECORD_VIDEO_OF_PLAYBACK = True      # Record during replay
RECORD_GAZE_MAT = True               # Save gaze matrix data
RECORD_FACE_TRACKER_DATA = False     # Save facial expression data
OLDER_SIGHTLAB_PID = False           # Use older participant ID format

# ----- Video Recording Method -----
# "OPENCV"           = Compressed videos (~50MB/min), may crash after ~10min
# "VIZARD_BUILT_IN"  = Uncompressed (~400MB/min), stable for hours, records Vizard window only
# "SIGHTLAB_BUILT_IN" = Vizard built in with compression - Can take some time to compress
# "IMAGEIO_FFMPEG"   = External window capture via imageio-ffmpeg, may crash after ~10min
SCREEN_RECORDER_TYPE = "IMAGEIO_FFMPEG"  

# ----- Video Quality Settings -----
VIDEO_RECORDING_WINDOW_HEIGHT_NEW = '1920'
VIDEO_RECORDING_WINDOW_WIDTH_NEW = '1080'

# ----- Timer & Session Control -----
USE_TIMER = True                     # Use timer instead of keypress to end trial
USE_TIMER_DROPDOWN = True            # Show dropdown to select timer length
DEFAULT_TIMER_LENGTH = 10            # Default timer length (seconds)
START_END_SESSION_KEY = ' '          # Spacebar to start/stop trial
PLAY_END_SOUND = True                # Play sound at end of trial
TRIAL_CONDITION = 'A'                # Default trial condition label
SET_NUMBER_OF_TRIALS = 1

# ============================================================================
# REAL-TIME STREAMING SETTINGS (During Recording)
# ============================================================================

REAL_TIME_STREAMING = True           # Show live window capture in VR during recording

# ----- Texture Alignment (if video appears offset) -----
# Use keyboard controls to adjust, then copy values here:
#   Arrow Keys: Move texture   |   Numpad 4/6/8/2: Scale texture
#   P: Print values  |  R: Reset to defaults
TEXTURE_OFFSET_X = 0.0               # Horizontal offset
TEXTURE_OFFSET_Y = 0.0               # Vertical offset  
TEXTURE_SCALE_X = 1.0                # Horizontal scale
TEXTURE_SCALE_Y = 1.0                # Vertical scale
TEXTURE_ADJUSTMENT_STEP = 0.05       # Adjustment increment per keypress

# ============================================================================
# REPLAY SETTINGS (During Playback)
# ============================================================================

HIDE_REPLAY_GUI = False              # Hide SightLab's replay GUI
FOLLOW_ON = True                     # Enable first-person view in replay
REPLAY_SECOND_GAZE_POINT_OFF = True  # Default True
override_screen_position = True      # Flag to control whether we override replay position
override_real_time_position = False  # Default False

# ----- Screen Position & Size -----
# Adjust these if the replay video appears misaligned or wrong size
# Use keyboard controls during replay to find perfect values:
#   Arrow Keys: Move  |  PgUp/PgDn: Depth  |  +/-: Width  |  [/]: Height
#   K: Print values  |  L: Reset  |  O: Toggle override

# ----- Viewpoint Adjustment -----
# Fine-tune camera position/rotation for optimal replay viewing

# ============================================================================
# PROFILE MAPPING AND PRESET CONFIGURATIONS
# ============================================================================
See the Config file for the full profile mapping list you can adjust