Architecture

High-level view of TomoGUI internals for developers and contributors.

Packages

tomogui (src/tomogui/)

Main GUI package. The TomoGUI class in gui.py is the PyQt5 QWidget that assembles every tab.

tomogui._infer_worker

Standalone CLI worker. Takes a data folder, model path, and one file per invocation (it also accepts a list of files, unused by the current GUI); runs DINOv2 inference on that file’s try_center TIFFs and writes center_of_rotation.txt.

tomogui._tomocor_infer

Bundled copy of the tomocor inference code (inference.py, model_archs.py, _utils.py) so TomoGUI can run AI Reco without requiring tomocor separately.

Layering

┌──────────────────────────────────────────┐
│          PyQt5 GUI (gui.py)              │
│  Main / Batch / HDF5 Viewer / Advanced   │
└──────────────────────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────┐
│    Subprocess dispatch (local / SSH)     │
│   TomoCuPy • _infer_worker • tomolog     │
└──────────────────────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────┐
│  Torch / DINOv2 • CUDA • HDF5 / TIFF IO  │
└──────────────────────────────────────────┘

Key subsystems

Unified batch queue

_run_batch_with_queue(files, recon_type, num_gpus, machine) is the single entry point for all parallel batch dispatch. recon_type is 'try', 'full', or 'infer'; the only per-type variation is inside _start_batch_job_async, which builds the appropriate subprocess command (tomocupy … vs python -m tomogui._infer_worker …). Polling uses QApplication.processEvents() rather than blocking QThread waits so the GUI stays responsive.

AI Reco pipeline

_batch_run_ai_selected orchestrates four phases, each a call to _run_batch_with_queue (Phase D is a sequential loop instead):

  • A — try reconstructions.

  • B — infer (one file per GPU slot). _on_infer_output parses [infer-worker] OK <path> => <cor> lines and updates the row’s COR input live. On clean exit the completion handler in _run_batch_with_queue also reads center_of_rotation.txt as a fallback.

  • C — full reconstructions on files whose Phase B produced a COR.

  • D (optional, gated by the ``batch_ai_upload_tomolog`` checkbox) — sequential _run_tomolog_for_file calls for every file whose Full completed successfully.

Fix COR Outliers

Pure-Python routine in gui.py (_fix_cor_outliers). Two passes on one click:

  1. Group selected rows by filename series (^(.*?)[._-]*(\d+)$). Within each series, compute median and MAD; flag deviations greater than min(max_delta, max(10, 5·MAD)); replace flagged values with the average of the two nearest non-flagged neighbours by index.

  2. Fill any still-empty selected rows with the mean of CORs in their series across the whole table (donor rows can be unchecked).

Per-dataset parameter persistence

Every reconstruction parameter tab writes its state to a JSON sidecar next to the projection HDF5 file. Selecting the file reloads that sidecar; Apply parameters to selected copies the sidecar to other rows.

See API Reference for a curated API overview.