Skip to main content

spam-gui

Graphical modules for spam (Software for the Practical Analysis of Materials), in a napari viewer.

The first module is the multimodal registration (MMR): it registers two 3D images of the same sample acquired with different modalities (e.g., x-rays and neutrons). The registration itself is spam's; spam-gui guides you through it, step by step:

  1. Load images (at a chosen binning, reusing the eye registration, crop and MMR registration of a coarser one). The two images can have different sizes: image 1 is shown on the voxels of image 2, the reference, centre on centre, and everything is done on image 2's voxels
  2. Eye registration (pairs of points). It carries the scale too, if the voxel sizes differ (« Zoom »: e.g., 2 for voxels of image 1 twice as large): Phi then takes image 1 about its centre to image 2 about its centre, with that scale
  3. Crop
  4. Joint histogram, in three panes: grey level mapping (the grey levels of each image spread over the bins); bin and peak selection (the bins, how the peaks are found, « Compute histogram »); the joint histogram with its peaks to tick (fitted by Gaussians). It is seen from above, or as a 3D surface in an isometric view rotated about its vertical axis with a slider
  5. Phase diagram
  6. MMR registration

plus a Summary, available at any time.

The second module is the eye registration (as spam's spam-ereg): 1. Load images › 2. Eye registration › 3. Save (Φ in spam's registration file, at this binning and for the original images; image 1 moved, as a TIFF). Its steps 1 and 2 are those of the multimodal registration, and what is done in them is shared: images loaded and registered by eye in one module are in use in the other (switching module with the module button, top left).

Install

spam-gui is installed from PyPI (pip install spam-gui), in a virtual environment as spam is. Installing it also installs spam (0.9.1 or later, as released: nothing in spam needs changing), napari and PyQt6 (Qt 6). It needs Python 3.10 or later. The commands below are for Ubuntu or Debian (and WSL).

spam is a dependency of spam-gui: pip installs it, so it is not installed on its own. Only the system libraries that pip cannot install come from apt: those spam needs, those of napari's window (Qt's display libraries), and git. apt installs only those missing: on an Ubuntu desktop, most are already there.

To use it

# install minimal system deps
sudo apt install python3-venv git libglu1-mesa libxcursor1 libxft2 libxinerama1 libgomp1 libgl1 libglib2.0-0 libdbus-1-3 \
    libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-shape0 libxcb-xinerama0 libxcb-cursor0
# Create a virtual environment (or skip this line to install spam-gui in an existing spam-venv)
/usr/bin/python3 -m venv spam-venv
# Activate your virtual environment
source spam-venv/bin/activate
# update python package manager
pip install -U pip
# install spam-gui (and with it spam, napari and PyQt6)
pip install spam-gui

Until its first release on PyPI, the last line is pip install "git+https://gitlab.com/spam-project/spam-gui.git" (the code as it is on GitLab).

To update it later, in the activated environment: pip install -U spam-gui. The version installed: spam-gui --version.

spam-gui used Qt 5 (PyQt5) before it moved to Qt 6: an environment installed then still has PyQt5, which napari would pick, and fail (« napari requires Qt >= 6.7.0, but PyQt5 … was imported »). Once, before the update above, replace it (and install libxcb-cursor0 with apt):

pip uninstall -y PyQt5 PyQt5-Qt5 PyQt5-sip
pip install -U "napari[pyqt6]"

To develop it (e.g., to write a new module)

The code is cloned, and installed in editable mode (it follows the code as it is edited), with the tools to test it and build it:

# install minimal system deps, and xvfb (a virtual screen: the window test and screenshots at any screen size, unseen)
sudo apt install python3-venv git libglu1-mesa libxcursor1 libxft2 libxinerama1 libgomp1 libgl1 libglib2.0-0 libdbus-1-3 \
    libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-shape0 libxcb-xinerama0 libxcb-cursor0 \
    xvfb
# Create a virtual environment (next to the code, not in it)
/usr/bin/python3 -m venv spam-venv
# Activate your virtual environment
source spam-venv/bin/activate
# update python package manager
pip install -U pip
# get the code (or git@gitlab.com:spam-project/spam-gui.git, with write access)
git clone https://gitlab.com/spam-project/spam-gui.git
cd spam-gui
# install spam-gui in editable mode, with the tools to test it and build it (pytest, pyflakes, build, twine...)
pip install -e ".[dev]"

To update it: git pull. Before writing a module, read SPEC.md (see « Writing a new module » below).

Start

spam-gui                 # opens the module used last (the first one, the very first time)
spam-gui mmr [image1 image2]
spam-gui ereg [image1 image2]
spam-gui --help          # the modules; spam-gui MODULE --help: the arguments of a module

Each module is a subcommand, with its own arguments. mmr, the multimodal registration, and ereg, the eye registration: the images (TIFF files, or folders of TIFF slices) are optional; image 1 is moved onto image 2, the reference. From an open napari window: Plugins › spam › spam-gui.

On Linux, spam-gui uses X11 (QT_QPA_PLATFORM=xcb), also in a Wayland session: under Wayland a program cannot place its windows (its pop-ups would not open at the centre of the window), and napari's drawing can fail (it does under WSL). It also sets PYOPENGL_PLATFORM=glx (unless already set), so that napari's drawing finds the OpenGL context Qt made with X11. Started from napari's menu instead, it uses the display napari chose.

