leonarski_fandClaude Opus 5
fb18457e6f
The rc.166 changelog was missing fourteen user-visible changes and carried rationale and measurements that belong here instead. Added: the native miniCBF sweep reader, the third-party and firmware-1.x NXmx masters, the plain LZ4 filter, the image orientation taken from the file's module direction vectors, the two beam-centre flags and their rescues, and the FFT reach past 500 A. Trimmed the rest to one line each, moving the numbers out of the user-facing file. RUGNUX.md described the input as a single Jungfraujoch master file, which it has not been since this branch; it now covers the foreign and legacy masters, the accepted compression filters and the miniCBF sweep, including how a sweep is collected from one named frame. Six options existed with no entry in the table - --beam-center-check, --beam-center-search, --fft-min-unit-cell, --min-indexed-spots, --rot3 and --no-p1-crosscheck - and -C now moves both FFT cell bounds, which was not written down anywhere. CPU_DATA_ANALYSIS.md carried two statements this branch made false: 7.5 still said pass 2 reuses pass 1's space group, and 13.1 still said centrings are ranked by net absence count. Both now describe what the code does - the group is determined after pass 2, and centrings are ranked by the same Beta-tail likelihood the screw test uses. Also documents the per-zone screw scoring, the coplanarity volume-fraction guard, the plane-normal transform, the FFT cell bounds and the twelve refined candidates. The miniCBF reader implements the x-CBF_BYTE_OFFSET scheme and reads the imgCIF axis table from the specification alone. No CBF code is vendored or linked, so there is no licence obligation, but reimplementing a published specification carries one of credit: ACKNOWLEDGEMENT.md gains a section and the two algorithms carry a one-line reference each. Both DOIs were resolved before being written. Rottger's initial was wrong where this branch first cited it - K, not A. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MxrrPcxodNiXzhNiECCVp5
173 lines
11 KiB
Markdown
173 lines
11 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.
|
|
- 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, 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.
|
|
- Mouse wheel on the diffraction image: **zoom** on its own, move the foreground with `Ctrl` or
|
|
`Shift`, and **step through the dataset one image per notch** with `Alt` (wheel up goes forward).
|
|
Some window managers grab `Alt`-modified mouse events before the application sees them; that is a
|
|
window-manager setting, not something the viewer can take back.
|
|
- 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, 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.
|
|
|
|
## 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).
|