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 `, 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:`loci_tools.jar` or the new :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