Introduction GUI Macro Language Plugin Programming Conclusions Resources
ImageJ / Fiji Short Introduction into Macro and Plugin Programming ZOI Friday seminar
B. Kov´aˇr
Department of Image Processing Institute of Information Theory and Automation
21. ´unora 2014 Introduction GUI Macro Language Plugin Programming Conclusions Resources Contents
1 Introduction
2 GUI
3 Macro Language
4 Plugin Programming
5 Conclusions Introduction GUI Macro Language Plugin Programming Conclusions Resources
ImageJ: successor of a software from the National Institutes of Health called NIH Image (Pascal-based, Mac only, early 90’s) • Public Domain – source code available, • Java based – Win, Mac, Linux, ... , • Macros & plug-ins, • Huge potential, very active community, • Technical design limitations (15 yrs. old design), • ⇒ ImageJ v2
ImageJ requires a Java runtime installed, can update itself and is shipped with small, generic set of Plugins and Macros...
ImageJ basically can do everything, it’s just sometimes very hard to find out how... Introduction GUI Macro Language Plugin Programming Conclusions Resources
Fiji – FijiisjustImageJ – ”ImageJ (batteries included)” • FiJi is an ImageJ distribution intended for Life sciences, • Huge set of Plugins, • Powerful update mechanism, • Extensive documentation, tutorials, etc., • But: shares ImageJ’s limitations. Introduction GUI Macro Language Plugin Programming Conclusions Resources
ImageJ • Generic image processing framework - unfocused
FiJi • Aimed for Life Sciences, • Emphasis on Registration, Segmentation & Volume Data, • Community development effort, • Quality mechanisms for plugins, • Support for more additional languages: Python, Ruby, Scala ..., • Script editor to develop plugins and macros. Introduction GUI Macro Language Plugin Programming Conclusions Resources Contents
1 Introduction
2 GUI
3 Macro Language
4 Plugin Programming
5 Conclusions Introduction GUI Macro Language Plugin Programming Conclusions Resources
The main window has three parts: 1 Menu bar 2 Tools 3 Status line • ImageJ & Java version • Memory architecture & current usage • Pixel positions and intensities while hovering on images • Descriptions of toolbar entries • ... Introduction GUI Macro Language Plugin Programming Conclusions Resources Contents
1 Introduction
2 GUI
3 Macro Language
4 Plugin Programming
5 Conclusions Introduction GUI Macro Language Plugin Programming Conclusions Resources
Macros can be used to • automate repetitive tasks • document what you did • share common procedures • provide consistency in your analysis • scripting languages (build-in, javascript, python, . . . )
A Macro is a program that automates a series of ImageJ commands. ImageJ has a dedicated programming language for this. Introduction GUI Macro Language Plugin Programming Conclusions Resources Introduction GUI Macro Language GettingPlugin Programming StartedConclusions Resources
The obligatory “Hello World” code: The obligatory ”Hello World”code:
macro "hello" { print("Hello World!"); }
Running this opens a new window “Log” showing the message:
→ print() is useful for debugging
Niko Ehrenfeuchter 6 ImageJ / FiJi workshop Imaging Core Facility Introduction GUI Macro Language Plugin Programming Conclusions Resources
Variables &Variables Strings & Strings The most important concept: a named piece of memory! The most• importantName and concept: value a named piece of memory! – Name and value –•ValueValue can can be benumeric numeric or text or text –•CanCan be be used used in arithmetic in arithmetic expressions expressions or string or combinations string combinations – Variables & Strings x = 2; y = 3; Self-references in expressions: result = x * x + y + y; amount = amountVariables * 2; & Strings namecounter = "Bob"; = counter + 1; msg = "Those days are over, " + name; Self-referencesprint(msg); in expressions:
Short-handamount for increment:= amount * 2; counter = counter + 1;
Niko Ehrenfeuchter 7 counter++; ImageJ / FiJi workshop Imaging Core Facility
Short-hand for increment:
counter++;
Niko Ehrenfeuchter 8 ImageJ / FiJi workshop Imaging Core Facility
Niko Ehrenfeuchter 8 ImageJ / FiJi workshop Imaging Core Facility Introduction GUI Macro Language Plugin Programming Conclusions Resources
Parameter input by user getNumber() can be usedParameter to request a numericalinput by input user by the user, getString() for text. getNumber() can be used to request a numerical input by the user:
macro "input_print_out_calc" { a = getNumber("a?", 10); b = getNumber("b?", 5); c = a*b; print("\\Clear"); print(c); }
Note: if no number is entered, no assignment will take place.
getString() for text: a = getString("b?", 5);
Niko Ehrenfeuchter 9 ImageJ / FiJi workshop Imaging Core Facility Introduction GUI Macro Language Plugin Programming Conclusions Resources
Running ImageJ commands Crucial element for macros: run ImageJ commands 1 Almost all commands can be run from macros 2 A few Plugins are not macro-ready Most convenient way to find the corresponding macro commands is to use the built-in Macro Recorder: Introduction GUI Macro Language Plugin Programming Conclusions Resources
Batch processing To apply a macro or multiple macro commands to many files, you could add file-accessing and looping commands or use the Batch Process tool. Introduction GUI Macro Language Plugin Programming Conclusions Resources
Looping Looping Loops areLoops required are required to iterate to a iterate certain a part certain of our part macro. of our macro.
macro "loop1" { msg = getString("message to loop?", "default"); for(i=0; i<5; i+=1) { print(i + ": " + msg); } }
Niko Ehrenfeuchter 12 ImageJ / FiJi workshop Imaging Core Facility Introduction GUI Macro Language Plugin Programming Conclusions Resources
Stack-processingStack-processing with loops with loops One very powerful application of loops is stack processing since manyOne ImageJvery powerful commands application work of loops just onis stack a single processing slice. since To work many on all slicesImageJ the “nSlices” commands and work “setSlice” just on a single commands slice. To are work used: on all slices the “nSlices” and “setSlice” commands are used:
macro "Measure Avg Intensity Stack" { frames=nSlices; run("Set Measurements...", " mean redirect=None decimal=4"); run("Clear Results"); for(i=0; i Niko Ehrenfeuchter 13 ImageJ / FiJi workshop Imaging Core Facility Introduction GUI Macro Language Plugin Programming Conclusions Resources Conditional statements If–else statements can be used to run a certain part only if one or more conditions are met. Note the ”==”in the condition (a comparison operator),Conditional this is different from statements a single ”=”(assignment). Other comparison operators are: < , <= , > , >If–else= , ! =statements can be used to run a certain part only if one or more conditions are met: num = getNumber("Number:", 3); if (num == 3) { print(num + ": default value"); } else { print(num + ": value changed"); } Note the “==” in the condition (a comparison operator), this is different from a single “=” (assignment). Other comparison operators are: < , <= , > , >= , != Niko Ehrenfeuchter 14 ImageJ / FiJi workshop Imaging Core Facility Introduction GUI Macro Language Plugin Programming Conclusions Resources User-defined functions User-defined functions WhenWhen macrosmacros becomebecome moremore sophisticated,sophisticated, it is is very very likely likely that that some parts somewill parts appear will multiple appear times. multiple These times. parts These should parts be shouldplaced bein separate placed in separatefunctions functions to avoid redundancy to avoid redundancy and improve and readability: improve readability: User-defined functions function CheckStack() { if (nSlices==1) { When macros become more sophisticated, it is veryexit("Image likely that is somenot a partsstack"); } will appear multiple times. These parts should be placed in separate macro “threshold check” { } functions to avoid redundancy and improve readability: CheckStack(); CheckThreshold(); function CheckThreshold() { getThreshold(lower, upper); getThreshold(lower, upper); } if ((lower==-1) && (upper==-1)) { function CheckStack() { exit("Must be thresholded"); if (nSlices==1) { } exit("Image is not a stack"); } } macro “threshold check” { } CheckStack(); CheckThreshold(); function CheckThreshold() { getThreshold(lower, upper); getThreshold(lower, upper); Niko Ehrenfeuchter 15 } ImageJ / FiJi workshop if ((lower==-1) && (upper==-1)) { Imaging Core Facility exit("Must be thresholded"); } } Niko Ehrenfeuchter 15 ImageJ / FiJi workshop Imaging Core Facility Return values Introduction GUI Macro Language Plugin Programming Conclusions Resources If your function does some calculation, you need a way to hand back the Return valuesresult to the code that called the function: Return values If your function does some calculation, you need a way to hand If your function does some calculation, youback need the result a way to the to codehand that back called the the function: result to the code that called the function: macro “function add” { function ReturnAdd(n, m) { a = 1; p = n + m; b = 2; return p; result = ReturnAdd(a, b); } print(result); } macro “function add” { function ReturnAdd(n, m) { a = 1; p = n + m; b = 2; return p; result = ReturnAdd(a, b); } print(result); } Niko Ehrenfeuchter 16 ImageJ / FiJi workshop Imaging Core Facility Niko Ehrenfeuchter 16 ImageJ / FiJi workshop Imaging Core Facility Introduction GUI Macro Language Plugin Programming Conclusions Resources Advanced dialogues If multiple values andAdvanced settings need todialogues be requested from the user, it is easier to use a ”Dialog”for this task: If multiple values and settings need to be requested from the user, it is easier to use a “Dialog” for this task: Dialog.create("input dialog"); Dialog.addMessage("my description"); Dialog.addNumber("value 1:", 0); Dialog.addNumber("value 2:", 0); Dialog.addCheckbox("really?", true); Dialog.show; val1 = Dialog.getNumber(); val2 = Dialog.getNumber(); really = Dialog.getCheckbox(); Niko Ehrenfeuchter 17 ImageJ / FiJi workshop Imaging Core Facility Introduction GUI Macro Language Plugin Programming Conclusions Resources Installing Macros Macros are recognized by ImageJ from the following filename suffixes: • *.IJM (preferred) • *.TXT (deprecated) Code files with the txt-suffix need to have an underscore in their name, otherwise ImageJ ignores them. The macro code files need to be placed in a sub-directory inside the ImageJ base directory: 1 macros 2 plugins (preferred) Introduction GUI Macro Language Plugin Programming Conclusions Resources Contents 1 Introduction 2 GUI 3 Macro Language 4 Plugin Programming 5 Conclusions Introduction GUI Macro Language Plugin Programming Conclusions Resources Plugins: when macros are not enough . . . Macros are quick and easy to record or write, but • Slooooow, • Waste memory for more complicated tasks, • Cannot use the full functionality of ImageJ, only what the built-in functions offer, • Run always in foreground, blocking the computer, Plugins are a much more powerful concept than macros and most of ImageJ’s built-in menu commands are in fact implemented as plugins. Plugins are implemented as Java classes, which means that you can use all features of the Java language, access the full ImageJ API and use all standard and third-party Java APIs in a plugin. Introduction GUI Macro Language Plugin Programming Conclusions Resources What does a plugin consist of? Plugins are .jar files (really .zip files with a certain structure), containing: • one or more Java class(es) implementing the functionality, and • a plugins.config file defining which menu entries offer the functionality. • optionally additional resources required by the plugin, such as images or icons. If the plugin is implemented in one Java class, and it offers only one menu entry in the Plugins menu, it can be offered as bare .java or .class file, too. Introduction GUI Macro Language Plugin Programming Conclusions Resources Installing plugins Plugins can be installed manually by copying the .jar file into the plugins/subdirectory of Fiji and by updating the menus using Help − > Update Menus. There are two easier ways, though: 1 Plugins − > Install PlugIn... 2 Or drag ’n drop the .jar file onto the Fiji main window. Introduction GUI Macro Language Plugin Programming Conclusions Resources Plugin development For writing new plugin programs, we also need text editor and Java compiler. The Java runtime environment (JRE) contains both, so no additional software is required to get started. It’s highly recommended to use one of the freely available integrated Java programming environments, such as Eclipse, InteliJ IDEA or NetBeans. Introduction GUI Macro Language Plugin Programming Conclusions Resources Types of Plugins There are basically three types of plugins: • those that do not require an image as input (implementing the interface PlugIn) • plugin filters, that require an image as input (implementing the interface PlugInFilter). • and PlugInFrame – a plugin that runs in its own window. Introduction GUI Macro Language Plugin Programming Conclusions Resources Images and Processors While the ImageJ API makes it easy to worj with images on the programming level, their internal representation is fairly complex. Introduction GUI Macro Language Plugin Programming Conclusions Resources Contents 1 Introduction 2 GUI 3 Macro Language 4 Plugin Programming 5 Conclusions Introduction GUI Macro Language Plugin Programming Conclusions Resources • ImageJ is a particularly flexible image-processing package that is a free, open source • The program will run on all computer platforms • ImageJ claims to be the fastest pure Java image processing program; it is capable of filtering a 2048x2048 image in 0.1 seconds (according to the ImageJ website) • ImageJ’s intended purpose is medical image processing, but it works very well in other context. • The software has a particular emphasis on analysis and incorporates a number of tools for measuring images. • As a result functions are often more mathematically “transparent” than in commercial packages such as Adobe Photoshop. • A well-developed “plugin” interface allows for customization. • A very active user community has contributed dozens of freely available plugins. • A “macro” interface allows tasks to be recorded and automated. Introduction GUI Macro Language Plugin Programming Conclusions Resources Resources 1 ”The Bible”- ImageJ user’s guide: http://rsbweb.nih.gov/ij/docs/guide/ 2 ImageJ dokuwiki: http://imagejdocu.tudor.lu/ 3 ImageJ macros: http://imagej.nih.gov/ij/macros/ 4 ImageJ mailing list: http://rsb.info.nih.gov/ij/list.html 5 ImageJ plugins: http://rsb.info.nih.gov/ij/plugins/index.html 6 FiJi download: http://fiji.sc/wiki/index.php/Downloads 7 FiJi wiki containing documentation for plugins, tutorials, etc: http://fiji.sc/wiki/