(xcclient)=

# User Interface Setup

If you haven't already, [download XCOMPUTE-CLIENT](https://xplicitcomputing.com/download.php). After installation, you will receive an email containing your XCOMPUTE-CLIENT fingerprint. You can also view your fingerprints in your [Account Profile](https://xplicitcomputing.com/account/profile.php).

## 1. Request Access

Unless connecting as a read-only guest (e.g., testing `xplicitcomputing.com`), send your fingerprint and email address to the administrator of the server host you wish to access. Once approved, the admin will add your endpoint to the server's `users.cfg`.

## 2. Launch & Login

### Starting the Application
- If installed via package manager, launch XCOMPUTE-CLIENT from your OS application menu.
- Alternatively, run from terminal: `xcompute-client` or `./path/to/xcompute-client`

Upon launch, `client.cfg` is loaded and the login window appears.

### Login Process
1. **Host Address**: Enter the server's DNS name (e.g., `xplicitcomputing.com`) or IPv4 address. If the server runs locally, use `localhost`.
2. **Port**: The default service port is `11235`. Leave blank to use the default.
3. **Credentials**: Enter your `email` and `fingerprint`. This is only required once per device/account.
4. **Directories**: Set default `input` and `output` paths for easy import/export operations. If unset, defaults to your home directory. Save the configuration.

> **Note**: Update speed depends on network bandwidth and latency between client and server.

## 3. Interface Overview

After successful login, `interface.cfg` is loaded for optional UX settings, and the main interface window appears as metadata and visuals buffer.

### Configuration Example (`interface.cfg`)
    startingTab=0
    dpi=100
    panSensitivity=50
    precision=3
    rotateSensitivity=50
    timeConstant=50
    zoomSensitivity=50
    groups=false
    loops=false
    surfaces=true
    volumes=true

The main display window is powered by Qt5. After connecting to XCOMPUTE-SERVER, the client buffers and renders server-side systems. Closing the window terminates the client connection, but simulations continue running server-side. Teammates can reconnect or load from saved states.

### Navigation & Widgets
- **System Tree**: Navigate hierarchically to work at varying levels of abstraction.
- **High-Speed Networks**: Result in faster metadata updates and smoother collaboration.

#### File Menu
Located at the top, provides core functionality:
- `File`: Import, Export, Save, Load, Load Directory
- `Settings`: Configure defaults for `compute.cfg` and `interface.cfg`
- `Assets`: Project resources and tools (in progress)
- `View`: Interface and scene controls
- `Help`: Documentation links and support contacts

Keyboard shortcuts are available; check menus for bindings.

#### Operating Tabs
Tabs filter tools and appearance based on the current context (what is selected or activated):
`Manage` | `Systems` | `Geometry` | `Physics` | `Conditions` | `Solver` | `Data` | `Visuals`

Often, workflows progresses left-to-right: define geometry → assign physics → set conditions → configure solver → analyze data.

#### Inspector Panel
The window showing context-specific information for the current context. Toggle visibility with `F1`. Can be docked to the left or right side of the interface.

## 4. File I/O

| Operation | Server Side | Client Side |
|-----------|-------------|-------------|
| **Input** | Load from host filesystem | Import from local machine |
| **Output** | Save to host filesystem | Export to local machine |

### Save & Load
- **Save**: Sends a command to the server to write system setup and state to the server's output directory (e.g., fast SSD).
- **Load**: Instructs the server to read files from its input directory. The client updates automatically once loaded.
- No file I/O occurs on the client filesystem during Save/Load; these are server-side operations.

### Import & Export
All file types can be imported/exported to maintain a single source of truth. Files reside on the server alongside their associated systems.

**Supported Neutral Formats:**
- Import: `stl`, `obj`, `msh`, `sdf`
- Export: `csv`, `vtu`, `stl`, `obj`, `msh`, `sdf`

**Native XC-Messages Formats:**
- `xcs`, `xcg`, `xco` (accessible via cross-language bindings)

### External Application Integration
Any file type can be associated with a shell command. By default, the OS uses `open` or `xdg-open`. Customize in `extensions.cfg`:

    vtu=paraview --special-options
    xcs=python3 -i path/to/concept_pb2.py
    xcg=python3 -i path/to/spatial_pb2.py
    xco=python3 -i path/to/vector_pb2.py
    py=python3 -i path/to/concept_pb2.py path/to/vector_pb2.py path/to/spatial_pb2.py

> Everything after `=` is executed as a shell command. No spaces are allowed around `=`, but spaces are permitted afterward.

## 5. Visualization & Rendering

The render scene uses an OpenGL context with a shader pipeline.

### Graphics Pipeline
Current implementation uses an explicit raster pipeline with two programmable stages:
`vertex.glsl` → `fragment.glsl`

### VAO Layered Processing
In-scene graphics are organized into Vertex Array Objects (VAOs) and rendered back-to-front:
- **Layer 0**: 3D physical space (metaobjects & metaregions)
- **Layers 1+**: 2D screen-space UX elements (HUD, text, tools)

### Metaobjects & Interaction
Most 3D objects are `metaobjects` composed of `metaregions`, representing server-side geometry. Transformations follow the standard `M-V-P` convention:
- `M` Model: Assigned server-side for metaobjects, client-side for UX elements.
- `V` View, `P` Projection: Managed client-side via the camera, optimized out for 2D.

**Interaction:**
- Click to select metaregions in prep for server-side operations.
- Double-click a metaregion to activate its parent metaobject.
- Double-click the background to navigate up one hierarchy level.
- Selection is currently limited to surfaces and faces.

### Camera Controls
- **Zoom**: Middle mouse wheel or multi-touch swipe
- **Rotate**: Hold middle mouse button, or `Ctrl` (Linux)
    - `⌘` + drag (macOS)

Press `R` to print render statistics to the console.

### Shader Customization
Advanced users can modify `shaders/vertex.glsl` and `shaders/fragment.glsl`. Press `Ctrl+R` (or `Cmd+R` on macOS) to dynamically reload shaders and the scene at runtime.

### Context Menu & XC Command Bar
- **Right-click**: Opens a context-driven menu (options depend on active tab/selection).
- **XC Button**: Enables a dynamic interpreter for manual/experimental commands.
  - `test`: Verify connectivity
  - `refresh`: Push latest metadata from server
  - `reload`: Load active system from server filesystem
  - `load users.cfg`: Update team roster on server
  - `cd <system_name>`: change directory

> Experimental Feature: XC CLI is in dev and will be documented upon ratification.

## 6. Troubleshooting

### Failed Authentication
**Cause**: Expired certificate, corrupt credentials, or unassigned MASH.  
**Fix**:
1. Clear keys/certs using the button in the Authentication Failure dialog.
2. Unassign the fingerprint in your [Account Profile](https://xplicitcomputing.com/account/profile.php).
3. Relaunch the application to request new credentials from XWS.

### Failed Login
Click the `Help` button on the login screen. Diagnostic dialogs will display error details and suggested actions.

### Runtime Errors

Logs are stored in `~/.local/state/xcompute/xcclient/log/`:

    # View logs
    ls -al ~/.local/state/xcompute/xcclient/log/xcclient-*.log
    # View errors
    ls -al ~/.local/state/xcompute/xcclient/log/xcclient-*.err
    # Open with text editor
    vi ~/.local/state/xcompute/xcclient/log/xcclient-VERSION.err