OME-FILES-CPP-OVERVIEW(7)

NAME
ome-files-cpp-overview - C++ implementation overview

OME-Files is a native C++ implementation of the Java Bio-Formats interfaces, providing a reference implementation of the OME-TIFF file format and the OME-XML metadata model for C++ developers.

Unlike the JACE bindings, this does not wrap the Java implementation. Readers and writers are provided for TIFF and OME-TIFF. All other readers and writers from the Bio-Formats Java implementation are currently unavailable.

NOTE: Due to the renaming of Bio-Formats to OME-Files, this will result in an API break between version 5.1 and 5.2 as a result of the renamed namespaces. Further breaking changes are planned as the basic interfaces are cleaned up to make them more flexible and efficient.

PREBUILT PACKAGES

  MacOS X Homebrew

Run:

brew tap homebrew/science
brew install bioformats-cpp [--without-docs] [--with-qt5]

--without-docs
    Do not build the HTML version of this manual (built by default).

--with-qt5
    Build the Qt5 OpenGL viewer widget library ome-qtwidgets and ome-files view image viewer (not built by default).

PREREQUISITES

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 OME-Files (OF [super]build). A subset of these are required for building client applications making use of OME-Files (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.

OME-Files may be built in two ways. The first is “standalone” (OF build) and requires the prerequisites to be installed in advance, for example using your operating system's package manager. The second is using a “super-build” (OF superbuild) which builds the prerequisites in addition to OME-Files, and is useful on systems where the prerequisites are unavailable, for example on Windows which lacks a package manager or on older systems such as CentOS 6 where the versions available through a package manager are too old. Note that the super-build cannot provide all prerequisites; some will still need installing before building, shown in the table below. Also note that the super-build may link against some system libraries when building packages such as libtiff, where the build system for the package will optionally use certain system libraries if available; this may result in a build which will not work on other systems unless these libraries are also installed. In the future, these dependencies will also be provided by the super-build.
 | Version | When required
Package | Recommended | Minimum | OF build | OF superbuild | 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.4 | 3.2 | • | • |  |
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 | ‡§ | ‡§ |  |
TeX (XeLaTeX) | TeXLive 2015 | TeXLive 2012 | § | § |  |

•   Required for OME-Files build; headers may be needed for client build; libraries and any data files required for deployment

◦   Optional for OME-Files build; if used for the OME-Files build, headers may be required for client build and libraries and any data files required for deployment

*   Optional, needed to build the OpenGL image viewer and client applications

†   Optional, needed to build the API reference

‡   Optional, needed to build the manual pages

§   Optional, needed to build the manual (HTML and PDF)

  Quick start

Install the following packages to build OME-Files 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:

BSD Ports
    pkg install devel/boost-all devel/cmake science/hdf5 graphics/png lang/python textproc/py-genshi graphics/tiff textproc/xerces-c3 devel/git devel/googletest math/glm devel/qt5 graphics/graphviz devel/apache-ant java/openjdk7 textproc/py-sphinx print/texlive-full

Debian/Ubuntu
    apt-get install build-essential libboost-all-dev cmake libhdf5-dev libpng12-dev python python-genshi libtiff5-dev libxerces-c-dev git libgtest-dev libglm-dev qt5-default libqt5-opengl5-dev libqt5-svg5-dev graphviz ant ant-contrib ant-optional openjdk-7-jdk openjdk-7-jre python-sphinx texlive-full

  Partial quick starts

Homebrew and RedHat/CentOS do not provide packages for everything that is needed. The commands listed will install most of the dependencies, but further dependencies will need to be installed as described in various sections below.

Homebrew
    brew install boost cmake hdf5 libpng python libtiff xerces-c git glm qt5 graphviz ant

RedHat/CentOS
    yum install libhdf5-devel libpng-devel python python-genshi libtiff-devel xerces-c-devel git gtest-devel graphviz java-1.7.0-openjdk See the Boost section for installing a newer version of Boost.

  Basic toolchain

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§

*   Available by default

†   Install Xcode

‡   Run yum groupinstall "Development Tools"

§   Install Visual Studio or Visual Studio Express

  Boost

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.

  CMake

If possible, install the following packages:
System | Package
BSD Ports | devel/cmake
Debian/Ubuntu | cmake
Homebrew | cmake
RedHat/CentOS | cmake

•   Website

•   Download

  HDF5

If possible, install the following packages:
System | Package
BSD Ports | science/hdf5
Debian/Ubuntu | libhdf5-dev
Homebrew | hdf5
RedHat/CentOS | libhdf5-devel

  PNG

If possible, install the following packages:
System | Package
BSD Ports | graphics/png
Debian/Ubuntu | libpng12-dev
Homebrew | libpng
RedHat/CentOS | libpng-devel

  Python

If possible, install the following packages:
System | Package
BSD Ports | lang/python
Debian/Ubuntu | python
Homebrew | python
RedHat/CentOS | python

•   Website

•   Download

•   Extra packages for Windows

    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.

  Python Genshi

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.

  TIFF

If possible, install the following packages:
System | Package
BSD Ports | graphics/tiff
Debian/Ubuntu | libtiff5-dev*
Homebrew | libtiff
RedHat/CentOS | libtiff-devel

*   libtiff4-dev with older releases

    4.0.2 and earlier do not have TIFFField accessor functions.

  Xerces-C

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

  Git

If possible, install the following packages:
System | Package
BSD Ports | devel/git
Debian/Ubuntu | git
Homebrew | git
RedHat/CentOS | git

•   Website

•   Download

  Google Test (gtest)

If possible, install the following packages:
System | Package
BSD Ports | devel/googletest
Debian/Ubuntu | libgtest-dev
Homebrew | N/A*
RedHat/CentOS | gtest-devel

*   gtest is not available in homebrew

    If using an 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 the gtest library was installed. If the library is located on the default library search path, this is not necessary.

•   Website

•   Zip download

•   SVN tag

  GLM

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.

•   Website

•   Download

  Qt5

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

*   Add /usr/local/opt/qt5/bin to PATH

•   Website

•   Download

  Doxygen
System | Package
BSD Ports | devel/doxygen
Debian/Ubuntu | doxygen
Homebrew | doxygen
RedHat/CentOS | doxygen

•   Website

•   Download

  Graphviz

If possible, install the following packages:
System | Package
BSD Ports | graphics/graphviz
Debian/Ubuntu | graphviz
Homebrew | graphviz
RedHat/CentOS | graphviz

•   Website

•   Download (for Windows)

  Apache Ant

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

•   Website

•   Download

  Java

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

•   Download

  Python Sphinx

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.

  TeX

If possible, install the following packages:
System | Package
BSD Ports | print/texlive-full
Debian/Ubuntu | texlive-full
Homebrew | N/A*
RedHat/CentOS | N/A†

*   Install TeXLive or MacTeX

†   Provides an obsolete version; install TeXLive

•   TeXLive website (for Unix)

•   TeXLive quick install (for Unix)

•   MacTeX website (for MacOS X)

•   MacTeX download (for MacOS X)

•   MikTeX website (for Windows)

•   MikTeX download (for Windows)

    Local font configuration may be required to make the TeX Gyre fonts available:

•   Linux and FreeBSD: Use the provided fontconfig template or create your own

•   MacOS X: Add to system using FontBook

•   Windows: May need adding to the system fonts if not found automatically

SOURCES

Download the OME-Files source code or the CMake superbuild source code, depending upon which type of build is required, as described above. The downloads page provides links to the source releases for both, as well as links to their git repositories. If you wish to build a specific release of OME-Files, the source release is appropriate, but if you wish to build the latest development work, or make changes to the sources, the git repository will be more useful.

BUILD ENVIRONMENT

  General

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:

•   Add to the system environment (globally)

•   Add to the user environment (affects a single user)

•   Set in a batch file and run this to set up the environment on demand (local to the command shell)

    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.

•   Activate a python virtualenv if needed

•   Ensure that needed tools are on the user PATH (e.g. ant, cmake, doxygen, dot, git, python, java, sphinx, xelatex)

•   Set CMAKE_PREFIX_PATH if some libraries and tools are not on the default search path. Not all tools need to be on the default path; some will be discovered automatically by cmake

  Homebrew

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.

CONFIGURING

OME-Files 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 OME-Files source tree. However, the source directory cannot be used 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 [-G <generator>] [<options>] /path/to/source

Where <generator> is the platform-specific build system to generate files for, and <options> are any additional options to configure the build to your requirements. See below for information about the different generators.

Run cmake -LH to see the configurable project options; use -LAH to see advanced options. The following basic options are supported:

cxxstd-autodetect=(ON|OFF)
    Enable or disable (default) C++ compiler standard autodetection. If enabled, the compiler will be put into C++11 mode if available, otherwise falling back to C++03 or C++98. If disabled, the default compiler standard mode is used, and it is the responsibility of the user to add the appropriate compiler options to build using the required standard. This is useful if autodetection fails or a compiler is buggy in certain modes (e.g. GCC 4.4 or 4.6 require -std=gnu++98 or else stdarg support is broken).

doxygen=(ON|OFF)
    Enable doxygen documentation. These will be enabled by default if doxygen is found.

extended-tests=(ON|OFF)
    Some of the unit tests are comprehensive and run many thousands of tests. These are enabled by default, but by setting to OFF a representative subset of the tests will be run instead to save time.

extra-warnings=(ON|OFF)
    Enable or disable additional compiler warnings in addition to the default set. These are disabled by default since they trigger a large number of false positives, particularly in third-party libraries outside our control.

fatal-warnings=(ON|OFF)
    Make compiler warnings into fatal errors. This is disabled by default.

qtgui=(ON|OFF)
    Enable building of the Qt5 widget library ome-qtwidgets and a simple Qt5 OpenGL image viewer. This is enabled by default if the needed libraries are available.

relocatable-install=(ON|OFF)
    Make the installed libraries, programs and datafiles relocatable; this means that they may be moved from their installation prefix to another location without breaking them. If OFF, the installation prefix is assumed to contain the libraries and datafiles. If ON, no assumptions are made, and a slower fallback is used to introspect the location. In all cases the location may be set in the environment to override the compiled-in defaults. This is OFF by default for a regular build, and ON by default for a superbuild.

sphinx=(ON|OFF)
    Build manual pages and HTML documentation with Sphinx. Enabled by default if Sphinx is autodetected.

sphinx-pdf=(ON|OFF)
    Build PDF documentation with Sphinx. Enabled by default if Sphinx and XeLaTeX are autodetected.

test=(ON|OFF)
    Enable unit tests. Tests are enabled by default.

xsdfu-debug=(ON|OFF)
    Enable debugging output for the model code generator.

    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.

    If using the superbuild, most of the options above will be available, and will be passed to the OME-Files build. In addition, the following options are provided:

build-packages=packages
    Build the specified list of packages (semicolon-separated). Defaults to ome-files. This can include any OME or third-party packages provided by the superbuild.

build-prerequisites=(ON|OFF)
    Build third-party prerequisites in addition to OME prerequisites such as ome-common and ome-files. Enabled by default. Disable to build against system libraries, with system python modules and system tools.

source-cache=directory
    Specify a directory in which to store downloaded source files; this is useful if you need to repeat the build since the source files will not need downloading again.

build-cache=directory
    Specify a directory from which to source pre-built third-party prerequisites. Useful to save time when rebuilding if the content of the superbuild-install directory is placed here after building third-party-prerequisites.

python-cache=directory
    Specify a directory from which to source pre-built third-party python prerequisites. Useful to save time when rebuilding if the content of the python directory is placed here after building third-party-prerequisites.

ome-superbuild_USE_SYSTEM_${package}=(ON|OFF)
    Use when build-prerequisites is enabled. This permits the selective disabling of the building of particular components, in order to use the system version of these components. By default, building of all components is enabled. ${package} is the component name. Look in the packages directory for a full list of components.

ome-superbuild_BUILD_${package}=(ON|OFF)
    Use when build-prerequisites is disabled. This permits the selective enabling of the building of particular components, in order to use the superbuild version of these components. By default, building of all components is disabled. ${package} is the component name. Look in the packages directory for a full list of components.

  C++11

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.

  Unix, Linux and MacOS X

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.

An alternative generator to consider is Ninja. It is recommended for parallel builds. This is similar to Unix Makefiles but allows building with the ninja tool in place of make. It is, in general, faster than make, and it is also much nicer when building in parallel since it will automatically adjust the number of jobs being run, and will also buffer the output for each job to allow the build log to be readable, rather than interleaving the output from concurrently running jobs.

If you wish to use an IDE such as Eclipse or KDevelop, alternative generators are also available, but are not actively tested by the OME continuous integration system.

  Windows

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 12 Win64" will configure for generating Visual Studio 2013 64-bit solution and project files for use with the Visual C++ compiler tool msbuild or for opening in the Visual Studio application.

An alternative generator to consider is Ninja. It is much faster than building the Visual Studio project and solution files with msbuild due to being much more effective at running jobs in parallel, since msbuild only runs project builds in parallel while ninja will run everything in parallel. ninja will also automatically adjust the number of jobs being run, and will also buffer the output for each job to allow the build log to be readable. The build log is also much less verbose than the output from msbuild. However, solution and project files for use within the Visual Studio application are not generated.

NOTE: There is no need to use the Visual Studio command shell when running cmake with Visual Studio generators since the generator specifies the version of Visual Studio to use. However, the Visual Studio command shell must be used (or a command shell with the appropriate environment set used) when using the Ninja generator, since the same generator is used for all Visual Studio versions and the specific compiler to use must be specified.

BUILDING

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

  Unix, Linux and MacOS X

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

Similarly, if using Ninja, simply run:

% ninja

or to build the API reference, run:

% ninja doc

If using an IDE, open the generated project file and proceed using the IDE to build the project.

  Windows

If using one of the Visual Studio generators, the generated solution and project files may be opened using the IDE and then built within the IDE. Alternatively, the solution or 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). Run:

