Component overview¶
The Bio-Formats code repository is divided up into separate components.
The Ant targets to build each component from the repository root are noted in the component descriptions below. Unless otherwise noted, each component can also be built with Maven by running mvn in the component’s subdirectory. The Maven module name for each component (as it is shown in most IDEs) is also noted in parenthesis.
Core components¶
The most commonly used and actively modified components.
Internal testing components¶
These components are used heavily during continuous integration testing, but are less relevant for active development work.
All components¶
autogen (Bio-Formats code generator):
Ant: jar-autogen
Contains everything needed to automatically generate documentation for supported file formats. format-pages.txt should be updated for each new file format reader or writer, but otherwise manual changes should be unnecessary. The following Ant targets are used to regenerate the documentation for all formats:
gen-format-pages
gen-meta-support
gen-original-meta-support
bio-formats-plugins (Bio-Formats Plugins for ImageJ):
Ant: jar-bio-formats-plugins
Everything pertaining to the Bio-Formats plugins for ImageJ lives in this
component. Note that when built, this component produces
bio-formats_plugins.jar (instead of bio-formats-plugins.jar) to
be in keeping with ImageJ plugin naming conventions.
bio-formats-tools (Bio-Formats command line tools):
Ant: jar-bio-formats-tools
The classes that implement the showinf, bfconvert, and mkfake command line tools are contained in this component. Note that this is built with the jar-bio-formats-tools Ant target, and not the tools target (which is the Ant equivalent of bundles).
bundles (bioformats_package bundle, LOCI Tools bundle):
Ant: tools
This is only needed by the Maven build system, and is used to aggregate all of
the individual .jar files into bioformats_package.jar. There should
not be any code here, just build system files.
This is a fork of JAI ImageIO. JAI ImageIO is no longer maintained; the most active fork is jai-imageio-core on GitHub. JAI provides support for decoding YCbCr JPEG-2000 data. This is primarily needed for reading images from histology/pathology formats in formats-gpl. There are no dependencies on other components.
The status of this component means that you may encounter errors due to conflicting JARs e.g. between Bio-Formats and other toolboxes within Fiji or MATLAB, especially when trying to open JPEG-2000 data. In this case, you will need to remove the conflicting JAR(s) as a workaround.
forks/turbojpeg (libjpeg-turbo Java bindings):
Ant: jar-turbojpeg
This is a fork of libjpeg-turbo. There are not any real code changes, but having this as a separate component allows us to package the libjpeg-turbo Java API together with all of the required binaries into a single .jar file using native-lib-loader. There are no dependencies on other components.
formats-api (Bio-Formats API):
Ant: jar-formats-api
This defines all of the high level interfaces and abstract classes for reading and writing files. There are no file format readers or writers actually implemented in this component, but it does contain the majority of the API that defines Bio-Formats. formats-bsd and formats-gpl implement this API to provide file format readers and writers. ome-common and ome-xml are both required as part of the interface definitions.
formats-bsd (BSD Bio-Formats readers and writers):
Ant: jar-formats-bsd
This contains readers and writers for formats which have a publicly available specification, e.g. TIFF. Everything in the component is BSD-licensed.
formats-gpl (Bio-Formats library):
Ant: jar-formats-gpl
The majority of the file format readers and some file format writers are contained in this component. Everything in the component is GPL-licensed (in contrast with formats-bsd). Most file formats represented in this component do not have a publicly available specification.
test-suite (Bio-Formats testing framework):
Ant: jar-tests
All tests that operate on files from our data repository (i.e. integration tests) are included in this component. These tests are primarily run by the continuous integration jobs, and verify that there are no regressions in reading images or metadata.
External components¶
The following have been decoupled from the Bio-Formats code repository and are now available as separate build dependencies:
Decoupled OME data model components:
Provides I/O classes that unify reading from files on disk, streams or files in memory, compressed streams, and non-file URLs. The primary entry points are Location, RandomAccessInputStream (for reading), and RandomAccessOutputStream (for writing).
In addition to I/O, there are several classes to assist in working with XML (XMLTools), date/timestamps (DateTools), logging configuration (DebugTools), and byte arithmetic (DataTools).
Provides classes for encoding and decoding compressed data for a variety of compression formats. ome-common is a required dependency for I/O and service loading.
This is a fork of the mdbtools-java project. There are numerous bug fixes, as well as changes to reduce the memory required for large files. There are no dependencies on other components.
This is a fork of Apache POI, which allows reading of Microsoft OLE document files. We have made substantial changes to support files larger than 2GB and reduce the amount of memory required to open a file. I/O is also handled by classes from ome-common, which allows OLE files to be read from memory.
Java implementation of the Metakit database specification. This uses classes from ome-common and is used by formats-gpl, but is otherwise independent of the main Bio-Formats API.
This component contains classes that represent the OME-XML schema. Some classes are committed to the Git repository, but the majority are generated at build time by using XSD-FU to parse the OME-XML schema files. Classes from this component are used by Bio-Formats to read and write OME-XML, but they can also be used independently.
All released and in-progress OME-XML schema files are contained in this component. The specification component is also the location of all XSLT stylesheets for converting between OME-XML schema versions, as well as example OME-XML files in each of the released schema versions.
Luratech LuraWave stubs and MIPAV stubs.
This component provides empty classes that mirror third-party dependencies which are required at compile time but cannot be included in the build system (usually due to licensing issues). The build succeeds since required class names are present with the correct method signatures; the end user is then expected to replace the stub .jar files at runtime.
This component contains the Java bindings for jxrlib, an open source implementation of the JPEG-XR image format standard.
