Skip to content

Latest commit

 

History

History
169 lines (124 loc) · 5.59 KB

index.rst

File metadata and controls

169 lines (124 loc) · 5.59 KB
Raw

Command line tools

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

.. toctree::
    :maxdepth: 1
    :titlesonly:
    :hidden:

    display
    conversion
    xml-validation
    edit
    domainlist
    formatlist
    ijview
    xmlindent
    mkfake

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:

  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 :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

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