spam-gui

Graphical modules for spam (Software for the Practical Analysis of Materials) in a napari window, packaged as spam_gui (command spam-gui). The multimodal registration (src/spam_gui/modules/mmr.py) is the first module and the reference implementation. More modules will follow; the code is being reorganised for them (SPEC.md section 3.4).

Before any change to a module or to the window

spam-gui is made of modules (e.g., the multimodal registration): never call them « tools ». A Python file is a « file », a part of spam (spam.DIC) a « spam package » (SPEC.md, « Words »).

Read SPEC.md first, and follow it. It describes what is common to all the modules: how a module is built, how the window looks and behaves, how large images are handled, how changes are tested, and how to work with the maintainers. Its checklist (section 8) defines when a module is done.

Then read the spec of the module concerned, specs/modules/<module>.md (e.g., specs/modules/mmr.md): what the module does, its steps, its state, and the decisions already taken for it, which must not be undone.

A new module starts with its spec: copy specs/TEMPLATE.md to specs/modules/<module>.md and fill it in with the maintainer before writing code.

Rules that always apply

• Never change spam's algorithms: the modules call spam as it is. If a result from spam looks wrong, explain why and offer options.
• No image analysis in spam-gui: it calls spam. spam-gui must work with the released spam (0.9.1 or later); an analysis function the released spam lacks goes in src/spam_gui/tospam/ (in folders as spam's, e.g. tospam/DIC/ for spam.DIC; written as in spam, without Qt, napari or other spam-gui files), and is listed in TO_SPAM.md. Check spam first, and ask the maintainer before writing one (SPEC.md section 1).
• Everything that concerns spam goes in TO_SPAM.md only, documented enough to hand to spam's developers (a problem: how to reproduce it, the cause, a fix): nothing else, and no workaround in spam-gui.
• Don't commit unless asked, and don't offer to: the maintainer handles commits.
• Work on an up-to-date branch. At the start of a session, before starting a piece of work, and regularly during long work: git fetch, then git status -sb. If the branch is behind its remote (or main moved on, for a feature branch), say so at once and ask before going on; don't pull, merge or rebase yourself.
• Check in often: give short updates, stop at each milestone with a screenshot and wait for feedback. When a placement or a look is ambiguous, ask with two or three options, each with a small ASCII sketch.
• Keep the module's spec up to date: decisions taken with the maintainer go in its « Decisions », with their reason (« (to confirm) » when it is not known: don't invent one).
• Keep TODO.md up to date: the work planned, in order; mark an item done (with its date) when it is.
• Keep OPEN_QUESTIONS.md up to date: one line for each « to confirm » or « to decide », pointing to the details; once answered, write the answer where it belongs and delete the line.

Commands

• Tests: pytest tests. The window test, which opens the window for about a minute: SPAM_GUI_TESTS=1 pytest tests/test_gui.py.
• Lint: pyflakes src tests (should report nothing).
• Run the venv's modules (python -m pytest, python -m pyflakes): a pytest from another environment may be first on the PATH.
• Window test and screenshots on a virtual screen (xvfb), unseen, with napari settings of their own (else the maintainer's saved window size is used, and changed): xvfb-run -a -s "-screen 0 1920x1080x24" env NAPARI_CONFIG=<tmp>/settings.yaml QT_QPA_PLATFORM=xcb LIBGL_ALWAYS_SOFTWARE=1 <command>. Check at least 1366×768, 1920×1080 and 3840×2160, both themes, each step with images loaded.
• Every window test (workflow, sizes, closing) at the three sizes, several at once (about 50 s): python tests/gui/screens.py. While iterating, one size or one test (python tests/gui/screens.py 1920x1080, --only workflow); all of them before reporting.
• Screenshots to look at (each step, three sizes, both themes; about 40 s): python tests/gui/screenshots.py (into tests/gui/screenshots/). A new feature, module, step or window adds its own there, named <module>-<step number>-<step title>[-<variant>].
• The docs as a website (the root Markdown files and specs/, published by GitLab Pages on each push to the default branch): python scripts/pages.py, then open public/index.html. Keep links between Markdown files relative (e.g., [SPEC.md](SPEC.md#9-decisions)): they become links between pages.