Skip to content

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).

Settings view displaying workspace folders, Backup & Restore, QuPath/Java Bio-Formats setup, memory sliders/inputs, logging level, updates, and backend profile controls.

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 click Clear to revert to default.
  • Backup & Restore: Configure a backup folder, click Create Backup to export an archive (Backup created), or click Restore Backup to 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). Choose Auto-detect, Browse to a JDK/JRE folder + Save, or click Download Java 17 (Eclipse Temurin JDK 17 for Windows x64).

3. Tune Memory Budgets & Logging Detail

  • Memory budgets (MiB):
    • Java heap (512–32768 MiB) — click Save; shows "Restart required" toast so the JVM initializes with the updated -Xmx.
    • Decoded tile cache (64–2048 MiB) — click Save to resize the pyramidal WSI tile cache budget (restart required).
  • Logging detail: Toggle between Standard (Errors only) (standard) and Detailed diagnostics (debug).

4. Updates & Environment / Backend Profile

  • Application version & updates: Displays Current version: vX.Y.Z with Check for updates and Download update.
  • Environment & Backend Profile: Select between:
    • Mode 3: Production Endpoints (apps/desktop/desktop_config.json)
    • Mode 4: Stage endpoints (displays API: and Identity: URLs; server-owned object storage)
    • Mode 2: Remote Worker / Cloudflare Endpoints & Credentials (optional Cloudflare Access Client ID, Cloudflare Access Client Secret, and Admin Bearer Token)
  • Click Test Connection to probe the active orchestrator (Connected · Server release ...), and Details to inspect Server 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 Settings triggers refreshQuPathInstallation() and refreshJavaRuntime() to verify external binary availability automatically.