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:
- 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 valueC:\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.
- E.g. on Windows with Java 1.7 or later, if you have checked out
the source at
- Compile the source with
ant compile
. - 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