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.
- 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.
- **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, reciprocal-space
  viewer, 2D azimuthal-integration image, calibration-image viewer and a magnifier; plus the
  *Inspector* (per-image statistics, image features, resolution rings, ROI statistics), the
  *Image strip* thumbnail feed and dataset-info charts.
- 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.
- Layout presets (*View ▸ Image layout / Processing layout / Reset layout*) rearrange the docks for
  looking at images or at processing results.

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

## Opening data

- **File ▸ Open** (`Ctrl+O`) — open a local HDF5 file.
- **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.h5>` 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.

## 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.
- zlib and Eigen — the two libraries not auto-fetched on Windows. Build/install both into one prefix
  (here `C:\deps`) and point CMake at it:
  ```
  :: static zlib
  git clone --branch v1.3.1 https://github.com/madler/zlib
  cmake -G Ninja -S zlib -B zlib-build -DCMAKE_INSTALL_PREFIX=C:/deps
  cmake --build zlib-build --target install
  :: Eigen 3.4 (header-only) -- install just the headers with `cmake --install`; the BLAS/LAPACK/test
  :: targets are disabled since they are not needed (and fail to build under MSVC). Use the 3.4 series:
  :: the project requests find_package(Eigen3 3.4), which Eigen's same-major rule rejects for 5.x.
  git clone --branch 3.4.0 https://gitlab.com/libeigen/eigen.git
  cmake -G Ninja -S eigen -B eigen-build -DCMAKE_INSTALL_PREFIX=C:/deps ^
    -DEIGEN_BUILD_BLAS=OFF -DEIGEN_BUILD_LAPACK=OFF -DEIGEN_BUILD_DOC=OFF -DBUILD_TESTING=OFF
  cmake --install eigen-build
  ```
- 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:/deps;C:/Qt/6.11.1/msvc2022_64"
cmake --build build-win --target jfjoch_viewer
```

Notes:

- `CMAKE_PREFIX_PATH` (the `C:/deps` prefix plus Qt) is the only required flag — CMake finds zlib and
  Eigen from the prefix, so no separate `-DZLIB_ROOT` is needed.
- 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`, the analysis CLIs,
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).