Usage

How do I apply an operation or macro to multiple images?

What is the largest size image that ImageJ can open?

There is a 2 gigapixel limit when opening and displaying image planes using the ImageJ 1.x user interface's default image viewer. However, one major goal of the ImageJ2 project is to break this limit. ImageJ2 uses the ImgLib2 library as its data model, which has much larger limits on the number of pixels (theoretically: ~2^63 per dimension, up to ~2^31 dimensions, totaling ~2^63^31 pixels). Hence, you can open larger images using the ImageJ2 API. But you will not be able to display them in the user interface yet.

Furthermore, the SCIFIO library (what ImageJ2 uses for data I/O) supports opening such images on-demand as "cell images" such that blocks are read from disk as you iterate over the image. This is similar to (but more powerful than) ImageJ 1.x's virtual stacks feature. In this way, you can write code to process these large images without displaying them.

The Fiji project also includes the BigDataViewer (BDV) plugin, which currently functions as an alternative viewer, to display arbitrarily large images backed by ImgLib2. In the future we hope to integrate BDV-driven UI technology more completely into ImageJ core. But there are a couple of limitations right now:

BDV was originally designed for large SPIM data; opening large image files more generally currently requires some coding. But we want to change this.

Many ImageJ 1.x plugins assume the data is stored in an ImageJ 1.x data structure, which is not what BDV uses. So "mixing and matching" IJ1 and IJ2 functionality is tricky here. But we are working to lift these restrictions as time goes on.

Mac OS X

How do I set up Java 6 on OS X?

Note: It should no longer be necessary to reinstall Java 6 on OS X. ImageJ should work fine with Java 8.

Alternately, if you are a developer looking to install the Java 6 Development Kit, you must log in to Apple Developer downloads with your Apple ID, search for "java for os x" and download the latest package ("Java for OS X 2013-005 Developer Package" at the time of this writing).

At any time, you can verify which Javas are installed on your system using this script.

Note however that, per the limitations of --java-home, you will have to jump through some hoops in order to run ImageJ with Java 6 if you also have Java 7 and/or 8 installed.

How do I run ImageJ on El Capitan?

If that does not work, see this guide for steps which could get things working again.

Alternately, ImageJ still works on El Capitan with Java 6 (see above).

Running

How do I launch ImageJ with a different version of Java?

On Windows

Install Java 8, and delete or rename the ImageJ.app\java and/or ImageJ.app\jre folders, if they exist. If this does not result in Fiji using the expected Java version, check the Environment Variables ( Control Panel ▶ System and Security ▶ System ▶ Advanced Settings ▶ Advanced ▶ Environment Variables) for the variable "JAVA_HOME". Update or create this variable as needed; its value should be the desired JDK or JRE that you would like to use for Fiji (for instance: "C:\Program Files\Java\jdk1.8.0_51"). See also Java environment variable setup.

On OS X

Note: the --java-home flag does not support Apple Java installations. Specifying Apple Javas with this flag will give an error message about being unable to find lib/server/libjvm.dylib. However, Fiji will fall back to Apple Java if no other Java installations are available.

In particular, this means that to run Java 6 on the latest OS X versions, you must do ONE of the following:

On Linux

One downside of doing this is that ImageJ will launch in a separate process, which has some unintuitive side effects. For example, Ubuntu's Unity user interface will not allow you to "Pin to Launcher" in this case...

How do I setup a launcher app for OS X for running with a different JVM version?

Start Automator and select to create an Application. Double-click Run Shell Script in the Library/Utilities folder and replace the text content — cat — with the following:

What is this headless mode and what do I need it for?

The term headless refers to running ImageJ without a graphical desktop, e.g. on a cluster. See the Headless page for more information.

Installing/Updating

How can I verify that my ImageJ is really 100% up to date?

ImageJ will report itself as "up to date" as long as all files installed in your ImageJ match the latest versions from the remote update sites. However, there are cases where your ImageJ may report itself as "up to date" but still be missing critical files, or have mismatching versions (e.g., the dreaded "NoSuchMethodError").

To be certain, run Help ▶ Update..., and click the "Advanced mode" button. Then verify the following View Options:

