Command line tools introduction

There are several scripts for using Bio-Formats on the command line.

Installation

Download bftools.zip, unzip it into a new folder.

Note

As of Bio-Formats 5.0.0, this zip now contains the bundled jar and you no longer need to download loci_tools.jar or the new bioformats_package.jar separately.

The zip file contains both Unix scripts and Windows batch files.

Tools available

Currently available tools include:

showinf
Prints information about a given image file to the console, and displays the image itself in the Bio-Formats image viewer (see Displaying images and metadata for more information).
ijview
Displays the given image file in ImageJ using the Bio-Formats Importer plugin. See Display file in ImageJ for details.
bfconvert
Converts an image file from one format to another. Bio-Formats must support writing to the output file (see Converting a file to different format for more information).
formatlist
Displays a list of supported file formats in HTML, plaintext or XML. See List supported file formats for details.
xmlindent
A simple XML prettifier similar to xmllint --format but more robust in that it attempts to produce output regardless of syntax errors in the XML. See Format XML data for details.
xmlvalid
A command-line XML validation tool, useful for checking an OME-XML document for compliance with the OME-XML schema.
tiffcomment
Dumps the comment from the given TIFF file’s first IFD entry; useful for examining the OME-XML block in an OME-TIFF file (also see Editing XML in an OME-TIFF).
domainlist
Displays a list of imaging domains and the supported formats associated with each domain. See List formats by domain for more information.
mkfake
Creates a “fake” high-content screen with configurable dimensions. This is useful for testing how HCS metadata is handled, without requiring real image data from an acquired screen. See Create a high-content screen for testing for more information.

Some of these tools also work in combination, for example Validating XML in an OME-TIFF uses both tiffcomment and xmlvalid.

Running any of these commands without any arguments will print usage information to help you. When run with the -version argument, showinf and bfconvert will display the version of Bio-Formats that is being used (version number, build date, and Git commit reference).

Command-line environment

A set of environment variables can be passed to all command-line utilities:

BF_CP
Extra directories to be added to the autodetected command-line classpath e.g. for external reader JARs. Default: empty.
BF_FLAGS
Additional flags to be sent to the JVM. Default: empty.
BF_MAX_MEM
Maximum heap size to be allocated to the JVM. Default: 512m.
BF_PROFILE
Enable profiling - see Profiling for more information. Default: off.
BF_PROFILE_DEPTH
Maximum profiling depth if profiling is activated. Default: 30.

Using the tools directly from source

Firstly, obtain a copy of the sources and build them (see Obtaining and building Bio-Formats). You can configure the scripts to use your source tree instead of bioformats_package.jar in the same directory by following these steps:

  1. Point your CLASSPATH to the checked-out directory and the JAR files in the jar folder.
    • E.g. on Windows with Java 1.7 or later, if you have checked out the source at C:\code\bio-formats, set your CLASSPATH environment variable to the value C:\code\bio-formats\jar\*;C:\code\bio-formats. You can access the environment variable configuration area by right-clicking on My Computer, choosing Properties, Advanced tab, Environment Variables button.
  2. Compile the source with ant compile.
  3. Set the BF_DEVEL environment variable to any value (the variable just needs to be defined).

Version checker

If you run bftools outside of the OMERO environment, you may encounter an issue with the automatic version checker causing a tool to crash when trying to connect to upgrade.openmicroscopy.org.uk. The error message will look something like this:

Failed to compare version numbers
java.io.IOException: Server returned HTTP response code: 400 for URL:
http://upgrade.openmicroscopy.org.uk?version=4.4.8;os.name=Linux;os.
version=2.6.32-358.6.2.el6.x86_64;os.arch=amd64;java.runtime.version=
1.6.0_24-b24;java.vm.vendor=Sun+Microsystems+Inc.;bioformats.caller=
Bio-Formats+utilities

To avoid this issue, call the tool with the -no-upgrade parameter.

Profiling

For debugging errors or investigating performance issues, it can be useful to use profiling tools while running Bio-Formats. The command-line tools can invoke the HPROF agent library to profile Heap and CPU usage. Setting the BF_PROFILE environment variable allows to turn profiling on, e.g.:

BF_PROFILE=true showinf -nopix -no-upgrade myfile