# Command line tools overview

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 `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. See Validating XML in an OME-TIFF for details.

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.8 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