Jungfraujoch/docs/JFJOCH_VIEWER.md

# jfjoch_viewer

`jfjoch_viewer` is the **interactive** desktop application of Jungfraujoch. It opens diffraction
datasets, displays each image together with the analysis overlay (spots, predictions, azimuthal
integration, per-image statistics), and can follow a live data collection by syncing with a
running [`jfjoch_broker`](JFJOCH_BROKER.md) over its HTTP interface.

It is a standalone Qt 6 application, distributed pre-built for **Linux and Windows** on the Gitea
release page and in the Jungfraujoch RPM/APT repositories — see [Release contents](RELEASE_CONTENTS.md)
for what each package contains and what it requires, and [Deployment](DEPLOYMENT.md) for how to
install it.

## Where it fits among the three analysis tools

| Tool | Mode | Driven by | Output |
| --- | --- | --- | --- |
| [`jfjoch_broker`](JFJOCH_BROKER.md) | Online, real-time streaming analysis on FPGA + GPU | HTTP/REST + ZeroMQ | Live results and statistics, images streamed to [`jfjoch_writer`](JFJOCH_WRITER.md) |
| **`jfjoch_viewer`** | **Interactive, on-screen exploration** | **Qt desktop application** | **On screen; a processing job can write the same files as `rugnux`** |
| [`rugnux`](RUGNUX.md) | Offline batch processing of a stored dataset | Command-line interface | `_process.h5`, and `.mtz`/`.cif`/`.hkl` when merging |

## Functionality

- Opens HDF5 files written by [`jfjoch_writer`](JFJOCH_WRITER.md) (`*_master.h5`) and the
  `*_process.h5` files produced by [`rugnux`](RUGNUX.md). It also opens NXmx files
  written by DECTRIS detectors, though that path has had only limited testing.
- Opens PILATUS miniCBF rotation sweeps. These store one frame per file, so naming any frame opens
  the whole sweep it belongs to. A raw CBF carries the images and the geometry but no analysis
  results, so the spot, reflection and per-image plot panels stay empty until something is computed.
- Runs an **embedded data-processing pipeline** — the same analysis code as the rest of
  Jungfraujoch — performing spot finding, indexing and integration on the displayed image, with the
  result drawn over it. This interactive analysis is not written anywhere.
- Runs **full processing jobs** on the open dataset with *Analyze dataset*, on the same
  [`rugnux`](RUGNUX.md) engine and off the GUI thread. The settings panel's **MX / AzInt / Calib**
  toggle decides what a run does — full analysis, azimuthal integration only, or a detector
  calibration — over a chosen image range, optionally writing `_process.h5` and the merged
  `.mtz`/`.cif`. A finished run becomes a selectable view of the dataset, so several processing runs
  can be compared against each other, and its merging statistics (or, for a calibration, its fitted
  geometry) open in their own window; the *Processing* panel lists the runs and reopens those
  results. The equivalent `rugnux` command line can also be copied out to run the same job on a
  cluster instead.
