README.md

---
title: AnyAct User Study
colorFrom: blue
colorTo: indigo
sdk: gradio
python_version: "3.10"
app_file: app.py
pinned: false
---

# AnyAct User Study

This repository contains a self-contained Gradio questionnaire for pairwise human motion reenactment evaluation.

## Included Data

The Space-ready copy already bundles all 30 study cases inside this repository:

- `videos/reference`
- `videos/anyact`
- `videos/vlm_hy_motion`
- `videos/echomotion`

The app reads those files through `data/study_config.json`, so it no longer depends on directories outside the repository.

## Runtime Storage

By default, the app stores runtime files under:

- `results/responses.csv`
- `results/responses.jsonl`
- `results/participants`
- `results/plots`

For Hugging Face Spaces, you should mount persistent storage and set:

```bash
USER_STUDY_RESULTS_DIR=/data/user_study_results
```

If the app is running inside a Space and `/data` exists, it automatically falls back to `/data/user_study_results` even without that variable.

## Local Run

```bash
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe app.py --share
```

## Hugging Face Spaces Deployment

### Option 1: Browser Upload

1. Create a new Hugging Face Space.
2. Choose `Gradio` as the SDK.
3. Upload the contents of this repository.
4. In the Space settings, optionally add persistent storage and set `USER_STUDY_RESULTS_DIR=/data/user_study_results`.

### Option 2: CLI

```bash
hf auth login
deploy_to_hf_space.bat username/space-name
```

The helper script creates the Space if needed and uploads this repository while excluding `.venv`, `.gradio`, `__pycache__`, and `results`.

## Files That Should Not Be Uploaded As Runtime Artifacts

The repository includes `.gitignore` rules so that local environments and transient results are not pushed by mistake:

- `.venv`
- `.gradio`
- `__pycache__`
- `results`

## Analysis

To analyze collected responses:

```bash
.\.venv\Scripts\python.exe analyze_results.py
```

This writes:

- `summary.csv`
- `participant_overview.csv`
- `plots/preference_barplot.png`

inside the chosen results directory.