Skip to content

Docs: make the host-PR sentences true now that all three hosts honour the rule (docs only) #134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
guijacquemet merged 1 commit into from
Oct 14, 2026
Merged

Docs: make the host-PR sentences true now that all three hosts honour the rule (docs only) #134

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

LabConstrictor Tools turns declared Python functions into a tool manifest: a machine-readable description of inputs, outputs and interface hints. Each host reads that description to build a form and handle results. The analysis runs in the application's own Python environment.

**The bridge is application-independent.** An application with valid, registered tool declarations can be discovered by the hosts without a dedicated plugin for that application. Whether its tools are useful in Fiji, Napari or QuPath depends on the work being done there, not on a list of approved applications. Which hosts list an app is the binding `hosts:` line of the app (rule in Tools: PROTOCOL.md, section "App hosts (which host lists an app)"; hosts honour it once their PRs merge, installers pass it from template 0.1.18).
**The bridge is application-independent.** An application with valid, registered tool declarations can be discovered by the hosts without a dedicated plugin for that application. Whether its tools are useful in Fiji, Napari or QuPath depends on the work being done there, not on a list of approved applications. Which hosts list an app is the binding `hosts:` line of the app (rule in Tools: PROTOCOL.md, section "App hosts (which host lists an app)"; the three hosts honour it; installers pass it from template 0.1.18, which is not released yet, so an app installed before that has no declaration and is listed in every host).

This repository provides the declaration API, schema, registry, worker, CLI and tests. The graphical hosts are separate repositories.

Expand Down
4 changes: 2 additions & 2 deletions docs/HOST_FEATURES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ All three need an app whose Tools is **0.3.0a1 or newer**; how to install each h
**Fiji limits (known, stated in the Fiji README):** a pixel-size field linked to an image follows that image's calibration by itself and there is **no "use the image's calibration" button**; typing the value the box already shows cannot be detected in a SciJava dialog (conformance case CAL-T9), so that field is cleared and the run blocked with a message, never a wrong value sent; `EnabledWhen` is ignored; `Collapsed` is a plain heading; no kept worker (a new worker for each run); the Macro Recorder does not record the plugin (a hand-typed macro line works, jar only).

