@page gui_applications GUI Applications

# Quadrix GUI Applications

This document provides instructions for using the two GUI applications available for the Quadrix dendritic analysis platform.

## Table of Contents
- [Web-Based GUI](#web-based-gui)
- [Tauri Desktop Application](#tauri-desktop-application)
- [Feature Comparison](#feature-comparison)
- [Troubleshooting](#troubleshooting)

---

## Web-Based GUI

The web-based GUI is ideal for server deployments and multi-user access.

### Features
- Modern, responsive interface
- Real-time plot generation
- Configurable plot dimensions
- Support for color mapping by metadata fields
- No installation required (browser-based)
- Accessible from any device on the network

### Running the Web GUI

1. **Build the project with plotting features:**
   ```bash
   cargo build --bin web_gui --features plotting --release
   ```

2. **Start the server:**
   ```bash
   cargo run --bin web_gui --features plotting --release
   ```

3. **Access the application:**
   - Open your browser and navigate to `http://localhost:3000`
   - For network access: `http://<server-ip>:3000`

### Usage

1. **Data Source:**
   - Enter the path to your CSV file on the server
   - CSV must contain columns named: `eigenvalue_1`, `eigenvalue_2`, `eigenvalue_3`
   - Optional: metadata columns for color coding (e.g., `species`, `region`)

2. **Plot Configuration:**
   - **Plot Title:** Set a descriptive title for your visualization
   - **Color By:** (Optional) Specify a metadata column for color coding
   - **Width/Height:** Adjust plot dimensions in pixels (default: 1200×600)

3. **Generate Plot:**
   - Click "Generate Plot" to create the visualization
   - The plot will appear on the right side of the screen
   - Generation time will be displayed in the header

4. **Features:**
   - Loading indicator shows progress
   - Error messages display if something goes wrong
   - Responsive design works on tablets and mobile devices
   - Press Enter to quickly regenerate with new parameters

### Deployment Notes

For production deployment:
```bash
# Build release version
cargo build --bin web_gui --features plotting --release

# Run with environment variables
PORT=3000 ./target/release/web_gui

# For systemd service, create /etc/systemd/system/quadrix-web.service:
[Unit]
Description=Quadrix Web GUI
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/quadrix
ExecStart=/path/to/quadrix/target/release/web_gui
Restart=always

[Install]
WantedBy=multi-user.target
```

---

## Tauri Desktop Application

The Tauri desktop app provides a native application experience with better performance and offline capabilities.

### Features
- Native desktop application (Windows, macOS, Linux)
- Dark mode UI optimized for long sessions
- Interactive 3D viewer (coming soon)
- Data explorer (coming soon)
- File browsing integration
- Faster performance than web version
- Works offline

### Building the Desktop App

1. **Navigate to the Tauri app directory:**
   ```bash
   cd tauri-app
   ```

2. **Build for development:**
   ```bash
   cargo tauri dev
   ```

3. **Build for production:**
   ```bash
   cargo tauri build
   ```

   The built application will be in:
   - **Linux:** `src-tauri/target/release/bundle/`
   - **macOS:** `src-tauri/target/release/bundle/macos/`
   - **Windows:** `src-tauri/target/release/bundle/msi/`

### Usage

#### Hexplot Viewer (Active)

1. **Select Data Source:**
   - Click the folder icon to browse for a CSV file
   - Or manually enter the file path

2. **Configure Plot:**
   - Set your desired title
   - Optionally specify a metadata column for color coding
   - Adjust width and height as needed

3. **Generate:**
   - Click "Generate Plot"
   - A loading spinner will appear during generation
   - The plot will be displayed when ready

4. **Export:**
   - Once generated, use the Export button to save the plot

#### 3D Viewer (Coming Soon)

Future features:
- Interactive 3D visualization of dendritic structures
- Rotate, zoom, and pan controls
- Point size adjustment
- Connection visualization
- Real-time rendering

#### Data Explorer (Coming Soon)

Future features:
- Browse and search datasets
- View eigenvalue distributions
- Statistical summaries
- Data filtering and sorting

### Navigation

Use the sidebar to switch between different views:
- **Hexplot Viewer:** Generate and view hexagonal plots
- **3D Viewer:** Interactive 3D dendritic structure visualization (coming soon)
- **Data Explorer:** Browse and analyze datasets (coming soon)

### Development

To modify the Tauri app:

1. **Frontend (HTML/CSS/JS):**
   - Files are in `tauri-app/ui/`
   - `index.html` - Main structure
   - `styles.css` - Styling and theme
   - `app.js` - JavaScript logic and Tauri API calls

2. **Backend (Rust):**
   - Files are in `tauri-app/src-tauri/src/`
   - `main.rs` - Tauri commands and application setup
   - `lib.rs` - Library exports

3. **Configuration:**
   - `tauri-app/src-tauri/tauri.conf.json` - App configuration
   - `tauri-app/src-tauri/Cargo.toml` - Rust dependencies

4. **Hot Reload:**
   ```bash
   cd tauri-app
   cargo tauri dev
   ```
   Changes to frontend files will hot-reload automatically.
   Changes to Rust files require a restart.

---

## Feature Comparison

| Feature | Web GUI | Desktop App |
|---------|---------|-------------|
| Installation | None (Browser) | Required |
| Platform | Any with browser | Windows/macOS/Linux |
| Performance | Good | Excellent |
| Offline Support | No | Yes |
| Multi-user | Yes | No |
| File Browsing | Server paths only | Native file picker |
| 3D Visualization | Planned | Planned |
| Auto-updates | Immediate | App updates needed |
| Resource Usage | Low (server-side) | Medium (local) |

---

## Troubleshooting

### Web GUI Issues

**Problem:** Cannot connect to server
- Ensure the web_gui process is running
- Check firewall settings
- Verify the correct port (default: 3000)

**Problem:** Plot generation fails
- Verify CSV file path is accessible to the server
- Check CSV file format (should have L1, L2, L3 eigenvalue columns)
- Look at server logs for detailed error messages

**Problem:** Slow plot generation
- Large datasets take longer to process
- Consider reducing plot dimensions
- Ensure server has adequate resources

### Desktop App Issues

**Problem:** App won't build
```bash
# Ensure Tauri CLI is installed
cargo install tauri-cli

# Check that all dependencies are available
cd tauri-app/src-tauri
cargo check
```

**Problem:** File picker not working
- Currently file picker requires manual path entry
- To add file picker support, install tauri-plugin-dialog:
  ```bash
  cd tauri-app/src-tauri
  cargo add tauri-plugin-dialog
  ```

**Problem:** Plot not displaying
- Check the browser console for errors (F12)
- Verify the CSV file is accessible
- Ensure the file path uses forward slashes or proper escaping

**Problem:** Application crashes on startup
- Check Rust version: `rustc --version` (should be 1.70+)
- Rebuild dependencies: `cargo clean && cargo tauri build`
- Check system requirements for your platform

### General Issues

**Problem:** CSV format errors
- **Required columns:** `eigenvalue_1`, `eigenvalue_2`, `eigenvalue_3` (exact names)
- Ensure CSV has proper headers in the first row
- Values should be floating-point numbers
- Use UTF-8 encoding
- Remove any special characters from file path
- See `data/test_eigenvalues.csv` for example format

**Problem:** Memory issues with large datasets
- Consider processing datasets in batches
- Reduce plot resolution
- Close other applications to free up RAM

---

## Additional Resources

- **Main README:** See `README.md` for library usage and API documentation
- **Rust Documentation:** Run `cargo doc --open` for detailed API docs
- **Tauri Documentation:** https://tauri.app/
- **Reporting Issues:** https://github.com/your-repo/issues (update with actual URL)

---

## Future Enhancements

### Planned Features

**Web GUI:**
- [ ] WebSocket support for real-time updates
- [ ] File upload functionality
- [ ] Session management and caching
- [ ] Multiple plot comparison view
- [ ] Export to various formats (SVG, PDF)
- [ ] Interactive Plotly.js integration

**Desktop App:**
- [ ] Complete 3D viewer with Three.js
- [ ] Data explorer with filtering
- [ ] Batch processing mode
- [ ] Preferences and settings panel
- [ ] Recent files list
- [ ] Keyboard shortcuts
- [ ] Theme customization

### Contributing

To contribute to either application:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

---

## License

Private - All rights reserved

For questions or support, contact the repository owner.
