Settings Tab
Overview
The Settings tab (SettingsPage.qml, route Settings) centralizes workstation paths, third-party pathology integrations (QuPath and Java 11+ Bio-Formats), memory budgets, diagnostic verbosity, desktop auto-updates, and server environment profiles (Mode 2, Mode 3 Production, Mode 4 Stage).
Step-by-Step Configuration Workflows
1. Application Paths, Logs Folder & Backups
- Default Projects Folder / Application Folder: Set or browse default storage directories (
Select default projects folder,Select application folder). - Desktop logs folder: Browse to customize where desktop log files write (
Default: application folder/logs), or clickClearto revert to default. - Backup & Restore: Configure a backup folder, click
Create Backupto export an archive (Backup created), or clickRestore Backupto recover saved application state.
2. QuPath & Java Runtime for Bio-Formats
- QuPath executable: Browse to the QuPath console executable and click
Save; Settings validates the binary and displays"Detected: <version>"(required for seamless QuPath bridge actions). - Java runtime for Bio-Formats: Java 11+ is required to open Bio-Formats whole-slide formats (including
.vsi). ChooseAuto-detect,Browseto a JDK/JRE folder +Save, or clickDownload Java 17(Eclipse Temurin JDK 17 for Windows x64).
3. Tune Memory Budgets & Logging Detail
- Memory budgets (MiB):
- Java heap (
512–32768 MiB) — clickSave; shows"Restart required"toast so the JVM initializes with the updated-Xmx. - Decoded tile cache (
64–2048 MiB) — clickSaveto resize the pyramidal WSI tile cache budget (restart required).
- Java heap (
- Logging detail: Toggle between
Standard (Errors only)(standard) andDetailed diagnostics(debug).
4. Updates & Environment / Backend Profile
- Application version & updates: Displays
Current version: vX.Y.ZwithCheck for updatesandDownload update. - Environment & Backend Profile: Select between:
- Mode 3: Production Endpoints (
apps/desktop/desktop_config.json) - Mode 4: Stage endpoints (displays
API:andIdentity:URLs; server-owned object storage) - Mode 2: Remote Worker / Cloudflare Endpoints & Credentials (optional
Cloudflare Access Client ID,Cloudflare Access Client Secret, andAdmin Bearer Token)
- Mode 3: Production Endpoints (
- Click
Test Connectionto probe the active orchestrator (Connected · Server release ...), andDetailsto inspectServer connection details(Server release,Backend code version, and configured worker variants).
flowchart TD
Profiles["Select Environment Profile (Mode 2 / Mode 3 Production / Mode 4 Stage)"] --> Test["Click Test Connection"]
Test -->|Success| Connected["Show Server Release ID & Details Modal"]
Test -->|Failure| Troubleshoot["Inspect URLs / TLS Truststore / Logs Tab"]Settings Controls Reference
| Section | Setting / Control | Allowed Values / Range | Restart Required? |
|---|---|---|---|
| Workspace | Application folder / Default projects folder | Writable local directory | No |
| Desktop logs folder | Custom logs directory (Browse / Clear) |
Default: <app folder>/logs |
No |
| Backup & Restore | Backup location, Create Backup, Restore Backup |
Local directory / backup archive | Recommend restart after restore |
| QuPath executable | Console executable path (Browse, Save, Clear) |
Validated QuPath CLI binary | No |
| Java runtime for Bio-Formats | JDK/JRE 11+ home (Browse, Save, Auto-detect, Download Java 17) |
Java 11+ (Temurin JDK 17 recommended) | Required for active Bio-Formats JVM |
| Memory budgets (MiB) | Java heap |
512–32768 MiB |
Yes |
| Memory budgets (MiB) | Decoded tile cache |
64–2048 MiB |
Yes |
| Logging detail | Verbosity selector | Standard (Errors only) or Detailed diagnostics |
Immediate |
| Application version & updates | Check for updates, Download update |
Release manifest match | Yes to apply update |
| Environment & Backend Profile | Mode 2 / Mode 3 / Mode 4 selector, Test Connection, Details |
Profile-specific API + Identity + optional Mode 2 headers | Re-auth on profile switch |
Technical Reference
- Mode Separation: Switching between Mode 2, Mode 3 Production, and Mode 4 Stage swaps server origins, OIDC identity endpoints, and server-release expectations cleanly without mixing tokens or persistent volumes.
- On-Mount Probing: Opening
SettingstriggersrefreshQuPathInstallation()andrefreshJavaRuntime()to verify external binary availability automatically.