Skip to content

Library for producing and processing on the Adaptive Particle Representation (APR).

License

Notifications You must be signed in to change notification settings

AdaptiveParticles/LibAPR

Repository files navigation

LibAPR - The Adaptive Particle Representation Library

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

CMake DOI

Python support

We provide python wrappers in a separate repository pyapr. This is likely the simplest option to first try and use the APR.

In addition to providing wrappers for most of the LibAPR functionality, the Python library contains a number of new features that simplify the generation and handling of the APR. For example:

  • Interactive APR conversion
  • Interactive APR z-slice viewer
  • Interactive APR raycast (maximum intensity projection) viewer
  • Interactive lossy compression of particle intensities

Dependencies

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

If compiling with APR_DENOISE flag the package also requires:

  • Eigen3.

Building

The repository requires submodules, and needs to be cloned recursively:

git clone --recursive https://github.com/AdaptiveParticles/LibAPR.git

CMake build options

Several CMake options can be given to control the build. Use the -D argument to set each desired option. For example, to disable OpenMP, change the cmake calls below to

cmake -DAPR_USE_OPENMP=OFF ..
Option Description Default value
APR_INSTALL Install library OFF
APR_BUILD_SHARED_LIB Build shared library OFF
APR_BUILD_STATIC_LIB Build static library ON
APR_BUILD_EXAMPLES Build executable examples OFF
APR_TESTS Build unit tests OFF
APR_BENCHMARK Build executable performance benchmarks OFF
APR_USE_LIBTIFF Enable LibTIFF (Required for tests and examples) ON
APR_PREFER_EXTERNAL_GTEST Use installed gtest instead of included sources OFF
APR_PREFER_EXTERNAL_BLOSC Use installed blosc instead of included sources OFF
APR_USE_OPENMP Enable multithreading via OpenMP ON
APR_USE_CUDA Enable CUDA functionality (under development) OFF
APR_DENOISE Enable denoising code (requires Eigen3) OFF

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.

Denoising support also requires libeigen3-dev.

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.

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 (Recommended), also install the llvm and libomp package via 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

Building on Windows

On windows there are two working strategies we have tested. Either cheating and using WSL2 and linux above, or utilising a recent version clang-cl or clang directly as included in MSVC 2019 >16.8.6. Note for earlier versions OpenMP support did not work.

The easiest way to set up your windows environment we have found is using chocolatey + vcpkg.

Chocolatey Install:

First install chocolatey using powershell: https://chocolatey.org/install

Open an admin powershell (for chocolatey steps)

If not installed, install git and cmake:

choco install -y git 
choco install -y cmake.portable

install the required visual studio compiler tools and clang: (Note you can also do this via downloading 2019 community and selecting the correct packages)

choco install visualstudio2019buildtools --params "--add Microsoft.Component.MSBuild --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset --add Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Llvm.Clang --add Microsoft.VisualStudio.Component.Windows10SDK.19041	--add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.ComponentGroup.UWP.VC.BuildTools"
choco install -y llvm

Now install your dependencies using vcpkg, in an install directory (VCPKG_PATH) of your choice do the following:

git clone https://github.com/microsoft/vcpkg
cd vcpkg
./bootstrap-vcpkg.bat
./vcpkg.exe install blosc:x64-windows gtest:x64-windows tiff:x64-windows hdf5:x64-windows szip:x64-windows

Now navigate to your cloned LibAPR directory (git clone --recursive https://github.com/AdaptiveParticles/LibAPR.git). You should have all dependencies set up to be able to build the library with clang-cl -A x64 -T ClangCL and to search for dependencies from vcpkg at your vcpkg install location: -DCMAKE_TOOLCHAIN_FILE="VCPKG_PATH/vcpkg/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows .

Now for example to build the tests and examples (Please note you will need to update below with your own VCPKG_PATH from the steps above.

mkdir build
cd build

Cmake -A x64 -DCMAKE_TOOLCHAIN_FILE="VCPKG_PATH/vcpkg/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows -T ClangCL -DAPR_BUILD_EXAMPLES=ON -DAPR_TESTS=ON ..
cmake --build . --config Release

The above examples is also used in CI and can be executed in the cmake-build_windows.sh

Docker build

We provide a working Dockerfile that installs the library within the image in a separate repository.

Note: not recently tested.

Install instructions

Please see INSTALL_INSTRUCTIONS and https://github.com/AdaptiveParticles/APR_cpp_project_example for a minimal project using the APR.

Examples and Documentation

There are 14 basic examples, that show how to generate and compute with the APR. These can be built by adding -DAPR_BUILD_EXAMPLES=ON to the cmake command.

Example How to ...
Example_get_apr create an APR from a TIFF and store as hdf5.
Example_get_apr_by_block create an APR from a (potentially large) TIFF, by decomposing it into smaller blocks, and store as hdf5.
Example_apr_iterate iterate over APR particles and their spatial properties.
Example_apr_tree iterate over interior APR tree particles and their spatial properties.
Example_neighbour_access access particle and face neighbours.
Example_compress_apr additionally compress the intensities stored in an APR.
Example_random_access perform random access operations on particles.
Example_ray_cast perform a maximum intensity projection ray cast directly on the APR.
Example_reconstruct_image reconstruct a pixel image from an APR.
Example_compute_gradient compute the gradient magnitude of an APR.
Example_apr_filter apply a filter (convolution) to an APR.
Example_apr_deconvolution perform Richardson-Lucy deconvolution on an APR.
Exampe_denoise denoise an APR (experimental)
Example_lazy_access lazily iterate over APR particles and their spatial properties

All examples except Example_get_apr and Example_get_apr_by_block 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 (note: this is outdated - in particular code examples may not work and some discussed parameters do not exist anymore).

LibAPR Tests

The testing framework can be turned on by adding -DAPR_TESTS=ON to the cmake command. All tests can then be run by executing

ctest

on the command line in your build folder. Please let us know by creating an issue, if any of these tests are failing on your machine.

Java wrappers

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

Note: not compatable with recent releases.

Coming soon

  • Improved documentation and updated library guide.
  • More examples of APR-based image processing and segmentation.
  • CUDA GPU-accelerated APR generation and additional processing options.
  • 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, dont hesitate to contact us if you have a project or algorithm you would like to try using the APR for. We would be glad to help!

Join the chat at https://gitter.im/LibAPR

Citing this work

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