> msbuild <project>.sln /p:Configuration=<configuration>

Where <project> is the specific package being built, and <configuration> is the build type, usually Debug or Release.

If using the Ninja generator, run the ninja 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). Run:

> ninja

TESTING

For all platforms and generators, it should usually be possible to run all tests using ctest. Run:

% ctest [-C <configuration>]

or to run verbosely:

% ctest -V [-C <configuration>]

Additional flags allow specification of the build configuration to use, logging, parallel building and other options. Please see the ctest documentation for further details. Running ctest directly is preferred over the methods detailed below since passing options works in all cases, and it is also possible to specify the build configuration (used on Windows).

Individual test programs may be run by hand if required.

  Unix, Linux and MacOS X

To run all tests, run:

% cmake --build . --target test

If using Unix Makefiles, simply run:

% make test

or verbosely:

% make test ARGS=-V

If using Ninja, simply run:

% ninja test

  Windows

To run all tests, if using a Visual Studio generator, run:

> msbuild RUN_TESTS.vcproj

If using Ninja, simply run:

> ninja test

INSTALLATION

  Unix, Linux and MacOS X

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

If using Ninja, simply run:

% ninja install

  Windows

When using a Visual Studio generator, there should be an INSTALL.vcxproj project which may be run using msbuild, for example:

> msbuild INSTALL.vcxproj /p:platform=x64

The INSTALL project may also be built within the Visual Studio application.

If using Ninja, simply run:

> ninja install

  Installation layout

A typical installation layout:

$CMAKE_INSTALL_PREFIX
├── bin
├── include
│   └── ome
│       ├── common
│       ├── compat
│       ├── files
│       └── xml
├── lib
├── libexec
└── share
    ├── icons
    ├── man
    └── xml

USING THE LIBRARY

The Doxygen API reference is used to document all aspects of the OME-Files API.

AUTHOR
The Open Microscopy Environment

COPYRIGHT
2000-2016, The Open Microscopy Environment