- **Detector calibration** against a powder standard, on the *Calib* page: pick the calibrant
  (`LaB6`, `AgBh`, `CeO2`, `Si`, `ice`, or the open dataset's own unit cell) and fit either the image
  on screen (*Guess* / *Refine detector calibration*) or the whole dataset (*Analyze dataset*, which
  writes a pyFAI `<output prefix>.poni`). The whole-dataset fit measures the rings either from the
  azimuthally-binned profile summed over the run (*Rings*, the default) or from the pooled spot lists
  (*Spots*), and reports PONI x/y, the two tilts and the distance against the header values. Judge it
  by the **radial rms**, not the beam-centre sigma: the sigma shrinks with the number of ring points,
  so a fit that sits a couple of pixels off every ring can still report a small one. *Rings* needs
  the run to be integrated in azimuthal sectors — with the AzInt page's *Azimuthal bins* below 4 the
  calibration run raises it to 32, as `rugnux --mode calibration` does, and says so.
  *Refine detector tilt* is ticked by default and fits the two tilts along with the centre and the
  distance; unticking it holds them where they are, for a calibration meant for a program that
  cannot express a tilted detector (`rugnux --no-refine-tilt`). It applies to both buttons and to
  *Analyze dataset*.
- **Settings** panel for the geometry, unit cell, spot finding, indexing, azimuthal integration,
  Bragg integration, scaling, powder calibration and a reference dataset — the same settings the
  CLI takes.
- Auxiliary windows: image list, dataset metadata, spot list, reflection list,
  2D azimuthal-integration image, calibration-image viewer and a magnifier; plus the
  *Inspector* (per-image statistics, image features, resolution rings, ROI statistics) and
  dataset-info charts.
- The *Inspector*'s **Image features** section decides what the overlay draws — spots, predictions,
  saturated and highest pixels, the beam stop — including whether the non-indexed spots and the
  spots that fall on an ice ring are drawn at all.
- User-mask editing: build a user mask interactively, load one from TIFF (replacing or adding to the
  current one), save it as TIFF, clear it, or upload it to a connected server.
- Mouse-driven navigation of the image, the grid scan and the plots — see
  [Mouse shortcuts](#mouse-shortcuts) below, which the viewer also shows under *Help ▸ Mouse
  Shortcuts*.
- *Help* shows the mouse shortcuts, the [acknowledgements](ACKNOWLEDGEMENT.md) and the third-party
  licenses.
- Layout presets (*View ▸ Image layout / Processing layout / Reset layout*) rearrange the docks for
  looking at images or at processing results.
- *View ▸ Font size* (or `Ctrl`+`+` / `Ctrl`+`-`) enlarges the text to 125 % or 150 %, on top of
  whatever scaling the desktop already applies, and the choice is remembered across restarts. The
  viewer also follows the desktop's own text scaling or display scaling on its own; over `ssh -X`,
  where no settings daemon delivers it, launch as `QT_SCALE_FACTOR=1.5 jfjoch_viewer` instead.

## Hardware

As with the rest of Jungfraujoch, **serious performance requires an NVIDIA GPU**. On systems with a
GPU, use the CUDA build (a separate package variant everywhere: RPM/APT repository, `.tgz` and
Windows installer) for the embedded indexing and integration; the non-CUDA build runs the same
pipeline on the CPU at much lower throughput. The CUDA build also runs on a machine without a GPU —
see [Release contents ▸ CUDA and non-CUDA builds](RELEASE_CONTENTS.md#cuda-and-non-cuda-builds).

The CUDA build needs an NVIDIA **driver** on the host but no CUDA toolkit — 525.60.13 or newer for
the CUDA 12 artefacts (RHEL 8 packages, portable Linux `.tgz`), 580.65.06 or newer on Linux and an
R580 driver on Windows for the CUDA 13 ones (RHEL 9, Ubuntu, Windows installer). The Windows
installer and the `.tgz` are CUDA 13 and CUDA 12 respectively, which also decides the oldest GPU
they run on — a V100 needs the CUDA 12 `.tgz`. See
[Release contents ▸ GPU generations and the NVIDIA driver](RELEASE_CONTENTS.md#gpu-generations-and-the-nvidia-driver).

### Remote displays

The viewer detects a remote display session (`ssh -X` and the like) and limits how often panning,
zooming and live playback repaint, since on such a link every repaint is shipped as pixels. The
detection can be overridden in *View ▸ Remote display mode* or with `JFJOCH_VIEWER_REMOTE=0`/`1`.
A VNC- or xpra-based remote desktop still transports the viewer far more efficiently than plain
X11 forwarding.

## Mouse shortcuts

The same list is available in the application under **Help ▸ Mouse Shortcuts**.

### Diffraction image

| Action | Effect |
| --- | --- |
| Wheel | Zoom in / out, centred on the cursor |
| `Shift` + wheel | Move the foreground (upper contrast limit) in linear steps |
| `Ctrl` + wheel | Move the foreground in multiplicative steps (×1.15 per notch) |
| `F` held + wheel | Same as `Shift` + wheel, for as long as `F` is held |
| `A` | Apply auto-contrast once; press it again to switch on continuous Auto |
| `Home` / `End` | Jump to the first / last image in the dataset |
| `Page Up` / `Page Down` | Step one image forward / back |
| Hover | Status bar shows the pixel position, its value and the resolution |
| Drag | Pan the image |
| `Shift` + drag | Draw a rectangular ROI |
| `Shift` + `Ctrl` + drag | Draw a circular ROI |
| Drag an ROI or its handle | Move or resize the selected ROI |
| Right click | Copy / save the image, fit to view, clear the ROI |

### Grid scan

| Action | Effect |
| --- | --- |
| Hover | Status bar shows the image number, the grid position and its value |
| `Shift` + hover | Load the image under the cursor while moving over the grid |
| Double click | Load the image under the cursor |

### Other views

| Action | Effect |
| --- | --- |
| 2D azimuthal image: double click | Zoom the diffraction image on the corresponding detector position |
| Dataset-info plot: hover | Status bar shows the image number and the plotted value |
| Dataset-info plot: `Shift` + hover | Load the hovered image |
| Spot / reflection list: double click | Zoom the diffraction image on that spot or prediction |
| Image list: double click | Load that image |
| Magnifier: wheel | Zoom the magnifier; it follows the cursor on the main image |

## Opening data

- **File ▸ Open** (`Ctrl+O`) — open a local HDF5 file, or any frame of a miniCBF sweep.
- **File ▸ Open HTTP** (`Ctrl+H`) — connect to a `jfjoch_broker` HTTP endpoint to follow a live
  collection. The dialog defaults to host `localhost` and port `8080`; these defaults can be
  overridden with the environment variables `JUNGFRAUJOCH_HTTP_HOST` and `JUNGFRAUJOCH_HTTP_PORT`.
- **Command line** — `jfjoch_viewer <file>` opens a file (or an `http://host:port` URL) on
  start-up. `--dbus <true|false>` (`-d`) enables or disables the D-Bus interface (default: enabled);
  `--help` and `--version` behave as usual.

## D-Bus interface

When enabled, the viewer registers the D-Bus interface `ch.psi.jfjoch_viewer`, so other processes
can drive it:

- `LoadFile(filename, image_number=0, summation=1)` — open a file (or an `http://host:port` URL)
  and display the given image.
- `LoadImage(image_number, summation=1)` — navigate to an image in the already-open dataset.

`summation` sums that many consecutive images before display. A repeated `LoadFile` call naming the
file that is already open is cheap (it just navigates, like `LoadImage`) rather than reopening it,
but a client stepping through images of a dataset it opened itself should still prefer `LoadImage` —
it needs no filename and avoids the file-identity comparison.

## Building from source on Windows

`jfjoch_viewer` is the one Jungfraujoch component that is cross-platform: it builds on Windows 11
with MSVC and the full CUDA GPU path. (The rest of Jungfraujoch — broker, receiver, FPGA host — is
Linux-only.) A pre-built installer is published with every release, so building from source is only
needed to develop or to change the build options. On Windows the build is automatically restricted
to the viewer and the libraries it needs (`JFJOCH_VIEWER_ONLY` is forced on), and the remaining
dependencies are fetched and built automatically (the first configure needs network access).

Verified toolchain — the same one the released installer is built with:

- Windows 11
- Visual Studio 2026 with the C++ (MSVC) toolset — required; CUDA on Windows builds through MSVC
- CUDA Toolkit 13.3 (12.8 or newer is required) — for the GPU indexing/integration path
- Qt 6.11 for MSVC (`msvc2022_64`), including the **Qt Charts** module — e.g. `C:\Qt\6.11.1\msvc2022_64`
- CMake plus Ninja. The CMake that ships with Visual Studio is the simplest choice and works out of
  the box — it comes with the C++ workload, so there is nothing extra to install. Any recent
  standalone CMake (from cmake.org, or the one bundled with Qt in `C:\Qt\Tools\CMake_64`) works too.
- Optional: [NSIS](https://nsis.sourceforge.io) to build the `.exe` installer.

Configure and build from an **x64 Native Tools Command Prompt for VS 2026** (so `cl`, `nvcc` and
`ninja` are on `PATH`):

```
cmake -G Ninja -B build-win -DCMAKE_BUILD_TYPE=Release ^
  -DCMAKE_PREFIX_PATH="C:/Qt/6.11.1/msvc2022_64"
cmake --build build-win --target jfjoch_viewer
```

Notes:

- `CMAKE_PREFIX_PATH` (Qt) is the only required flag. Every other dependency, zlib and Eigen
  included, is downloaded and built by the configure itself, so nothing else has to be installed.
- The CUDA toolchain is located automatically from the `CUDA_PATH` environment variable that the
  CUDA installer sets (or from `nvcc` on `PATH`). Pass `-DCMAKE_CUDA_COMPILER=".../bin/nvcc.exe"`
  only if `nvcc` is installed in a nonstandard location and is not found.
- For a machine without an NVIDIA GPU, add `-DJFJOCH_USE_CUDA=OFF`: the viewer then runs the same
  pipeline on the CPU (FFTW indexer) at lower throughput.

To produce a self-contained installer (bundles the Qt runtime via `windeployqt` and — on the CUDA
build — the cuFFT runtime DLL, so the target host needs neither Qt nor a CUDA toolkit), with NSIS
installed:

```
cd build-win
cpack
```

The NSIS generator is selected automatically on Windows (no `-G` needed). What comes out, and how
the CUDA and CPU variants are named and told apart, is described in
[Release contents ▸ Windows installer](RELEASE_CONTENTS.md#windows-installer).