Merge pull request #165 from AdaptiveParticles/develop

bump master

Author: joeljonsson

.github/workflows/cmake.yml

@@ -1,4 +1,4 @@
-name: CMake
+name: Build and Test
 
 on:
   push:

.gitignore

@@ -217,6 +217,8 @@ cmake-build-debug/
 cmake-build-release/
 cmake-build*
 xcode*
+build-cmake-debug/
+build-cmake-release/
 #####
 # Xcode private settings (window sizes, bookmarks, breakpoints, custom executables, smart groups)
 #

CMakeLists.txt

@@ -25,11 +25,11 @@ option(APR_DENOISE "enable denoising code" OFF)
 
 # Validation of options
 if (NOT APR_BUILD_SHARED_LIB AND NOT APR_BUILD_STATIC_LIB)
-    message(FATAL_ERROR "At least one target: APR_BUILD_SHARED_LIB or APR_BUILD_STATIC_LIB must be build!")
+    message(FATAL_ERROR "At least one target: APR_BUILD_SHARED_LIB or APR_BUILD_STATIC_LIB must be enabled")
 endif()
 if (NOT APR_USE_LIBTIFF)
     if (APR_TESTS OR APR_BUILD_EXAMPLES)
-        message(FATAL_ERROR "Building tests orexamples not possible when APR_USE_LIBTIFF=OFF!")
+        message(FATAL_ERROR "Building tests or examples is not possible when APR_USE_LIBTIFF=OFF")
     endif()
 endif()
 
