leonarski_f
dd67cffde6
The changelog section had grown to 22 entries written from the commits
rather than for a user. Collapsed to 13, each saying what is gained
before what changed, with related work merged - the six anisotropy
entries into one, five space-group entries into two, five
integration-radius entries into one - and four things added that had no
entry at all: the packaging split, the statically linked cuFFT, the Ceres
back-end drop and REPORT_VERSION reaching 3.
CPU_DATA_ANALYSIS gains 9.5, the adaptive integration radius: the r80
measurement, the clamp, the constant-ring-area r3, the convergence test,
why it applies to the final pass only and the density fallback. Three
passages there had gone stale against the code: 13.1 still described the
I/sigma quantile fallback that b90fcfb98 deleted, and 13.5 said the gate
tests delta_B when it tests delta_B_linear and that the high-symmetry
caution fires wherever the Laue class leaves one free direction, which
0da593b32 narrowed.
RUGNUX gains an Installation section - there was no page anywhere saying
where rugnux comes from - a synopsis, a worked first run naming the files
that actually appear and the report keys to grep, and sections on the
unmerged export and on diffraction anisotropy. Its report section list
was one section behind: anisotropy is 9, warnings is 10.
The packaging change reached further than the changelog implied, so the
pages describing what a release ships were corrected too: the viewer
tarball no longer carries rugnux or the two developer utilities, the
Linux archives link cuFFT statically rather than shipping it beside the
binary under an $ORIGIN rpath, the aarch64 archive has a higher glibc
floor than the RHEL 8 ones and is untested on hardware, the archives
unpack with no top-level directory, and the notices live per package
under share/doc/jfjoch_<component>. The RHEL 9.5 vm_flags workaround in
FPGA_PCIE_DRIVER is obsolete and now says so.
162 lines
10 KiB
Markdown
162 lines
10 KiB
Markdown
# 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` 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).
|