tomh104/charade_experiment
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

merged READMEs

Browse Source
This commit is contained in:
tom.hempel
2025-09-17 13:57:29 +02:00
parent 698890f20c
commit 37efbe8719
2 changed files with 153 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

154
README.md
View File

@ -3,9 +3,161 @@
## Structure ## Structure
- `app.apk` - VR Charades application - `app.apk` - VR Charades application
- `experiment-scripts/` - Control scripts and web interface (see separate README) - `experiment-scripts/` - Control scripts and web interface
- `data-analysis/` - Analysis notebook and face/hand tracking data - `data-analysis/` - Analysis notebook and face/hand tracking data
- `videos/` - Recorded experiment footage - `videos/` - Recorded experiment footage
- `vrcharades-unity/` - Unity source code - `vrcharades-unity/` - Unity source code
- `VR_Charades_Paper.pdf` - Research paper - `VR_Charades_Paper.pdf` - Research paper
- `Einverstaendniserklaerungen.pdf` - Consent forms - `Einverstaendniserklaerungen.pdf` - Consent forms
## Running Experiments
### Prerequisites
1. Create and activate a virtual environment:
```bash
# Windows
cd experiment-scripts
python -m venv venv
venv\Scripts\activate
# Linux/Mac
cd experiment-scripts
python3 -m venv venv
source venv/bin/activate
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
### Experiment Scripts 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. 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 `experiment-scripts/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)
```
#### 2. Start the Relay Server
```bash
cd experiment-scripts
python server.py
```
#### 3. Start the Web Interface
```bash
cd experiment-scripts
python -m fastapi dev app.py
```
Then navigate to `http://localhost:8000`
#### 4. Configure VR Clients
Tell clients which server to connect to:
```bash
# Windows PowerShell (replace with your actual VR headset IPs)
cd experiment-scripts
$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)
cd experiment-scripts
TARGET_IP="YOUR_PLAYER1_IP,YOUR_PLAYER2_IP" python3 control.py "IP:127.0.0.1"
```
#### 5. Set Experiment Condition
Choose one of these modes:
```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"
```
#### 6. Prepare Word List
Shuffle the word list for randomization:
```bash
# Windows PowerShell
cd experiment-scripts
Get-Content word-list.txt | Sort-Object {Get-Random} | Out-File word-list-shuffled.txt
# Linux/Mac
cd experiment-scripts
shuf word-list.txt > word-list-shuffled.txt
```
### Web Interface Usage
Once you have the web interface running at `http://localhost:8000`:
#### 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
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 and counts down
3. **During the session**:
- **Mark words correct**: Hover over a word and check the checkbox if guessed correctly
- **Visual indicators**: ▶ = Current word, ✅ = Correct, ❌ = Time expired
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, correctness, and time remaining
### Mode Details
Mode format: `<show_head>;<show_facial_expression>;<show_eye_rotation>;<show_hands>`
- **Dynamic modes**: Real-time face/hand tracking
- **Static modes**: Participants use controllers instead of natural movement

164
experiment-scripts/README.md
View File

@ -1,164 +0,0 @@
# VR Charades Experiment Scripts
This directory contains scripts to run and control VR Charades experiments.
## 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