@@ -42,7 +42,7 @@ list(APPEND CMAKE_MODULE_PATH
 ###############################################################################
 
 set (APR_VERSION_MAJOR 2)
-set (APR_VERSION_MINOR 0)
+set (APR_VERSION_MINOR 1)
 set (APR_VERSION_PATCH 0)
 set (APR_VERSION_STRING ${APR_VERSION_MAJOR}.${APR_VERSION_MINOR}.${APR_VERSION_PATCH})
 
@@ -355,7 +355,7 @@ endif(APR_BUILD_EXAMPLES)
 if(APR_TESTS)
     message(STATUS "APR: Building tests")
     if(APR_PREFER_EXTERNAL_GTEST)
-        find_package(GTest 1.8.0)
+        find_package(GTest 1.10.0)
     endif()
     if(GTEST_FOUND)
         include_directories(${GTEST_INCLUDE_DIRS})

INSTALL_INSTRUCTIONS.md

@@ -1,15 +1,17 @@
 # Install instructions for LibAPR.
 
-The way to use it is configure it via some new APR_* variables (can be set to ON/OFF depending on needs) which describes what to build and if it should be installed through cmake commands:
+The build is configured it via several CMake options (APR_* variables), which can be set to ON/OFF depending on your needs.
+The following options control the build type and installation:
 
-APR_BUILD_STATIC_LIB=ON
-APR_BUILD_SHARED_LIB=OFF
-APR_INSTALL=ON
-(all other configuration possibilities are now in the top of CMakeLists.txt file)
+- APR_BUILD_STATIC_LIB=ON
+- APR_BUILD_SHARED_LIB=OFF
+- APR_INSTALL=ON
+
+See [README](README.md) for the full list of build options.
 
 ## OSX / UNIX Installation
 
-so full command line would look like: (-DCMAKE_INSTALL_PREFIX=/tmp/APR can be used for a non-default location)
+The full command-line to install the library may look like:
 
 ```
 mkdir build
@@ -18,35 +20,34 @@ cmake -DAPR_INSTALL=ON -DAPR_BUILD_STATIC_LIB=ON -DAPR_BUILD_SHARED_LIB=OFF ..
 make
 make install
 ```
-
-You may need file-permissions (sudo for the install)
+with other build options turned on/off as required. Non-default install locations can be set via 
+`-DCMAKE_INSTALL_PREFIX=/tmp/APR`. Depending on the location, you may need file-permissions (sudo) for the install command.
 
 ## Windows Installation Clang
 
-``
+On Windows the install commands may look like:
+
+```
 cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_TOOLCHAIN_FILE="PATH_TO_VCPKG\vcpkg\scripts\buildsystems\vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows -T ClangCL -DAPR_BUILD_STATIC_LIB=ON -DAPR_BUILD_SHARED_LIB=OFF -DAPR_INSTALL=ON ..
 cmake --build . --config Release
-``
-
-Need to be in a console running as administrator. 
-
-``
 cmake --install .
-``
+```
 
-## Minimal example CMAKE
+(Probably need to be in a console running as administrator)
 
-To use APR the minimalistic CMakeLists.txt file can be found here: https://github.com/AdaptiveParticles/APR_cpp_project_example
+## Minimal CMake example
 
-##
+A minimalistic CMakeLists.txt file for using LibAPR in another C++ project can be found here: https://github.com/AdaptiveParticles/APR_cpp_project_example
 
-APR::staticLib (Note, tested across Windows, Linux, and Mac)
-APR::sharedLib (Note, not tested)
+### Notes:
 
-If shared version is preferred then APR::sharedLib should be used (and of course APR_BUILD_SHARED_LIB=ON during lib build step).
+If shared version is preferred then `APR::sharedLib` should be used (and of course APR_BUILD_SHARED_LIB=ON during the build step).
 
-NOTICE: if APR is installed in not standard directory then some hint for cmake must be provided by adding install dir to CMAKE_PREFIX_PATH like for above example:
+Use of `APR::staticLib` has been tested across Windows, Linux, and Mac.
+`APR::sharedLib` has currently only been tested on Linux.
 
+If APR is installed in a non-standard location then some hint for cmake must be provided by adding the install directory 
+to CMAKE_PREFIX_PATH, for example:
 ```
 export CMAKE_PREFIX_PATH=/tmp/APR:$CMAKE_PREFIX_PATH
 ```

README.md

@@ -12,40 +12,24 @@ Labeled Zebrafish nuclei: Gopi Shah, Huisken Lab ([MPI-CBG](https://www.mpi-cbg.
 
 ## Python support
 
-We now provide python wrappers in a separate repository [PyLibAPR](https://github.com/AdaptiveParticles/PyLibAPR)
+We provide python wrappers in a separate repository [pyapr](https://github.com/AdaptiveParticles/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:
+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
 
-
-## Version 2.0 release notes
-
-The library has changed significantly since release 1.1. __There are changes to IO and iteration that are not compatible 
-with the older version__. 
-
-* New (additional) linear access data structure, explicitly storing coordinates in the sparse dimension, 
-  similar to Compressed Sparse Row.
-* Block-based decomposition of the APR generation pipeline, allowing conversion of very large images.
-* Expanded and improved functionality for image processing directly on the APR:
-  * APR filtering (spatial convolutions).
-  * [APRNumerics](./src/numerics/APRNumerics.hpp) module, including e.g. gradient computations and Richardson-Lucy deconvolution.
-  * CUDA GPU-accelerated convolutions and RL deconvolution (currently only supports dense 3x3x3 and 5x5x5 stencils)
-
-
 ## Dependencies
 
 * HDF5 1.8.20 or higher
 * OpenMP > 3.0 (optional, but recommended)
 * CMake 3.6 or higher
 * LibTIFF 4.0 or higher
 
-
-NB: This update to 2.0 introduces changes to IO and iteration that are not compatable with old versions.
-
 If compiling with APR_DENOISE flag the package also requires:
 * Eigen3.
 
@@ -67,6 +51,7 @@ 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 |
@@ -76,15 +61,18 @@ cmake -DAPR_USE_OPENMP=OFF ..
 | APR_PREFER_EXTERNAL_GTEST | Use installed gtest instead of included sources | ON |
 | APR_PREFER_EXTERNAL_BLOSC | Use installed blosc instead of included sources | ON |
 | APR_USE_OPENMP | Enable multithreading via OpenMP | ON |
-| APR_USE_CUDA | Enable CUDA (Under development - APR conversion pipeline is currently not working with CUDA enabled) | OFF |
+| 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.
+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.
 
-For denoising support also requires: `libeigen3-dev`
+Denoising support also requires `libeigen3-dev`.
 
-In the directory of the cloned repository, run
+In the directory of the cloned repository, run:
 
 ```
 mkdir build
@@ -97,9 +85,11 @@ This will create the `libapr.so` library in the `build` directory.
 
 ### Building on OSX
 
-On OSX, install the `cmake`, `hdf5` and `libtiff`  [homebrew](https://brew.sh) packages and have the [Xcode command line tools](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/) installed.
+On OSX, install the `cmake`, `hdf5` and `libtiff`  [homebrew](https://brew.sh) packages and have the 
+[Xcode command line tools](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/) 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.
+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
 
@@ -160,11 +150,11 @@ Note: not recently tested.
 
 ## Install instructions 
 
-Please see: INSTALL_INSTRUCTIONS.md and https://github.com/AdaptiveParticles/APR_cpp_project_example for a minimal project using the APR.
+Please see [INSTALL_INSTRUCTIONS](INSTALL_INSTRUCTIONS.md) and https://github.com/AdaptiveParticles/APR_cpp_project_example for a minimal project using the APR.
 
 ## Examples and Documentation
 
-There are 12 basic examples, that show how to generate and compute with the APR. These can be built by adding 
+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 ... |
@@ -181,10 +171,13 @@ There are 12 basic examples, that show how to generate and compute with the APR.
 | [Example_compute_gradient](./examples/Example_compute_gradient.cpp) | compute the gradient magnitude of an APR. |
 | [Example_apr_filter](./examples/Example_apr_filter.cpp) | apply a filter (convolution) to an APR. |
 | [Example_apr_deconvolution](./examples/Example_apr_deconvolution.cpp) | perform Richardson-Lucy deconvolution on an APR. |
+| [Exampe_denoise](./examples/Example_denoise.cpp) | denoise an APR (experimental) |
+| [Example_lazy_access](./examples/Example_lazy_access.cpp) | 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](./docs/lib_guide.pdf).
+For tutorial on how to use the examples, and explanation of data-structures see [the library guide](./docs/lib_guide.pdf) 
+(note: this is outdated - in particular code examples may not work and some discussed parameters do not exist anymore).
 
 ## LibAPR Tests
 
@@ -196,7 +189,9 @@ on the command line in your build folder. Please let us know by creating an issu
 
 ## Java wrappers
 
-Basic Java wrappers can be found at [LibAPR-java-wrapper](https://github.com/krzysg/LibAPR-java-wrapper) Not compatable with recent releases.
+Basic Java wrappers can be found at [LibAPR-java-wrapper](https://github.com/AdaptiveParticles/LibAPR-java-wrapper). 
+
+Note: not compatable with recent releases.
 
 ## Coming soon
 

benchmarks/BenchCudaAccessInit.cpp

@@ -70,12 +70,12 @@ inline void bench_access_full(APR& apr,ParticleData<partsType>& parts,int num_re
 
     for(int r = 0; r < 5; ++r) {
         auto access = apr.gpuAPRHelper();
-        access.init_gpu();
+        access.init_gpu(true);
         error_check ( cudaDeviceSynchronize() )
         error_check( cudaGetLastError() )
 
         auto tree_access = apr.gpuTreeHelper();
-        tree_access.init_gpu();
+        tree_access.init_gpu(true);
         error_check ( cudaDeviceSynchronize() )
         error_check( cudaGetLastError() )
     }
@@ -84,14 +84,14 @@ inline void bench_access_full(APR& apr,ParticleData<partsType>& parts,int num_re
     for(int r = 0; r < num_rep; ++r) {
         timer2.start_timer("apr access");
         auto access = apr.gpuAPRHelper();
-        access.init_gpu();
+        access.init_gpu(true);
         error_check ( cudaDeviceSynchronize() )
         timer2.stop_timer();
         apr_time += timer2.timings.back();
 
         timer2.start_timer("tree access");
         auto tree_access = apr.gpuTreeHelper();
-        tree_access.init_gpu();
+        tree_access.init_gpu(true);
         error_check ( cudaDeviceSynchronize() )
         timer2.stop_timer();
         tree_time += timer2.timings.back();
@@ -115,12 +115,12 @@ inline void bench_access_partial(APR& apr,ParticleData<partsType>& parts,int num
 
     for(int r = 0; r < 5; ++r) {
         auto tree_access = apr.gpuTreeHelper();
-        tree_access.init_gpu();
+        tree_access.init_gpu(true);
         error_check ( cudaDeviceSynchronize() )
         error_check( cudaGetLastError() )
 
         auto access = apr.gpuAPRHelper();
-        access.init_gpu(tree_access);
+        access.init_gpu(tree_access, true);
         error_check ( cudaDeviceSynchronize() )
         error_check( cudaGetLastError() )
     }
@@ -130,14 +130,14 @@ inline void bench_access_partial(APR& apr,ParticleData<partsType>& parts,int num
 
         timer2.start_timer("tree access");
         auto tree_access = apr.gpuTreeHelper();
-        tree_access.init_gpu();
+        tree_access.init_gpu(true);
         error_check ( cudaDeviceSynchronize() )
         timer2.stop_timer();
         tree_time += timer2.timings.back();
 
         timer2.start_timer("apr access");
         auto access = apr.gpuAPRHelper();
-        access.init_gpu(tree_access);
+        access.init_gpu(tree_access, true);
         error_check ( cudaDeviceSynchronize() )
         timer2.stop_timer();
         apr_time += timer2.timings.back();

benchmarks/BenchIO.cpp

@@ -106,13 +106,11 @@ inline void bench_apr_io(APR& apr,ParticleData<partsType>& parts,int num_rep,Ana
 
     aprFile.open(file_name,"WRITE");
 
-    aprFile.set_read_write_tree(false);
-
     for (int r = 0; r < num_rep; ++r) {
 
         timer_steps.start_timer("write_apr");
 
-        aprFile.write_apr(apr,r);
+        aprFile.write_apr(apr, r, "t", false);
 
         timer_steps.stop_timer();
 
@@ -132,8 +130,6 @@ inline void bench_apr_io(APR& apr,ParticleData<partsType>& parts,int num_rep,Ana
 
     aprFile.open(file_name,"READ");
 
-    aprFile.set_read_write_tree(false);
-
     for (int r = 0; r < num_rep; ++r) {
 
         timer_steps.start_timer("read_apr");

benchmarks/BenchPartData.cpp

@@ -155,7 +155,7 @@ inline void bench_lazy_particle_data(APR& apr,ParticleData<partsType>& parts,int
 
     LazyData<uint16_t> parts_lazy;
 
-    parts_lazy.init_file(writeFile,"parts",true);
+    parts_lazy.init(writeFile, "parts");
 
     parts_lazy.open();
 

benchmarks/BenchPipeline.cpp

@@ -86,8 +86,6 @@ inline void bench_apr_pipeline(APR& apr,ParticleData<partsType>& parts,int num_r
 
     aprFile.open("file_name","WRITE");
 
-    aprFile.set_read_write_tree(false);
-
     for (int r = 0; r < num_rep; ++r) {
 
         timer_steps.start_timer("get_apr");
@@ -98,13 +96,13 @@ inline void bench_apr_pipeline(APR& apr,ParticleData<partsType>& parts,int num_r
 
         timer_steps.start_timer("sample_parts");
 
-        part_vec[r].sample_parts_from_img_downsampled(apr_vec[r],pipelineImage);
+        part_vec[r].sample_image(apr_vec[r], pipelineImage);
 
         timer_steps.stop_timer();
 
         timer_steps.start_timer("write_apr");
 
-        aprFile.write_apr(apr_vec[r],r);
+        aprFile.write_apr(apr_vec[r], r, "t", false);
 
         timer_steps.stop_timer();
 

benchmarks/FilterBenchmarks.hpp

@@ -817,13 +817,13 @@ inline void bench_richardson_lucy_apr(APR& apr, ParticleData<partsType>& parts,
 
     // burn-in
     for(int i = 0; i < num_rep/10; ++i) {
-        richardson_lucy(access, tree_access, input_gpu.get(), output_gpu.get(), stencil_gpu.get(), stencil_gpu.get(), 5, niter, true);
+        APRNumericsGPU::richardson_lucy(access, tree_access, input_gpu.get(), output_gpu.get(), stencil_gpu.get(), stencil_gpu.get(), 5, niter, true);
     }
     cudaDeviceSynchronize();
 
     timer.start_timer("richardson lucy");
     for(int i = 0; i < num_rep; ++i) {
-        richardson_lucy(access, tree_access, input_gpu.get(), output_gpu.get(), stencil_gpu.get(), stencil_gpu.get(), 5, niter, true);
+        APRNumericsGPU::richardson_lucy(access, tree_access, input_gpu.get(), output_gpu.get(), stencil_gpu.get(), stencil_gpu.get(), 5, niter, true);
     }
     cudaDeviceSynchronize();
     timer.stop_timer();