Skip to content
Library for producing and processing on the Adaptive Particle Representation (APR).
Branch: master
Clone or download
Latest commit f4cc25f Apr 30, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmake Cmake: Fix linking together multiple libraries on Windows Mar 19, 2019
docs name changed MeshData -> PixelData May 9, 2018
examples minor change to the example, that could have lead the compression enc… Jan 25, 2019
external updated the c-blosc commit Jul 16, 2018
test SWIG removed Apr 3, 2019
.gitignore upgradded the smooth filter, added documentation, and added the depth… Jan 8, 2018
.gitmodules Fix of remote for pybind11 May 8, 2018
.travis.yml SWIG removed Apr 3, 2019
CMakeLists.txt Version 1.2.0 Apr 3, 2019
LICENSE Add Apache License 2.0 file, closes #12 Feb 8, 2018 Update Apr 30, 2019 Turn on python testing for travis Jun 21, 2018
pom.xml Add APRIterator::set_iterator_to_particle_number(uint32_t) and bump J… Feb 7, 2018

LibAPR - The Adaptive Particle Representation Library

Library for producing and processing on the Adaptive Particle Representation (APR) (For article see:

Labeled Zebrafish nuclei: Gopi Shah, Huisken Lab (MPI-CBG, Dresden and Morgridge Institute for Research, Madison); see also Schmid et al., Nature Communications 2017

Build Status DOI


  • HDF5 1.8.20 or higher
  • OpenMP > 3.0 (optional, but suggested)
  • CMake 3.6 or higher
  • LibTIFF 4.0 or higher

NB: This branch introduces changes to IO and iteration that are not compatable with old versions.


The repository requires sub-modules, so the repository needs to be cloned recursively:

git clone --recursive

If you need to update your clone at any point later, run

git pull
git submodule update

Building on Linux

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 ..

This will create the library in the build directory, as well as all of the examples.

Docker build

We provide working Dockerfile that install the library within the image on a separate repo.

Building on OSX

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 (this can also be done using homebrew), 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 ..

This will create the library in the build directory, as well as all of the examples.

In case you want to use the homebrew-installed clang (OpenMP support), 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 ..

Building on Windows

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.

Examples and Documentation

There are nine basic examples, that show how to generate and compute with the APR:

Example How to ...
Example_get_apr create an APR from a TIFF and store as hdf5.
Example_apr_iterate iterate through a given APR.
Example_neighbour_access access particle and face neighbours.
Example_compress_apr additionally compress the intensities stored in an APR.
Example_compute_gradient compute a gradient based on the stored particles in an APR.
Example_produce_paraview_file produce a file for visualisation in ParaView or reading in Matlab.
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.
Example_reconstruct_image reconstruct a pixel image from an APR.

All examples except Example_get_apr require an already produced APR, such as those created by Example_get_apr.

For tutorial on how to use the examples, and explanation of data-structures see the library guide.

Python support

Basic functionality is supported in Python through wrappers. To build the python module, use the CMake option


Example usage of the available functionality:

Example How to ...
Example_get_apr_from_array create an APR from an ndarray and store as hdf5.
Example_get_apr_from_file create an APR from a TIFF and store as hdf5.
Example_reconstruct_image read in an APR and reconstruct a pixel image

Note that you may have to manually change the sys.path.insert() statements before import pyApr in these scripts to insert your build folder.

Java wrappers

Basic Java wrappers can be found at LibAPR-java-wrapper

Coming soon

  • more examples for APR-based filtering and segmentation
  • 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
  • improved java wrapper support
  • CUDA GPU-accelerated APR generation and processing
  • Block based decomposition for extremely large images.
  • Time series support.

Contact us

If anything is not working as you think it should, or would like it to, please get in touch with us!! Further, if you have a project, or algorithm, you would like to try using the APR for also please get in contact we would be glad to help!

Join the chat at

Citing this work

If you use this library in an academic context, please cite the following paper:

You can’t perform that action at this time.