From 80a1d300f77d7bf0e770c4ad8eb0310afa52f589 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 21:07:54 +0300 Subject: [PATCH 01/18] docs: explain QuPath region analysis and result coordinates --- README.md | 128 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 73 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index bf50067..91085a4 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,98 @@ -# LabConstrictor-QuPath (prototype) +# LabConstrictor for QuPath -Runs the tools of every installed LabConstrictor app (NucleiSky, CellTracksColab, ...) from **Extensions > LabConstrictor tools...** in -QuPath 0.7. The form is generated from the tool's declared schema ([LabConstrictor-Tools](https://github.com/CellMigrationLab/LabConstrictor-Tools), -`docs/PROTOCOL.md`); the tool runs in the app's own Python environment through the LabConstrictor worker (JSON lines on stdin/stdout), -so QuPath never imports the app's packages and needs no Python of its own. Same idea as the Napari and Fiji front-ends. +**Run Python image analysis on a selected part of a whole-slide image—and put the results back in the right place.** -## Install -1. Install the LabConstrictor app(s) (the installer registers them; check with `labconstrictor-tools list`). -2. Drop `labconstrictor-qupath-0.1.0.jar` on the QuPath window (or into the QuPath extensions folder) and restart QuPath. -3. **Extensions > LabConstrictor tools...** +LabConstrictor connects QuPath to tools installed with LabConstrictor applications. You choose an image or region in QuPath, run a tool in the application's own Python environment, and inspect the results without moving your analysis code into QuPath. + +This is a **prototype for QuPath 0.7**. It is useful for testing region-based workflows, but not yet a replacement for native QuPath measurements or detections. + +## Try a region-based analysis + +1. Install and register a LabConstrictor application with image-analysis tools. +2. Open an image in QuPath and select one or more annotations. +3. Choose **Extensions > LabConstrictor tools...**. +4. Pick the application and tool, select **Current image** and set **Image area** to **Selected annotation(s)**. +5. Run the tool. The bridge exports the bounding region at full resolution, passes it to the tool and presents the results. + +For tools returning points or outlines associated with the current image, the bridge adds the region's origin back to their coordinates. A point found inside a crop can therefore be placed at the correct position on the original slide. + +You can also choose **Current viewport** or **Whole image**. The region chooser applies to the currently open QuPath image, not to arbitrary image files or other project images. -Without the jar: open `src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy` in QuPath's Script Editor and run it. +## What QuPath sends -## What it does -* Pick an app and a tool. Numbers (range, unit), choices, checkboxes, text, files and folders become fields; parameters of a group sit under a heading, advanced ones in a collapsed section, optional ones without a default have a "set" box (unticked = the tool gets nothing), and `enabled_when` greys fields out. -* **Image inputs**: the image open in QuPath, any image of the open project, or a file. QuPath's image is exported losslessly as TIFF (the whole image, or the part chosen under **Image area**, see below). The pixel size of the chosen image fills the tool's pixel-size field (micrometres). -* Results open in a window: values, tables (as a table), images (a preview, the path and an "Open in QuPath" button), alignment matrices, files, messages (also shown under the status line) and points. -* **Interaction hints** of the manifest: a `choices_from` parameter is a dropdown filled by another tool of the app (a text field when that tool cannot answer), `clear_after_run` parameters are reset after a successful run, a `Collapsed` group is a folded section, and an output with `Replace()` reuses the results window of the tool instead of opening a new one. -* **Channel selector**: an image input declared with `PickChannel()` gets a Channel chooser (the channel names of the chosen image, or of a file); the tool receives only that channel. -* **Points** found in the image that is open in QuPath become a point annotation named `:` (replaced by the next run when the output declares `Replace()`); points of any other image are shown as a table. -* "No match" is a message, not an error. Progress bar, Cancel (a tool that ignores it is killed after 3 s), worker kept between runs (or not), details of the last run, no worker left behind when the window closes. -* Results are kept in `~/.labconstrictor/results/` (the newest 20), like the command line. +The extension builds a form from the tool's declared Python inputs. It supports numbers, choices, text, files, folders, channels and selected regions where the tool declares them. -## Large images: the Image area and the size guard -Every image or labels input that uses the image open in QuPath ("Current image: ...") has an **Image area** chooser beside the image chooser: +- **Image input:** use the current image, another image in the project or an image file. QuPath exports its own image data to TIFF. +- **Image area:** whole image, selected annotation bounding box or current viewport for the open image. +- **Selection mask:** when a tool declares `RegionOf(...)`, selected annotations can also be sent as a labelled mask over the chosen area. +- **Channel:** tools declaring `PickChannel()` can receive one selected channel. +- **Calibration:** pixel size from QuPath can fill the tool's calibration field. -* **Whole image** (default): as before. -* **Selected annotation(s)**: the bounding box of the selected annotations (points do not count), widened to whole pixels and clamped to the image; z and t are those of the viewer. -* **Current viewport**: the bounds of the region the viewer shows, clamped to the image. +When multiple inputs require different image areas, the bridge refuses the run instead of silently combining incompatible coordinate systems. -A project image or a file is always sent whole (the chooser is disabled and its tooltip says why). A missing selection or viewer is reported, never guessed around. +### Large slides: an intentional size limit -The tool receives only the area; **results come back on the right place of the slide**: outlines (annotations) and points are moved by the area's origin (x0, y0). The offset comes from the image named by the output's `apply_to` (a RegionOf parameter counts as the image it belongs to), else from the first image input. Because results have only one offset, several image inputs must use the same area; a run that mixes different areas (or an area with a whole image or a file) is refused with a message. A RegionOf selection mask is painted over the area only (same crop and offset), so its 100 M pixel cap applies to the cropped size and a selection on a big image works. +Before exporting an image from QuPath, the extension checks the width × height of the exported area. The default limit is **100 million pixels per plane**. Above that, the run stops with an explanation and asks you to select a smaller area or use a file. -**Size guard.** Before an image is exported through QuPath (a path to a file is passed on untouched and is not checked) the number of pixels of one plane of the exported area (width x height) is compared with a budget of 100 000 000 pixels. Above it the run is refused with a message that names the image and its size and gives the two ways out: "choose Image area: Selected annotation(s)", or use a smaller image or a file. Nothing is downsampled or cropped silently. Change the budget with the system property `lc.qupath.max_export_pixels` (a positive whole number of pixels), e.g. `-Dlc.qupath.max_export_pixels=400000000` in QuPath's JVM options; the tests set a tiny value to trigger the guard on a small image. An invalid value is ignored (logged once) and the default is used. +It does **not** silently downsample the image. Exports currently use full resolution. File paths supplied directly to a tool are passed through rather than subjected to QuPath's export-size check. + +Advanced users can change the limit with the JVM property `lc.qupath.max_export_pixels`, but doing so can substantially increase memory use. + +## What comes back + +| Tool result | Current behavior | +|---|---| +| Points associated with the open image | QuPath point annotation at the correct image coordinates | +| Outlines associated with the open image | QuPath annotations with the region offset restored | +| Image or labels | Preview and path; images can be opened in QuPath | +| Table | Table in the result window | +| Values, files, alignment or messages | Displayed in the result window or status area | + +**Important:** label images are not currently converted into native QuPath detections or annotations. Result tables are not written into object measurements. Results from a file or another project image are not silently placed on the current image. + +## Install -The downsample of an export is 1 for now and is kept next to the offset (`downsample`, always 1.0), so the later resolution step changes one place. +First install and register the LabConstrictor application you want to use. You can inspect registration with: -## Fallbacks (intended) -Each of these is deliberate and is written once to QuPath's log (logger `labconstrictor`) when it happens. Every other failure is logged with its stack trace and shown to the person (status line or Details). +```bash +labconstrictor-tools list +labconstrictor-tools doctor +``` -| Where | What happens | What the person sees | -|---|---|---| -| `choices_from` parameter (dropdown twin) | The source tool is not ready (a value it depends on is empty), failed, or did not return a list: the text field stays | The plain text field; after a failure the status line says "The choices for '...' could not be loaded (type the value): reason" (first time only) | -| `PickChannel` image input | The chosen image has one channel (or none can be read): the channel chooser stays hidden and the tool gets the whole image | No Channel chooser; an unreadable file also shows "Channels of '...' could not be read" in the status line | -| Image area other than the whole image, in Copy as command | A terminal line cannot name a selection or a viewport: the line sends the whole file | A note line "# image: QuPath sent only the Image area '...' (the command line has no area); the command sends the whole file" before the command | -| Points / outlines output | The image searched was not the image open in QuPath (a file, or another project image): nothing is added to the open image | The table (points) or the line "Not placed on an image (...)" in the results window | +Build or obtain the extension jar, then drop `labconstrictor-qupath-0.1.0.jar` onto the QuPath window (or place it in the extensions folder) and restart QuPath. -## Not done yet -* Images are exported at full resolution only (no downsample or pixel-size choice yet); RGB / brightfield images are exported as RGB TIFF. -* Label images are shown as a preview, not converted to QuPath annotations/detections, and tables are not added to the measurements. -* No headless/script API, no Windows/macOS testing, no menu entry per tool. +Choose **Extensions > LabConstrictor tools...**. -## Build and test - QUPATH=/path/to/QuPath JAVA_HOME= ./build.sh # QuPath 0.7 is built with Java 25 - QUPATH=/path/to/QuPath LC_HOME= tests/run_gui_test.sh # needs xvfb; 21 checks +For development, the bridge can also be run from QuPath's Script Editor using: -`BODY=gui_test_interactions_body.groovy tests/run_gui_test.sh` runs the interaction hints, messages and points against the example app of labconstrictor-tools (`labconstrictor_tools.examples.interactions`, registered in `LC_HOME`; 9 checks). +```text +src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy +``` -`BODY=gui_test_playground_body.groovy tests/run_gui_test.sh` runs the tools of the LabConstrictor Playground app (check, device dropdown, big image, crash, no memory, 200 000 points; 8 checks; register the Playground in `LC_HOME` first). +QuPath does not need the application's Python packages. The bridge launches the tool worker in the registered application's interpreter. -`BODY=gui_test_channel_body.groovy tests/run_gui_test.sh` checks the channel chooser of `PickChannel` inputs with a 3-channel TIFF (the tool receives only the chosen channel; 4 checks). +## Limitations worth knowing -`BODY=gui_test_adversarial_body.groovy tests/run_gui_test.sh` throws odd input at the hints (a broken or malformed source tool, 5000 unicode options, a default the source does not list, empty and 50 000 points, a very long message, a failing run); register `tests/adversarial_app` as `adv` first (12 checks). +- QuPath 0.7 is the current target; native Windows and macOS testing is still needed. +- Image export is full-resolution only. There is no user-selectable downsample or target pixel size yet. +- There is no headless/script API or menu entry for each individual tool. +- Dynamic choice lists may fall back to a text field if their source tool cannot answer; failures are reported. +- The **Copy as command** output cannot reproduce a QuPath annotation or viewport selection by itself. It warns when the command would instead send a whole file. +- Very large tables and object outputs have display limits. A preview is not the same as importing measurements or detections into the project. -``BODY=gui_test_fallbacks_body.groovy tests/run_gui_test.sh` checks that failures that used to be silent are reported (bad number typed into a field, unreadable value in Copy as command, host failure with stack trace in Details, unreadable channel file, intended fallbacks logged; 12 checks; needs the `interactions` example app in `LC_HOME`). -`BODY=gui_test_area_body.groovy tests/run_gui_test.sh` checks the Image area and the size guard against the `interactions` example app and the blobs fixture (guard at and one pixel over the budget, the exported area equals the server region, outlines and points land at the blobs' full-image coordinates, the viewport area, RegionOf over an area, differing areas refused, Copy as command note; 48 checks). +The shared log is under `~/.labconstrictor/logs/` by default. Use **Details** when a tool fails, or run `labconstrictor-tools support-bundle` when reporting an issue. -`BODY=gui_test_buttons_body.groovy tests/run_gui_test.sh` clicks "Rescan apps" and "Restart worker" (3 checks; on the version before the split the Rescan button threw `MissingMethodException` because a local variable named `rescan` shadowed the method). +## For developers and testers -### Lint (runs in CI) and what CI does not run +The main extension script is `src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy`. It contains the registry reader, worker connection, form, image export, coordinate conversion and result presentation. -`.github/workflows/lint.yml` lints `LabConstrictorTools.groovy` with `npm-groovy-lint` (pinned version, CodeNarc rules, config in `.groovylintrc.json`; each disabled rule has its reason there). It fails on any finding, including info. Run it locally (needs Node and Java): +The GUI tests require a real QuPath installation and are **not run in CI**. To run them on Linux: - npx --yes npm-groovy-lint@18.0.0 --path src/main/resources/org/cellmigrationlab/labconstrictor/qupath --files "**/*.groovy" --failon info +```bash +QUPATH=/path/to/QuPath JAVA_HOME=/path/to/jdk25 ./build.sh +QUPATH=/path/to/QuPath LC_HOME=/path/to/test-registry tests/run_gui_test.sh +``` -The GUI tests above are **not** run in CI: they need a real QuPath (0.7, Java 25), a virtual display and registered LabConstrictor apps, which a GitHub runner does not have. Run them by hand with `tests/run_gui_test.sh` before merging a change to the script. +Additional test bodies cover image areas, export limits, interaction hints, channels, fallbacks and Playground stress cases. See `tests/` for the scripts and fixtures. -`tests/gui_test_body.groovy` drives the real dialog in QuPath on a virtual screen (project with two calibrated images, both apps) and writes screenshots. +Related projects: [Toolkit](https://github.com/CellMigrationLab/LabConstrictor-Tools) · [Fiji](https://github.com/CellMigrationLab/LabConstrictor-Fiji) · [Napari](https://github.com/CellMigrationLab/napari-labconstrictor) · [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground). From 1bb3dee117ab76c4964a2750d2b365df08e7ca2e Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 21:21:40 +0300 Subject: [PATCH 02/18] docs: narrow QuPath claims and clarify native result limits --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 91085a4..ee7272c 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # LabConstrictor for QuPath -**Run Python image analysis on a selected part of a whole-slide image—and put the results back in the right place.** +**Run registered Python tools on QuPath image regions.** LabConstrictor connects QuPath to tools installed with LabConstrictor applications. You choose an image or region in QuPath, run a tool in the application's own Python environment, and inspect the results without moving your analysis code into QuPath. -This is a **prototype for QuPath 0.7**. It is useful for testing region-based workflows, but not yet a replacement for native QuPath measurements or detections. +This is a **prototype for QuPath 0.7**. It does not convert label images into native detections or add result tables to object measurements. -## Try a region-based analysis +## Run a tool on an image region 1. Install and register a LabConstrictor application with image-analysis tools. 2. Open an image in QuPath and select one or more annotations. @@ -30,7 +30,7 @@ The extension builds a form from the tool's declared Python inputs. It supports When multiple inputs require different image areas, the bridge refuses the run instead of silently combining incompatible coordinate systems. -### Large slides: an intentional size limit +### Export size limit Before exporting an image from QuPath, the extension checks the width × height of the exported area. The default limit is **100 million pixels per plane**. Above that, the run stops with an explanation and asks you to select a smaller area or use a file. @@ -71,7 +71,7 @@ src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTool QuPath does not need the application's Python packages. The bridge launches the tool worker in the registered application's interpreter. -## Limitations worth knowing +## Limitations - QuPath 0.7 is the current target; native Windows and macOS testing is still needed. - Image export is full-resolution only. There is no user-selectable downsample or target pixel size yet. @@ -86,7 +86,7 @@ The shared log is under `~/.labconstrictor/logs/` by default. Use **Details** wh The main extension script is `src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy`. It contains the registry reader, worker connection, form, image export, coordinate conversion and result presentation. -The GUI tests require a real QuPath installation and are **not run in CI**. To run them on Linux: +The GUI tests require a real QuPath installation. They were not run for this documentation change. To run them on Linux: ```bash QUPATH=/path/to/QuPath JAVA_HOME=/path/to/jdk25 ./build.sh From a2e08911dc3ab9555cb2f00911413813a3c6ff2d Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 21:23:46 +0300 Subject: [PATCH 03/18] docs: define maintainable documentation structure --- docs/DOCUMENTATION_MAP.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docs/DOCUMENTATION_MAP.md diff --git a/docs/DOCUMENTATION_MAP.md b/docs/DOCUMENTATION_MAP.md new file mode 100644 index 0000000..6912523 --- /dev/null +++ b/docs/DOCUMENTATION_MAP.md @@ -0,0 +1,19 @@ +# Documentation map + +Selected regions and correct slide coordinates. + +The [README](../README.md) is the entry point. Detailed material belongs in the sections below. This map records the intended structure; a named page may still need to be created or updated by the implementation maintainers. + +| Section | Intended file | Scope | +|---|---|---| +| Overview and first run | `README.md` | Selected annotation workflow and expected result | +| Image export | `docs/IMAGE_AREAS.md` | Whole image, selected annotations, viewport, resolution, calibration, limits | +| Results and coordinates | `docs/RESULTS.md` | Coordinate transforms, native objects versus previews, tables, limits | +| Install and troubleshoot | `docs/INSTALL.md` | Extension/script, QuPath/JDK versions, registry, logs | +| Testing | `docs/TESTING.md` | GUI harness, region fixtures, platform matrix, unsupported workflows | + +## Maintenance + +Coordinate frames and whether results become native QuPath objects are the central contract. Code owners should check each output type and export guard against code. + +When changing a tool or host behavior, update the relevant section in the same PR. Prefer one tested example to several unverified ones. Mark unsupported behavior explicitly; do not turn planned features into present-tense claims. From 615eb4bc9471ac203dde3ae9c8fff7efcea4c67d Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 21:25:21 +0300 Subject: [PATCH 04/18] docs: remove planning map; create actual documentation pages instead --- docs/DOCUMENTATION_MAP.md | 19 ------------------- 1 file changed, 19 deletions(-) delete mode 100644 docs/DOCUMENTATION_MAP.md diff --git a/docs/DOCUMENTATION_MAP.md b/docs/DOCUMENTATION_MAP.md deleted file mode 100644 index 6912523..0000000 --- a/docs/DOCUMENTATION_MAP.md +++ /dev/null @@ -1,19 +0,0 @@ -# Documentation map - -Selected regions and correct slide coordinates. - -The [README](../README.md) is the entry point. Detailed material belongs in the sections below. This map records the intended structure; a named page may still need to be created or updated by the implementation maintainers. - -| Section | Intended file | Scope | -|---|---|---| -| Overview and first run | `README.md` | Selected annotation workflow and expected result | -| Image export | `docs/IMAGE_AREAS.md` | Whole image, selected annotations, viewport, resolution, calibration, limits | -| Results and coordinates | `docs/RESULTS.md` | Coordinate transforms, native objects versus previews, tables, limits | -| Install and troubleshoot | `docs/INSTALL.md` | Extension/script, QuPath/JDK versions, registry, logs | -| Testing | `docs/TESTING.md` | GUI harness, region fixtures, platform matrix, unsupported workflows | - -## Maintenance - -Coordinate frames and whether results become native QuPath objects are the central contract. Code owners should check each output type and export guard against code. - -When changing a tool or host behavior, update the relevant section in the same PR. Prefer one tested example to several unverified ones. Mark unsupported behavior explicitly; do not turn planned features into present-tense claims. From c5c517e1b7b793139cf2aa00a01d975b71af1a98 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 21:26:07 +0300 Subject: [PATCH 05/18] docs: add actual user guide with workflow, results and maintainer checks --- docs/USING_QUPATH.md | 57 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/USING_QUPATH.md diff --git a/docs/USING_QUPATH.md b/docs/USING_QUPATH.md new file mode 100644 index 0000000..19b502d --- /dev/null +++ b/docs/USING_QUPATH.md @@ -0,0 +1,57 @@ +# Using LabConstrictor in QuPath + +The QuPath extension runs registered LabConstrictor Python tools on image data selected in QuPath. It is currently a prototype targeting QuPath 0.7. + +## Before you start + +Install the QuPath extension and a registered LabConstrictor application. Open an image in QuPath. Use `labconstrictor-tools list` to inspect installed applications. + +## Run a tool on a selected region + +1. Select one or more annotations. +2. Open **Extensions > LabConstrictor tools...**. +3. Select an application and tool. +4. Choose **Current image** and **Selected annotation(s)** for the image area. +5. Run the tool and inspect the returned result. + +A tool may instead accept a file or another project image. Image-area choices for the current image do not automatically apply to those sources. + +## Image areas and export + +### Whole image + +Exports the full image at its native resolution, subject to the export-size limit. + +### Selected annotations + +Exports the bounding region of the selected annotation(s). The selected annotation mask can also be supplied separately when the tool declares `RegionOf(...)`. + +### Current viewport + +Exports the visible image region. Viewport size and zoom can affect the chosen area; check what is being analysed. + +### Resolution and limits + +QuPath exports at full resolution; it does not silently downsample. The default limit is 100 million pixels per plane. For larger regions, select a smaller area or provide an image file. + +## Coordinates and results + +The bridge keeps track of the exported region's position in the source image. Points and outlines associated with the current image are transformed back into slide coordinates. + +| Return type | Current handling | +|---|---| +| Points | QuPath point annotations when associated with the open image | +| Outlines | QuPath annotations when associated with the open image | +| Image / labels | Preview or image path | +| Table | Result table | +| Values / message / file | Result display | + +**Label images are not imported as native QuPath detections.** Tables are not added to object measurements. Do not interpret a displayed result as a persistent QuPath object unless it appears in the object hierarchy. + +## Troubleshooting + +If export fails, check the selected area, export size and calibration. If results are misplaced, check which input image the output refers to and whether the region was selected on the open image. Inspect the extension's error details and the shared LabConstrictor log. + +## Maintainer checks + +Test coordinate restoration with a region that starts away from (0, 0). Verify points, polygons, image previews, table display, multiple annotations, export guards and file-versus-current-image behavior. Record QuPath and Java versions and the operating system used for each test. From 6e3171af2f26e438640ced74c14be26147d000f6 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 21:26:22 +0300 Subject: [PATCH 06/18] docs: link README to real user guide --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index ee7272c..4db0fa6 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,8 @@ QuPath does not need the application's Python packages. The bridge launches the The shared log is under `~/.labconstrictor/logs/` by default. Use **Details** when a tool fails, or run `labconstrictor-tools support-bundle` when reporting an issue. +For more detail, see [QuPath image regions and results](docs/USING_QUPATH.md). + ## For developers and testers The main extension script is `src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy`. It contains the registry reader, worker connection, form, image export, coordinate conversion and result presentation. From 09fc1f9f16492f63aef1b7e4da33630515567b75 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 21:32:31 +0300 Subject: [PATCH 07/18] docs: link real scientific applications and qualify bridge availability --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 4db0fa6..06c6807 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,17 @@ The shared log is under `~/.labconstrictor/logs/` by default. Use **Details** wh For more detail, see [QuPath image regions and results](docs/USING_QUPATH.md). +## Applications you can try + +These are separate scientific applications, not tools bundled with this bridge. Install an application and its LabConstrictor tool registration before expecting it to appear in Fiji, Napari or QuPath. + +- [LabConstrictor Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) — synthetic images, segmentation outputs, installation checks and host integration tests. [Installers](https://github.com/CellMigrationLab/LabConstrictor-Playground/releases). +- [NucleiSky](https://github.com/CellMigrationLab/NucleiSky) — registration of microscopy images using nuclei positions. [Desktop installation](https://github.com/CellMigrationLab/NucleiSky/blob/main/.tools/docs/download_executable.md). Its repository documents Fiji integration; verify the installed version exposes the required tools. +- [VLab4Mic desktop application](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) — fluorescence microscopy simulations and image comparison. [Installation guide](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic/blob/main/.tools/docs/download_executable.md). Its repository documents Napari and Fiji bridge workflows. +- [CellTracksColab desktop application](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor) — cell-track analysis. [Desktop installation](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor/blob/main/.tools/docs/download_executable.md). Check the installed application's declared tools before assuming a particular host workflow is available. + +**Compatibility is tool- and host-specific.** An application having a desktop installer does not by itself establish that every analysis function is exposed through the bridge. Use `labconstrictor-tools list` to inspect the installed tools. + ## For developers and testers The main extension script is `src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy`. It contains the registry reader, worker connection, form, image export, coordinate conversion and result presentation. From ca76e8e90215602ff7bdd59f024412c2fa6a4e24 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 21:32:51 +0300 Subject: [PATCH 08/18] docs: link installable scientific applications from user guide --- docs/USING_QUPATH.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/USING_QUPATH.md b/docs/USING_QUPATH.md index 19b502d..acd0e9d 100644 --- a/docs/USING_QUPATH.md +++ b/docs/USING_QUPATH.md @@ -2,6 +2,10 @@ The QuPath extension runs registered LabConstrictor Python tools on image data selected in QuPath. It is currently a prototype targeting QuPath 0.7. +## Scientific applications + +For applications you can install, see [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground), [NucleiSky](https://github.com/CellMigrationLab/NucleiSky), [VLab4Mic desktop](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) and [CellTracksColab desktop](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor). The corresponding README links to installation instructions and explains which host workflows have been documented. Only tools registered by the installed application appear in the bridge. + ## Before you start Install the QuPath extension and a registered LabConstrictor application. Open an image in QuPath. Use `labconstrictor-tools list` to inspect installed applications. From 866d4cd2a983eaec54ca945a8379f810c1730d62 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 21:33:50 +0300 Subject: [PATCH 09/18] docs: add Guess the Condition to available applications --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 06c6807..e281225 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,7 @@ These are separate scientific applications, not tools bundled with this bridge. - [NucleiSky](https://github.com/CellMigrationLab/NucleiSky) — registration of microscopy images using nuclei positions. [Desktop installation](https://github.com/CellMigrationLab/NucleiSky/blob/main/.tools/docs/download_executable.md). Its repository documents Fiji integration; verify the installed version exposes the required tools. - [VLab4Mic desktop application](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) — fluorescence microscopy simulations and image comparison. [Installation guide](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic/blob/main/.tools/docs/download_executable.md). Its repository documents Napari and Fiji bridge workflows. - [CellTracksColab desktop application](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor) — cell-track analysis. [Desktop installation](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor/blob/main/.tools/docs/download_executable.md). Check the installed application's declared tools before assuming a particular host workflow is available. +- [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition) — blinded classification of microscopy images to test whether experimental conditions can be distinguished across biological repeats. [Desktop installers](https://github.com/CellMigrationLab/GuessTheCondition/releases) and [Colab notebook](https://colab.research.google.com/github/CellMigrationLab/GuessTheCondition/blob/main/notebooks/GuessTheCondition/GuessTheCondition.ipynb). Its repository documents five bridge tools for Napari and Fiji. **Compatibility is tool- and host-specific.** An application having a desktop installer does not by itself establish that every analysis function is exposed through the bridge. Use `labconstrictor-tools list` to inspect the installed tools. From 6be3e478beac9f48e323d4f472a18bd9e07f92bf Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 21:34:07 +0300 Subject: [PATCH 10/18] docs: link Guess the Condition from host guide --- docs/USING_QUPATH.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/USING_QUPATH.md b/docs/USING_QUPATH.md index acd0e9d..f8117aa 100644 --- a/docs/USING_QUPATH.md +++ b/docs/USING_QUPATH.md @@ -4,7 +4,7 @@ The QuPath extension runs registered LabConstrictor Python tools on image data s ## Scientific applications -For applications you can install, see [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground), [NucleiSky](https://github.com/CellMigrationLab/NucleiSky), [VLab4Mic desktop](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) and [CellTracksColab desktop](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor). The corresponding README links to installation instructions and explains which host workflows have been documented. Only tools registered by the installed application appear in the bridge. +For applications you can install, see [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground), [NucleiSky](https://github.com/CellMigrationLab/NucleiSky), [VLab4Mic desktop](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) and [CellTracksColab desktop](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor) and [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition). The corresponding README links to installation instructions and explains which host workflows have been documented. Only tools registered by the installed application appear in the bridge. ## Before you start From 9c9a117a227424bb03f494c689974f0b9e6c9155 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 22:00:37 +0300 Subject: [PATCH 11/18] docs: replace duplicated app catalog with relevant verified workflows --- README.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index e281225..c71a9af 100644 --- a/README.md +++ b/README.md @@ -84,17 +84,11 @@ The shared log is under `~/.labconstrictor/logs/` by default. Use **Details** wh For more detail, see [QuPath image regions and results](docs/USING_QUPATH.md). -## Applications you can try +## Applications -These are separate scientific applications, not tools bundled with this bridge. Install an application and its LabConstrictor tool registration before expecting it to appear in Fiji, Napari or QuPath. +[Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) provides synthetic images and outputs for checking QuPath's bridge. Other installable applications, including [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition), [NucleiSky](https://github.com/CellMigrationLab/NucleiSky), [VLab4Mic](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) and [CellTracksColab](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor), are listed in the [Toolkit application list](https://github.com/CellMigrationLab/LabConstrictor-Tools#applications). -- [LabConstrictor Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) — synthetic images, segmentation outputs, installation checks and host integration tests. [Installers](https://github.com/CellMigrationLab/LabConstrictor-Playground/releases). -- [NucleiSky](https://github.com/CellMigrationLab/NucleiSky) — registration of microscopy images using nuclei positions. [Desktop installation](https://github.com/CellMigrationLab/NucleiSky/blob/main/.tools/docs/download_executable.md). Its repository documents Fiji integration; verify the installed version exposes the required tools. -- [VLab4Mic desktop application](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) — fluorescence microscopy simulations and image comparison. [Installation guide](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic/blob/main/.tools/docs/download_executable.md). Its repository documents Napari and Fiji bridge workflows. -- [CellTracksColab desktop application](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor) — cell-track analysis. [Desktop installation](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor/blob/main/.tools/docs/download_executable.md). Check the installed application's declared tools before assuming a particular host workflow is available. -- [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition) — blinded classification of microscopy images to test whether experimental conditions can be distinguished across biological repeats. [Desktop installers](https://github.com/CellMigrationLab/GuessTheCondition/releases) and [Colab notebook](https://colab.research.google.com/github/CellMigrationLab/GuessTheCondition/blob/main/notebooks/GuessTheCondition/GuessTheCondition.ipynb). Its repository documents five bridge tools for Napari and Fiji. - -**Compatibility is tool- and host-specific.** An application having a desktop installer does not by itself establish that every analysis function is exposed through the bridge. Use `labconstrictor-tools list` to inspect the installed tools. +Their availability as desktop applications does **not** establish that their workflows have been tested in QuPath. Inspect the registered tools and check inputs, outputs and coordinate handling before using them on whole-slide data. ## For developers and testers From 3aec0f5a20f74bf8538b7eeeb20bfab9f97e1268 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 22:01:04 +0300 Subject: [PATCH 12/18] docs: fix awkward links and state app compatibility by host --- docs/USING_QUPATH.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/USING_QUPATH.md b/docs/USING_QUPATH.md index f8117aa..3f3a80b 100644 --- a/docs/USING_QUPATH.md +++ b/docs/USING_QUPATH.md @@ -4,7 +4,7 @@ The QuPath extension runs registered LabConstrictor Python tools on image data s ## Scientific applications -For applications you can install, see [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground), [NucleiSky](https://github.com/CellMigrationLab/NucleiSky), [VLab4Mic desktop](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) and [CellTracksColab desktop](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor) and [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition). The corresponding README links to installation instructions and explains which host workflows have been documented. Only tools registered by the installed application appear in the bridge. +Start with [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) to exercise the QuPath bridge. The [Toolkit application list](https://github.com/CellMigrationLab/LabConstrictor-Tools#applications) links to scientific applications, including Guess the Condition. Their QuPath behavior is not established by those listings. ## Before you start From 5ba22c65c044f25ca631f33e64827dbf2d6f1445 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 22:01:45 +0300 Subject: [PATCH 13/18] docs: avoid linking to README heading that is not yet merged --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c71a9af..b2bbc50 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ For more detail, see [QuPath image regions and results](docs/USING_QUPATH.md). ## Applications -[Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) provides synthetic images and outputs for checking QuPath's bridge. Other installable applications, including [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition), [NucleiSky](https://github.com/CellMigrationLab/NucleiSky), [VLab4Mic](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) and [CellTracksColab](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor), are listed in the [Toolkit application list](https://github.com/CellMigrationLab/LabConstrictor-Tools#applications). +[Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) provides synthetic images and outputs for checking QuPath's bridge. Other installable applications, including [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition), [NucleiSky](https://github.com/CellMigrationLab/NucleiSky), [VLab4Mic](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) and [CellTracksColab](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor), are listed in the [Toolkit application list](https://github.com/CellMigrationLab/LabConstrictor-Tools). Their availability as desktop applications does **not** establish that their workflows have been tested in QuPath. Inspect the registered tools and check inputs, outputs and coordinate handling before using them on whole-slide data. From 36b9566ab9c8a853be91220573c674f39f20ae7a Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 22:01:47 +0300 Subject: [PATCH 14/18] docs: avoid linking to README heading that is not yet merged --- docs/USING_QUPATH.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/USING_QUPATH.md b/docs/USING_QUPATH.md index 3f3a80b..f885841 100644 --- a/docs/USING_QUPATH.md +++ b/docs/USING_QUPATH.md @@ -4,7 +4,7 @@ The QuPath extension runs registered LabConstrictor Python tools on image data s ## Scientific applications -Start with [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) to exercise the QuPath bridge. The [Toolkit application list](https://github.com/CellMigrationLab/LabConstrictor-Tools#applications) links to scientific applications, including Guess the Condition. Their QuPath behavior is not established by those listings. +Start with [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) to exercise the QuPath bridge. The [Toolkit application list](https://github.com/CellMigrationLab/LabConstrictor-Tools) links to scientific applications, including Guess the Condition. Their QuPath behavior is not established by those listings. ## Before you start From 621924b2650c6d3565d7fd2cabbc71be5fea176d Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 22:11:00 +0300 Subject: [PATCH 15/18] docs: clarify manifest-driven support and focus on host usefulness --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b2bbc50..051b84c 100644 --- a/README.md +++ b/README.md @@ -86,9 +86,11 @@ For more detail, see [QuPath image regions and results](docs/USING_QUPATH.md). ## Applications -[Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) provides synthetic images and outputs for checking QuPath's bridge. Other installable applications, including [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition), [NucleiSky](https://github.com/CellMigrationLab/NucleiSky), [VLab4Mic](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) and [CellTracksColab](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor), are listed in the [Toolkit application list](https://github.com/CellMigrationLab/LabConstrictor-Tools). +QuPath reads the same registered LabConstrictor tool manifests as the other hosts. A scientific application does not need a separate QuPath extension to expose its declared tools. -Their availability as desktop applications does **not** establish that their workflows have been tested in QuPath. Inspect the registered tools and check inputs, outputs and coordinate handling before using them on whole-slide data. +[Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) provides a small example for checking the host. Other applications include [NucleiSky](https://github.com/CellMigrationLab/NucleiSky), [VLab4Mic](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic), [CellTracksColab](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor) and [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition). See the [Toolkit](https://github.com/CellMigrationLab/LabConstrictor-Tools) for installation links. + +**The issue is usefulness, not an application-specific integration requirement.** Image-region analysis and spatial outputs are natural fits for QuPath; game controls or other workflows may be less convenient there. Check how QuPath handles the tool's declared inputs and outputs, especially coordinate mapping and native object creation. ## For developers and testers From d2cc04df3c17eb6b5ffcf4d3f2920b18d8fb0663 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Thu, 8 Oct 2026 22:11:26 +0300 Subject: [PATCH 16/18] docs: explain generic manifest connection in host guide --- docs/USING_QUPATH.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/USING_QUPATH.md b/docs/USING_QUPATH.md index f885841..390b7b2 100644 --- a/docs/USING_QUPATH.md +++ b/docs/USING_QUPATH.md @@ -4,7 +4,7 @@ The QuPath extension runs registered LabConstrictor Python tools on image data s ## Scientific applications -Start with [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) to exercise the QuPath bridge. The [Toolkit application list](https://github.com/CellMigrationLab/LabConstrictor-Tools) links to scientific applications, including Guess the Condition. Their QuPath behavior is not established by those listings. +QuPath can discover tools from any registered LabConstrictor application whose manifest uses a supported protocol. It does not need a separate extension for each application. Choose tools that benefit from QuPath's image regions, annotations or coordinates; see the [Toolkit](https://github.com/CellMigrationLab/LabConstrictor-Tools) for examples. ## Before you start From 4f5958e41f010867cc3c15da5f3a6e7f6ba692e8 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Fri, 9 Oct 2026 05:51:03 +0300 Subject: [PATCH 17/18] docs: correct QuPath first run, scope and test-installation warning --- README.md | 110 +++++++++++++++--------------------------------------- 1 file changed, 30 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index 051b84c..505f0ab 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,58 @@ # LabConstrictor for QuPath -**Run registered Python tools on QuPath image regions.** +Run tools from any **registered LabConstrictor application** on QuPath images. QuPath reads the application's tool manifest, builds a form and launches the tool in its own Python environment. Applications do not need separate QuPath plugins. -LabConstrictor connects QuPath to tools installed with LabConstrictor applications. You choose an image or region in QuPath, run a tool in the application's own Python environment, and inspect the results without moving your analysis code into QuPath. +This is a **prototype targeting QuPath 0.7**. See [Using LabConstrictor in QuPath](docs/USING_QUPATH.md) for image-area choices, coordinates, results and limitations. -This is a **prototype for QuPath 0.7**. It does not convert label images into native detections or add result tables to object measurements. +## Start here -## Run a tool on an image region +1. Install a [LabConstrictor application](#applications) with registered tools. Check it using `labconstrictor-tools list` and `labconstrictor-tools doctor`. +2. Build the QuPath extension (see below), or obtain its JAR if available. Install it by dragging the JAR onto QuPath's main window or copying it to the QuPath user extensions directory. Restart QuPath. +3. Open an image and choose **Extensions > LabConstrictor tools...**. +4. Select an application and tool. For a region-based run, select an annotation, choose **Current image**, and set **Image area** to **Selected annotation(s)**. +5. Inspect the result window and any annotations created in the image hierarchy. -1. Install and register a LabConstrictor application with image-analysis tools. -2. Open an image in QuPath and select one or more annotations. -3. Choose **Extensions > LabConstrictor tools...**. -4. Pick the application and tool, select **Current image** and set **Image area** to **Selected annotation(s)**. -5. Run the tool. The bridge exports the bounding region at full resolution, passes it to the tool and presents the results. +**Selected annotation(s)** exports the **bounding rectangle** of the selected objects, not just pixels inside their shapes. A separate `RegionOf(...)` input can supply a labelled selection mask if the tool declares one. The extension exports at full resolution, with a default limit of **100 million pixels per plane**. -For tools returning points or outlines associated with the current image, the bridge adds the region's origin back to their coordinates. A point found inside a crop can therefore be placed at the correct position on the original slide. +Points and outlines associated with the image open in QuPath can become annotations in slide coordinates. Image and label results have previews, but **label images are not converted to native detections**, and result tables do not automatically become object measurements. -You can also choose **Current viewport** or **Whole image**. The region chooser applies to the currently open QuPath image, not to arbitrary image files or other project images. +Do not switch the active QuPath image or change its selection during a running analysis until [run-state handling](https://github.com/CellMigrationLab/LabConstrictor-QuPath/issues/16) is corrected. Check the pixel-size field whenever you change image sources ([calibration issue](https://github.com/CellMigrationLab/LabConstrictor-QuPath/issues/15)). -## What QuPath sends +## Install or build -The extension builds a form from the tool's declared Python inputs. It supports numbers, choices, text, files, folders, channels and selected regions where the tool declares them. - -- **Image input:** use the current image, another image in the project or an image file. QuPath exports its own image data to TIFF. -- **Image area:** whole image, selected annotation bounding box or current viewport for the open image. -- **Selection mask:** when a tool declares `RegionOf(...)`, selected annotations can also be sent as a labelled mask over the chosen area. -- **Channel:** tools declaring `PickChannel()` can receive one selected channel. -- **Calibration:** pixel size from QuPath can fill the tool's calibration field. - -When multiple inputs require different image areas, the bridge refuses the run instead of silently combining incompatible coordinate systems. - -### Export size limit - -Before exporting an image from QuPath, the extension checks the width × height of the exported area. The default limit is **100 million pixels per plane**. Above that, the run stops with an explanation and asks you to select a smaller area or use a file. - -It does **not** silently downsample the image. Exports currently use full resolution. File paths supplied directly to a tool are passed through rather than subjected to QuPath's export-size check. - -Advanced users can change the limit with the JVM property `lc.qupath.max_export_pixels`, but doing so can substantially increase memory use. - -## What comes back - -| Tool result | Current behavior | -|---|---| -| Points associated with the open image | QuPath point annotation at the correct image coordinates | -| Outlines associated with the open image | QuPath annotations with the region offset restored | -| Image or labels | Preview and path; images can be opened in QuPath | -| Table | Table in the result window | -| Values, files, alignment or messages | Displayed in the result window or status area | - -**Important:** label images are not currently converted into native QuPath detections or annotations. Result tables are not written into object measurements. Results from a file or another project image are not silently placed on the current image. - -## Install - -First install and register the LabConstrictor application you want to use. You can inspect registration with: +The extension is packaged as `labconstrictor-qupath-0.1.0.jar`. For a development build against an installed QuPath 0.7 and JDK 25: ```bash -labconstrictor-tools list -labconstrictor-tools doctor -``` - -Build or obtain the extension jar, then drop `labconstrictor-qupath-0.1.0.jar` onto the QuPath window (or place it in the extensions folder) and restart QuPath. - -Choose **Extensions > LabConstrictor tools...**. - -For development, the bridge can also be run from QuPath's Script Editor using: - -```text -src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy +QUPATH=/path/to/QuPath JAVA_HOME=/path/to/jdk25 ./build.sh ``` -QuPath does not need the application's Python packages. The bridge launches the tool worker in the registered application's interpreter. - -## Limitations - -- QuPath 0.7 is the current target; native Windows and macOS testing is still needed. -- Image export is full-resolution only. There is no user-selectable downsample or target pixel size yet. -- There is no headless/script API or menu entry for each individual tool. -- Dynamic choice lists may fall back to a text field if their source tool cannot answer; failures are reported. -- The **Copy as command** output cannot reproduce a QuPath annotation or viewport selection by itself. It warns when the command would instead send a whole file. -- Very large tables and object outputs have display limits. A preview is not the same as importing measurements or detections into the project. +The JAR is written to `target/labconstrictor-qupath-0.1.0.jar`. Follow [QuPath's manual extension installation instructions](https://qupath.readthedocs.io/en/stable/docs/intro/extensions.html#installing-extensions-manually) to install it. Alternatively, developers can open `src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy` in QuPath's Script Editor. -The shared log is under `~/.labconstrictor/logs/` by default. Use **Details** when a tool fails, or run `labconstrictor-tools support-bundle` when reporting an issue. - -For more detail, see [QuPath image regions and results](docs/USING_QUPATH.md). +For troubleshooting, check the extension's **Details** window and the LabConstrictor log under `~/.labconstrictor/logs/` (or the configured `LC_HOME`). See the [user guide](docs/USING_QUPATH.md). ## Applications -QuPath reads the same registered LabConstrictor tool manifests as the other hosts. A scientific application does not need a separate QuPath extension to expose its declared tools. +The manifest makes the bridge **application-independent**; the list below is a set of examples, not a compatibility allowlist. Choose tools according to how useful their inputs and outputs are in QuPath. -[Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) provides a small example for checking the host. Other applications include [NucleiSky](https://github.com/CellMigrationLab/NucleiSky), [VLab4Mic](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic), [CellTracksColab](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor) and [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition). See the [Toolkit](https://github.com/CellMigrationLab/LabConstrictor-Tools) for installation links. +- [LabConstrictor Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground) — test images and bridge diagnostics +- [NucleiSky](https://github.com/CellMigrationLab/NucleiSky) — microscopy-image registration +- [VLab4Mic desktop](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic) — fluorescence-image simulation +- [CellTracksColab desktop](https://github.com/CellMigrationLab/CellTracksColab_LabConstrictor) — cell-track analysis +- [Guess the Condition](https://github.com/CellMigrationLab/GuessTheCondition) — blinded microscopy-image classification -**The issue is usefulness, not an application-specific integration requirement.** Image-region analysis and spatial outputs are natural fits for QuPath; game controls or other workflows may be less convenient there. Check how QuPath handles the tool's declared inputs and outputs, especially coordinate mapping and native object creation. +Each application must be installed and its tool module registered before its tools appear. The [LabConstrictor Toolkit](https://github.com/CellMigrationLab/LabConstrictor-Tools) documents the shared manifest and registration. -## For developers and testers +## Development and tests -The main extension script is `src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy`. It contains the registry reader, worker connection, form, image export, coordinate conversion and result presentation. +The QuPath implementation is in `src/main/resources/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorTools.groovy`. The extension entry point is `src/main/java/org/cellmigrationlab/labconstrictor/qupath/LabConstrictorExtension.java`. -The GUI tests require a real QuPath installation. They were not run for this documentation change. To run them on Linux: +The GUI test harness requires QuPath, Java and (on Linux) `xvfb-run`. **It alters the selected QuPath installation** by copying the JAR into `lib/app` and modifying `lib/app/QuPath.cfg`; use a disposable test installation: ```bash -QUPATH=/path/to/QuPath JAVA_HOME=/path/to/jdk25 ./build.sh -QUPATH=/path/to/QuPath LC_HOME=/path/to/test-registry tests/run_gui_test.sh +QUPATH=/path/to/disposable-QuPath JAVA_HOME=/path/to/jdk25 ./build.sh +QUPATH=/path/to/disposable-QuPath LC_HOME=/path/to/test-registry tests/run_gui_test.sh ``` -Additional test bodies cover image areas, export limits, interaction hints, channels, fallbacks and Playground stress cases. See `tests/` for the scripts and fixtures. +See `tests/` for test bodies and fixtures. The GUI tests were not run for this documentation change. The extension's [open issues](https://github.com/CellMigrationLab/LabConstrictor-QuPath/issues) record implementation work. -Related projects: [Toolkit](https://github.com/CellMigrationLab/LabConstrictor-Tools) · [Fiji](https://github.com/CellMigrationLab/LabConstrictor-Fiji) · [Napari](https://github.com/CellMigrationLab/napari-labconstrictor) · [Playground](https://github.com/CellMigrationLab/LabConstrictor-Playground). +Related hosts: [Fiji](https://github.com/CellMigrationLab/LabConstrictor-Fiji) · [Napari](https://github.com/CellMigrationLab/napari-labconstrictor). From c163c43b89ba731c5cbf61c1e8690312d22a32b3 Mon Sep 17 00:00:00 2001 From: guijacquemet Date: Fri, 9 Oct 2026 05:51:22 +0300 Subject: [PATCH 18/18] docs: correct QuPath image-area behavior and result limitations in guide --- docs/USING_QUPATH.md | 82 ++++++++++++++++++++++++++------------------ 1 file changed, 48 insertions(+), 34 deletions(-) diff --git a/docs/USING_QUPATH.md b/docs/USING_QUPATH.md index 390b7b2..0c97210 100644 --- a/docs/USING_QUPATH.md +++ b/docs/USING_QUPATH.md @@ -1,61 +1,75 @@ # Using LabConstrictor in QuPath -The QuPath extension runs registered LabConstrictor Python tools on image data selected in QuPath. It is currently a prototype targeting QuPath 0.7. +LabConstrictor reads the tool manifest of any registered scientific application. The same application can be accessed from other hosts; in QuPath, the useful workflows are generally those involving image regions, annotations and spatial results. -## Scientific applications +This guide describes the current QuPath 0.7 prototype. For installation, build instructions and application links, start with the [README](../README.md). -QuPath can discover tools from any registered LabConstrictor application whose manifest uses a supported protocol. It does not need a separate extension for each application. Choose tools that benefit from QuPath's image regions, annotations or coordinates; see the [Toolkit](https://github.com/CellMigrationLab/LabConstrictor-Tools) for examples. +## Run a tool -## Before you start +1. Open an image in QuPath. +2. Select one or more annotations if you want to work on a smaller area. +3. Choose **Extensions > LabConstrictor tools...**, select an application and tool. +4. Select **Current image** for the image input. Set **Image area** to **Selected annotation(s)** to export their bounding rectangle, or choose another area. +5. Review parameters, especially pixel size, then run the tool. +6. Inspect the result window and any annotations added to the project. -Install the QuPath extension and a registered LabConstrictor application. Open an image in QuPath. Use `labconstrictor-tools list` to inspect installed applications. +An annotation selection does not automatically restrict the analysis to pixels inside its shapes: the **Image area** setting exports their bounding box. If a tool declares a separate `RegionOf(...)` labels input, the selected annotations can also be sent as a mask. -## Run a tool on a selected region +## Image inputs and areas -1. Select one or more annotations. -2. Open **Extensions > LabConstrictor tools...**. -3. Select an application and tool. -4. Choose **Current image** and **Selected annotation(s)** for the image area. -5. Run the tool and inspect the returned result. +| Image source | Available area | +|---|---| +| Current image | Whole image, selected annotations or current viewport | +| Another project image | Whole image | +| File | File passed directly, unless channel extraction requires QuPath to export it | + +**Whole image** exports the full-resolution image, using the first Z/T plane in the current implementation. -A tool may instead accept a file or another project image. Image-area choices for the current image do not automatically apply to those sources. +**Selected annotation(s)** exports the bounding rectangle of the chosen annotations, rounded to pixel boundaries and clipped to the image. The exported Z/T plane follows the viewer. Selections spanning different Z/T planes require particular care: the bounding-box calculation does not filter the selected annotations by plane. -## Image areas and export +**Current viewport** exports its visible bounds, clipped to the image, at full resolution. The viewer's Z/T plane is used. -### Whole image +The default export guard is **100 million pixels per plane**. This limits host-side image exports, not image files passed as paths without export. The system property `lc.qupath.max_export_pixels` can change the budget; higher limits require more memory. There is no automatic downsampling. -Exports the full image at its native resolution, subject to the export-size limit. +### Multiple image inputs -### Selected annotations +A tool can receive multiple images. When using cropped areas, the current bridge requires their spatial areas to agree, since it supports a single coordinate offset for outputs. A mixed cropped/whole-image run is refused. Check the result's `apply_to` association before interpreting spatial data. -Exports the bounding region of the selected annotation(s). The selected annotation mask can also be supplied separately when the tool declares `RegionOf(...)`. +### Calibration -### Current viewport +A tool may declare `PixelSizeOf(...)` to prefill its pixel-size parameter from the chosen image. **Check the value after changing source**, particularly when switching to a file or an image without usable calibration. Until [issue #15](https://github.com/CellMigrationLab/LabConstrictor-QuPath/issues/15) is fixed, the field may retain an earlier value. -Exports the visible image region. Viewport size and zoom can affect the chosen area; check what is being analysed. +## Results and coordinates -### Resolution and limits +The bridge stores the selected area's origin and uses it to map local pixel coordinates from results back to full-resolution slide coordinates. -QuPath exports at full resolution; it does not silently downsample. The default limit is 100 million pixels per plane. For larger regions, select a smaller area or provide an image file. +| Output | Current behavior | +|---|---| +| Points | Point annotation on the open image, when associated with it; otherwise a table | +| Shapes | Polygon annotations, including holes and numeric feature measurements, when associated with the open image | +| Image and labels | Preview, path and an option to open the image | +| Table | View in the results window, with a display row limit | +| Affine | Matrix display (not an applied image transform) | +| Values and messages | Results panel or status | -## Coordinates and results +A label-image preview is **not** an imported QuPath detection or annotation, and tabular outputs are **not** copied into measurements automatically. Points and shapes are persistent objects only when added to the image hierarchy. -The bridge keeps track of the exported region's position in the source image. Points and outlines associated with the current image are transformed back into slide coordinates. +**Do not change the active QuPath image or selected annotations while a tool is running.** Currently the result import and some input lookups access live QuPath state rather than the exact image/selection used to start the run. See [issue #16](https://github.com/CellMigrationLab/LabConstrictor-QuPath/issues/16). -| Return type | Current handling | -|---|---| -| Points | QuPath point annotations when associated with the open image | -| Outlines | QuPath annotations when associated with the open image | -| Image / labels | Preview or image path | -| Table | Result table | -| Values / message / file | Result display | +### Checking placement -**Label images are not imported as native QuPath detections.** Tables are not added to object measurements. Do not interpret a displayed result as a persistent QuPath object unless it appears in the object hierarchy. +For spatial tools, inspect the original image and confirm that annotations are positioned where expected. A useful regression case places an annotation away from the origin, crops around it, then checks the restored coordinates. ## Troubleshooting -If export fails, check the selected area, export size and calibration. If results are misplaced, check which input image the output refers to and whether the region was selected on the open image. Inspect the extension's error details and the shared LabConstrictor log. +If no application appears, check its registration with `labconstrictor-tools list` and `labconstrictor-tools doctor`. + +If export fails, check the area size and whether annotations are selected. If a worker fails, inspect **Details** and the shared LabConstrictor log. If a table is malformed, preserve the source CSV for an issue report: QuPath currently reads CSV by physical lines and [does not support multiline quoted cells correctly](https://github.com/CellMigrationLab/LabConstrictor-QuPath/issues/17). + +The **Copy as command** feature cannot reproduce a selected annotation, viewport crop or channel extraction by itself; it adds explanatory notes and uses a whole-file path where possible. + +## Maintainer regression checks -## Maintainer checks +Verify the areas, pixel calibration, selected region masks, point and polygon offsets, Z/T planes, multiple image inputs, output types, cancellation and background worker state. Include a long-running test that switches active images before the result returns, and a multiline CSV case. Record QuPath, Java and operating-system versions used. -Test coordinate restoration with a region that starts away from (0, 0). Verify points, polygons, image previews, table display, multiple annotations, export guards and file-versus-current-image behavior. Record QuPath and Java versions and the operating system used for each test. +The test harness is documented in the [README](../README.md). It modifies the QuPath installation selected for testing, so use a disposable copy.