# Setting Up the VIPR Web App

## Prerequisites

- **Docker**: Docker client application installed and running

---

## Step 1: Clone the VIPR Framework Repository

```bash
git clone https://codebase.helmholtz.cloud/vipr/vipr-framework.git
```

---

## Step 2: Install and Start Docker Desktop

Ensure Docker Desktop is installed and running on your system.

**Download Docker Desktop:**
- macOS: https://www.docker.com/products/docker-desktop
- Windows: https://www.docker.com/products/docker-desktop
- Linux: https://docs.docker.com/desktop/install/linux-install/

---

## Step 3: Start the VIPR Framework

Navigate to the `vipr-framework` directory and start the services using Docker Compose:

```bash
cd vipr-framework
cp docker-compose.override.yml.example docker-compose.override.yml
mkdir -p storage
docker compose up --wait
```

The override file mounts the local `./storage` directory into the API and worker
containers. Create this directory before starting Docker Compose so Docker does
not create the bind-mounted directory with root-owned permissions. The
application creates the required subdirectories for results, model downloads,
and cache files as needed.

If `storage/` already exists with the wrong owner and the containers report
`Permission denied`, make it writable for the backend container user before
restarting:

```bash
sudo chown -R 1001:1001 storage/
```

This will pull and start the latest stable release. To use the `edge` release, adjust the images to point to `main` 

`.env`
```dotenv
FRONTEND_IMAGE=registry.hzdr.de/vipr/vipr-frontend/main:latest
BACKEND_IMAGE=registry.hzdr.de/vipr/vipr-api/main:latest
```

**Services:**
- **Backend API**: Running on port 8000
- **Frontend**: Running on port 5000

---

## Step 4: Open the Web Application

The Web Application is exposed on port `5000`

The `docker-compose.override.yml.example` from Step 3 already exposes the
frontend. If you create the override file manually instead, add:

```yaml
services:
  vipr-frontend:
    ports:
      - "5000:5000"
```

Restart the services:

```bash
docker compose up --wait
```

Open your browser and navigate to:

```
http://localhost:5000
```

![VIPR Web Interface](docs-sphinx/docs/images/web_app_gui.png)
*VIPR web interface with workflow sidebar and results panel*

You should see the VIPR web interface with the following components:
- Top navigation bar with **SAVE**, **LOAD**, **LOAD EXAMPLES**, and **VIEW CONFIG** buttons
- Left sidebar with workflow steps:
  1. **Normalize**
  2. **Preprocess**
  3. **Predict**
  4. **Postprocess**
- Main panel for results visualization

---

## Step 5: Load Example Data

1. Click the **"LOAD EXAMPLES"** button in the top navigation bar
2. Choose an example configuration (e.g., **Ni500**)
3. The configuration will load with example reflectometry data

---

## Step 6: Run Prediction

1. Scroll down in the left column to find the **"RUN PREDICTION"** button
2. Click **"RUN PREDICTION"**
3. Wait for the inference to complete

### Results Display

After prediction completes, you will see:

- **Reflectivity Curve** - Comparison of experimental, predicted, and polished data
- **Goodness of Fit** metrics:
  - Chi-squared (χ²) values for predicted and polished results
  - RMSE (Root Mean Square Error) values
  - RSS (Residual Sum of Squares) values

**Example Output:**
```
Chi-squared χ² (Predicted): 20306407.30 (Reduced: 203064.07302)
χ² (Polished): 20309049.80 (Reduced: 203090.498)
RMSE (Predicted): 0.110268 (RMSE: 0.332065)
RSS (Polished): 0.110083 (RMSE: 0.331788)
```

### Interactive Features

- **Zoom**: Use mouse wheel or pinch gesture on the plot
- **Pan**: Click and drag on the plot
- **Toggle curves**: Click legend items to show/hide data series
- **RESULTS/STREAMING tabs**: Switch between final results and live updates

---

## Configuration Workflow

The left sidebar shows the inference pipeline with editable steps:

### 1. Normalize
- Data normalization settings
- Click **EDIT** to modify normalization parameters

### 2. Preprocess
- Data preprocessing filters
- Default filter: `INFERENCE_PREPROCESS_PRE_FILTER` → `Reflectorch_preprocess_interpolate`
- Click **EDIT** to adjust preprocessing steps

### 3. Predict
- Model inference configuration
- Handler: `reflectorch_predictor`
- Click **EDIT** to modify prediction parameters:
  - Prior bounds for thicknesses, roughnesses, SLDs
  - Q resolution
  - Polishing options

### 4. Postprocess
- Result postprocessing
- Click **EDIT** to add custom postprocessing steps

### Run Prediction
- **RUN PREDICTION** button: Execute the full pipeline
- **Auto Execute** checkbox: Automatically run on configuration changes

---

## Working with Custom Configuration

### Loading Your Own Data

1. Click the **EDIT CONFIGURATION** button in the **LOAD DATA** step in the left column.
2. Expand the **DATA LOADER** panel. Under Upload CSV File, you can provide your own experimental data set. 
3. Configure column mappings if needed (Q column, Intensity column)

### Change Model

1. Click the **EDIT CONFIGURATION** button in the **LOAD MODEL** step in the left column.
2. Expand the **MODEL LOADER** panel. 
3. Select Model Loader (Reflectorch, Panpe)
4. Select the specific model under **Parameters**. 


### Modify Prediction Parameters

1. Click the **EDIT CONFIGURATION** button in the **PREDICT** step in the left column.
2. Expand the **PREDICTORS** panel. 
3. Change the prediction parameters as desired. 

### Viewing Full Configuration

Click **VIEW CONFIG** in the app bar to see the complete YAML configuration, including:
- Data loading parameters
- Model settings
- Prior bounds
- Preprocessing filters
- Postprocessing options

### Saving Your Configuration

Click the **SAVE** button in the app bar to export your configuration as JSON. You can import the configuration again by clicking the **LOAD** button. 

**Note:** In some cases, previously uploaded experimental data may no longer be available when loading a saved configuration. If this occurs, re-upload your data using the **LOAD DATA** step before running the prediction.

---

## Stopping the Application

To stop the VIPR services:

1. Return to the terminal where Docker Compose is running
2. Press **CTRL+C** to stop all services
3. Optionally, clean up containers:
   ```bash
   docker compose down
   ```

---
