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 :downloads:`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 :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. 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 :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. 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: :source:`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 ` - A macro that uses the Bio-Formats macro extensions to print the chosen file's plane timings to the Log. :source:`recursiveTiffConvert.txt ` - A macro for recursively converting files to TIFF using Bio-Formats. :source:`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 ` - 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 ` - This macro from Sebastien Huart splits timepoints/channels on all DV files in a folder. :source:`batchTiffConvert.txt ` - This macro converts all files in a directory to TIFF using the Bio-Formats macro extensions. :source:`Read_Image ` - A simple plugin that demonstrates how to use Bio-Formats to read files into ImageJ. :source:`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 :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` (and :file:`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 :menuselection:`All files` or :menuselection:`All supported file types` in the ``Files of type`` box, 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.