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

Where it fits among the three analysis tools

Tool	Mode	Driven by	Output
jfjoch_broker	Online, real-time streaming analysis on FPGA + GPU	HTTP/REST + ZeroMQ	Live results and statistics, images streamed to jfjoch_writer
jfjoch_viewer	Interactive, on-screen exploration	Qt desktop application	Displayed on screen (results not saved to disk)
jfjoch_process	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 (*_master.h5) and the *_process.h5 files produced by jfjoch_process. 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 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.