update jython wiki tutorial

[nkicg6]

I came across the Jython tutorial on the wiki and noticed a few problems that I would be happy to fix. Starting with https://github.com/imagej/imagej-scripting/blob/master/src/main/resources/script_templates/Tutorials/Wiki_Jython_Tutorial_1.py

1. defs should not be (and are almost never) nested. It is unclear why this would be demonstrated as it is not particularly useful, it is not typically used in python code, and it makes things more confusing, especially for someone who is new to Jython or python.
2. Topics demonstrated in the nested functions can be better demonstrated as individual functions (for example, the string join with a separator)
3. Java interop and javadocs are very confusing if you are not a Java programmer. It is a lot easier to understand if you show the specific javadoc reference then show an example of how to use it to do something useful.

from ij import IJ
# we can use Java classes directly by importing them and then calling them with the constructors 
# (for classes) or arguments (for static functions/methods) defined in Javadocs.
# For example, we imported the IJ class above, so we can create an image with the
# IJ.createImage function https://imagej.nih.gov/ij/developer/api/ij/IJ.html#createImage-java.lang.String-int-int-int-int-
# This can be called just like a python function, and from the docs, we see we need to provide a
# title (string), width (int), height (int), depth (int), and bitdepth (int) and it returns an 
# ImagePlus object (https://imagej.nih.gov/ij/developer/api/ij/ImagePlus.html)

test_img = IJ.createImage("Test image", 512, 512, 1, 8)
# check the type:
print(type(test_img))
# <type 'ij.ImagePlus'>

# you can easily access the fields on this object and call methods to manipulate it 
# (refer to docs https://imagej.nih.gov/ij/developer/api/ij/ImagePlus.html for what is possible) 

width = test_img.width
height = test_img.height
print("test_img is {} wide and {} tall.".format(width, height))
test_img.show()

I have started making changes in my fork, but before I make a large pull request I wanted to know whether there was any interest in cleaning this up/improving this wiki tutorial? If so, I wanted to clarify what general concepts were meant to be covered in the three tutorials so I could tailor the instructions to these topics (if they exist).

I know some work was done on this in the past few years, but I think it can be made more accessible and helpful to beginners with some simple changes. I was a beginner very recently and remember the pain points of Jython and Java interop coming from the python world so I think I can offer a different perspective.

Thanks!

[imagejan]

/cc @m-entrup and @LauLauThom, as they contributed most to the Jython Scripting wiki page and the code here.

I'm not a Python/Jython expert at all, but I agree with your suggestions regarding general best practice in programming.

Improvements to both the wiki page and the code in this repository are most welcome. Please note though that most of the more recent documentation is in https://github.com/imagej/tutorials in the form of Jupyter notebooks using 1) Groovy as the recommended scripting language within ImageJ, or 2) native Python (not Jython) via pyimagej.

[acardona]

Hi Nick, Please keep in mind the target audience: scientists without any formal training in programming, and with zero or very little programming experience. I have received very good feedback over the years about this python tutorial for fiji https://www.ini.uzh.ch/~acardona/fiji-tutorial/ https://www.ini.uzh.ch/~acardona/fiji-tutorial/#imglib2-n5 even though it takes an unconventional approach often. The goal is to get non-programmers to become self-sufficient, not to impose a purist view. Getting things done is the target. That said, under that light any improvements to the Jython Scripting wiki would be wellcome. The last round of big edits some years ago removed a lot of useful examples, pushing them all into https://imagej.net/Jython_Scripting_Examples . Rescuing some of the concepts and libraries introduced in those examples would be great. Best, Albert

Missatge de Jan Eglinger notifications@github.com del dia dc., 29 de gen. 2020 a les 9:50:

/cc @m-entrup https://github.com/m-entrup and @LauLauThom https://github.com/LauLauThom, as they contributed most to the Jython Scripting wiki page and the code here.

I'm not a Python/Jython expert at all, but I agree with your suggestions regarding general best practice in programming.

Improvements to both the wiki page and the code in this repository are most welcome. Please note though that most of the more recent documentation is in https://github.com/imagej/tutorials in the form of Jupyter notebooks using 1) Groovy as the recommended scripting language within ImageJ, or 2) native Python (not Jython) via pyimagej.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/imagej/imagej-scripting/issues/34?email_source=notifications&email_token=AAAMKGW66DFXMA7Y5I3XXTDRAFGPJA5CNFSM4KM7EAHKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEKGS2RI#issuecomment-579677509, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAMKGSIMEJ2QYVFA5EP6VLRAFGPJANCNFSM4KM7EAHA .

[LauLauThom]

Hi all, great to hear that you would like to contribute ! As far as I am concerned, I added a few section to this page, mostly about IJ-OpenCV. I did not touch the previous examples but indeed they are first too long, and some show bad practices like you mentioned. Splitting in smaller examples would be great!

Personally, I preferred the code formatting offered by the wiki page rather than going through GitHub. I know that with GitHub we have nice tracking of changes but the wiki also has this functionality. Especially you get notified of any further changes to any pages you ever edited, no need to activate notifications like on GitHub.