View uninstalled files only: Shows files that are available from remote ImageJ update sites, but not installed in your ImageJ. Consider changing the "Status/Action" to "Install" for these items, especially any .jar files that are flagged with "Not installed" status.

View locally modified files only: Shows files that have been edited locally (i.e., do not match any version from the remote update sites). Consider changing the "Status/Action" to "Update" for these items, especially any .jar files that you did not intentionally modify.

View local-only files: Shows files that are not known at all to the remote update sites. These files were likely added manually (e.g., if you installed additional plugins manually; see "How do I install additional plugins" below). Consider deleting these files if you do not need them, especially any .jar files of unknown origin or conflicting file names.

If you flag any changes to be made, press the "Apply changes" to update your ImageJ. And after restarting ImageJ, you might want to run Help ▶ Update... again to make sure everything looks the way you expect!

How do I install additional plugins?

If the plugin is published on an ImageJ update site, you can run Help ▶ Update then click the Manage update sites button to enable it. Not only does this install the plugins for you automatically, but you will also be notified of any updates whenever they are released.

Otherwise, you can drag 'n drop the .jar files onto the ImageJ window, or use Plugins ▶ Install Plugin... with .jar, .class and .java files, or copy the plugins to ImageJ.app/plugins/ and restart ImageJ. See the walk-through with screenshots.

How do I downgrade ImageJ?

Downgrading is generally not recommended as a longterm solution, but can be handy to avoid new bugs that crop up.

If you need to downgrade to avoid a critical bug, please report that bug to the developers so that it can be fixed in a future version!

You can change the version of ImageJ 1.x used via the Help ▶ Update ImageJ... menu item. This only changes the version of ImageJ 1.x—not all ImageJ components, plugins, etc.

Lastly, if you have not yet upgraded, and have a currently working configuration, you can make a backup copy of your ImageJ folder before upgrading. Then if the upgrade has undesirable consequences, switch back to the old copy.

My plugin runs fine in the Script Editor, but it does not show up in the menus when I install it. What's wrong?

To be picked up as a plugin, the .jar's file name must contain an underscore, and it either needs to contain an appropriate plugins.config file or the class name needs to contain an underscore, too.

The safest way to ensure these conventions is to use the File ▶ Export as .jar file menu item.

I tried to update ImageJ via Help ▶ Update, but it throws an exception instead?

The easiest way to get back a functional updater is to import this URL via File ▶ Import ▶ URL....

If that does not work, please delete the files ij-ui-swing-updater-2.0.0-SNAPSHOT.jar, ij-updater-core-2.0.0-SNAPSHOT.jar and ij-core-2.0.0-SNAPSHOT.jar from the ImageJ.app/jars/ directory (MacOSX users, ^ Ctrl+click on the ImageJ icon and select Open Package Contents and open the jars/ directory you see there). After that, the Updater should magically repair itself.

I updated ImageJ via Help ▶ Update, and now it does not start anymore!

The Updater always says Connection refused. Maybe it does not use the proxy?

Indeed, an earlier version of the Updater does not use your system-wide network proxy settings. This is fixed in the meantime, but you need to update the updater using this script (just download it and open it in ImageJ).

Compatibility

What is the difference between ImageJ1 and ImageJ2?

ImageJ1 is an extensible platform for scientific image analysis. ImageJ2 is redesigned from the ground up to meet the same needs, yet engineered with future-proof flexibility to adapt to researchers' growing requirements (new data types, higher dimensionality, huge images, etc...).

Will ImageJ1 macros, plugins and scripts still work in ImageJ2?

Yes. We are completely committed to 100% backwards compatibility with ImageJ1. ImageJ2 includes the latest version of ImageJ1 "under the hood" so that existing macros, plugins and scripts will still run the same as before.

ImageJ2 user interfaces are just plugins; ImageJ2 runs with the "ImageJ1 legacy UI" by default. But we have also created a new ImageJ2 user interface modeled after ImageJ1 to a very large extent, with all the same shortcut keys and behaviors whenever possible. Either way, ImageJ2 looks and feels like ImageJ1, but with a powerful new infrastructure allowing it to process a wider variety of image data more quickly and easily.

