Serial XFEL stills inputs: readers from the files themselves, module geometry and its refinement

Combines the stills reader and module work (stills-readers, stills-modgeom, stills-euxfel) onto
rc178 with the owner's decisions for this release:

- Inputs are files, never a directory; several files of one format are one dataset (the multi-input
  CLI of the previous commit), so every reader takes an explicit list: JFJochXFELReader::ReadFiles,
  ReadCXI, ReadPanelTable and JFJochXTCReader::ReadFiles take std::vector<std::string>; ListFiles and
  xtc::CollectStreams are gone, CanRead* accept a regular file only.
- One HDF5 frame reader (JFJochCrystFELReader -> JFJochXFELReader) parameterised by what the file holds:
  per-shot groups or a 3D stack, a /metadata panel table (posx/posy/angle, pixel size, nominal camera
  length, pixel mask: as SACLA writes), a Cheetah CXI single panel (square frame; a tiled slab is
  refused with a message). At most 8 files open; every file checked against the first. Signed 32-bit
  decode, per-frame 3D masks, panels at their own coffset (from the EuXFEL work).
- Frames stored one chunk each are read the way the NXmx reader reads its images: only the chunk's
  place is asked of HDF5 under its lock (H5Dget_chunk_info_by_coord), the bytes are read through
  HDF5ImageSource::RawFile (positional, no lock) and decoded outside it - deflate(+shuffle) by zlib,
  bitshuffle/LZ4 (and zstd, plain LZ4) by CompressedImage's decoders. Bitshuffle/LZ4 used to go through
  HDF5's filter under the global lock, one frame at a time.
- LCLS-I XTC (Rayonix): wavelength from the beam record, pixel size from the Rayonix model and
  binning, only --detector-distance needed; damaged/compressed frames skipped, a truncated last event
  dropped; std::ifstream, no POSIX calls: builds with MSVC. No DIALS .expt support at all.
- CrystFEL .geom: module geometry only (panel ranges, fs/ss, corners, pixel size, coffset, data path)
  and optionally the camera length; everything else is ignored with a note in the log.
- --mask-good / --mask-bad <file>:<dataset>: a mask array in another HDF5 file, in the frames' stored
  layout (what a .geom's mask_file used to give).
- Gain measured on the background for panel-table and CXI input that states none (--gain overrides).
- Detector modules from explicit geometry only (DetectorModules: the reader's panels, an NXmx file with
  one NXdetector_module per module, or --module-geometry); never from the image. Spots and predictions
  are mapped through the modules, the image is not re-assembled.
- Module refinement in the stills bundle adjustment (Ceres; per-module shift and in-plane turn, gauge
  on mean shift/turn/scale and on the two tilt-like patterns when the tilt is refined; adopted only
  where it predicts held-out frames better). Applied for a foreign multi-panel detector (panel table,
  .geom panels); for a JUNGFRAU measured and reported only. Written to <prefix>_modules.h5 (NXmx
  NXdetector_module groups), read back with --module-geometry.
- A panel-table file's camera length is nominal: with a reference cell it is refined from the cell.
- Broker and writer output unchanged: masters keep the single NXdetector_module group, the start
  message carries no module list.

Tests: [CrystFELGeometry], JFJochXFELReader_*, JFJochXTCReader, [JFJochMultiReader], [CellPopulation],
SaturationCeiling_*, [DetectorModules], RefineGlobalGeometry_ModulePlacement, [reindex], Sublattice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015CeEGgpKdfkCTJb3YNMJcu

tests/CrystFELGeometryTest.cpp

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 
 #include <catch2/catch_all.hpp>
+#include <algorithm>
 #include <filesystem>
 #include <fstream>
 
@@ -19,19 +20,19 @@ std::string WriteGeom(const std::string &name, const std::string &text) {
 
 TEST_CASE("CrystFELGeometry_OldSyntax", "[CrystFELGeometry][portable]") {
     // One panel and whole-frame bad strips, global keys only: the old syntax.
-    const auto geom = crystfel::Read("../../tests/crystfel/jf4m.geom");
+    std::vector<std::string> ignored;
+    const auto geom = crystfel::Read("../../tests/crystfel/jf4m.geom", ignored);
     REQUIRE(geom.panels.size() == 1);
     CHECK(geom.panels[0].res == Catch::Approx(13333.3));
-    CHECK(geom.panels[0].clen == "0.075");
-    CHECK(geom.panels[0].adu_per_photon.value() == Catch::Approx(1.0));
-    CHECK(geom.photon_energy == "12400");
+    CHECK(geom.panels[0].clen->path.empty());
+    CHECK(geom.panels[0].clen->value == Catch::Approx(0.075));
     CHECK(geom.data == "/entry/data/data");
-    REQUIRE(!geom.bad.empty());
-    CHECK(geom.bad[0].panel.empty());
-    CHECK(!geom.bad[0].in_lab);
-    CHECK(geom.bad[0].min_fs == 1030);
-    CHECK(geom.bad[0].max_fs == 1037);
-    CHECK(geom.bad[0].max_ss == 2163);
+    // Only the module geometry is read: gain, photon energy, value flags and bad regions are ignored.
+    CHECK(!geom.panels[0].adu_per_photon.has_value());
+    CHECK(!geom.photon_energy.has_value());
+    CHECK(!geom.flag_lessthan.has_value());
+    CHECK(geom.bad.empty());
+    CHECK(std::find(ignored.begin(), ignored.end(), "photon_energy") != ignored.end());
 }
 
 TEST_CASE("CrystFELGeometry_Panels", "[CrystFELGeometry][portable]") {
@@ -51,8 +52,8 @@ q1/min_ss = 0
 q1/max_ss = 1023
 q1/fs = +0.000390x -1.000000y
 q1/ss = +1.000000x +0.000390y
-q1/corner_x = 32.9283
-q1/corner_y = 1033.68
+q1/corner_x = 25.5
+q1/corner_y = 1040.25
 q1/coffset = 0.000067
 q2/min_ss = 1024
 q2/max_ss = 2047
@@ -70,18 +71,20 @@ badbox/max_x = 10
 badbox/min_y = -5
 badbox/max_y = 5
 )");
-    const auto geom = crystfel::Read(path);
+    std::vector<std::string> ignored;
+    const auto geom = crystfel::Read(path, ignored);
     REQUIRE(geom.panels.size() == 2);
     const auto &q1 = geom.panels[0];
     CHECK(q1.name == "q1");
-    CHECK(q1.clen == "/LCLS/detector_1/EncoderValue");
+    CHECK(q1.clen->path == "/LCLS/detector_1/EncoderValue");
+    CHECK(q1.clen->scale == Catch::Approx(1e-3));
     CHECK(q1.coffset == Catch::Approx(0.000067));
-    CHECK(q1.adu_per_eV.value() == Catch::Approx(0.001));
+    CHECK(!q1.adu_per_eV.has_value());
     CHECK(q1.fs_x == Catch::Approx(0.00039));
     CHECK(q1.fs_y == Catch::Approx(-1.0));
     CHECK(q1.ss_x == Catch::Approx(1.0));
     CHECK(q1.ss_y == Catch::Approx(0.00039));
-    CHECK(q1.corner_y == Catch::Approx(1033.68));
+    CHECK(q1.corner_y == Catch::Approx(1040.25));
     CHECK(q1.max_ss == 1023);
 
     const auto &q2 = geom.panels[1];
@@ -89,17 +92,53 @@ badbox/max_y = 5
     CHECK(q2.fs_y == Catch::Approx(0.0));
     CHECK(q2.ss_y == Catch::Approx(1.0));
     CHECK(q2.min_ss == 1024);
-    CHECK(q2.adu_per_photon.value() == Catch::Approx(9.5));
+    CHECK(!q2.adu_per_photon.has_value());
     CHECK(q2.res == Catch::Approx(20000));
 
     CHECK(geom.data == "/%/data");
-    CHECK(geom.mask_file == "mask.h5");
-    CHECK(geom.mask_bad == 1);
-    REQUIRE(geom.bad.size() == 2);
-    CHECK(geom.bad[0].panel == "q1");
-    CHECK(geom.bad[0].max_fs == 4);
-    CHECK(geom.bad[1].in_lab);
-    CHECK(geom.bad[1].min_x == Catch::Approx(-10));
-    CHECK(geom.bad[1].max_y == Catch::Approx(5));
+    CHECK(geom.masks.empty());
+    CHECK(geom.bad.empty());
+    for (const std::string key: {"adu_per_eV", "photon_energy", "mask", "mask_file", "mask_good", "mask_bad",
+                                 "q2/adu_per_photon", "badq1/min_fs", "badbox/max_y"})
+        CHECK(std::find(ignored.begin(), ignored.end(), key) != ignored.end());
+    std::filesystem::remove(path);
+}
+
+TEST_CASE("CrystFELGeometry_UnitsAndRefusals", "[CrystFELGeometry][portable]") {
+    std::vector<std::string> ignored;
+    const auto path = WriteGeom("jfjoch_crystfel_geometry_units.geom", R"(
+clen = 70.5 mm
+photon_energy = 9.3 keV
+res = 10000
+mask0_data = /entry/mask
+mask0_badbits = 0x6
+p0/min_fs = 0
+p0/max_fs = 99
+p0/min_ss = 0
+p0/max_ss = 99
+p0/mask_edge_pixels = 2
+p0/no_index = false
+some_new_keyword = 1
+)");
+    const auto geom = crystfel::Read(path, ignored);
+    CHECK(geom.panels[0].clen->value == Catch::Approx(0.0705));
+    CHECK(!geom.photon_energy.has_value());
+    CHECK(geom.masks.empty());
+    CHECK(std::find(ignored.begin(), ignored.end(), "some_new_keyword") != ignored.end());
+    CHECK(std::find(ignored.begin(), ignored.end(), "p0/mask_edge_pixels") != ignored.end());
+
+    // A camera length is optional.
+    const auto no_clen = WriteGeom("jfjoch_crystfel_geometry_noclen.geom",
+                                   "res = 10000\np0/min_fs = 0\np0/max_fs = 9\np0/min_ss = 0\np0/max_ss = 9\n");
+    CHECK(!crystfel::Read(no_clen, ignored).panels[0].clen.has_value());
+    std::filesystem::remove(no_clen);
+
+    for (const std::string bad: {"p0/fs = +1.0x +0.1z", "dim1 = 0", "p0/data = /other", "detector_shift_x = /x"}) {
+        const auto p = WriteGeom("jfjoch_crystfel_geometry_refused.geom",
+                                 "clen = 0.1\nres = 10000\nphoton_energy = 9000\np0/min_fs = 0\np0/max_fs = 9\n"
+                                 "p0/min_ss = 0\np0/max_ss = 9\n" + bad + "\n");
+        CHECK_THROWS(crystfel::Read(p, ignored));
+        std::filesystem::remove(p);
+    }
     std::filesystem::remove(path);
 }