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 on the Gitea release page and in the
Jungfraujoch RPM/APT repositories (see [Deployment](DEPLOYMENT.md)).

## 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** | **Displayed on screen (results not saved to disk)** |
| [`jfjoch_process`](JFJOCH_PROCESS.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 [`jfjoch_process`](JFJOCH_PROCESS.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 images.
  Results are shown on screen but are **not** saved to disk.
- Auxiliary windows and panels: image list, image metadata, spot list, reflection list,
  per-region-of-interest statistics, the azimuthal-integration profile, and dataset-info charts.
- User-mask editing: build a user mask interactively, clear it, save it as TIFF, or upload it to a
  connected server.

## Hardware

As with the rest of Jungfraujoch, **serious performance requires an NVIDIA GPU**. On systems with a
GPU, use the CUDA build (provided as separate RPM/APT repositories) for the embedded indexing and
integration; the non-CUDA build runs the same pipeline on the CPU at much lower throughput.

## 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.) There is no pre-built Windows package yet, so build it from source. 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:

- 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 no Qt and no CUDA toolkit,
only an NVIDIA GPU driver), with NSIS installed:

```
cd build-win
cpack
```

The NSIS generator is selected automatically on Windows (no `-G` needed). The installer filename and
the Add/Remove Programs entry mark the CUDA/CPU variant, while the install folder and Start Menu
group stay plain `Jungfraujoch` (the two variants share an install location and replace each other —
CUDA is a strict superset):

| Build | Installer file | Add/Remove Programs |
| --- | --- | --- |
| CUDA (default) | `jfjoch-<version>-win64-cuda<major>.exe` | `Jungfraujoch (CUDA)` |
| `-DJFJOCH_USE_CUDA=OFF` | `jfjoch-<version>-win64-cpu.exe` | `Jungfraujoch (CPU)` |

`<major>` is the CUDA toolkit major version (e.g. `cuda13`). The cuFFT DLL is ~256 MB, so the CUDA
installer is correspondingly larger — hence the variant tag in the filename.