Add callback mechanism for GUI mode #301

elevans · 2024-03-04T21:29:33Z

Update

Update I wanted to preserve the original text (below) for this PR as its relevant to the goals (i.e. create a better experience for macOS users). With the awesome work that @ctrueden has done with jaunch we now have a way to actually support interactive mode on macOS. This PR introduces the following new elements and also paves the way for interactive mode on macOS via jaunch.

This PR adds:

A "global gateway" which enables other projects to hook into a already running instance of imagej (e.g. napari-imagej).
A callback mechanism which enables users to register functions with when_imagej_starts(). This can enable some GUI related workflows on macOS (a kind of limited psuedo-interactive mode). See notebook 5 section 5.2 for the relevant documentation. This callback mechanism is not compatible with napari.
An override flag to the main init method. This flag will enable users/developers to bypass initialization checks/blocks we've put in place to stop unsupported/application breaking behavior -- mainly interactive mode on macOS. To test interactive mode on macOS:
- Install/setup jaunch.
- Modify jaunch's fiji.py file. Add the override=True flag to ij = imagej.init(app_dir, mode="interactive") on line 72.
- Jaunch Fiji with ./fiji-macos-universal -i --python.

Some other relevant information: Based on what I now understand about Python's threading system and some experimentation on macOS/Linux with jaunch, Python will always think its in a main thread. There is no way (from what I gather) to know if a particular Python instance was started with/in a pthread. Instead, threads that are spawned from an already running instance, say in a function that creates threads, are identified as "non-main" thread. This is obvious, but it would have been cool if there was a way to know about how the current instance was started.

Original text