The window

The window opens within its screen (maximised the first time, or if the size it had does not fit the screen). Its panels follow its size:

  • the images are shown in one, two or three windows side by side (« Single », « Double », « Triple », on the right): at first, both images in one window; image 1 on the left and image 2 on the right; image 1, image 2 and both in a checkerboard. Each view keeps its windows' settings;
  • the borders between the panels, and between the image windows, can be dragged (a double click on a border between two windows gives them the same width again);
  • the two small buttons at the far left and right, just above the panels, hide and show the panels on that side, to give the images more room;
  • napari's menus (File, View, Layers...) are hidden: Ctrl+M shows them (and hides them again);
  • the panels are always there (they cannot be closed or moved); the layer controls and the layer list can be collapsed to one line by a click on their title (▾, ▸), to leave more height to the other;
  • the layer controls show the basic controls of a layer (an image: its opacity, its histogram and contrast limits, its colormap); « ▸ Advanced » shows the others, the 3D ones among them (labelled « (3D) »);
  • in a narrow window, the steps show their numbers only (their titles are in their tooltips), and what does not fit in a panel scrolls.

Large images

Images of several GB each can be larger than the memory: spam-gui does not need them in memory.

  • Coarse binnings first. Register at a coarse binning (e.g., 16 or 4), then load a finer one with the eye registration, crop and MMR registration of the coarser one ticked (step 1). The joint histogram and the phase diagram (steps 4, 5) are made again at each binning: their peaks change with the binning.
  • At full resolution (binning 1), an image is read from its file as it is used, when the file allows it: a single TIFF file that is not compressed. A compressed file or a folder of slices is loaded in memory if it fits there; otherwise it is first copied into a scratch file of the same size.
  • Long calculations (reading and binning, the joint histogram, saving the images) run a part of the image at a time, in threads, with a progress bar and a button to cancel.
  • The registration itself (step 6) is spam's, and needs its region in memory: about 60 bytes for each voxel (2 GB for 320³ voxels, 60 GB for 1000³). Step 6 says how much the region needs and how much is available, and asks before starting a registration that does not fit. At full resolution, register a crop (step 3).
  • 3D views need both images whole in memory: they are refused for images that do not fit (load a coarser binning for a 3D view).
  • Scratch files (an image that cannot be read as it is used, or image 1 moved on a very large crop) go to the temporary folder, and are deleted when they are no longer used. To put them elsewhere (e.g., on a larger or faster disk): SPAM_GUI_SCRATCH=/path/to/folder spam-gui.

Writing a new module

New modules follow SPEC.md: how a module is built (steps, panes, shared files), how it looks and behaves, and how it is tested. It is written so that it can also be given to Claude: in this repository, ask Claude Code to read SPEC.md, then to build the module.

Tests

From a developer install (see « To develop it » above):

pytest tests

One more test drives the window itself through the whole registration, on a small pair of images it makes. It opens the window for about a minute, so it only runs when asked:

SPAM_GUI_TESTS=1 pytest tests/test_gui.py

To run it on a virtual screen (xvfb, see « To develop it »), unseen, at a chosen screen size:

SPAM_GUI_TESTS=1 xvfb-run -a -s "-screen 0 1920x1080x24" env QT_QPA_PLATFORM=xcb LIBGL_ALWAYS_SOFTWARE=1 pytest tests/test_gui.py

Docs as a website

The Markdown files of the repository (this one, SPEC.md, TODO.md, OPEN_QUESTIONS.md, TO_SPAM.md, the specs) are published as a website by GitLab Pages on each push to the default branch (.gitlab-ci.yml). To build it locally, from a developer install: python scripts/pages.py, then open public/index.html.

Licence

GPL-3.0-or-later, as spam (see LICENSE.md).

Metadata

Release files for spam-gui 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spam-gui 0.1.0
File Size Uploaded Provenance Actions
spam_gui-0.1.0.tar.gz 405.6 kB Without provenance Details for spam_gui-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for spam-gui 0.1.0
File Interpreter ABI Platform Actions
spam_gui-0.1.0-py3-none-any.whl Python 3 none any Details for spam_gui-0.1.0-py3-none-any.whl

Total release size: 752.5 kB

Release files / spam_gui-0.1.0.tar.gz

Download URL spam_gui-0.1.0.tar.gz
Size 405.6 kB
Tags Source
SHA-256 checksum
How to use checksums
4bf609f62fbf23c5f4dadd1a8286edf19be84f5ff17950cf138e2153c57628e8
BLAKE2b-256 checksum
How to use checksums
b16a3168ce9ac35a7a56cab4fdf7c4a811689f70c51a5d561107e100fb66fde1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / spam_gui-0.1.0-py3-none-any.whl

Download URL spam_gui-0.1.0-py3-none-any.whl
Size 346.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
654aaf8420766febd4a93443cdb1d5661b70272d2c0bb33e672883f31631fa99
BLAKE2b-256 checksum
How to use checksums
bd19996829091fc4e6074f9a6178cb881bdd5330cec3352bf65facabcb2f3fdc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for spam-gui 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page