Merge pull request #176 from AdaptiveParticles/bump_version_2.1.0

joeljonsson · web-flow · commit e8b221afd128 · 2022-06-15T16:33:09.000+02:00
Bump version 2.1.0
diff --git a/CMakeLists.txt b/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})
 
diff --git a/INSTALL_INSTRUCTIONS.md b/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
 ```
diff --git a/README.md b/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
 
diff --git a/src/numerics/APRNumericsGPU.cu b/src/numerics/APRNumericsGPU.cu
@@ -209,32 +209,17 @@ void APRNumericsGPU::richardson_lucy(GPUAccessHelper& access, GPUAccessHelper& t
 
     VectorData<stencilType> psf_vec;
     VectorData<stencilType> psf_flipped_vec;
-
-    if(use_stencil_downsample) {
-        APRStencil::get_downsampled_stencils(psf, psf_vec, access.level_max() - access.level_min(), normalize_stencil);
-        APRStencil::get_downsampled_stencils(psf_flipped, psf_flipped_vec, access.level_max() - access.level_min(), normalize_stencil);
-    }
+    const int num_levels = use_stencil_downsample ? access.level_max() - access.level_min() : 1;
+    APRStencil::get_downsampled_stencils(psf, psf_vec, num_levels, normalize_stencil);
+    APRStencil::get_downsampled_stencils(psf_flipped, psf_flipped_vec, num_levels, normalize_stencil);
 
     output.resize(input.size());
 
-    /// allocate GPU memory
-    ScopedCudaMemHandler<inputType*, JUST_ALLOC> input_gpu(input.data(), input.size());
+    /// allocate GPU memory and copy data
+    ScopedCudaMemHandler<inputType*, H2D> input_gpu(input.data(), input.size());
     ScopedCudaMemHandler<stencilType*, JUST_ALLOC> output_gpu(output.data(), output.size());
-    ScopedCudaMemHandler<stencilType*, JUST_ALLOC> psf_gpu;
-    ScopedCudaMemHandler<stencilType*, JUST_ALLOC> psf_flipped_gpu;
-
-    if(use_stencil_downsample) {
-        psf_gpu.initialize(psf_vec.data(), psf_vec.size());
-        psf_flipped_gpu.initialize(psf_flipped_vec.data(), psf_flipped_vec.size());
-    } else {
-        psf_gpu.initialize(psf.mesh.get(), psf.mesh.size());
-        psf_flipped_gpu.initialize(psf_flipped.mesh.get(), psf_flipped.mesh.size());
-    }
-
-    /// copy input and psf to the device
-    input_gpu.copyH2D();
-    psf_gpu.copyH2D();
-    psf_flipped_gpu.copyH2D();
+    ScopedCudaMemHandler<stencilType*, H2D> psf_gpu(psf_vec.data(), psf_vec.size());
+    ScopedCudaMemHandler<stencilType*, H2D> psf_flipped_gpu(psf_flipped_vec.data(), psf_flipped_vec.size());
 
     if(resume) {
         output_gpu.copyH2D();
@@ -254,8 +239,10 @@ template void APRNumericsGPU::gradient_magnitude(GPUAccessHelper&, GPUAccessHelp
 template void APRNumericsGPU::gradient_magnitude(GPUAccessHelper&, GPUAccessHelper&, VectorData<uint64_t>&, VectorData<float>&, VectorData<float>&, VectorData<float>&, VectorData<float>&);
 template void APRNumericsGPU::gradient_magnitude(GPUAccessHelper&, GPUAccessHelper&, VectorData<float>&, VectorData<float>&, VectorData<float>&, VectorData<float>&, VectorData<float>&);
 
+template void APRNumericsGPU::richardson_lucy(GPUAccessHelper&, GPUAccessHelper&, uint8_t*, float*, float*, float*, int, int, bool, bool);
 template void APRNumericsGPU::richardson_lucy(GPUAccessHelper&, GPUAccessHelper&, uint16_t*, float*, float*, float*, int, int, bool, bool);
 template void APRNumericsGPU::richardson_lucy(GPUAccessHelper&, GPUAccessHelper&, float*, float*, float*, float*, int, int, bool, bool);
 
+template void APRNumericsGPU::richardson_lucy(GPUAccessHelper&, GPUAccessHelper&, VectorData<uint8_t>&, VectorData<float>&, PixelData<float>&, int, bool, bool, bool);
 template void APRNumericsGPU::richardson_lucy(GPUAccessHelper&, GPUAccessHelper&, VectorData<uint16_t>&, VectorData<float>&, PixelData<float>&, int, bool, bool, bool);
-template void APRNumericsGPU::richardson_lucy(GPUAccessHelper&, GPUAccessHelper&, VectorData<float>&, VectorData<float>&, PixelData<float>&, int, bool, bool, bool);
+template void APRNumericsGPU::richardson_lucy(GPUAccessHelper&, GPUAccessHelper&, VectorData<float>&, VectorData<float>&, PixelData<float>&, int, bool, bool, bool);
diff --git a/src/numerics/miscCuda.cu b/src/numerics/miscCuda.cu
@@ -69,8 +69,8 @@ __global__ void elementWiseSqrt(float* __restrict__ input,
 }
 
 
-template<typename T>
-__global__ void copyKernel(const T* in, T* out, const size_t size){
+template<typename T, typename S>
+__global__ void copyKernel(const T* __restrict__ in, S* __restrict__ out, const size_t size){
 
     for(size_t idx = blockIdx.x * blockDim.x + threadIdx.x; idx < size; idx += blockDim.x * gridDim.x) {
         out[idx] = in[idx];
@@ -440,10 +440,11 @@ template __global__ void elementWiseMult(uint16_t*, const uint16_t*, const size_
 
 template __global__ void elementWiseDiv(const float*, const float*, float*, const size_t);
 template __global__ void elementWiseDiv(const uint16_t*, const float*, float*, const size_t);
-template __global__ void elementWiseDiv(const uint16_t*, const uint16_t*, uint16_t*, const size_t);
+template __global__ void elementWiseDiv(const uint8_t*, const float*, float*, const size_t);
 
 template __global__ void copyKernel(const float*, float*, const size_t);
-template __global__ void copyKernel(const uint16_t*, uint16_t*, const size_t);
+template __global__ void copyKernel(const uint16_t*, float*, const size_t);
+template __global__ void copyKernel(const uint8_t*, float*, const size_t);
 
 template __global__ void fillWithValue(float*, float, const size_t);
 template __global__ void fillWithValue(uint16_t*, uint16_t, const size_t);
diff --git a/src/numerics/miscCuda.hpp b/src/numerics/miscCuda.hpp
@@ -91,8 +91,8 @@ __global__ void addSquare(float* in1, const float* in2, size_t size);
 __global__ void elementWiseSqrt(float* input, size_t size);
 
 
-template<typename T>
-__global__ void copyKernel(const T* in, T* out, const size_t size);
+template<typename T, typename S>
+__global__ void copyKernel(const T* in, S* out, const size_t size);
 
 
 template<typename T>