The ImageJ1 macro language has been extremely useful to many users. However, it has a substantial limitation: its functions are separate from those available from Java and the other scripting languages.

In ImageJ2, the goal is to provide one unified set of functions, which is fully accessible from Java and all scripting languages. Hence, ImageJ2 plugins and scripts are more flexible than ImageJ1plugins and macros. They can run headless on a server, and are accessible from various applications such as CellProfiler, KNIME, OMERO, and headless from the command line. We would encourage newly developed scripts and plugins to use the ImageJ2 API since it offers these advantages, but the ImageJ1 API will remain accessible, too.

Can I call ImageJ1 API from an ImageJ2 command?

Yes, although it is not recommended. You will lose most of the advantages of ImageJ2 if you embed calls to ImageJ1 within your command. ImageJ1 is rather tightly coupled to AWT and hence does not work well headless. For details, see the Headless page.

How do I install Fiji?

How do I turn my ImageJ installation into a Fiji one?

Fiji is just ImageJ. If you are running ImageJ2, simply run Help ▶ Update, click Manage update sites, and enable the Fiji update site.

Or if you are running ImageJ1, you can bootstrap the updater by drag 'n dropping this link onto your running ImageJ and run the Javascript that was opened in a text window. After that, you can run Fiji/ImageJ using the ImageJ launcher that was installed into the ImageJ directory.

An increasing number of plugins use features of ImageJ2, which are not available in ImageJ 1.x.

If you install multiple plugins with complex dependency chains in this manner, you may have dependency version conflicts. For things to work, you will need to ensure that all the library versions are compatible. The Fiji maintainers have already solved this problem for the Fiji distribution.

So you could save yourself a lot of pain by using Fiji instead.

That said, you can install a Fiji plugin in a vanilla ImageJ 1.x installation, as long as you copy all its dependencies with it. You can do this as follows:

Interoperability

How can I call ImageJ from MATLAB, or vice versa?

Development

Why do I get a NoSuchMethodError/NoSuchClassDefFoundError when running a rebuilt plugin?

This is most likely caused by version skew, i.e. when an incompatible version of a build dependency is installed. Example: if you build against mpicbg-1.0.0.jar and run that plugin in a Fiji which has only installed mpicbg-0.6.1.jar, the latter might miss some methods or classes, or even contain incompatible class definitions.

To investigate, you can use mvn dependency:copy-dependencies on the command-line (to copy all build dependencies into target/dependency/) and then use your favorite Zip tool to look for the class name mentioned in the exception. In Eclipse, you can simply use Ctrl+Shift+T (or Command+Shift+T on MacOSX) to look open the respective class; If a recent enough Eclipse is used, and the default settings have not been tampered with, this will start downloading and show the source attached to the dependency.

Once you know which dependency is supposed to contain the class/method, compare the version number of the file(s) in ImageJ.app/plugins/ and ImageJ.app/jars/.

Sometimes, classes are contained in multiple .jar files. This is a frequent source of problems e.g. when some developers try to be helpful and include dependencies' classes into their plugin .jar files. This is a problem because those class files are naturally not updated when the dependency is installed as a proper, separate .jar file and updated. To investigate such issues, use the Find Jar For Class command in Fiji, to determine which .jar file serves the class you are looking for.

What is Maven, and why did you pick it?

Maven is a system to build .jar files from source code, and to manage dependencies (i.e. it is easy to specify which minimal version of, say, ImageJ is required by the source code).

We picked it because we need a standard way to interact and collaborate with other projects and with each other. For starters, it allows developers to stay with their favorite development environment (Eclipse, Netbeans, IntelliJ, etc).

Class loading issue in 3-rd party libraries (e.g. JPPF)

Libraries trying to load resources or classes with the current thread's class loader rather than with IJ's class loader may fail. The solution is to first set the current thread's class loader to the IJ-classloader. This must be done from the same thread that will later call the problematic code:

Thread.currentThread().setContextClassLoader(IJ.getClassLoader());

How do I see the source code for a command?

ImageJ is open source; as such, it is possible to inspect the source code for any command, in the interest of transparency and reproducibility.

This method requires that you know in which repository the code lives. However, you can combine it with search.imagej.net method above to figure out which repository, then load the code on GitHub, if desired.

