Frequently Asked Questions

Revision as of 11:28, 15 March 2013 by Rueden (talk | contribs) (Development: Add entry on getting the source for a command)



The image I loaded is displayed all black! But it is not black!

This problem usually arises when 12-bit or 14-bit images are loaded into Fiji without autoscaling. In that case, they are treated as if they were 16-bit images, and therefore the dynamic range is all wrong. You can fix this by clicking on Image>Adjust>Brightness/Contrast... and hitting the Auto button.


How do I install Fiji?

The installation of Fiji is described on specific pages for MacOSX, Windows and Linux.

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

Fiji is just ImageJ. Hence it is very easy to bootstrap the updater and add the Fiji update site: Simply drag 'n drop 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.

How do I install additional plugins?

You can drag 'n drop the .jar files onto the Fiji window, or use Plugins>Install Plugin... with .jar, .class and .java files, or copy the plugins to and call Help>Refresh Menus manually. A walk-through with screenshots is available here.

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 Fiji via Help>Update Fiji, 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 directory (MacOSX users, Ctrl-click on the Fiji icon and select Open Package Contents and open the jars/ directory you see there). After that, the Updater should magically repair itself.

If that still fails, please download a fresh copy from here.

I updated Fiji via Help>Update Fiji, and now it does not start anymore!

If you are on MacOSX, most likely you did not update in some time, and you were bitten by a bug in the updater that is already fixed (but you did not get the fix in time). Please follow these instructions.

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 Fiji).

Alternatively, you can update the updater manually like this:

  • open the Script Editor with File>New>Script
  • set the language to Beanshell in the Language menu of the editor
  • paste the following code (and adjust it to match your settings):
import ij.IJ;

System.setProperty("", "true");"Update Fiji");
  • run the script via the Run menu

I updated to Ubuntu 11.04 and now I no longer see the Title bar when I close Fiji

I can no longer move any windows or use the X button on the title bar to close them (the window decorations all disappear).

If you are really on Ubuntu 11.04, an update should fix the problem. If you are not on Ubuntu 11.04, or if the update does not fix the problem, please read on for possible workarounds.

This is not a Fiji problem but a bug in the NVIDIA driver. One solution is described in:

Edit (as root) the file /etc/X11/xorg.conf and add the following 2 options in Section "Device" before the EndSection line:

  Option "AddARGBVisuals" "True"
  Option "AddARGBGLXVisuals" "True"

The above eases the problem but does not completely solve it. The solution will be an updated driver from NVIDIA when it is available. If you choose to remain with Unity or Ubuntu Classic, you may log out and then log in again when the problem appears. You can also restart the window manager without logging out by running

  compiz --replace &

in a terminal. This restores the window decorations but all windows from all virtual desktops end in the first one.

Another solution is to install Unity-2D and choose it when you log in. This seems to work well. It also solves a number of general display problems.

3D Viewer

The 3D Viewer opens a window saying An unexpected exception occurred.

If in the same window, it also says:

java.lang.NullPointerException:Canvas3D: null GraphicsConfiguration

the reason is most likely that your graphics setup does not have any hardware 3D acceleration. This can happen e.g. when you run Fiji via a remote X11 connection (3D acceleration works only when the graphics are displayed on the same machine as the program runs).

Unfortunately, there is not workaround/fix for this situation yet, except to use Fiji locally when you want to use the 3D Viewer.

Problem with Intel graphics cards

There is a known problem with older Windows drivers for some Intel graphics cards. Usually, this is fixed by installing new drivers. If you would like to help make Fiji nicer by detecting faulty driver versions, please contact us.

The 3D Viewer simply crashes

Unfortunately, there are quite a large number of possible reasons. Please help us by debugging the issues and contacting us (mailing list or IRC) with the information. You can also report a Bug, which will provide a lot of addidtional, potentially useful information.

Only a gray rectangle is shown by the 3D Viewer

As with 3D Viewer crashes, there are quite a large number of possible reasons. Please help us by debugging the issues and contacting us (preferably via mailing list) with the information. You can also report a Bug, which will provide a lot of addidtional, potentially useful information.


How do I develop Fiji in Eclipse?

Please refer to the page Developing Fiji in Eclipse.

How can I build Fiji from the command-line?

Download and build it. You need Git for that (if you are on Windows, please use Git for Windows).

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).

For details, please refer to our page on Maven.

How do I create a new ImageJ plugin using Maven?

Please refer to our page on Maven.

How do I upload a new release of a Fiji plugin?

Please refer to our tutorial how to upload files.

How do I upload a new release of a core ImageJ library such as ImgLib?

The same way as a Fiji plugin. But it will upload to the ImageJ update site (you can only upload to one update site at a time, though, see also this ticket).

What is the recommended way to develop in Fiji?

Over the years we evolved a development style as follows:

  • create a topic branch
  • test as much as you need to be comfortable to merge
  • merge
  • deal with any fall-out

