Include a headless scripting example that uses macros and Fiji plugins

[AdamDHines]

Added two minimal code working examples of using ImageJ macros in headless operation, one with and without Fiji plugins. This was added to the Headless.md document. I have the example_stack.tif available to share/upload for others to test with.

[elevans]

Hi @AdamDHines. Thanks for this PR and your additions to the documentation. I took a look at your sections and I think this content is already covered by jupyter tutorial notebook 07-Running-Macros-Scripts-and-Plugins. Do you agree or am I missing something? I think we can improve notebook 7 however. Your Fiji plugin example would be a nice addition...I'm pretty sure I have some jittery data to use that will be interesting to look at.

[AdamDHines]

Thanks for looking into it @elevans, I disagree that doc 7 covers functional headless operation. Whilst the macro example used in 7.1 is headless, it doesn't use any images. My examples explicitly described the process of converting Dataset to ImagePlus and then using imp.show() to get macros to operate on images in headless mode. The scripting example in 7.2 I suppose covers this, but requires Groovy scripting whereas I feel my examples are simpler/more minimal. When trying the process of running macros on images for 7.3, the ij.WindowManager.getCurrentWindow() method fails to detect any open images using my method.

For example, this doesn't work:

# initialize ImageJ with Fiji plugins
import imagej
ij = imagej.init('sc.fiji:fiji:2.13.1')

# open example .tif stack
img = ij.io().open('/Users/adam/data/example_stack.tif')
current = ij.WindowManager.getCurrentImage()
print(current)

Operating in headless mode - the original ImageJ will have limited functionality.
Operating in headless mode - the WindowManager class will not be fully functional.
None

I don't have any insight into why Blobs works differently, maybe because it's a built in sample dataset?

[ctrueden]

@AdamDHines The headless issues you are talking about are relating to the original ImageJ (not ImageJ2) and are covered by section 11 of the tutorials. That said, section 11 needs some updates and improvements in this area. For example, the note that calling imp.show() is needed to activate an ImagePlus in headless mode is buried in section "11.7 Running ImageJ macros", and furthermore there is still an obsolete paragraph "Warning: There is currently a bug where show() triggers a java.awt.HeadlessException" but this bug is fixed in newer versions of ImageJ2, and IMHO should be removed from the PyImageJ docs.

Hopefully you and @elevans can work together to sort out how to improve sections 7 and/or 11 to include the needed information in an intuitive way. For example, perhaps section 7 should have a link to section 11 as a heads up regarding original-ImageJ-related headless issues?

[AdamDHines]

Thanks @ctrueden, I take your points - I wasn't aware it was in the documentation. I agree with adding links and thinking about how to make it more intuitive, I'm coming from the perspective of somebody that recently tried (and failed!) to get headless macros to work. I still think it's more intuitive to have some actual script examples in the Headless section, as that's where I first went to look at the beginning.

@elevans, if we removed my first macro running example would you then like to see the Fiji plugins example expanded a bit? I can make some edits and new commits to provide some links in other docs the working with original ImageJ section.

[elevans]

Hi @AdamDHines Its 2024 and I've finally have time to come back to come back to this. Since this PR has been open I've made some extensive changes to the PyImageJ documentation. If you are still interested and have the time, do you think you could check out the latest docs? If you think there are some improvements to be made, thats great. Otherwise I'll close this PR. Thanks!

[elevans]

The PyImageJ documentation has been updated since this PR has been opened and I feel it sufficiently covers headless operation.