Using the "Open Source for Menu Item" command:

Run Plugins ▶ Scripting ▶ Open Source for Menu Item.

Unfortunately, you must select this from the menu, not using the Command Finder.

Run the command whose source you want to see.

E.g., Process ▶ Binary ▶ Make Binary.

Again, select it from the menu directly, not using the Command Finder.

In the future, we plan to make this easier by having one single easy command for viewing the source code.

What are "external" plugins?

As far as users are concerned, external Fiji plugins are exactly the same as internal Fiji plugins. For developers, "external plugin" simply implies that the plugin's source code is maintained in its own source code repository. For example, TrakEM2 has been an external Fiji plugin since Fiji's inception.

Where should I put the jars of my plugin?

If you develop a Fiji plugin, the result will be in the form of one or more jars containing your plugin and possibly third-party libraries that you rely on. To deploy your plugin you put the jars in the plugins/ or jars/ Fiji subdirectories. The general idea is that only the jars directly containing plugin classes go into plugins/. Auxiliary and third-party jars go into jars/. (see this mail for more background on this.)

How can I call ImageJ from my software?

If your software is written in Java, we recommend using Maven to structure your project. You can then add dependencies to portions of ImageJ that are of interest to you. See the ImageJ tutorials for examples.

In some cases, use of this JAR file is appropriate and convenient; for example, CellProfiler uses it to integrate with ImageJ. However, you should consider carefully what would be best for your project; see the Uber-JAR page for further information.

Does ImageJ work on mobile devices such as Android?

Not yet as an end-user application. But since Android is a Java-based platform, there is hope. One of the ImageJ2 project's central design goals was a better separation of concerns, which could make things like an Android version of ImageJ possible. In particular, the core components of ImageJ2 are militant in their avoidance of certain Java SE packages not present in the Android version of Java (which is based on Java ME), such as Java AWT.

That said, ImageJ2 has not even been compile-tested yet using an Android SDK, so there are surely many problems which would need to be resolved. In the future, the ImageJ development team hopes to set up some continuous integration surrounding Android using the ImageJ Jenkins server. If you are interested in helping drive this effort forward, please write to the imagej-devel mailing list!

Another possibility for the future is a client/server version of ImageJ that runs in a web browser using HTML5 and JavaScript, which could include cross-platform support for mobile devices (Android, iPhone, tablets, etc.). Again, much groundwork has been done to make the ImageJ2 core design compatible with such an application, but no one has written the server- or client-side yet. If you are seriously interested in helping to pursue such an application, you might also want to check out the OMERO project, which is a client/server application which has some integration with ImageJ.

Community

Why is there Fiji when there is already ImageJ? And what is this ImageJ2 about?

In short: we all collaborate, but have slightly different focus, hence the different projects and names.

How can we be sure that ImageJ1, ImageJ2 and Fiji aren't going to diverge or fork over time?

We are working to create an architecture where the programs work together and preserve compatibility. Fiji is just ImageJ with batteries included, and ImageJ2 includes ImageJ1 as-is for maximum compatibility. Fiji now uses ImageJ2 at its core. Most importantly, all involved developers are strongly dedicated to avoiding divergence—we are working closely together to ensure that ImageJ2 represents a continuation of ImageJ and Fiji, rather than a project fork.

Would it make sense to merge the ImageJ2 and Fiji projects?

