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.
Download :downloads:`bioformats_package.jar <artifacts/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.
The Bio-Formats Importer plugin can display image stacks in several ways:
- In a standard ImageJ window (including as a hyperstack)
- 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 :menuselection:`File --> Open` instead of
explicitly choosing
:menuselection:`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.
To upgrade, just overwrite the old bioformats_package.jar with the :downloads:`latest one <>`.
You can also upgrade the Bio-Formats plugin directly from ImageJ. Select :menuselection:`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.
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:
:source:`basicMetadata.txt <components/bio-formats-plugins/utils/macros/basicMetadata.txt>` - A macro that uses the Bio-Formats macro extensions to print the chosen file's basic dimensional parameters to the Log.
:source:`planeTimings.txt <components/bio-formats-plugins/utils/macros/planeTimings.txt>` - A macro that uses the Bio-Formats macro extensions to print the chosen file's plane timings to the Log.
:source:`recursiveTiffConvert.txt <components/bio-formats-plugins/utils/macros/recursiveTiffConvert.txt>` - A macro for recursively converting files to TIFF using Bio-Formats.
:source:`bfOpenAsHyperstack.txt <components/bio-formats-plugins/utils/macros/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).
:source:`zvi2HyperStack.txt <components/bio-formats-plugins/utils/macros/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.
:source:`dvSplitTimePoints.txt <components/bio-formats-plugins/utils/macros/dvSplitTimePoints.txt>` - This macro from Sebastien Huart splits timepoints/channels on all DV files in a folder.
:source:`batchTiffConvert.txt <components/bio-formats-plugins/utils/macros/batchTiffConvert.txt>` - This macro converts all files in a directory to TIFF using the Bio-Formats macro extensions.
:source:`Read_Image <components/bio-formats-plugins/utils/Read_Image.java>` - A simple plugin that demonstrates how to use Bio-Formats to read files into ImageJ.
:source:`Mass_Importer <components/bio-formats-plugins/utils/Mass_Importer.java>` - 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.
- "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 :menuselection:`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 :menuselection:`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 :file:`bioformats_package.jar` in you ImageJ plugins folder, or a copy
of :file:`bioformats_package.jar` and a copy of :file:`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 :file:`bioformats_package.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 Typebox (e.g..ome.tiffor OME-TIFF). This can prevent BigTIFF and OME BigTIFF files from being created, as the.btfor.ome.btffile extension will be overwritten. To ensure that the desired extension is used, select :menuselection:`All files` or :menuselection:`All supported file types` in theFiles of typebox, as an extension will not be automatically added in those cases. - Saving an open image using Bio-Formats must be done via :menuselection:`Plugins > Bio-Formats > Bio-Formats Exporter` or the corresponding macro code. :menuselection:`File > Save` and :menuselection:`File > Save As...` do not use Bio-Formats. In particular, using :menuselection:`File > Save As...` to save a TIFF will result in an ImageJ-specific TIFF being written. While Bio-Formats can read ImageJ TIFFs, other software may not; see :doc:`/formats/tiff` for additional information.