Command line tools overview
===========================

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

Installation
------------

Download :downloads:`bftools.zip <artifacts/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 :file:`bioformats_package.jar`
    separately.


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

Tools available
---------------

Currently available tools include:

.. glossary::

    showinf
        Prints information about a given image file to the console, and
        displays the image itself in the Bio-Formats image viewer (see
        :doc:`display` for more information).

    ijview
        Displays the given image file in ImageJ using the Bio-Formats Importer
        plugin.  See :doc:`ijview` for details.

    bfconvert
        Converts an image file from one format to another. Bio-Formats must
        support writing to the output file (see :doc:`conversion` for more
        information).

    formatlist
        Displays a list of supported file formats in HTML, plaintext or XML.
        See :doc:`formatlist` for details.

    xmlindent
        A simple XML prettifier similar to :command:`xmllint --format` but more
        robust in that it attempts to produce output regardless of syntax
        errors in the XML.  See :doc:`xmlindent` for details.

    xmlvalid
        A command-line XML validation tool, useful for checking an OME-XML
        document for compliance with the OME-XML schema.  See :doc:`xml-validation` 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
        :doc:`edit`).

    domainlist
        Displays a list of imaging domains and the supported formats
        associated with each domain.  See :doc:`domainlist` 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 :doc:`mkfake`
        for more information.

Some of these tools also work in combination, for example
:doc:`xml-validation` uses both :command:`tiffcomment` and :command:`xmlvalid`.

Running any of these commands without any arguments will print usage
information to help you. When run with the ``-version`` argument, :command:`showinf`
and :command:`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:

.. glossary::

    :envvar:`BF_CP`
        Extra directories to be added to the autodetected command-line
        classpath e.g. for external reader JARs. Default: empty.

    :envvar:`BF_FLAGS`
        Additional flags to be sent to the JVM. Default: empty.

    :envvar:`BF_MAX_MEM`
        Maximum heap size to be allocated to the JVM. Default: 512m.

    :envvar:`BF_PROFILE`
        Enable profiling - see :ref:`profiling` for more information.
        Default: off.

    :envvar:`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
:ref:`source-obtain-and-build`). 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.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.

#. Compile the source with ``ant compile``.
#. Set the :envvar:`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:

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
:envvar:`BF_PROFILE` environment variable allows to turn profiling on, e.g.::

    BF_PROFILE=true showinf -nopix -no-upgrade myfile

.. _HPROF: https://docs.oracle.com/javase/7/docs/technotes/samples/hprof.html