Fiji and ImageJ2 are fundamentally the same software, using the same launcher. So from the standpoint of development effort, the ImageJ2 and Fiji projects have indeed merged. ImageJ2 is the core software, and several pieces of infrastructure originally developed for Fiji have now migrated to ImageJ2 (e.g., the Updater, Launcher and Script Editor components). At heart, Fiji is just a big collection of life sciences plugins (though "Fijabcolsp" doesn't have quite the same ring to it). In other words, Fiji is just an ImageJ update site ("Fijaius")—and as such, you can obtain a working Fiji installation by downloading ImageJ2, running the updater, and enabling the Fiji update site.

All of that said, we do not want to get rid of the two distinct project names, since people are familiar with both. But we are integrating resources when feasible: e.g., the ImageJ wiki and the Fiji wiki are really both the same wiki with different skins, to make cross-linking more seamless. But we want to ensure it is clear that ImageJ is not a life-sciences-specific project, whereas Fiji is. Historically, because Fiji has a life sciences focus, there have been some users who refused to switch from vanilla ImageJ1 to Fiji even though Fiji makes users' lives easier in lots of ways. With ImageJ2, we want to avoid such misconceptions.

More effort is still needed to clarify web resources, to explain concisely and clearly where people should go in different circumstances. We also have plans to make bug reporting simpler and easier across the projects.

I have a problem that is not covered on this page!

How to report issues?

Use the Help ▶ Report a Bug command, which adds a ticket report to the Fiji bug tracker. While private mail might seem more desirable sometimes, but it is almost always inferior to the open process we established in ImageJ. For starters, bug reporters are unlikely to know who would be the best person to address the issue.

I reported an issue, but it is still not fixed! Why not?

ImageJ is an Open Source community project. The list of contributors is large but most of the people involved are not paid to work on it. We greatly value community contributions and assistance.

There are very few professional developers (at the moment, only one: Curtis Rueden) whose formal jobs include responding to and addressing bug reports. These developers are not paid solely to fix bugs—rather, they are working to solve scientific problems and to advance the software's capabilities. And their attention is spread thin across many projects: ImageJ, Fiji, SCIFIO, SciJava, LOCI, OME, ImgLib2, OpenSPIM, SLIM Curve, NAR plugin for Maven, and others.

The organizations above total over 300 source code repositories, many of which have dozens of open issues in their issue trackers. There are also several hundred tickets in the old ImageJ issue tracker that are pending migration to GitHub Issues, as well as over a hundred open issues in the Fiji Bugzilla.

So please understand that just because we have not responded to a bug report, does not mean we are uninterested in fixing it. It's just that we are very busy, and can use all the help we can get!

If you want to increase the chances of your issue being worked on, you can:

How do I contribute a bug fix or patch, or propose an idea for a change?

Miscellaneous

Why do you program in Java? Is C++ not much faster?

With Oracle buying Sun and Apple deprecating Java, does Java have a future?

Yes. Java is one of the most popular programming languages and still one of the top choices for high-performance, cross-platform applications. Oracle is unlikely to attempt to "kill" Java, but even if they tried they probably couldn't—OpenJDK is open source and there is a massive community of Java developers behind it. Now that Apple is partnering with Oracle and the OpenJDK community, we are likely to see Java on Mac OS X get better, not worse. Java's popularity will eventually wane, but not because of any company's actions now. Rather, as with any programming language, new technologies will emerge and gain popularity, over a course of many years.

Why does ImageJ still target Java 6?

As of June 2014, around 19% of Mac OS X systems still run version 10.6 Snow Leopard or older [1]. (In December 2013, it was around 25%.) Unfortunately, Apple and the OpenJDK developer community decided to target OS X 10.7 Lion and above for Java 7 and 8. For the time being, to avoid abandoning older machines which cannot be upgraded from Snow Leopard, ImageJ continues to target Java 6.

Furthermore, updating the required version to a newer version of Java would necessitate improvements to the ImageJ Updater such that it could also update the bundled version of Java, which would be a substantial undertaking. Otherwise, most existing installations of ImageJ would stop working, and those users would need to download ImageJ from scratch again.

How are you addressing the fact that with increased modularity comes increased complexity?

How about a version of ImageJ for the web browser, mobile devices, etc.?

While a pure web version of ImageJ would be desirable for a number of reasons, there are several substantial challenges with current technology. In particular, it would be difficult for a Javascript-based ImageJ to maintain compatibility with existing plugins, macros and scripts. For now, our goal is to continue improving the Java version of ImageJ, while remaining cognizant of developments in the web applications domain, to reduce the difficulties of a web version at some future date.

We are developing ImageJ with a careful eye toward modularity, avoiding gratuitous dependencies—particularly on AWT, which is not available on most mobile devices. We hope this approach makes it easier to port ImageJ to additional platforms in the future.

A shorter term pragmatic solution would be an ImageJ web client that connects to a remote server running ImageJ in headless mode, which does the heavy lifting. See also the OMERO project.