Add conversion support for index images to ImgLib2 and legacy ImageJ ROIs

[elevans]

This PR adds support to convert index images (Python or Java) into either of the following:

1. A net.imagej.roi.DefaultROITree populated with ImgLib2 ROIs.
2. ImageJ RoiManager populated with legacy converted ROIs (e.g. net.imagej.legacy.convert.roi.polygon2d.Polygon2DWrapper).

Because there's no real way to tell the difference between an index image and some other type of image data (without making assumptions) I feel its best to not register these index image functions with scyjava/pyimagej converters.

Included in this PR:

• converters for index images into ROIs
• tests for index images to ROIs
• Cellpose/StarDist use case

To run the use case you'll need Cellpose and StarDist. This environment.yml file should do the trick:

name: cellstar
channels:
    - conda-forge
    - defaults
dependencies:
    - pyimagej
    - jupyterlab
    - openjdk=11
    - pip
    - pip:
        - tensorflow==2.12.*
        - stardist
        - cellpose

Don't forget to pull this branch and pip install -e . before running the notebook!

[codecov]

Codecov Report

Attention: 11 lines in your changes are missing coverage. Please review.

Comparison is base (c003095) 77.68% compared to head (f205852) 77.81%.

Files	Patch %	Lines
src/imagej/convert.py	64.00%	9 Missing ⚠️
src/imagej/_java.py	86.66%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #283      +/-   ##
==========================================
+ Coverage   77.68%   77.81%   +0.13%     
==========================================
  Files          16       16              
  Lines        1949     2010      +61     
==========================================
+ Hits         1514     1564      +50     
- Misses        435      446      +11     

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

[gselzer]

Great tutorial @elevans!

Just had some small suggestions.

[hinerm]

@elevans I created an environment with the indicated yml and pip install -e . but when I run the notebook the first cell fails with a dependency not found exception on StarDist.

When I paste the exact same line into a python interpreter launched in the exact same environment that started jupyter, it works no problem. :(

I noticed that I'm using python 3.8 locally and I think you used 3.11 when you made the ipynb. Is 3.11 necessary?

[gselzer]

@hinerm I ran using the following environment.yml:

name: cellstar
channels:
    - conda-forge
    - defaults
dependencies:
    - python=="3.8"
    - pyimagej
    - jupyterlab
    - openjdk=11
    - pip
    - pip:
        - tensorflow==2.12.*
        - stardist
        - cellpose

and things seem to work fine. How did you install python 3.8?

[hinerm]

How did you install python 3.8?

@gselzer it's just my system python, since it wasn't specified in the environment.yml specified.

I'm trying with your method of specification. Interestingly I earlier tried >=3.11 and environment creation failed with dependency conflicts.

Further interestingly, python=="3.8" syntax does not work on my computer. I have to remove the double quotes.

Edit: specifying python==3.8 did not work either. Still can't find StarDist

[elevans]

@hinerm I updated the jupyter notebook to use %pip install package magic per Curtis's recommendation. Would you mind giving the notebook a try again?

[hinerm]

@hinerm I updated the jupyter notebook to use %pip install package magic per Curtis's recommendation. Would you mind giving the notebook a try again?

Do I need to do anything different to install it? I assume if you use %pip install you need to trust the notebook?

I assume the environment file should now be:

name: cellstar
channels:
    - conda-forge
    - defaults
dependencies:
    - python=3.8
    - pyimagej
    - jupyterlab
    - openjdk=11
    - pip

Anyway, this doesn't work for me. It looks like the stardist has a dependency on csbdeep that is not compatible with tensorflow 2.12.

What version of stardist and csbdeep are you getting from pip? I think we want to pin a stardist version compatible with the chosen tensorflow on all OS's. Welcome to dependency hell.

[elevans]

@hinerm After many hours of painful testing across Linux, Windows and macOS I found the following shell commands to be the most successful for installing cellpose and stardist:

%%capture
!mamba install -y -c conda-forge tensorflow stardist
!pip install cellpose

I tested this on the following systems:

• Windows 10/11
• Linux (Ubuntu 22.04.3 LTS)
• macOS Sonoma

While testing on macOS, I got bit by the lack of interactive mode support. Bummer! So I included a check for macOS and switch to headless mode with some explanations.

[elevans]

I'm going to do something spicy 🌶️ and merge this branch. The actual new code in convert.py and the accompanying tests have already been reviewed since @hinerm had troubles with the Jupyter notebook. Letting mamba/conda resolve the tensorflow and stardist side of things while installing cellpose from PyPi and not conda-forge was the trick. Since then all I've done is update the cellpose jupyter notebook with shell commands, compatibility with macOS and extra notes.

[ctrueden]

Thank you @elevans—this is great work. I have a couple of requests, though:

• I'd like to avoid promising DefaultWritablePolygon2D, in favor of using the interface where needed.
• Ideally, the conversion logic between index images and ImgLib2 ROIs would live in imagej-common, and simply get called from Python. Then people on the Java side can take advantage of it as well in their scripts.

I would be OK merging this branch once the issue with DefaultWritablePolygon2D is addressed, since we can add the Java-side conversion logic afterward and then replace the code here with a more concise method call. But I would appreciate it if you could do it soon, before we forget about it.

Finally, about the brightness/contrast adjustment: did you try automating that? If so, did you run into any problems? I'm happy to help figure out how to do it, and/or fix any bugs relating to that, as needed.

[ctrueden]

Awesome, thanks @elevans!