Note
This documentation is for the new Bio-Formats 5.1 version. See the latest Bio-Formats 5.0.x version or the previous versions page to find documentation for the version you are using.
A completely native Bio-Formats C++ interface is now available. Unlike the JACE bindings, this does not wrap the Java implementation. With this release, TIFF reading and writing, and OME-TIFF reading are available. OME-TIFF writing will be available soon. All other readers and writers from the Java implementation are currently unavailable; the intention is that support for these will be added over time.
Note
The C++ implementation is functional in Bio-Formats version 5.1. However, API stability will not be guaranteed until version 5.2 since it may be necessary to refactor certain parts of the API for optimal usability, robustness and performance. Applications built against version 5.1 of the API may require updating to work with version 5.2, if they make use of any part of the API which is changed incompatibly.
In order to build the C++ library and its documentation, a number of packages are required to be installed. Note that the minimum version is the minimum version we regularly test with; older versions may work but are not supported. Some packages are required only for building Bio-Formats (BF build). A subset of these are required for building client applications making use of Bio-Formats (Client build) For end-user deployment (Deploy), the library packages rather than the development packages should be preferred; in some cases such as for Boost and Qt5, these are split up into a separate package for each library.
Version | When required | ||||
---|---|---|---|---|---|
Package | Recommended | Minimum | BF build | Client build | Deploy |
Boost | 1.54 | 1.48 | • | • | • |
HDF5 | 1.8.x | 1.8.x | ◦ | ◦ | ◦ |
PNG | 1.2 | 1.2 | • | • | • |
TIFF | 4.0.3 | 3.9.5 | • | • | • |
Xerces-C | 3.0 | 3.0 | • | • | • |
GLM* | 0.9.6 | 0.9.5 | ◦ | ◦ | |
Qt5* | 5.2 | 5.0 | ◦ | ◦ | ◦ |
CMake | 3.0 | 2.8.12 | • | ||
Python | 2.7 | 2.6 | • | ||
Python Genshi | 0.7 | 0.6 | • | ||
Git | 2.1.x | 1.7.x | ◦ | ||
GTest | 1.7 | 1.5 | ◦ | ||
Doxygen† | 1.8 | 1.6 | ◦ | ||
Graphviz† | 2.x | 1.8.10 | ◦ | ||
Python Sphinx‡§ | 1.2.x | 1.1.x | ◦ | ||
Apache Ant§ | 1.9.x | 1.8.x | ◦ | ||
Java§ | 1.7.x | 1.6.x | ◦ | ||
TeX (XeLaTeX)§ | TeXLive 2014 | TeXLive 2012 | ◦ |
Due to lacking a package manager, if building on Windows most of the above packages will require downloading and installing by hand. Links for these are provided below.
Install the following packages to build Bio-Formats C++. A subset of these packages (or their dependencies) may be used for deployment, where the development package headers and tools for building documentation etc. are not required. Run the appropriate command below for your platform to install the build dependencies:
Note that Homebrew and RedHat/CentOS do not provide packages for everything you need; see below for details.
A functional compiler, assembler and linker are required to build C++ code.
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | N/A* |
Debian/Ubuntu | build-essential |
Homebrew | N/A† |
RedHat/CentOS | N/A‡ |
Windows | N/A§ |
If possible, install one of the following packages:
System | Package |
---|---|
BSD Ports | devel/boost-all |
Debian/Ubuntu | libboost-all-dev |
Homebrew | boost |
RedHat/CentOS | boost-devel |
1.48 or later needed for Boost.Geometry; 1.54 or later needed for Boost.Geometry spatial indexes. RHEL/CentOS 6 users might want to look at the Boost 1.48 SCL or build a more recent Boost release.
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | devel/cmake |
Debian/Ubuntu | cmake |
Homebrew | cmake |
RedHat/CentOS | cmake |
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | science/hdf5 |
Debian/Ubuntu | libhdf5-dev |
Homebrew | hdf5 |
RedHat/CentOS | libhdf5-devel |
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | graphics/png |
Debian/Ubuntu | libpng12-dev |
Homebrew | libpng |
RedHat/CentOS | libpng-devel |
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | lang/python |
Debian/Ubuntu | python |
Homebrew | python |
RedHat/CentOS | python |
For Python on Windows, either download separate installers for each package, or install setuptools and pip for Python, then pip install needed packages; ensure downloaded packages are 64-bit if using 64-bit Python.
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | textproc/py-genshi |
Debian/Ubuntu | python-genshi |
Homebrew | N/A |
RedHat/CentOS | python-genshi |
Use pip install genshi if a packaged version is not available.
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | graphics/tiff |
Debian/Ubuntu | libtiff5-dev* |
Homebrew | libtiff |
RedHat/CentOS | libtiff-devel |
4.0.2 and earlier do not have TIFFField accessor functions.
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | textproc/xerces-c3 |
Debian/Ubuntu | libxerces-c-dev |
Homebrew | xerces-c |
RedHat/CentOS | xerces-c-devel |
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | devel/git |
Debian/Ubuntu | git |
Homebrew | git |
RedHat/CentOS | git |
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | devel/googletest |
Debian/Ubuntu | libgtest-dev |
Homebrew | N/A* |
RedHat/CentOS | gtest-devel |
An embedded copy of GTest is provided; it is only necessary to use a system-provided or self-built copy of GTest if the embedded copy is not functional on a specific system.
If using an external GTest, make sure that GTEST_ROOT is set in the environment, or that -DGTEST_ROOT=/path/to/gtest is passed to cmake and that this points to the location where you installed the gtest library. If the library is located on the default library search path, this is not necessary.
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | math/glm |
Debian/Ubuntu | libglm-dev |
Homebrew | glm |
RedHat/CentOS | N/A |
Note
Older versions will allow compilation but use degrees rather than radians, which will lead to unexpected results.
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | devel/qt5 |
Debian/Ubuntu | qt5-default libqt5-opengl5-dev libqt5-svg5-dev |
Homebrew | qt5* |
RedHat/CentOS | N/A |
System | Package |
---|---|
BSD Ports | devel/doxygen |
Debian/Ubuntu | doxygen |
Homebrew | doxygen |
RedHat/CentOS | doxygen |
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | graphics/graphviz |
Debian/Ubuntu | graphviz |
Homebrew | graphviz |
RedHat/CentOS | graphviz |
If possible, install one of the following packages:
System | Package |
---|---|
BSD Ports | devel/apache-ant |
Debian/Ubuntu | ant ant-contrib ant-optional |
Homebrew | ant |
RedHat/CentOS | N/A |
If possible, install one of the following packages:
System | Package |
---|---|
BSD Ports | java/openjdk7 |
Debian/Ubuntu | openjdk-7-jdk openjdk-7-jre |
Homebrew | N/A |
RedHat/CentOS | java-1.7.0-openjdk |
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | textproc/py-sphinx |
Debian/Ubuntu | python-sphinx |
Homebrew | N/A (use pip) |
RedHat/CentOS | N/A (use pip) |
Use pip install sphinx if a packaged version is not available.
If possible, install the following packages:
System | Package |
---|---|
BSD Ports | print/texlive-full |
Debian/Ubuntu | texlive-full |
Homebrew | N/A* |
RedHat/CentOS | N/A† |
Local font configuration may be required to make the TeX Gyre fonts available:
Custom configuration is needed primarily on Windows, where the needed tools may not be on the search path by default. There are several possible approaches here:
The first will affect all programs running on the system and so may cause problems, particularly if multiple configurations or tool versions are to be used. The last offers the greatest flexibility and safety, and can be sourced automatically when starting a shell if a console replacement such as ConsoleZ is used.
If qt5 and glm are installed, for building the Qt image viewer, ensure that /usr/local/opt/qt5/bin is on the PATH to allow Qt to be autodetected by cmake.
Source tree layout:
cpp
├── cmake
├── ext
├── lib
│ └── ome
│ ├── bioformats
│ │ ├── detail
│ │ ├── in
│ │ ├── out
│ │ └── tiff
│ ├── common
│ │ ├── endian
│ │ └── xml
│ │ └── dom
│ ├── compat
│ ├── internal
│ ├── qtwidgets
│ ├── test
│ └── xml
├── libexec
│ ├── info
│ └── view
├── share
└── test
Top-level directories inside cpp:
Components in lib and test:
Bio-Formats uses cmake, a generic cross-platform build system which generates build files for a large number of common build systems and IDEs. For example, on BSD, Linux and MacOS X, Unix make Makefile files may be created. On Windows, Visual Studio msbuild .sln solution files and .vcxproj project may be created. However, Eclipse, Sublime Text or several other IDEs or alternative build systems may be used instead, if desired.
Start by creating a temporary build directory. This directory may be in any location inside or outside the Bio-Formats source tree. However, you may not use the source directory as the build directory. (This fills the source tree full of autogenerated files.)
Run cmake from the temporary build directory:
% mkdir build
% cd build
% cmake /path/to/bioformats
Run cmake -LH to see the configurable project options; use -LAH to see advanced options. The following basic options are supported:
For example, to disable tests, run cmake -Dtest=OFF. Options will typically be enabled by default if the prerequisites are available.
The installation prefix may be set at this point using -DCMAKE_INSTALL_PREFIX=prefix. The build system and compiler to use may also be specified. Please see the cmake documentation for further details of all configurable options, and run cmake --help to list the available generators for your platform.
C++11 features such as std::shared_ptr are used when using a C++11 or C++14 compiler, or when -Dcxxstd-autodetect=ON is used and the compiler can be put into a C++11 or C++14 compatibility mode. When using an older compatbility mode such as C++98, the Boost equivalents of C++11 library features will be used as fallbacks to provide the same functionality. In both cases these types are imported into the ome::compat namespace, for example as ome::compat::shared_ptr, and the types in this namespace should be used for portability when using any part of the API which use types from this namespace.
The default generator is Unix Makefiles, and the standard CXX, CXXFLAGS and LDFLAGS environment variables may be set to explicitly specify the compiler, compiler flags and linker flags, respectively. These may be useful for adding additional -I and -L include and library search paths, for example.
If you wish to use an IDE such as Eclipse or KDevelop, an alternative generator may be used.
On Windows, the generator will require specifying by hand, and this will configure the version of Visual Studio (or other compiler) to use. For example, -G "Visual Studio 11 Win64" will configure for generating Visual Studio 2012 64-bit build files for use with the Visual C++ compiler.
Note
There is no need to use the Visual Studio command shell when running cmake.
For all platforms and generators, it should usually be possible to build using:
% cmake --build
which will invoke the platform- and generator-specific build as appropriate.
To build the API reference documentation, run:
% cmake --build . --target doc
If using Unix Makefiles, simply run:
% make
with any additional options required, for example -j to enable parallel building, or VERBOSE=1 to show the details of every command being executed.
To build the API reference documentation, run:
% make doc
If using an IDE, open the generated project file and proceed using the IDE to build the project.
If using Visual Studio, the generated project files may be opened using the IDE and then built within the IDE. Alternatively, the project files may be built directly using the msbuild command-line tool inside a Visual Studio command prompt (or an appropriately configured command prompt which has run VCVARSALL.BAT or equivalent to configure the environment).
For all platforms and generators, it should usually be possible to run all tests using ctest. Run:
% ctest
or to run verbosely:
% ctest -V
Additional flags allow specification of the build configuration to use, logging, parallel building and other options. Please see the ctest documentation for further details.
Individual test programs may be run by hand if required.
To run all tests, run:
% cmake --build . --target test
or verbosely:
% cmake --build . --target test -- ARGS=-V
If using Unix Makefiles, simply run:
% make test
or verbosely:
% make test ARGS=-V
To install the headers and libraries directly on the system into the configured prefix:
% cmake --build . --target install
Alternatively, to install into a staging directory:
% cmake --build . --target install -- DESTDIR=/path/to/staging/directory install
If using Unix Makefiles, simply run:
% make install
Alternatively, to install into a staging directory:
% make DESTDIR=/path/to/staging/directory install
When using Visual Studio, there should be an INSTALL.vcxproj project which may be run using msbuild, for example:
> msbuild INSTALL.vcxproj /p:platform=x64
A typical installation layout:
$CMAKE_INSTALL_PREFIX
├── bin
├── include
│ └── ome
│ ├── bioformats
│ ├── common
│ ├── compat
│ └── xml
├── lib
├── libexec
└── share
├── icons
├── man
└── xml
The Doxygen API reference is used to document all aspects of the Bio-Formats API.