Also with the wiki we can easily alternate with small code blocks and wiki explanations. I think this would improve readability, over a massive code from GitHub that has both the code and the documentation. Also the wiki allows to edit only fractions of the page rather than the full page, by clicking [edit] next to any subtitle of a page. The best to get started with the wiki is to go all the way down the page where you should find an option to login. Once logged in, the [edit] should appear next to the titles. Just pick one paragraph that is nicely formatted to use as example, or edit the full page if you want to see the diversity of formatting options. No worries if it's not perfect we can always polish after you, the wiki can be frustrating initially.

About Jan's comment, I feel like the jupyter notebook do not have a lot of visibility, and to my mind they rather target advanced users. At least for Jython, I feel like contributions should go to the existing wiki page rather than a separate jupyter notebook in some n-th repository 😂

One important point, many scripting practices are shared between the scripting languages like https://imagej.net/Scripting_basics Therefore I think one could add links to those generic scripts on the Jython page, and maybe highlight a bit-more jython specific cases in details on this dedicated page.

[m-entrup]

Hi all, for me it's fine if you start improving the "Jython Scripting" wiki page. As I switched from image processing in physics to web development (a system engineering framework), I do not use ImageJ any more and can't contribute to the changes.

When creating the current Jython Scripting I decided not to edit the old one but start from scratch. In my opinion it was not useful to have a duplicate of Scripting basics in Jython. Therefore, I created some more complex examples that use functionalities of Jython that are not available in other scripting languages. By adding links to recourses that explain the used functionalities the reader should be encouraged to read about python/jython. Looking at this code today, I see that it contains bad practices. But when I wrote them I was not that experienced with python and influenced by years of programming in Java.

Feel free to change the wiki page as you like.

[nkicg6]

Thank you all for your input. @acardona I want to emphasize that I am definitely not simply trying to enforce best practices in python for the wiki page.

The goal is to get non-programmers to become self-sufficient, not to impose a purist view. Getting things done is the target.

I absolutely agree, this is also my goal for making any changes. Your tutorial is certainly one of the most helpful out there and a standard for learning Jython scripting. In terms of making people without programming backgrounds more self sufficient, this is primarily what I wanted to work on, as this is where I have recently come from. The hardest part of learning to script workflows with FIJI/Jython was doing something that was not covered in a tutorial or on stackoverflow. I did not know how Java worked (and neither does anyone I regularly work with) and it took me years to figure out how to read javadocs and get a good enough handle on the API to do something new. Looking back, if this process was spelled out somewhere I think I could have figured it out a lot earlier. What I really want to add is a few examples of referring to javadocs to understand how to work with classes and methods to do simple things. I think teaching people how to read the API would be very helpful to a beginner on the home page of the wiki.

@LauLauThom I was hesitant to edit the wiki page because I don't want to break anything and wanted some kind of approval before pushing a change, but if you say so I will add a few quick examples to explain what I mean this weekend. How is communication and feedback handled when editing the wiki directly?

@m-entrup I agree, it is not useful to re-cover basics and I do appreciate the examples you added, they exposed some features and methods I did not know about! Any changes I would make to your examples would simply be to clarify things for someone who is proficient, but not an expert. Thank you for the work you put into that.

Nick

[imagejan]

@nkicg6 wrote:

How is communication and feedback handled when editing the wiki directly?

I suggest you create a new forum topic in the Websites category, tagged with imagej and wiki. (The Discussion/Talk functionality of the wiki is essentially unused and not recommended.)

[LauLauThom]

@nkicg6 You make a good point about the Javadoc. I'm thinking that we could make a dedicated wiki page about "How to work with the Javadoc/API", then we could add it to a new menu entry in "Scripting". EDIT: I just added it. Feel free to complete it ;)

About communication, there is no real validation of the changes, they are directly visible :D Usually one of us is notified of the changes and might correct a few things if necessary. You can leave a small "commit"-like message for the changes, that helps to figure out the changes in the history ;)

[ctrueden]

@LauLauThom wrote:

I feel like the jupyter notebook do not have a lot of visibility, and to my mind they rather target advanced users.

That is unfortunate, because they are intended to be the first entry point into learning the ImageJ API. That is why they are organized in a numbered "book" style order, and linked as the very first thing from https://imagej.net/Scripting#Getting_started and https://imagej.net/Development#Quick_start. The target audience is not advanced scripters or programmers, but rather those just getting started with ImageJ scripting, who want to learn about it from the "ground up." Suggestions are very welcome for organizing all these materials in a better way.

[nkicg6]

@LauLauThom wrote:

You make a good point about the Javadoc. I'm thinking that we could make a dedicated wiki page about "How to work with the Javadoc/API", then we could add it to a new menu entry in "Scripting". EDIT: I just added it. Feel free to complete it ;)

Thank you for getting that started! I will add an example now and work on it more over the weekend. I just started a topic in the forum to continue this discussion so others can get involved like @imagejan suggested. https://forum.image.sc/t/add-working-with-imagej-api-section-to-jython-scripting-tutorial-on-wiki/33523

closing this for now, thank you all for your feedback and help.