OS X Installation

Installation

Download ImageJ for Mac OS X from the Download page. The ZIP file you download (Image1.xx.zip) should automatically expand to a folder named "ImageJ". Copy this folder to the Applications folder, open it, and copy ImageJ64.app to the dock. A 32-bit version of ImageJ (ImageJ.app), needed for running QuickTime plugins, is also available, but it is unabe to use more than 1800MB of memory.

The first time you run ImageJ on OS X 10.7 or later you may get get an "ImageJ can't be opened because it is from an unidentified developer" message, which can be bypassed by right clicking on ImageJ64.app or ImageJ.app and selecting "Open" from the drop down menu.

OS X 10.10 (Yosemite) does not include key files required for running commands like File>Import>Using QuickTime and File>Save As>QuickTime Movie that use QuickTime for Java. You can work around this problem by copying the files QTJava.zip and libQTJNative.jnilib, available at imagej.nih.gov/ij/download/qt/ into ~/Library/Java/Extensions, where "~" is your home directory. Yosemite hides the Library folder by default, so you will need to open your home folder and check "Show Library Folder" in the View>Show View Options dialog. Before copying the files, you will need to create the ~/Library/Java and ~/Library/Java/Extensions folders.

Memory

Use the Edit>Options>Memory & Threads command to make more than default 192MB of memory available to ImageJ. Note that setting the "Maximum Memory" value to more than about 75% of real RAM may result in poor perfomance due to virtual memory "thrashing". The maximum amount of memory that can be allocated on 32-bit systems is about 1.8GB. Another way to make more memory available to ImageJ is by running from the command line and using the -Xmx option. Note that ImageJ is limited to 64MB when you run it by double clicking on ij.jar.

The Edit>Options>Memory command updates the VMOptions key in the Contents/Info.plist XML file in the ImageJ application.

    <key>VMOptions</key>
    <string>-Xms64m -Xmx1000m</string>
You will get an error message if you do not have write permission for the ImageJ application. To check and/or change the permissions, open the ImageJ folder, select the ImageJ application, and use the Finder's File>Get Info command. You will also get an error message if the ImageJ application has been renamed.

Using 64-bit Java on Leopard

On Macs with 64-bit Intel processors, Java 1.5 or later and OS X 10.5 or later, you can use ImageJ64, which is able to use more than 1.8GB memory. The title of the Edit>Options>Memory & Threads dialog box changes to "Memory (64-bit)" when ImageJ is running in 64-bit mode.
Dialog
Note that commands that use QuickTime for Java (e.g., FIle>Save As>QuickTime Movie) do not work with ImageJ64.

Upgrading

Use the Help>Update ImageJ command to upgrade to the latest version of ImageJ.

Drag and Drop

The OS X version of ImageJ opens images, text files, ROIs and LUTs that are dropped on the ImageJ icon.

Known Problems

  1. With Java 1.6, the first drag and drop on the ImageJ window is sometimes ignored. This bug can be worked around by dropping on the toolbar instead of the status bar. Apple fixed this bug in Java 1.6.0_17 (late 2009).
  2. Using command-v to paste text into the file name field of Save As dialog boxes does not work. This is a bug in the Java FileDialog class that can worked around by right-clicking in the name field and selecting "Paste" from the drop down menu.
  3. The optional "Tap to Click" feature on MacBooks and MacBook Pros does not reliably enable/disable checkboxes in ImageJ dialog boxes.
  4. Keyboard shortcuts sometimes require holding down the command key with Java 1.5 and Java 1.6. To reproduce this problem, press shift-b to open the "blobs" sample image, create a selection, press "w" to close the image, then try to open "blobs" again by pressing shift-b.
  5. Shift-clicking to select multiple ROIs in the ROI Manager does not work with Java 1.6. This bug has been reported to Apple (ID# 7092724).
  6. Commands and plugins that use QuickTime for Java fail with 64-bit versions of Java and Java 1.6 on Mac OS X is 64-bit only.
  7. On Leopard, running Java 1.5.0, the File>New>System Clipboard command generates an exception. This bug is reported to be fixed in the Java for Mac OS X 10.5 Update 2.
  8. On Leopard, pressing return to dismiss a dialog sometimes results in the default text field values being used instead of the entered values. ImageJ 1.40e and later have a work around for this bug.
  9. ImageJ sometimes crashes on OS X. Upgrading to the latest version of Java should reduce the number of crashes. This bug has been reported to Apple (ID# 3488737).
  10. OS X requires a lot of memory for each open window. Converting a 1024x1024x10x8-bit stack (10MB) to separate images requires 58MB of additional memory!
  11. There does not appear to be a way to unselect an ROI in the ROI Manager (java.awt.List bug). As a workaround, press the "Unselect" button.
  12. Image drawing is very slow. The Plasma plugin and Plasma2 applet are test cases for this problem.
  13. The available memory value displayed by ImageJ (1.32h or later) is 64MB too high when ImageJ is started by double-clicking on ij.jar or run from the command line due to a bug in Java's Runtime.maxMemory() method.
  14. With Java 1.4.2, the cursor is always an arrowhead. This bug has been reported to Apple (ID# 3761991). A test case applet is available.

Troubleshooting

Here are three common problems encountered when running ImageJ on Mac OS X, and their solutions:
  • I upgraded Java and ImageJ64 stopped working.

    Upgrade to the ImageJ64 included with ImageJ 1.42.

  • Commands that use QuickTime do not work.

    Use ImageJ instead of ImageJ64. QuickTime for Java does not work in 64-bit mode.

  • The Help>Update ImageJ command is missing or does not work.

    Use the ImageJ Updater plugin, which is included with ImageJ 1.42.

  • Adding JAR Files

    Some plugins require a Java code library contained in a JAR file (e.g., Jama.jar). ImageJ's plugin class loader automatically loads code from such libraries as long as the JAR file is in the plugins folder or an immediate subfolder. The Plugins>Compile and Run command in ImageJ 1.39 and later also supports JAR file libraries located in the plugins folder or a subfolder. Note that Compile and Run will not recognize the JAR file if the name does not end in ".jar" or if the name contains an underscore.

    Switching Java Versons

    On OS X 10.4 and later, the Java Preferences utility in /Applications/Utilities/Java allows you to switch to a different version of Java:
    1. Launch Java Preferences.
    2. In the Applications area, drag "J2SE 6.0 (64-bit)", "J2SE 5.0" or "J2SE 1.4.2" to the top position.
    3. Click the "Save" button.

    Running from the Command Line

    To run ImageJ from the command line, open a Terminal window, cd to the ImageJ directory, then use the java command to run ImageJ. The easiest way to do this is to drag the ImageJ folder to the Terminal Window, type return, then type:
    java -jar -Xmx1024m ImageJ64.app/Contents/Resources/Java/ij.jar
    
    The -Xmx1024m switch specifies that ImageJ will have available a maximum of 1024MB (1GB) of RAM.

    Use a command like this to run ImageJ from any directory:

    java -Xmx1024m -jar /Applications/ImageJ/ImageJ64.app/Contents/Resources/Java/ij.jar -ijpath /Applications/ImageJ
    
    ImageJ recognizes the following command line options:
      "file-name"
         Opens a file
         Example 1: blobs.tif
         Example 2: /Users/wayne/images/blobs.tif
         Example 3: e81*.tif
    
      -macro path [arg]
         Runs a macro or script (JavaScript, BeanShell or Python), passing an
         optional string argument, which the macro or script can be retrieve
         using the getArgument() function. The macro or script is assumed to 
         be in the ImageJ/macros folder if 'path' is not a full directory path.
         Example 1: -macro analyze.ijm
         Example 2: -macro script.js /Users/wayne/images/stack1
         Example 2: -macro script.py '1.2 2.4 3.8'
    
      -batch path [arg]
        Runs a macro or script (JavaScript, BeanShell or Python) in
        batch (no GUI) mode, passing it an optional argument.
        ImageJ exits when the macro finishes.
    
      -eval "macro code"
         Evaluates macro code
         Example 1: -eval "print('Hello, world');"
         Example 2: -eval "return getVersion();"
    
      -run command
         Runs an ImageJ menu command
         Example: -run "About ImageJ..."
         
      -ijpath path
         Specifies the path to the directory containing the plugins directory
         Example: -ijpath /Applications/ImageJ
    
      -port
         Specifies the port ImageJ uses to determine if another instance is running
         Example 1: -port1 (use default port address + 1)
         Example 2: -port2 (use default port address + 2)
         Example 3: -port0 (don't check for another instance)
    
      -debug
         Runs ImageJ in debug mode
    

    About the Icon

    The ImageJ icon for OS X is based on a photograph by Tom Grill of a
    Hartnack microscope, circa 1870's, at www.arsmachina.com. A full size PNG version of the icon is available at rsb.info.nih.gov/ij/images/ImageJ.png. An article
    on O'Reilly's macdevcenter.com site explains how to create photorealistic
    icons for Mac OS X.