What each host does with each feature
For app authors and plugin developers: how napari, Fiji and QuPath present each marker of a tool's declaration. For a plain summary of what a person can do in each host, read What works where first; the notebook form and the command line are covered below.
The hosts are the napari plugin (a dock widget), the Fiji plugin (a SciJava dialog, from the jar or the script) and the QuPath extension (a JavaFX window). All three need an app whose Tools is 0.3.0a1 or newer (INSTALL.md). How to install and open each plugin is in its own guide: napari, Fiji, QuPath.
Feature by feature
"Plain" means the host shows an ordinary field and nothing is lost.
| Feature | napari | Fiji | QuPath |
|---|---|---|---|
| Plain parameters, bounds, units, help | yes | yes | yes |
| Input help (ⓘ after the label of each input with a description) | the description on hover and on keyboard focus; a click keeps it open | the description on hover | the description on hover and on keyboard focus; a click keeps it open |
Optional ("set" box) |
yes | yes ("Set |
yes |
Group, Advanced |
headings; a "Show advanced settings" box | headings, including "Advanced settings" | headings; a folded "Advanced settings" section |
Collapsed |
yes (click the heading) | plain heading (SciJava cannot fold) | yes (titled pane) |
Widget("slider"), Widget("radio") |
slider, radio buttons | slider and radio styles | slider beside the box, radio buttons |
EnabledWhen |
greys out | ignored: every field stays editable | greys out |
PixelSizeOf |
prefilled from the layer's scale and length unit; a scale in pixel units counts as not calibrated (blank, run blocked) | prefilled from the calibration; not calibrated: blank, run blocked | prefilled from the image; not calibrated: blank, run blocked |
ChoicesFrom |
dropdown, updated when its inputs change | dropdown from the values of the previous run; a text field the first time | dropdown, updated when its inputs change |
ClearAfterRun |
yes | yes, in the form that comes back after a run | yes |
PickChannel |
the colours of an RGB layer, the channels of a TIFF file | a channel number | channel names |
RegionOf |
"use the selection" box: the selected Shapes layer | "Use the selection" box: the ROI Manager selection, else the image's ROI | "use the selection" box: the selected annotations |
ImageOut, LabelsOut |
a layer | a window | a preview with "Open in QuPath" |
TableOut |
a table dock | a Results table | a table in the results window |
Scalars |
the status line | the Log window | the results window and the status line |
MessageOut |
a quoted block under the status | the Log window and a dialog | a label under the status and in the results |
PointsOut |
a points layer, scaled like its image | point ROIs, the ROI Manager and a table | a point annotation on the open image, else a table |
ShapesOut |
a shapes layer (outer boundary of each part; a note when holes are dropped) | an overlay and ROI Manager entries, holes kept | annotations with measurements, holes kept |
Affine |
an overlay layer | an overlay window | the matrix is shown |
Replace |
updates the layer or dock in place | closes the previous window, overlay or ROIs | reuses the results window; replaces only the annotations the tool drew |
| Copy as command | a menu: terminal line or Python snippet | printed in the Log window after each run; menu command "Copy last run as command" | a menu: terminal line or Python snippet |
| Progress, Cancel, run details | yes; the worker is kept for repeat runs | progress, Esc to cancel, an error dialog; a new worker for each run | yes; the worker is kept for repeat runs |
| Fiji macros | — | a macro line typed by hand runs the tool without a dialog (jar only); the Macro Recorder does not record it | — |
Not available in any host yet: tracks, time and depth axes of inputs, figures as outputs, repeating a run, and batch runs. A result with known axes does open in Fiji as a hyperstack (result_axes_v1).
Fiji limits. A pixel-size field linked to an image follows that image's calibration by itself; there is no "use the image's calibration" button. A SciJava dialog cannot tell whether the person retyped the value the box already shows, so that field is cleared and the run is blocked with a message, rather than sending a value that might be wrong.
Each row has a test in the host's own suite that runs the example app labconstrictor_tools.examples.interactions; a change that breaks a row fails that suite.
Behaviour shared by every host
These come from Tools and the worker, so every host behaves the same:
- Which apps a host lists. A host lists an app only if the app's
hosts:line names it; an app installed with an older installer has no such line and is listed everywhere, with a sentence in the log (PROTOCOL.md). A host also leaves out an app whose Tools is too old, with a sentence saying why. - Data travels as files. Images and label images go as TIFF files: the host writes an open image to a temporary TIFF, or passes the path of the person's file. Tables and points go as CSV files, outlines as GeoJSON files, and results always come back as files. The app and the host must be on the same computer.
- Big TIFF inputs are memory-mapped (Tools 0.3.0a1 and later). An uncompressed, contiguous TIFF of 8 MiB or more is mapped copy-on-write; any other big TIFF is read whole, and the worker says why in the log. There is no tile-by-tile reading.
LC_TIFF_MEMMAP=0turns it off. On Windows, a tool that keeps a reference to its input keeps the file locked until the worker ends (OPERATIONS.md). - Shared-memory images (
shm_order_v1): the worker readsCandFblocks in the order they were written and refuses any otherorder. A host that sends F-ordered blocks requiresshm_order_v1(PROTOCOL.md). The worker can read an image from a shared-memory block, but no host sends shared memory today.
In a notebook and on the command line
"Notebook" is the form a notebook shows for a tool (labconstrictor_tools.notebook.form). "Command line" is labconstrictor-tools run. Neither is filtered by hosts or host_requirements: every registered tool runs there.
| Input | Notebook | Command line |
|---|---|---|
| Image, label image | type the path of a file | the path of a file |
| Table | type the path of a CSV file | the path of a CSV file |
| File, folder | type the path | the path |
| Number, text, yes/no, choice | yes | yes |
| Optional value left unset | a "set" box | leave it out |
Choices filled by another tool (ChoicesFrom) |
a text field | type the value |
Selection as a region (RegionOf) |
give a label image file | give a label image file |
One channel of an image (PickChannel) |
no: the whole image is sent | no: the whole image is sent |
Pixel size read from the image (PixelSizeOf) |
no: type it | no: type it |
| Part of a large image | no | no |
| Result | Notebook | Command line |
|---|---|---|
| Image, label image | a picture of the first plane | a TIFF file |
| Table | yes | a CSV file |
| Numbers and short values, message | yes | yes |
| Points | a table | a CSV file |
| Outlines | the file is named, nothing is drawn | a GeoJSON file |
| Alignment | the matrix is printed | the matrix is printed |
| File | its path is printed | yes |
Replace |
— | — |
| Running | Notebook | Command line |
|---|---|---|
| Runs in the app's own Python, in a separate process | no: in the notebook's own kernel | yes |
| Progress | yes | printed lines |
| Cancel | interrupt the kernel | Ctrl+C |
| Faster repeat runs (kept worker) | — | no |
| Shared log file | yes | yes |
A run record (run.json), and cleanup of old results and records |
no | yes |
| Details after a failure | the error line | yes |
| Run without a window (scripts, batch) | — | yes |
The notebook form shows ranges and tooltips, but no groups or "advanced" section (one flat list), no greyed-out fields, no sliders or radio buttons, and it does not clear ClearAfterRun fields after a run.
How each host is tested
| Linux | Windows | macOS | |
|---|---|---|---|
| Tools (worker, command line) | automated tests | automated tests | automated tests |
| napari plugin | automated tests, full set | automated tests, full set | automated tests, full set |
| Fiji plugin | automated tests, full set | a short automated check at each release (the menu entry exists, the dialog lists an app) | the same short check, Apple silicon |
| QuPath extension | automated tests, full set | short automated checks at each release | the same short checks, Apple silicon |
| App installers | the release check installs and runs a released app on a fresh machine | the same | the same |
| Tested by people | napari and Fiji; QuPath not yet | app installs and the three plugins | app installs and the three plugins |
Automated tests run on GitHub's machines.
Host feature ids (for host_requirements)
An app can require a host feature by id in host_requirements.<host>.features (PROTOCOL.md). Each host declares its ids next to its version and passes both to the rule. An id is never renamed or reused; it is added in the release that implements it.
| Host | Id | Meaning | Since |
|---|---|---|---|
| every host | host_requirements_v1 |
the host applies the host_requirements rule (a host without it ignores the field) |
napari v0.1.0-alpha.5, Fiji v0.1.0-alpha.7, QuPath v0.1.0-alpha.7 |
| QuPath | shapes_owner_v1 |
Replace removes only the annotations tagged with the run's labconstrictor.output |
v0.1.0-alpha.6 |
| Fiji | log_progress_v1 |
progress and a heartbeat in the Log window during long runs | v0.1.0-alpha.6 |
| Host | Its version, as passed to check |
|---|---|
| napari | importlib.metadata.version("napari-labconstrictor") |
| Fiji | the jar manifest's Implementation-Version (the release tag). The loose script has none: None (unknown). The system property lc.fiji.plugin_version replaces it in tests |
| QuPath | the jar's Implementation-Version (the release tag). The system property lc.qupath.plugin_version replaces it in tests |
Copy as command: the format every host produces
The reference implementation is labconstrictor_tools.command (command_line, python_snippet). Fiji and QuPath build the same text.
-
Terminal line:
<app python> -m labconstrictor_tools run <App> <tool id> name=value ..., onename=valueper parameter that is set (unset optional parameters are left out), booleans astrue/false. Each argument is quoted for the person's shell: POSIXshlex.quoterules, or on Windows the C runtime (CommandLineToArgvW) rules for cmd.exe:- a text with only letters, digits and
-_.:/\=+,stays bare; anything else, and the empty text, goes in double quotes; - backslashes are literal, except a run in front of a
"(doubled, then\") and a run at the end of the text (doubled, in front of the closing quote); - inside the quotes
^ & | < >are literal for cmd.exe; - limits that cannot be escaped without breaking the C runtime rules: cmd.exe expands
%NAME%even inside quotes when NAME is a defined variable; a text with an odd number of"upsets cmd.exe's quote tracking later in the line; a line break cannot be pasted into cmd.exe; PowerShell reads quotes by other rules (use the Python snippet there).
Every host must produce exactly the strings in
tests/quote_vectors.json(a list of{text, posix, windows}). - a text with only letters, digits and
-
Images, labels, tables, files: a layer or window cannot be named on a command line, so each required one gets a placeholder (
image=image.tif) and the text starts with# replace the file for: image. Where a host knows the file behind the input, it uses that path. - Python snippet:
client.run_once("<App>", "<tool id>", {...})with the same values as Python literals, then a print of the status and results.