Introduction into Macro Programming

Macros can be used to

The most important concept when starting to program macros are variables. A variable is a placeholder for a changing entity. It has a name and a value, which can be numeric or text (so-called strings).

Variables are needed whenever you want to execute the same code several times, but for different images, parameters, etc

Variables can also be used to store user input obtained through a dialog.

A variable can be assigned like this:

In this example, factor is the name of the variable, 1024 is the value assigned to the variable. The semicolon tells ImageJ that the assignment is done.

Example: assign text to a variable:

In this case, the variable is named message, and the text Hello, World! is assigned to it; Text is specified inside double quotes.

You can use variables in expressions: you can calculate with numeric variables, and you can concatenate text and text variables. Example:

This assigns the variable x the value 2, the variable y the value 3, and then assigns the variable result the square of x plus the square of y.

This example shows how to concatenate a fixed text with the value of a variable:

Note: a common pitfall is to include the name of a variable in a string. The following code demonstrates this:

(BAD lines are commented out to discourage copying them. If you paste this code in the script editor, you can uncomment these lines to see their errors)

The same principle applies when using variables which reflect parameters passed to a run() method, e.g.

Note: when concatenating strings, whitespace will not automatically be added. So care must be taken, for example when spaces are desired.

When a variable is assigned, the right-hand side is evaluated first, and only then the assignment is performed. This allows you to double the value of a variable:

First, amount * 2 is evaluated. The result is then assigned back to the variable amount, effectively doubling it.

A very important operation is to increment a variable's value by one:

It is so important that there is a short form for it:

Most of the time, you will call functions which implement the actions you want to execute. Functions have names, like variables, but they also have parameters that you can pass to the functions. ImageJ comes with many predefined functions that you can call to perform specific calculations or other operations.

This example writes Hello, World! to the Log window:

As before, a semicolon signifies the end of the statement. The name of the function is write, and the parameter list is enclosed in parentheses. In the case of write, there is only one parameter. If there are more parameters to be passed, they have to be separated by commas:

Like write, newImage is a builtin function of ImageJ. The order of the parameters is relevant, this is the way the function knows what each parameter means.

For recurring tasks, you can define your own functions:

Note that the title is just another variable, which is implicitly assigned when the function is called. In other words, this call will execute the code in above definition, with the variable title set to My pretty new image:

When you read your code again in six months from now, you want to understand what your code does, and why. For this, you can add comments, i.e. text which is ignored by ImageJ when it executes the macro. Example:

Everything after the two slashes up to the end of the line is a comment.

You can also have multi-line comments enclosed in /* ... */ blocks:

When reading macros written by other people, you will often find the concept of commented-out code. This is code that is pretended to be a comment so that it is not executed. Example:

Typical uses for commented-out code are instructions that help with debugging, but are too verbose (or too slow) for regular execution of the macro.

Sometimes, you need to execute a certain part of the code if and only if a certain condition is met. Example:

There are several parts to a conditional block: the if keyword, the condition inside the parentheses, and the code block enclosed in curly braces.

In this case, the condition calls the function is to ask whether the current image is binary, and the exclamation mark negates the result, i.e. !is("binary") yields true if and only if the current image is not binary (as opposed to is("binary"), which returns true in the opposite case).

If the code block consists of only one statement, the curly braces may be omitted, but it is a good practice to keep them (for example, nested conditional blocks are much easier to understand with curly braces than without).

Likewise, it is a good practice to indent the code inside the conditional block (i.e. to add white space in front of the lines inside the block). This makes reading the code much easier, too.

You can optionally add an else clause, i.e. a code block that is executed when the condition is not met. Example:

To repeat instructions several times, loops are used. Example:

This code will run Dilate ten times. The syntax of the for loop consists of the for keyword, followed by three statements enclosed in parentheses, and the code block to be executed.

The three statements defining how often to run the code block are the

In this example, the variable i is first initialized to zero, then the condition is checked, and as i is smaller than 10, the code block is executed. After that, i is incremented, and the condition is checked again. As 1 is still smaller than 10, the code block is executed again. This repeats for the values 2, 3, ..., 9, but after the variable i was incremented from 9 to 10, the condition does not hold true anymore, so the loop is finished.

Even if the counter variable was not used inside the code block in this example, you are free to do so, of course.

Note that starting with 0 and testing for the condition "smaller than 10" will result in the code block being run 10 times. It is the standard way to execute a certain block of code a fixed number of times.

To loop over a stack, one can use the variable nSlices.

Note: The Plugins > Macro > Install... command is an ImageJ 1.x command that does not yet support the SciJava Script Parameters syntax (@) that was introduced with ImageJ2.

Keyboard shortcuts can be defined by adding the key within brackets at the end of the macro name. Example:

By choosing a macro name that ends in Action Tool, you can install new tools into the toolbar:

The icon is defined by a funny-looking string (in this case, C000R11ee). To learn how to define your own icon, please have a look here.

Many tools open an option dialog upon double-click on the icon. You can do that, too, by choosing a name that ends in Action Tool Options:

This section contains a number of macros which you can use as starting points to write your own macros.

If you're interested in performing a certain procedure for all files in a given folder, you might want to have a look a the tutorial How to apply a common operation to a complete directory or at the macro template that you can open in the Script Editor via Templates  › Macros  › Process Folder.

When you need to resize an image but all you know is what width (in pixels) a structure has that you selected as a ROI, this macro is for you:

This macro splits a hyperstack into its individual timepoints, so that you end up with as many new images as the original hyperstack had frames: