ImageJ overview

ImageJ is an image processing and analysis application written in Java, widely used in the life sciences fields, with an extensible plugin infrastructure. You can use Bio-Formats as a plugin for ImageJ to read and write images in the formats it supports.

Installation

Download bioformats_package.jar and drop it into your ImageJ/plugins folder. Next time you run ImageJ, a new Bio-Formats submenu with several plugins will appear in the Plugins menu, including the Bio-Formats Importer and Bio-Formats Exporter.

Usage

The Bio-Formats Importer plugin can display image stacks in several ways:

• In a standard ImageJ window (including as a hyperstack)
• Using the LOCI Data Browser plugin (included)
• With Joachim Walter’s Image5D plugin (if installed)
• With Rainer Heintzmann’s View5D plugin (if installed)

ImageJ v1.37 and later automatically (via HandleExtraFileTypes) calls the Bio-Formats logic, if installed, as needed when a file is opened within ImageJ, i.e. when using File ‣ Open instead of explicitly choosing Plugins ‣ Bio-Formats ‣ Bio-Formats Importer from the menu.

For a more detailed description of each plugin, see the Bio-Formats page of the ImageJ wiki.

Upgrading

To upgrade, just overwrite the old bioformats_package.jar with the latest one.

You can also upgrade the Bio-Formats plugin directly from ImageJ. Select Plugins ‣ Bio-Formats ‣ Update Bio-Formats Plugins from the ImageJ menu, then select which release you would like to use. You will then need to restart ImageJ to complete the upgrade process.

Macros and plugins

Bio-Formats is fully scriptable in a macro, and callable from a plugin. To use in a macro, use the Macro Recorder to record a call to the Bio-Formats Importer with the desired options. You can also perform more targeted metadata queries using the Bio-Formats macro extensions.

Here are some example ImageJ macros and plugins that use Bio-Formats to get you started:

basicMetadata.txt - A macro that uses the Bio-Formats macro extensions to print the chosen file’s basic dimensional parameters to the Log.

planeTimings.txt - A macro that uses the Bio-Formats macro extensions to print the chosen file’s plane timings to the Log.

recursiveTiffConvert.txt - A macro for recursively converting files to TIFF using Bio-Formats.

bfOpenAsHyperstack.txt - This macro from Wayne Rasband opens a file as a hyperstack using only the Bio-Formats macro extensions (without calling the Bio-Formats Importer plugin).

zvi2HyperStack.txt - This macro from Sebastien Huart reads in a ZVI file using Bio-Formats, synthesizes the LUT using emission wavelength metadata, and displays the result as a hyperstack.

dvSplitTimePoints.txt - This macro from Sebastien Huart splits timepoints/channels on all DV files in a folder.

batchTiffConvert.txt - This macro converts all files in a directory to TIFF using the Bio-Formats macro extensions.

Read_Image - A simple plugin that demonstrates how to use Bio-Formats to read files into ImageJ.

Mass_Importer - A simple plugin that demonstrates how to open all image files in a directory using Bio-Formats, grouping files with similar names to avoiding opening the same dataset more than once.

Usage tips

• “How do I make the options window go away?” is a common question. There are a few ways to do this:
  • To disable the options window only for files in a specific format, select Plugins > Bio-Formats > Bio-Formats Plugins Configuration, then pick the format from the list and make sure the “Windowless” option is checked.
  • To avoid the options window entirely, use the Plugins > Bio-Formats > Bio-Formats Windowless Importer menu item to import files.
  • Open files by calling the Bio-Formats importer plugin from a macro.
• A common cause of problems having multiple copies of bioformats_package.jar in you ImageJ plugins folder, or a copy of bioformats_package.jar and a copy of formats-gpl.jar. It is often difficult to determine for sure that this is the problem - the only error message that pretty much guarantees it is a NoSuchMethodException. If you downloaded the latest version and whatever error message or odd behavior you are seeing has been reported as fixed, it is worth removing all copies of bioformats_package.jar (and loci_tools.jar or any other Bio-Formats jars) and download a fresh version.
• The Bio-Formats Exporter plugin’s file chooser will automatically add the first listed file extension to the file name if a specific file format is selected in the Files of Type box (e.g. .ome.tif for OME-TIFF). This can prevent BigTIFF and OME BigTIFF files from being created, as the .btf or .ome.btf file extension will be overwritten. To ensure that the desired extension is used, select All files or All supported file types in the Files of type box, as an extension will not be automatically added in those cases.