Library for producing and processing on the Adaptive Particle Representation (APR) (For article see: https://www.biorxiv.org/content/early/2018/02/09/263061).
Labeled Zebrafish nuclei: Gopi Shah, Huisken Lab (MPI-CBG, Dresden and Morgridge Institute for Research, Madison); see also Schmid et al., Nature Communications 2017
- HDF5 1.8.20 or higher
- OpenMP > 3.0 (optional, but suggested)
- CMake 3.6 or higher
- LibTIFF 5.0 or higher
- SWIG 3.0.12 (optional, for generating Java wrappers)
Opening hdf5 files in ParaView or HDFView requires additional installation of two libraries:
- c-blosc 1.11.2 or higher
- hdf5-blosc 1.1.0 or higher
The repository requires sub-modules, so the repository needs to be cloned recursively:
git clone --recursive https://github.com/cheesema/LibAPR
If you need to update your clone at any point later, run
git pull
git submodule update
On Ubuntu, install the cmake
, build-essential
, libhdf5-dev
and libtiff5-dev
packages (on other distributions, refer to the documentation there, the package names will be similar). OpenMP support is provided by the GCC compiler installed as part of the build-essential
package.
In the directory of the cloned repository, run
mkdir build
cd build
cmake ..
make
This will create the libapr.so
library in the build
directory, as well as all of the examples.
We provide working Dockerfile that install the library within the image on a separate repo.
On OSX, install the cmake
, hdf5
and libtiff
homebrew packages and have the Xcode command line tools installed.
If you want to compile with OpenMP support, also install the llvm
package, as the clang version shipped by Apple currently does not support OpenMP.
In the directory of the cloned repository, run
mkdir build
cd build
cmake ..
make
This will create the libapr.so
library in the build
directory, as well as all of the examples.
In case you want to use the homebrew-installed clang, modify the call to cmake
above to
CC="/usr/local/opt/llvm/bin/clang" CXX="/usr/local/opt/llvm/bin/clang++" LDFLAGS="-L/usr/local/opt/llvm/lib -Wl,-rpath,/usr/local/opt/llvm/lib" CPPFLAGS="-I/usr/local/opt/llvm/include" cmake ..
Compilation only works with mingw64/clang or the Intel C++ Compiler, with Intel C++ being the recommended way
You need to have Visual Studio 2017 installed, with the community edition being sufficient. LibAPR does not compile correctly with the default Visual Studio compiler, so you also need to have the Intel C++ Compiler, 18.0 or higher installed. cmake
is also a requirement.
Furthermore, you need to have HDF5 installed (binary distribution download at The HDF Group and LibTIFF (source download from SimpleSystems. LibTIFF needs to be compiled via cmake
. LibTIFF's install target will then install the library into C:\Program Files\tiff
.
In the directory of the cloned repository, run:
mkdir build
cd build
cmake -G "Visual Studio 15 2017 Win64" -DTIFF_INCLUDE_DIR="C:/Program Files/tiff/include" -DTIFF_LIBRARY="C:/Program Files/tiff/lib/tiff.lib " -DHDF5_ROOT="C:/Program Files/HDF_Group/HDF5/1.8.17" -T "Intel C++ Compiler 18.0" ..
cmake --build . --config Debug
This will set the appropriate hints for Visual Studio to find both LibTIFF and HDF5. This will create the apr.dll
library in the build/Debug
directory, as well as all of the examples. If you need a Release
build, run cmake --build . --config Release
from the build
directory.
There are nine basic examples, that show how to generate and compute with the APR:
Example | How to ... |
---|---|
Example_get_apr | create an APR file from a TIFF. |
Example_apr_iterate | iterate through a given APR file. |
Example_neighbour_access | access particle and face neighbours. |
Example_compress_apr | additionally compress the intensities stored in an APR file. |
Example_compute_gradient | compute a gradient based on the stored particles in an APR file. |
Example_produce_paraview_file | produce a file for visualisation in ParaView. |
Example_random_access | perform random access operations on particles. |
Example_ray_cast | perform a maximum intensity projection ray cast directly on the APR data structures read from an APR file. |
Example_reconstruct_image | reconstruct an pixel image from an APR file. |
For tutorial on how to use the examples, and explanation of data-structures see the library guide.
- more examples for APR-based filtering and segmentation
- more convenient use from CMake projects
- deployment of the Java wrappers to Maven Central so they can be used in your project directly
- support for loading the APR in Fiji, including scenery-based 3D rendering
If you use this library in an academic context, please cite the following paper:
- Cheeseman, Günther, Susik, Gonciarz, Sbalzarini: Forget Pixels: Adaptive Particle Representation of Fluorescence Microscopy Images (bioRxiv 2018) https://www.biorxiv.org/content/early/2018/02/09/263061