Library for producing and processing on the Adaptive Particle Representation (APR) (For article see: https://www.nature.com/articles/s41467-018-07390-9).
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)
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 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 (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 ..
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 (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 ..
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 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.
Basic functionality is supported in Python through wrappers. To build the python module, use the CMake option
-DAPR_BUILD_PYTHON_WRAPPERS=ON
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.
Basic Java wrappers can be found at LibAPR-java-wrapper
- 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.
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!
If you use this library in an academic context, please cite the following paper:
- Cheeseman, Günther, Gonciarz, Susik, Sbalzarini: Adaptive Particle Representation of Fluorescence Microscopy Images (Nature Communications, 2018) https://doi.org/10.1038/s41467-018-07390-9