This development style has been adopted by the ImageJDev team, with two additions (making the fall-out step much smaller):

  • tests are added as automated regression tests (to be run by the continuous integration whenever new changes were pushed) whenever possible.
  • merges are usually done with --no-ff, so that even fast-forwarding branches (i.e. rebased on top of master) will get a merge commit in which the branch is described more broadly.

How to report issues?

Add a ticket report to Fiji's or to ImageJDev's ticket system; private mail might seem more desirable sometimes, but it is almost always inferior to the open process we established in Fiji. For starters, bug reporters are unlikely to know who would be the best person to address the issue.

I cloned fiji.git, but have a compile error regarding a class Appearance.

If you get an error similar to this:

Building plugins/VIB_.jar <- src-plugins/VIB_/ src...
Building plugins/3D_Viewer.jar <- src-plugins/3D_Viewer/ImageJ_3D_...
src-plugins/3D_Viewer/customnode/ cannot find symbol
symbol  : class Appearance
location: package

it means that you do not have Java3D installed. This happens typically when you have an environment variable JAVA_HOME set to an existing JDK without Java3D. To force the Fiji Build system to clone Fiji's known-good JDK, call


Alternatively, if you have write permissions to the path JAVA_HOME points to, you could install Java3D manually.

I tried to build Fiji, but get Target misc/headless.jar was not built!

You need to update the ImageJA submodule:

git submodule update ImageJA

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:


How do I see the source code for a command?

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

Here are several ways to do so:

  1. Using the Command Finder:
    • Press L for the Command Finder.
    • Type the name of the command.
    • Press the down arrow to select it.
    • Click the Source button.
    • This will open the source from the ImageJ web site online source.
    • Note: this method is very convenient, but only works for core ImageJ sources, not Fiji-specific code.
  2. Using's search:
    • Using the Command Finder, locate your command, taking note of the Class column's value.
      • E.g., if we type "make binary" we see that the class is ij.plugin.Thresholder.
    • In your browser, type the name of the class followed by ".java"; e.g.:
    • This will automatically perform a search throughout all code known to for that source file. If there are multiple matches, you will see them all. Clicking on a match opens it in the gitweb interface.
    • Note: this method does a broad search and can find many things, but only Java code. If you want to search for a script instead, you will need to take note of the script argument:
      • For example, in Command Finder, if you type "scale to dpi" you will see that the "Class" is something like: Javascript.Refresh_Javascript_Scripts(".../
      • You can find this code by typing:
      • Scripts written in other languages work similarly.
  3. Using GitHub:
    • Using the Command Finder, locate your command, taking note of the Class column's value.
      • E.g., if we type "make binary" we see that the class is ij.plugin.Thresholder.
    • Open the relevant project in GitHub:
    • Press the T key, and type the name of the file you are looking for.
      • In the example above, this is
    • You should end up with a hit like:
    • This method requires that you know in which repository the code lives. However, you can combine it with the search method above to figure out which repository, then load the code on GitHub, if desired.
  4. 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.
    • This will open the source using the gitweb interface.

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


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

The ImageJ, Fiji and ImageJ2 projects are very closely related. Here are two attempts to clarify the situation:

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

This is a Wiki but I cannot edit it! Why?

We do not want to spend resources on spam reduction, so we settled on the following strategy: anybody with an account can add new accounts. So please ask in our chat room or on one of our mailing lists and direct the good people at this page. You should have an account in less than 5 minutes after asking for it.

The Wiki is lacking documentation about X, Y and Z

Please ask any person with a Wiki account to register a new account for you (this procedure should help prevent spam without requiring anybody to play sanitor), and enhance the Wiki. We are thankful for all contributions!

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

If you have an issue that is not mentioned here, you might want to ask on one of the mailing lists, or via IRC, or enter a bug report.

How to report issues?

Add a ticket report to Fiji's or to ImageJDev's ticket system; private mail might seem more desirable sometimes, but it is almost always inferior to the open process we established in Fiji. For starters, bug reporters are unlikely to know who would be the best person to address the issue.


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

While it used to be true that Java is always slower than the equivalent in C++, this is no longer true. There have been quite a few benchmarks comparing Java vs C++ performance, this one probably being the grandfather of all.

Pragmatically, one should note that there is not really a big difference in performance when comparing Java to C++.

The real reason why Fiji is written in Java is that ImageJ is written in Java.

The reason why we chose ImageJ as the core of Fiji is that it runs without trouble and without recompiling on the major platforms: Windows, MacOSX and Linux. And plugins compiled on one platform also execute on all other platforms without recompiling. And profiling and debugging is easier with Java than with C++. And all programs/plugins double as libraries.

So the true reason why we use Java is probably: it makes Fiji accessible.

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

The term headless refers to running Fiji without a graphical desktop, e.g. on a cluster.

For technical reasons, GUI elements such as a menu or a button cannot be used when running Java on Linux in headless mode. That is the reason why we put custom classes into a file called headless.jar which override specific ImageJ classes that would try to instantiate GUI elements. In headless mode, that .jar file is inserted into the Java class path. In non-headless mode, the .jar file is not inserted into the class path (that is the reason why headless.jar is not in the jars/ subdirectory).