Until we can find a true interactive mode for macOS (see #298) this callback mechanism gives macOS users the ability to run their desired Python functions before the REPL is locked by the AppHelper.runConsoleEventLoop().

Here's how you register a callback with PyImageJ:

import imagej

# register a function that takes no params
imagej.when_imagej_starts(lambda: func())

# register an ImageJ function (if a parameter is present, assume its ij)
imagej.when_imagej_starts(lambda ij: ij.RoiManager.getRoiManager())

# initialize ImageJ in GUI mode
ij = imagej.init(mode='gui')

Unfortunately this callback strategy doesn't work with napari. Registering the callback lambda: napari.Viewer() results in this segfault:

(pyimagej) loci@dyn-144-92-48-223 Documents % python test.py
WARNING: package sun.awt.X11 not in java.desktop
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by net.imagej.legacy.IJ1Helper (file:/Users/loci/.jgo/net.imagej/imagej/RELEASE/28b74e6959b0634f2a8e10c27afe06e7039fb4a0dc582d9746d028ba40e5bd04/imagej-legacy-1.2.1.jar) to method com.apple.eawt.Application.getApplication()
WARNING: Please consider reporting this to the maintainers of net.imagej.legacy.IJ1Helper
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release
#
# A fatal error has been detected by the Java Runtime Environment:
#
#  SIGILL (0x4) at pc=0x00007ff8116c90c2, pid=2487, tid=42247
#
# JRE version: OpenJDK Runtime Environment Zulu11.70+15-CA (11.0.22+7) (build 11.0.22+7-LTS)
# Java VM: OpenJDK 64-Bit Server VM Zulu11.70+15-CA (11.0.22+7-LTS, mixed mode, tiered, compressed oops, g1 gc, bsd-amd64)
# Problematic frame:
# C  [libdispatch.dylib+0x50c2]  _dispatch_assert_queue_fail+0x66
#
# No core dump will be written. Core dumps have been disabled. To enable core dumping, try "ulimit -c unlimited" before starting Java again
#
# An error report file with more information is saved as:
# /Users/loci/Documents/hs_err_pid2487.log
#
# If you would like to submit a bug report, please visit:
#   http://www.azul.com/support/
# The crash happened outside the Java Virtual Machine in native code.
# See problematic frame for where to report the bug.
#
zsh: abort      python test.py
(pyimagej) loci@dyn-144-92-48-223 Documents %

codecov · 2024-03-04T21:34:38Z

Codecov Report

Attention: Patch coverage is 78.39506% with 35 lines in your changes missing coverage. Please review.

Project coverage is 77.48%. Comparing base (a173d5a) to head (a833767).
Report is 14 commits behind head on main.

Files	Patch %	Lines
src/imagej/__init__.py	43.33%	17 Missing ⚠️
tests/test_legacy.py	68.57%	11 Missing ⚠️
tests/test_fiji.py	12.50%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #301      +/-   ##
==========================================
- Coverage   77.81%   77.48%   -0.33%     
==========================================
  Files          16       17       +1     
  Lines        2010     2034      +24     
==========================================
+ Hits         1564     1576      +12     
- Misses        446      458      +12

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

elevans · 2024-06-10T17:29:32Z

~~Just fyi all PyImageJ builds will fail for python 3.12 until labeling=0.1.14 no longer pins pillow <10 in the conda-feedstock recipe. See this issue.~~

Edit: This is no longer an issue with labeling 0.1.14's release.

gselzer

In general, I'm excited about these changes @elevans!

I'm a bit wary about that new override parameter on the initialization function, though - let's discuss below.

src/imagej/__init__.py

conftest.py

src/imagej/__init__.py

Otherwise, there is no way to access it from other threads. This may be useful for scenarios like napari-imagej, where access to Python scripting is available from threads other than the blocked one.

This is an internal variable, not intended as public API.

It doesn't need to be "ij_wrapper" or "ij_fixture". It's OK to be ij!

This test checks that functions registered via when_imagej_starts get called as part of imagej.init.

This commit adds section 5.2 to the "Convenience methods of PyImageJ" that describes how to use the when_image_starts callback mechanism.

This commit introduces a check to determine if the current running thread is the main thread. If True, then we continue to block interactive mode on macOS (it is not possible to share the main thread with GUI event loop needed for the ImageJ GUI). If False, then the current thread is *not* the main thread (e.g. a jaunched session) and interactive mode for macOS can proceed.

elevans · 2024-07-15T16:03:41Z

Thanks @gselzer for your review! It made it sooo much better! I addressed all your comments. Ready to merge?

gselzer

I love the new changes!

...unfortunately, I requested a couple new things 😅

tests/test_callbacks.py

src/imagej/__init__.py

gselzer · 2024-07-15T19:13:32Z

src/imagej/__init__.py

-    # Add function to the list of callbacks to invoke upon start_jvm().
-    global _init_callbacks
-    _init_callbacks.append(f)
+    if sj.jvm_started():


This doesn't seem like the right check, does it? Presumably, users would want to utilize an initialized ImageJ here. Is that always the case if the JVM is running? I'm assuming there's some period in between...

Good catch! I lifted this from scyjava but thinking more deeply about it, the right check should be the existence of the gateway itself. So the check becomes:

global gateway if gateway: f(gateway)

I'll need to test this...

Since we agreed that we will only have a gateway attribute on the imagej module created in GUI mode, this solution no longer works/makes sense. This method works as intended when called before initializing ImageJ in GUI mode. However, if ImageJ is already initialized and the main thread consumed by the event loop then it becomes impossible to call when_imagej_starts_(), making any check of a pre-existing gateway attribute pointless. As I see it, there is no good way to detect if an ImageJ has been initialized in addition to obtaining a handle on the gateway to use with the desired callback. Thus, I decided to remove this commit and revert it back to just loading the callbacks into the _init_callbacks global list.

Before I resolve this though, what do you think @gselzer?

Yeah, I think that makes sense too.

Use a more descriptive attribute name and value for when_imagej_starts() test.

This commit adds the pthread library loading exception to the logger and assumes that the current thread is the main thread if no pthread library is found.

elevans force-pushed the global-gateway branch 3 times, most recently from 15e8366 to dbb930c Compare May 10, 2024 16:32

elevans force-pushed the global-gateway branch 3 times, most recently from 884c7df to 3f0188b Compare May 28, 2024 02:13

elevans force-pushed the global-gateway branch from 3f0188b to ca14ef3 Compare June 26, 2024 16:16

elevans force-pushed the global-gateway branch from 5993e09 to 2a9bec7 Compare July 5, 2024 16:21

elevans requested review from gselzer, ctrueden and hinerm July 5, 2024 16:44

gselzer reviewed Jul 8, 2024

View reviewed changes

src/imagej/__init__.py Show resolved Hide resolved

conftest.py Outdated Show resolved Hide resolved

src/imagej/__init__.py Outdated Show resolved Hide resolved

elevans force-pushed the global-gateway branch from 2a9bec7 to a833767 Compare July 12, 2024 19:29

ctrueden and others added 8 commits July 15, 2024 10:17

In GUI mode, stash ImageJ gateway in a global var

fec5cee

Otherwise, there is no way to access it from other threads. This may be useful for scenarios like napari-imagej, where access to Python scripting is available from threads other than the blocked one.

Make rai_lock property private

bd2e4d3

This is an internal variable, not intended as public API.

Add when_imagej_starts callback mechanism

f38b200

Simplify name of ImageJ2 gateway fixture

29c2f9e

It doesn't need to be "ij_wrapper" or "ij_fixture". It's OK to be ij!

Add a simple test of when_imagej_starts callback

ccb0e81

This test checks that functions registered via when_imagej_starts get called as part of imagej.init.

Create gateway, run callbacks in same function

221da1e

Add docs section on how to use when_imagej_starts

3bae68b

This commit adds section 5.2 to the "Convenience methods of PyImageJ" that describes how to use the when_image_starts callback mechanism.

elevans force-pushed the global-gateway branch 2 times, most recently from fda4992 to d0eed46 Compare July 15, 2024 15:45

elevans force-pushed the global-gateway branch from ec41fe6 to d114090 Compare July 15, 2024 18:18

gselzer reviewed Jul 15, 2024

View reviewed changes

elevans added 2 commits July 19, 2024 09:37

Use descriptive attribute name for callback test

7667a09

Use a more descriptive attribute name and value for when_imagej_starts() test.

Improve macOS pthread detection exception handling

972592d

This commit adds the pthread library loading exception to the logger and assumes that the current thread is the main thread if no pthread library is found.

elevans force-pushed the global-gateway branch from d114090 to 972592d Compare July 19, 2024 15:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add callback mechanism for GUI mode #301

Add callback mechanism for GUI mode #301

elevans commented Mar 4, 2024 •

edited

Loading

codecov bot commented Mar 4, 2024 •

edited

Loading

elevans commented Jun 10, 2024 •

edited

Loading

gselzer left a comment

elevans commented Jul 15, 2024

gselzer left a comment

gselzer Jul 15, 2024

elevans Jul 15, 2024

elevans Jul 19, 2024 •

edited

Loading

gselzer Aug 15, 2024

Add callback mechanism for GUI mode #301

Are you sure you want to change the base?

Add callback mechanism for GUI mode #301

Conversation

elevans commented Mar 4, 2024 • edited Loading

Update

Original text

codecov bot commented Mar 4, 2024 • edited Loading

Codecov Report

elevans commented Jun 10, 2024 • edited Loading

gselzer left a comment

Choose a reason for hiding this comment

elevans commented Jul 15, 2024

gselzer left a comment

Choose a reason for hiding this comment

gselzer Jul 15, 2024

Choose a reason for hiding this comment

elevans Jul 15, 2024

Choose a reason for hiding this comment

elevans Jul 19, 2024 • edited Loading

Choose a reason for hiding this comment

gselzer Aug 15, 2024

Choose a reason for hiding this comment

elevans commented Mar 4, 2024 •

edited

Loading

codecov bot commented Mar 4, 2024 •

edited

Loading

elevans commented Jun 10, 2024 •

edited

Loading

elevans Jul 19, 2024 •

edited

Loading