PyImageJ Documentation Revitalization

[hinerm]

I decided to start one parent issue for documentation which can be updated with other documentation improvements.

Things I've noticed:

• The Troubleshooting notebook is not in sync with the Troubleshooting page
• Integration doesn't mention napari-imagej
• Initialization --> "with more memory" feels like it is contradicting the "configuring the JVM". Clarify when to use one or the other.
• Make the "Ways to initialize" table fit without horizontal scrollbars
• "Tutorial notebooks" would benefit from an "open in colab" option/better interactivity. Is there a way to embed in RTD?
• Blob detection (interactive) uses napari??
• "Troubleshooting -> Common Errors" would benefit from separation of scope (user, developer)
• Some examples do not use reproducible initialization
• Update examples to not use wsr.imagej.net
• 6.2 is broken?
• All the Ops stuff is ImageJ Ops and should probably be removed
• https://py.imagej.net/en/latest/Cellpose-StarDist-Segmentation.html needs work (version pins)
• Improve headless instructions with subprocess.Popen(["Xvfb", ":99", "-screen", "0", "1024x768x24"]) and a clearer explanation of when headless mode is really needed
• All installation instructions need to be updated to use uv

Related issues:

• Update documentation on colab installation #331
• Add citation info #332

[hinerm]

After discussion, @elevans and I think the best way forward is to rewrite the tutorials as Colab notebooks. This seems like the most stable (sadly) notebook environment available right now, allowing technically non-savvy users to quickly get to the point they can run the notebooks without additional setup

We can then have instructions for transitioning to running these on a local jupyter notebook server (using UV!). We just need to be explicit in those directions.

I have a Starter Python notebook that we can adapt for the tutorials.

As we migrate to Colab we have to consider developing LLM rules

NB: Colab does have GitHub integration, but I think it is for your GitHub account.. so "open in Colab" badges/links are still probably ideal? Maybe there's a way to fork and open a notebook though?

High level goal:

The RTD page itself should be very minimal. It should quickly sort out users to a quick start section to start playing with pyimagej in colab, or direct developers to the API.

[ctrueden]

After discussion, @elevans and I think the best way forward is to rewrite the tutorials as Colab notebooks. This seems like the most stable (sadly) notebook environment available right now, allowing technically non-savvy users to quickly get to the point they can run the notebooks without additional setup

But weren't we just discussing how Colab broke backwards compatibility by updating to Python 3.12? That seems unstable to me. I would caution against relying on Google technology for any of our core materials.

[hinerm]

But weren't we just discussing how Colab broke backwards compatibility by updating to Python 3.12?

It is unstable and yes; Colab does not seem like a suitable environment for scientific reproducibility at this time, and we will make that clear. But to me the point of having notebooks for PyImageJ is to have something that non-developers can come and click and run and learn. Coupled with the chatbot integration to explain and generate code, Colab is the best environment I have found for running Python notebooks without requiring local setup. I see it as the only viable option for newer/less technical users to try using PyImageJ right now.

Even though these notebooks will have Colab linkage, they are still just notebooks and will not be tied to the Colab environment. We will also create dedicated instructions for configuring local environments and running these notebooks locally in ways that are reproducible. But this requires that the user clones the repo locally, manages local environments, etc... and I want to scaffold the instructions building up to that, and give people a chance to try PyImageJ first before investing in this additional learning.

[hinerm]

worth looking into: https://code.visualstudio.com/docs/datascience/notebooks-web

[ctrueden]

I briefly tried running the intro PyImageJ notebook in Codespaces (https://github.dev/imagej/pyimagej; accessible from the GitHub repo by pressing .). It works to click into the doc folder and open the notebook, but actually running cells requires installing the Python extension, which for me today failed with Error while installing 'Python' extension.

So for now, I would say that experience does not beat Colab for usability! 😆

[hinerm]

one thing I didn't try was dedicated links for binder - I used the generic Binder interface which is terrible.

[ctrueden]

I pushed an environment.yml to imagej/pyimagej base directory, so that it works with Binder.

I used environment.yml, rather than requirements.txt or Pipfile, so that Java gets preinstalled in the Docker image, rather than it getting pulled down on demand in every container instance.

One thing that makes using Binder painful is that the first cell execution is very slow (took several minutes for me testing just now), probably due to it pulling down all of Fiji. We should enhance PyImageJ to display a progress bar on the console, like how cjdk does when downloading Java; this will likely necessitate changes in jgo, but it would be a big usability improvement. Another thing we could do is write a Dockerfile for Binder that includes the ~/.m2/repository and/or ~/.jgo cache directories already containing the needed JAR files.

[imagesc-bot]

This issue has been mentioned on Image.sc Forum. There might be relevant details there:

https://forum.image.sc/t/bina-exchange-of-experiences-reflections-and-outcomes-from-aug-25-llm-image-analysis-workshop/116372/1

[imagesc-bot]

This issue has been mentioned on Image.sc Forum. There might be relevant details there:

https://forum.image.sc/t/fiji-friends-weekly-dev-update-thread/103718/115