## Which apps a host offers
Each host reads the registry. Which app each host *must* offer is the discovery rule (decided 14 Oct 2026; binding rule in Tools, feature `app_hosts_v1`, Tools PR #133, merged): **CellTracksColab** is hidden from Napari, Fiji and QuPath (notebook only); **NucleiSky, Guess the Condition and Playground** are offered by all three; **VLab4Mic** is offered by Napari and Fiji and **not** by QuPath. discovery rule: see PROTOCOL.md, section "App hosts (which host lists an app)". Hosts honour the rule once their PRs merge (Napari #61, Fiji #47, QuPath #35: open, not merged), and installers pass it from template 0.1.18 (template PR #33, not merged); until then a host offers every registered app that passes its compatibility check (not verified for each host). A host also leaves out, with a sentence in its Log, an app whose Tools is too old. The test steps are in [HUMAN_TEST_PROTOCOL.md](HUMAN_TEST_PROTOCOL.md#6-discovery-who-shows-which-app).
Each host reads the registry. Which app each host *must* offer is the discovery rule (decided 14 Oct 2026; binding rule in Tools, feature `app_hosts_v1`, Tools PR #133, merged): **CellTracksColab** is hidden from Napari, Fiji and QuPath (notebook only); **NucleiSky, Guess the Condition and Playground** are offered by all three; **VLab4Mic** is offered by Napari and Fiji and **not** by QuPath. discovery rule: see PROTOCOL.md, section "App hosts (which host lists an app)". All three hosts honour the rule (merged: Napari #61, Fiji #47, QuPath #35; no host has a tag or release yet). Installers pass it from template 0.1.18 (template PR #33, not merged: it waits for the Tools tag `v0.3.0-alpha.1`); an app installed before that has no declaration and every host lists it, logging the 'declares no hosts' sentence of [PROTOCOL.md](PROTOCOL.md#app-hosts-which-host-lists-an-app). A host also leaves out, with a sentence in its Log, an app whose Tools is too old. The test steps are in [HUMAN_TEST_PROTOCOL.md](HUMAN_TEST_PROTOCOL.md#6-discovery-who-shows-which-app).


| Feature | Napari | Fiji | QuPath |
Expand All @@ -42,7 +42,7 @@ Each host reads the registry. Which app each host *must* offer is the discovery
| `Affine` | overlay layer | overlay window | matrix shown |
| Shared-memory image `order` (feature id `shm_order_v1`, Tools 0.3.0a1) | Worker side, same for every host: `C` / `F` (and Appose's `C_ORDER` / `F_ORDER`) are read in the order they were written, anything else is refused with `unreadable_image`. A host that sends an F-ordered block must require `shm_order_v1` ([PROTOCOL.md](PROTOCOL.md#tools-version-and-features)). Which host sends which order is not checked in this repository | same | same |
| Big TIFF inputs are memory-mapped (Tools 0.3.0a1, no feature id) | Worker side, same for every host, nothing to do: a TIFF of 8 MiB or more that is uncompressed and contiguous is mapped copy-on-write; any other big TIFF is read the plain way and the worker says why in the log and on stderr (`LC_TIFF_MEMMAP=0` turns it off). On Windows a tool that keeps its input keeps the file locked until the worker ends ([OPERATIONS.md](OPERATIONS.md#troubleshooting)) | same | same |
| Per-host listing of apps (`hosts` of the app, feature id `app_hosts_v1`, Tools 0.3.0a1) | binding rule in Tools; once Napari PR #61 merges: lists an app only if its registry entry names `napari` (or has no `hosts`, logged); an excluded app is skipped with the sentence of [PROTOCOL.md](PROTOCOL.md#app-hosts-which-host-lists-an-app) | same, once Fiji PR #47 merges | same, once QuPath PR #35 merges |
| Per-host listing of apps (`hosts` of the app, feature id `app_hosts_v1`, Tools 0.3.0a1) | binding rule in Tools; Napari (PR #61, merged) lists an app only if its registry entry names `napari` (or has no `hosts`, logged); an excluded app is skipped with the sentence of [PROTOCOL.md](PROTOCOL.md#app-hosts-which-host-lists-an-app) | same (Fiji PR #47, merged) | same (QuPath PR #35, merged) |
| Progress, Cancel, kept worker, run details | yes | progress and Esc | yes |
| Macro / command recording | no | yes (macro recorder, replay) | no |

Expand Down
13 changes: 6 additions & 7 deletions docs/HUMAN_TEST_PROTOCOL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,9 +139,9 @@ Nothing in `<...>` is a variable your terminal understands: type the real folder
---

## 3. Which host shows which app (the discovery matrix)
This is the **decided rule**; it is the binding rule in Tools (feature `app_hosts_v1`, Tools PR #133, merged); hosts honour it once their PRs merge (Napari #61, Fiji #47,
QuPath #35: open) and installers pass it from template 0.1.18 (template PR #33, not merged). Check the Tools tag, the host versions and the installer of your test set.
Without them every host lists every registered app that passes its compatibility check ([REPOSITORIES.md](REPOSITORIES.md)); the tests D1 to D3 are written for the rule.
This is the **decided rule**; it is the binding rule in Tools (feature `app_hosts_v1`, Tools PR #133, merged); the three hosts honour it (merged: Napari #61, Fiji #47,
QuPath #35; no host has a tag yet) and installers pass it from template 0.1.18 (template PR #33, not merged). Check the Tools tag, the host versions and the installer of your test set.
An app installed by an older installer has no declaration and every host lists it, logging the 'declares no hosts' sentence ([REPOSITORIES.md](REPOSITORIES.md)); the tests D1 to D3 are written for the rule.
discovery rule: see PROTOCOL.md, section "App hosts (which host lists an app)"

| App | Napari | Fiji | QuPath | Notebook (the app's own window) |
Expand Down Expand Up @@ -275,13 +275,13 @@ A mismatch is a **Major** FAIL (an app that must be hidden is shown, or one that

### D2. VLab4Mic is not offered in QuPath
**Do:** install VLab4Mic. Open QuPath's app chooser. Press **Rescan apps**.
**Expect:** VLab4Mic is not there, while it is in Napari and Fiji; the other apps are unaffected. The host writes `'VLab4Mic' is not listed in qupath: the app declares hosts: notebook, napari, fiji` to the Tools log (`<LC_HOME>/logs/labconstrictor.log`) and shows it wherever it reports left-out apps. This holds only once the installers pass `--app-manifest` (template 0.1.18 and the app sync are not merged yet): not verified until the apps are re-installed with an installer that passes the hosts. For an app registered by an installer that passes no hosts the sentence is `'<app>' declares no hosts, so it is listed in every host; register it with --app-manifest (or --hosts) to choose`, and the app is then listed in every host.
**Expect:** VLab4Mic is not there, while it is in Napari and Fiji; the other apps are unaffected. The host writes `'VLab4Mic' is not listed in qupath: the app declares hosts: notebook, napari, fiji` to the Tools log (`<LC_HOME>/logs/labconstrictor.log`) and shows it wherever it reports left-out apps. The hosts honour the rule; what is still future is the declaration: it exists only once the installers pass `--app-manifest` (template 0.1.18 and the app sync are not merged yet), so this is not verified until the apps are re-installed with an installer that passes the hosts. For an app registered by an installer that passes no hosts the sentence is `'<app>' declares no hosts, so it is listed in every host; register it with --app-manifest (or --hosts) to choose`, and the app is then listed in every host.

- [ ] PASS - [ ] FAIL - [ ] N/A Notes: ______________________________

### D3. CellTracksColab is offered nowhere
**Do:** install CellTracksColab next to another app. Look at all three hosts (Rescan apps / restart Fiji).
**Expect:** not in any list, no error. The host writes `'CellTracksColab' is not listed in <host>: the app declares hosts: notebook` to the Tools log and shows it wherever it reports left-out apps (write down the line you see). The other app still works. This holds only once the installers pass `--app-manifest` (template 0.1.18 and the app sync are not merged yet): not verified until the apps are re-installed with an installer that passes the hosts.
**Expect:** not in any list, no error. The host writes `'CellTracksColab' is not listed in <host>: the app declares hosts: notebook` to the Tools log and shows it wherever it reports left-out apps (write down the line you see). The other app still works. The hosts honour the rule; the declaration exists only once the installers pass `--app-manifest` (template 0.1.18 and the app sync are not merged yet), so this is not verified until the apps are re-installed with an installer that passes the hosts; before that the app is listed in every host.

- [ ] PASS - [ ] FAIL - [ ] N/A Notes: ______________________________

Expand Down Expand Up @@ -398,7 +398,6 @@ Send, in one message or issue titled `Test report: <OS> <your name> <date> <Tool
## Appendix. What the author of this protocol did and did not verify
Written on 14 Oct 2026 from the repositories (Tools `main` 535450d, the host READMEs of Napari 7ddf41f, Fiji f9277af, QuPath 9e64c6d, the app
repositories at their `main`) and from the case files (`lc_tests/cases.json`) of the apps. **Not run by a person from this file:** every step on
Windows and macOS; any step with a released Fiji or QuPath jar (none was published when this was written); the discovery rule (not yet in the
code); the release numbers of the apps (planned); how the hosts show the "helper" tools of an app (for example "List the devices"). The older
Windows and macOS; any step with a released Fiji or QuPath jar (none was published when this was written); the discovery rule (in Tools and in the three hosts since 14 Oct; no installer passes the declaration yet); the release numbers of the apps (planned); how the hosts show the "helper" tools of an app (for example "List the devices"). The older
Linux checks (Ubuntu 24.04, Napari 0.9, Fiji with Java 21) were made with NucleiSky 0.1.1 and an earlier Tools; the numbers in the NucleiSky
file are the ones of that run and of the app's own cases, and they are marked there. If a step in this document is wrong or unclear, please say so; that is a documentation bug.
12 changes: 6 additions & 6 deletions docs/OPERATIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
How a person installs an app and the three hosts is one page: [INSTALL.md](INSTALL.md). In short:
* Each app environment needs `labconstrictor-tools` (standard library only, no dependencies); the app installer installs it from a **tag** (`LC_TOOLS_PIN`, below), and the hosts need Tools **0.3.0a1 or newer** in the app.
* **Install rules** (they come from the sandbox findings of 13 Oct): no space anywhere in the install path (the installers refuse it); macOS and Windows update by uninstalling first; Linux `installer.sh -u` updates in place only after a *finished* install (otherwise delete `<prefix>/pkgs` or uninstall first); testers install only tagged versions and only the latest.
* Napari (nothing is on PyPI yet; **Python 3.11 or newer, Qt6 backend**): `pip install "napari[pyqt6]" https://github.com/CellMigrationLab/LabConstrictor-Tools/archive/refs/tags/v0.3.0-alpha.1.zip https://github.com/CellMigrationLab/LabConstrictor-napari/archive/refs/tags/<NAPARI_TAG>.zip` in the napari environment. The plugin had no tag when this was written, so `<NAPARI_TAG>` does not exist yet; its README and user guide still give `refs/heads/main.zip` lines for both Tools and the plugin (an untagged install, which the rule above forbids for testers). Source archives: no `git` program needed. Plugins > LabConstrictor tools.
* Napari (nothing is on PyPI yet; **Python 3.11 or newer, Qt6 backend**): `pip install "napari[pyqt6]" https://github.com/CellMigrationLab/LabConstrictor-Tools/archive/refs/tags/v0.3.0-alpha.1.zip https://github.com/CellMigrationLab/LabConstrictor-napari/archive/refs/tags/<NAPARI_TAG>.zip` in the napari environment. The plugin has no tag yet (14 Oct 2026), so `<NAPARI_TAG>` is a placeholder that does not resolve; its README and user guide now give the same tag lines (Napari PR #60, merged) and no longer use `refs/heads/main.zip`. Source archives: no `git` program needed. Plugins > LabConstrictor tools.
* Fiji (jar from the release, `labconstrictor-fiji-<tag>.jar`): copy it to `Fiji.app/plugins/`, restart: Plugins > LabConstrictor > LabConstrictor Tools... The release also carries `labconstrictor-fiji-script-<tag>.zip` (the script **and its `lib` folder**, to unzip into `Fiji.app/scripts/Plugins/LabConstrictor/`; entry without the dots; macro calls need the jar) and `SHA256SUMS` (Fiji README at f9277af; no Fiji release existed when this was written).
* QuPath 0.7.0 (jar from the release, `labconstrictor-qupath-<tag>.jar`): drag it onto the QuPath window and restart: Extensions > LabConstrictor tools... The Script Editor alternative is the **single file** `LabConstrictorTools-all.groovy` of the release; the repository's script is split into part files that only the jar and the build join (QuPath README at 9e64c6d; no QuPath release existed when this was written).
* Fiji, Napari and QuPath never import an app's packages, so apps with conflicting dependencies can coexist.
Expand All @@ -30,13 +30,13 @@ State at 14 Oct 2026 (read from the `main` branches of the repositories; search

| Repository | Pin today (file and line) | Pin pull request (draft, do not merge before the tag) | New app release after it | Still open outside the hooks |
|---|---|---|---|---|
| `labconstrictor-playground` | `app/bash_bat_scripts/post_install.sh:83` and `post_install.bat:232` | #27 | 0.0.4 (latest 0.0.3) | `notebooks/LabConstrictorPlayground/LabConstrictorPlayground.ipynb` line 48 (`!pip install -q ...refs/heads/main.zip`); `.github/workflows/ci.yml` installs Tools `@main` on purpose (development CI) |
| `NucleiSky` | `post_install.sh:73` and `post_install.bat:223`: the bridge is **merged** (`nucleisky_lc_tools` is on `main`) | #38 | 0.1.4 (latest 0.1.3) | none found |
| `labconstrictor-vlab4mic` | `post_install.sh:73` and `post_install.bat:223` | #17 | proposed 0.1.6, to be confirmed (latest 0.1.5) | `README.md` lines 56-57 tell users to `pip install` Tools and the Napari plugin from `refs/heads/main.zip` |
| `guessthecondition` | `post_install.sh:73` and `post_install.bat:223` | #14 | proposed 0.0.1, to be confirmed (latest 0.0.0) | none found |
| `labconstrictor-playground` | `app/bash_bat_scripts/post_install.sh:83` and `post_install.bat:232` | #27 | 0.0.4, stated by the maintainer (latest 0.0.3) | `notebooks/LabConstrictorPlayground/LabConstrictorPlayground.ipynb` line 48 (`!pip install -q ...refs/heads/main.zip`); `.github/workflows/ci.yml` installs Tools `@main` on purpose (development CI) |
| `NucleiSky` | `post_install.sh:73` and `post_install.bat:223`: the bridge is **merged** (`nucleisky_lc_tools` is on `main`) | #38 | 0.1.4, stated by the maintainer (latest 0.1.3) | none found |
| `labconstrictor-vlab4mic` | `post_install.sh:73` and `post_install.bat:223` | #17 | 0.1.6, proposed, to be confirmed (latest 0.1.5) | `README.md` lines 56-57 tell users to `pip install` Tools and the Napari plugin from `refs/heads/main.zip` |
| `guessthecondition` | `post_install.sh:73` and `post_install.bat:223` | #14 | 0.0.1, proposed, to be confirmed (latest 0.0.0) | none found |
| `CellTracksColab` | **no Tools step on `main`** (no tools registered); the held branch `bridge-test` has an unpinned `refs/heads/main.zip` line | none | 1.1.2 is held until the bridge decision (latest 1.1.1) | the bridge must be pinned to a tag before it is merged |
| `LabConstrictor` (template) | `post_install.sh:73` and `post_install.bat:223` | #33 (template 0.1.18: pin, pinned actions, template CI, install rules) | template release after #33 (tag: <fill in>) | apps get the pin and the install page by the template sync after it is released |
| Docs that tell people to `pip install` Tools | `LabConstrictor-napari/README.md` lines 75-76 and 135 and `docs/user-guide.md` lines 20-21 (`refs/heads/main.zip`, the development version); this repository's README and docs name the tag | | | say `refs/tags/<tag>.zip` once the tags exist (the napari row is updated after napari PR #60 is merged, because that PR changes the napari docs) |
| Docs that tell people to `pip install` Tools | `LabConstrictor-napari/README.md` (line 77) and `docs/user-guide.md` (line 20) already say `refs/tags/<tag>.zip` with the placeholder `<NAPARI_TAG>` (Napari PR #60, merged); this repository's README and docs name the tag | | | replace `<NAPARI_TAG>` by the real tag once Napari has one |

The tests of this repository keep the strings `LC_TOOLS_SPEC`, `refs/tags/`, `refs/heads/main.zip`, `post_install.sh` and `post_install.bat` in the pinning section above.

Expand Down
Loading
Loading