From 8d749a56099e14660300e392a0688370f740f934 Mon Sep 17 00:00:00 2001 From: "tom.hempel" Date: Wed, 17 Sep 2025 13:53:25 +0200 Subject: [PATCH] updated README for scripts --- experiment-scripts/README.md | 176 +++++++++++++++++++++++++--- experiment-scripts/requirements.txt | 1 + 2 files changed, 163 insertions(+), 14 deletions(-) create mode 100644 experiment-scripts/requirements.txt diff --git a/experiment-scripts/README.md b/experiment-scripts/README.md index 15fb0c7..58583b1 100644 --- a/experiment-scripts/README.md +++ b/experiment-scripts/README.md @@ -1,16 +1,164 @@ -# README +# VR Charades Experiment Scripts -The documentation for most files can be found inside the file itself. -The most important files are: +This directory contains scripts to run and control VR Charades experiments. - - control.py: For setting up the conditions - - app.py: For running the HTML user interface - - server.py: For running the relay server - - To setup the experiment environment, you should: - 1. Connect the HMDs to same network as the server - 2. Start the relay server (i.e. server.py) - 3. Start the HTML user interface (e.g. using `fastapi dev app.py`) - 4. Communicate the server IP to the HMDs using `TARGET_IP= python3 control.py 'IP:'` - 5. Setup the desired condition (see control.py for more information) - 6. Shuffle the word-list (i.e. word-list.txt); on linux this can be achieved using shuf e.g. `shuf word-list.txt > word-list-shuffled.txt` +## Installation + +1. Create and activate a virtual environment: +```bash +# Windows +python -m venv venv +venv\Scripts\activate + +# Linux/Mac +python3 -m venv venv +source venv/bin/activate +``` + +2. Install Python dependencies: +```bash +pip install -r requirements.txt +``` + +## Files Overview + +- **app.py**: Web interface for controlling the experiment and word list +- **server.py**: UDP relay server for communication between VR clients +- **control.py**: Command-line tool for setting VR client modes and server IP +- **index.html**: Web UI served by app.py +- **word-list.txt**: Default list of charade words + +## Setup Instructions + +### 1. Prepare Dependencies +```bash +# Activate your virtual environment first +# Windows: venv\Scripts\activate +# Linux/Mac: source venv/bin/activate + +pip install -r requirements.txt +``` + +### 2. Network Setup +- Connect all VR headsets to the same network as the server +- Note the IP addresses of the VR headsets (you'll need these for configuration) +- **Important**: Update `server.py` lines 19-20 with your actual VR headset IPs + ```python + # Replace these example IPs with your actual headset IPs + DEVICE1_ADDR = ("YOUR_PLAYER1_IP", 5001) # e.g., ("192.168.1.100", 5001) + DEVICE2_ADDR = ("YOUR_PLAYER2_IP", 5001) # e.g., ("192.168.1.101", 5001) + ``` + +### 3. Start the Relay Server +```bash +python server.py +``` + +### 4. Start the Web Interface +```bash +python -m fastapi dev app.py +``` +Then navigate to `http://localhost:8000` + +### 5. Configure VR Clients + +Tell clients which server to connect to: +```bash +# Windows PowerShell (replace with your actual VR headset IPs) +$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "IP:127.0.0.1" + +# Linux/Mac (replace with your actual VR headset IPs) +TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" python3 control.py "IP:127.0.0.1" + +# Example with actual IPs: +# $env:TARGET_IP="192.168.1.100,192.168.1.101" ; python control.py "IP:127.0.0.1" +``` + +### 6. Set Experiment Condition + +Choose one of these modes (replace YOUR_PLAYER1_IP,YOUR_PLAYER2_IP with actual IPs): +```bash +# Dynamic Face only +$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:1;1;1;0" + +# Dynamic Hands only +$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:0;0;0;1" + +# Dynamic Hands + Face +$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:1;1;1;1" + +# Static Face only +$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:1;0;0;0" + +# Static Hands only (requires controllers) +$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:0;0;0;1" + +# Static Hands + Face (requires controllers for hands) +$env:TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" ; python control.py "MODE:1;0;0;1" +``` + +### 7. Prepare Word List + +Shuffle the word list for randomization: +```bash +# Windows PowerShell +Get-Content word-list.txt | Sort-Object {Get-Random} | Out-File word-list-shuffled.txt + +# Linux/Mac +shuf word-list.txt > word-list-shuffled.txt +``` + +## Web Interface Usage + +Once you have the web interface running at `http://localhost:8000`, follow these steps: + +### Setting Up a Charades Session + +1. **Configure Player IPs** + - Enter the IP addresses of Player 1 and Player 2 VR headsets + - These should match the IPs you used in the `control.py` commands + - **Note**: The default placeholders (10.42.0.38, 10.42.0.100) are examples - use your actual headset IPs + +2. **Prepare Word List** + - Copy your shuffled word list from `word-list-shuffled.txt` + - Paste it into the large text area on the right side + - Click the **"Modify"** button to generate interactive word items + +3. **Set Game Parameters** + - **Current Player For Acting**: Select which player will be acting out the words + - **Time (s)**: Set the time limit for each word (e.g., 30 seconds) + - **Last Word Status**: Set to "None" for the first word + +### Running the Experiment + +#### Manual Mode (Individual Words) +1. Enter a word in the "Word" field +2. Select the acting player (Player 1 or Player 2) +3. Set the time limit +4. Click **"Send"** to transmit the word to the VR headsets + +#### Automatic Mode (Word List) +1. After clicking "Modify" with your word list, the interface shows all words with timers +2. The system automatically: + - Starts with the first word + - Sends it to the selected acting player + - Counts down the timer for each word + - Moves to the next word when time expires or word is marked correct + +3. **During the session**: + - **Mark words correct**: Hover over a word and check the checkbox if guessed correctly + - **Timer display**: Shows remaining time for current word + - **Visual indicators**: + - ▶ = Current word being acted + - ✅ = Correctly guessed word + - ❌ = Time expired / incorrect word + +4. **Stop the session**: Click **"Stop"** to end early + +### Exporting Results + +1. After completing the word list, click **"Save as CSV"** +2. This downloads a CSV file with: + - Word name + - Whether it was guessed correctly (true/false) + - Time remaining when completed \ No newline at end of file diff --git a/experiment-scripts/requirements.txt b/experiment-scripts/requirements.txt new file mode 100644 index 0000000..a08191c --- /dev/null +++ b/experiment-scripts/requirements.txt @@ -0,0 +1 @@ +fastapi[standard]>=0.116.0