Merge pull request #90 from cheesema/develop

Develop

Author: cheesema

.travis.yml

@@ -28,6 +28,7 @@ install:
 - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then brew install swig gnupg2 hdf5; fi
 - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then /usr/libexec/java_home -V; fi
 - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then echo "UPDATESTARTUPTTY" | gpg-connect-agent > /dev/null 2>&1; fi
+- if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then brew install cmake || brew upgrade cmake ; fi
 - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then alias swig="swig3.0"; fi
 - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then export COMPILER=clang++-3.6; fi
 - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then export CXX=clang++-3.6; fi

CMakeLists.txt

@@ -1,20 +1,23 @@
 ###############################################################################
 # APR - Adaptive Particle Representation
 ###############################################################################
-cmake_minimum_required(VERSION 3.2)
-project(LibAPR)
+cmake_minimum_required(VERSION 3.9)
+project(LibAPR DESCRIPTION "Adaptive Particle Representation library")
 
 set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 # APR build options:
-option(APR_INSTALL "Install APR library" ON)
+option(APR_INSTALL "Install APR library" OFF)
 option(APR_BUILD_SHARED_LIB "Builds shared library" ON)
-option(APR_BUILD_STATIC_LIB "Builds shared library" ON)
+option(APR_BUILD_STATIC_LIB "Builds static library" OFF)
 option(APR_BUILD_EXAMPLES "Build APR examples" OFF)
 option(APR_TESTS "Build APR tests" OFF)
 option(APR_PREFER_EXTERNAL_GTEST "When found, use the installed GTEST libs instead of included sources" OFF)
 option(APR_PREFER_EXTERNAL_BLOSC "When found, use the installed BLOSC libs instead of included sources" OFF)
 option(APR_BUILD_JAVA_WRAPPERS "Build APR JAVA wrappers" OFF)
+option(APR_USE_CUDA "should APR use CUDA? (experimental - under development)" OFF)
+option(APR_BENCHMARK "add benchmarking code" OFF)
 
 # Validation of options
 if (NOT APR_BUILD_SHARED_LIB AND NOT APR_BUILD_STATIC_LIB)
@@ -106,44 +109,73 @@ elseif (CMAKE_CXX_COMPILER_ID MATCHES "Clang")
     set(CMAKE_CXX_FLAGS_DEBUG "-O0 -g")
 endif()
 
+if (APR_BENCHMARK)
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DAPR_BENCHMARK")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DAPR_BENCHMARK")
+endif()
+
 
 ###############################################################################
 # Generate APR library
 ###############################################################################
 
 set(LIBRARY_NAME apr)
 
+include_directories(src)
+
 set(SOURCE_FILES src/io/blosc_filter.c src/io/hdf5functions_blosc.cpp)
 set(SOURCE_FILES_RAYCAST src/numerics/APRRaycaster.cpp src/vis/Camera.cpp src/vis/Object.cpp src/vis/RaytracedObject.cpp)
 
 add_library(aprObjLib OBJECT ${SOURCE_FILES} ${SOURCE_FILES_RAYCAST})
 
+if(APR_USE_CUDA)
+    message(STATUS "APR: Building CUDA for APR")
+    set(CMAKE_CUDA_STANDARD 14)
+    set(CMAKE_CUDA_FLAGS "--cudart shared -g -lineinfo -Xptxas -O3,-v -use_fast_math -DAPR_USE_CUDA")
+    if(APR_BENCHMARK)
+        set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -DAPR_BENCHMARK")
+    endif()
+    enable_language(CUDA)
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DAPR_USE_CUDA")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DAPR_USE_CUDA")
+    set(APR_CUDA_SROUCE_FILES
+	        src/algorithm/ComputeGradientCuda.cu
+            src/algorithm/ComputeBsplineRecursiveFilter.cu
+            src/algorithm/ComputeInverseCubicBsplineCuda.cu
+            src/data_structures/Mesh/PixelData.cu
+            src/algorithm/LocalIntensityScale.cu)
+    include_directories(${CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES})
+endif()
+
 if(APR_BUILD_STATIC_LIB)
     # generate static library used as a intermediate step in generating fat lib
     set(STATIC_TARGET_NAME staticLib)
-    add_library(${STATIC_TARGET_NAME} STATIC $<TARGET_OBJECTS:aprObjLib>)
+    add_library(${STATIC_TARGET_NAME} STATIC $<TARGET_OBJECTS:aprObjLib> ${APR_CUDA_SROUCE_FILES})
+    target_compile_features(${STATIC_TARGET_NAME} PUBLIC cxx_std_14)
     set_target_properties(${STATIC_TARGET_NAME} PROPERTIES OUTPUT_NAME ${LIBRARY_NAME})
+    set_target_properties(${STATIC_TARGET_NAME} PROPERTIES CUDA_SEPARABLE_COMPILATION OFF)
     target_include_directories(${STATIC_TARGET_NAME} PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}>)
 
     # generate fat static library by adding dependencies
-    include(cmake/AddStaticLibs.cmake)
     if(NOT BLOSC_FOUND)
+        include(cmake/AddStaticLibs.cmake)
         addStaticLibs(${STATIC_TARGET_NAME} blosc_static)
     endif()
 endif()
 
 if(APR_BUILD_SHARED_LIB)
 # generate fat shared library
     set(SHARED_TARGET_NAME sharedLib)
-    add_library(${SHARED_TARGET_NAME} SHARED $<TARGET_OBJECTS:aprObjLib>)
+    add_library(${SHARED_TARGET_NAME} SHARED $<TARGET_OBJECTS:aprObjLib> ${APR_CUDA_SROUCE_FILES})
+
     target_include_directories(${SHARED_TARGET_NAME} PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}>)
     set_target_properties(${SHARED_TARGET_NAME} PROPERTIES OUTPUT_NAME ${LIBRARY_NAME})
     set_target_properties(${SHARED_TARGET_NAME} PROPERTIES LIBRARY_OUTPUT_NAME ${LIBRARY_NAME})
     set_target_properties(${SHARED_TARGET_NAME} PROPERTIES ARCHIVE_OUTPUT_NAME ${LIBRARY_NAME})
     set_property(TARGET ${SHARED_TARGET_NAME} PROPERTY VERSION ${APR_VERSION_STRING})
     set_property(TARGET ${SHARED_TARGET_NAME} PROPERTY SOVERSION ${APR_VERSION_MAJOR})
 
-    target_link_libraries(${SHARED_TARGET_NAME} PRIVATE ${HDF5_LIBRARIES} ${TIFF_LIBRARIES})
+    target_link_libraries(${SHARED_TARGET_NAME} PRIVATE ${HDF5_LIBRARIES} ${TIFF_LIBRARIES}  ${CUDA_CUDART_LIBRARY})
     if(BLOSC_FOUND)
         target_link_libraries(${SHARED_TARGET_NAME} PRIVATE ${BLOSC_LIBRARIES} ${ZLIB_LIBRARIES})
     else()
@@ -163,7 +195,6 @@ else()
     set(APR_BUILD_LIBRARY ${STATIC_TARGET_NAME})
 endif()
 
-
 ###############################################################################
 # Install APR library
 ###############################################################################
@@ -216,17 +247,14 @@ endif(APR_INSTALL)
 # Examples
 ###############################################################################
 if(APR_BUILD_EXAMPLES)
-    include_directories(src)
     message(STATUS "APR: Building examples")
     add_subdirectory(examples)
 endif(APR_BUILD_EXAMPLES)
 
-
 ###############################################################################
 # Tests
 ###############################################################################
 if(APR_TESTS)
-    include_directories(src)
     message(STATUS "APR: Building tests")
     if(APR_PREFER_EXTERNAL_GTEST)
         find_package(GTest 1.8.0)

README.md

@@ -1,6 +1,6 @@
 # LibAPR - The Adaptive Particle Representation Library
 
-Library for producing and processing on the Adaptive Particle Representation (APR) (For article see: https://www.biorxiv.org/content/early/2018/02/09/263061).
+Library for producing and processing on the Adaptive Particle Representation (APR) (For article see: https://www.biorxiv.org/content/early/2018/03/02/263061).
 
 <img src="./docs/apr_lowfps_lossy.gif?raw=true">
 
@@ -16,10 +16,6 @@ Labeled Zebrafish nuclei: Gopi Shah, Huisken Lab ([MPI-CBG](https://www.mpi-cbg.
 * LibTIFF 5.0 or higher
 * SWIG 3.0.12 (optional, for generating Java wrappers)
 
-Opening hdf5 files in ParaView or HDFView requires additional installation of two libraries:
-* c-blosc 1.11.2 or higher
-* hdf5-blosc 1.1.0 or higher
-
 ## Building
 
 The repository requires sub-modules, so the repository needs to be cloned recursively:
@@ -58,7 +54,7 @@ We provide working Dockerfile that install the library within the image on a sep
 
 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, also install the `llvm` package, as the clang version shipped by Apple currently does not support OpenMP.
+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
 
@@ -71,7 +67,7 @@ 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, modify the call to `cmake` above to
+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 ..
@@ -102,24 +98,34 @@ There are nine basic examples, that show how to generate and compute with the AP
 
 | Example | How to ... |
 |:--|:--|
-| [Example_get_apr](./examples/Example_get_apr.cpp) | create an APR file from a TIFF. |
-| [Example_apr_iterate](./examples/Example_apr_iterate.cpp) | iterate through a given APR file. |
+| [Example_get_apr](./examples/Example_get_apr.cpp) | create an APR from a TIFF and store as hdf5. |
+| [Example_apr_iterate](./examples/Example_apr_iterate.cpp) | iterate through a given APR. |
 | [Example_neighbour_access](./examples/Example_neighbour_access.cpp) | access particle and face neighbours. |
-| [Example_compress_apr](./examples/Example_compress_apr.cpp) |  additionally compress the intensities stored in an APR file. |
-| [Example_compute_gradient](./examples/Example_compute_gradient.cpp) | compute a gradient based on the stored particles in an APR file. |
-| [Example_produce_paraview_file](./examples/Example_produce_paraview_file.cpp) | produce a file for visualisation in ParaView. |
+| [Example_compress_apr](./examples/Example_compress_apr.cpp) |  additionally compress the intensities stored in an APR. |
+| [Example_compute_gradient](./examples/Example_compute_gradient.cpp) | compute a gradient based on the stored particles in an APR. |
+| [Example_produce_paraview_file](./examples/Example_produce_paraview_file.cpp) | produce a file for visualisation in ParaView or reading in Matlab. |
 | [Example_random_access](./examples/Example_random_access.cpp) | perform random access operations on particles. |
-| [Example_ray_cast](./examples/Example_ray_cast.cpp) | perform a maximum intensity projection ray cast directly on the APR data structures read from an APR file. |
-| [Example_reconstruct_image](./examples/Example_reconstruct_image.cpp) | reconstruct an pixel image from an APR file. |
+| [Example_ray_cast](./examples/Example_ray_cast.cpp) | perform a maximum intensity projection ray cast directly on the APR data structures read from an APR. |
+| [Example_reconstruct_image](./examples/Example_reconstruct_image.cpp) | 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](./docs/lib_guide.pdf).
 
 ## Coming soon
 
 * more examples for APR-based filtering and segmentation
-* more convenient use from CMake projects
 * deployment of the Java wrappers to Maven Central so they can be used in your project directly
 * support for loading the APR in [Fiji](https://fiji.sc), including [scenery-based](https://github.com/scenerygraphics/scenery) 3D rendering
+* basic python wrapper support
+* improved java wrapper support
+* CUDA GPU-accelerated APR generation and processing
+
+## 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 https://gitter.im/LibAPR](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/LibAPR/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 ## Citing this work
 

examples/Example_compress_apr.cpp

@@ -14,10 +14,11 @@ Example_compress_apr -i input_image_tiff -d input_directory
 
 Optional:
 
--compress_type number (1 or 2) (1 - WNL compression (Default), 2 - prediction step with lossless, potential rounding error)
+-compress_type number (1 or 2) (1 - WNL compression, only variance stabalization step (Default), 2 - variance stabalization and x,y,z prediction (note slower for ~30% compression gain)
 -quantization_level (Default 1: higher increasing the loss nature of the WNL compression aproach)
+-compress_level (the IO uses BLOSC for lossless compression of the APR, this can be set from 1-9, where higher increases the compression level. Note, this can come at a significant time increase.)
 
-e.g. Example_compress_apr -i nuc_apr.h5 -d /Test/Input_examples/ -compress_type 2
+e.g. Example_compress_apr -i nuc_apr.h5 -d /Test/Input_examples/ -compress_type 1
 
 Note: fine grained parameters can be tuned within the file, to play with lossless compression level, method used, and other parameters.
 
@@ -59,17 +60,47 @@ int main(int argc, char **argv) {
     APRCompress<uint16_t> comp;
     ExtraParticleData<uint16_t> symbols;
 
+    //feel free to change
+    unsigned int blosc_comp_type = BLOSC_ZSTD;
+    unsigned int blosc_comp_level = options.compress_level;
+    unsigned int blosc_shuffle = 1;
+
     comp.set_quantization_factor(options.quantization_level); //set this to adjust the compression factor for WNL
     comp.set_compression_type(options.compress_type);
 
-    timer.start_timer("compress");
-    apr.write_apr(options.directory ,name + "_compress",comp,BLOSC_ZSTD,1,2);
+    //compress the APR and write to disk
+    timer.start_timer("compress and write");
+    FileSizeInfo fileSizeInfo = apr.write_apr(options.directory ,name + "_compress",comp,blosc_comp_type,blosc_comp_level,blosc_shuffle);
     timer.stop_timer();
 
-    timer.start_timer("decompress");
+    float time_write = (float) timer.timings.back();
+
+    //read the APR and decompress
+    timer.start_timer("read and decompress");
     apr.read_apr(options.directory + name + "_compress_apr.h5");
     timer.stop_timer();
 
+    float time_read = (float) timer.timings.back();
+
+    float original_pixel_image_size = (2.0f*apr.orginal_dimensions(0)*apr.orginal_dimensions(1)*apr.orginal_dimensions(2))/(1000000.0);
+    std::cout << std::endl;
+    std::cout << std::endl;
+    std::cout << "Original image size: " << original_pixel_image_size << " MB" << std::endl;
+
+    float apr_compressed_file_size = fileSizeInfo.total_file_size;
+
+    std::cout << "Compressed (Lossy - WNL) APR: " << apr_compressed_file_size << " MB" << std::endl;
+    std::cout << "Compression Ratio: " << original_pixel_image_size/apr_compressed_file_size << std::endl;
+    std::cout << std::endl;
+    std::cout << std::endl;
+
+    std::cout << "Effective Datarate Write (by original image size): " << original_pixel_image_size/time_write << " MB*/s" << std::endl;
+    std::cout << "Effective Datarate Read (by original image size): " << original_pixel_image_size/time_read << " MB*/s" << std::endl;
+
+    std::cout << std::endl;
+    std::cout << std::endl;
+
+    //writes the piece-wise constant reconstruction of the APR to file for comparison
     PixelData<uint16_t> img;
     apr.interp_img(img,apr.particles_intensities);
     std::string output = options.directory + name + "_compress.tif";
@@ -93,49 +124,53 @@ char* get_command_option(char **begin, char **end, const std::string &option)
 }
 
 
-    cmdLineOptions read_command_line_options(int argc, char **argv){
+cmdLineOptions read_command_line_options(int argc, char **argv){
 
-        cmdLineOptions result;
+    cmdLineOptions result;
 
-        if(argc == 1) {
-            std::cerr << usage << std::endl;
-            exit(1);
-        }
+    if(argc == 1) {
+        std::cerr << usage << std::endl;
+        exit(1);
+    }
 
-        if(command_option_exists(argv, argv + argc, "-i"))
-        {
-            result.input = std::string(get_command_option(argv, argv + argc, "-i"));
-        } else {
-            std::cout << "Input file required" << std::endl;
-            exit(2);
-        }
+    if(command_option_exists(argv, argv + argc, "-i"))
+    {
+        result.input = std::string(get_command_option(argv, argv + argc, "-i"));
+    } else {
+        std::cout << "Input file required" << std::endl;
+        exit(2);
+    }
 
-        if(command_option_exists(argv, argv + argc, "-d"))
-        {
-            result.directory = std::string(get_command_option(argv, argv + argc, "-d"));
-        }
+    if(command_option_exists(argv, argv + argc, "-d"))
+    {
+        result.directory = std::string(get_command_option(argv, argv + argc, "-d"));
+    }
 
-        if(command_option_exists(argv, argv + argc, "-compress_type"))
-        {
-            result.compress_type = (unsigned int)std::stoi(std::string(get_command_option(argv, argv + argc, "-compress_type")));
-        }
+    if(command_option_exists(argv, argv + argc, "-compress_type"))
+    {
+        result.compress_type = (unsigned int)std::stoi(std::string(get_command_option(argv, argv + argc, "-compress_type")));
+    }
 
-        if(result.compress_type > 2 || result.compress_type == 0){
+    if(result.compress_type > 2 || result.compress_type == 0){
 
-            std::cerr << "Invalid Compression setting (1 or 2)" << std::endl;
-            exit(1);
-        }
+        std::cerr << "Invalid Compression setting (1 or 2)" << std::endl;
+        exit(1);
+    }
 
 
-        if(command_option_exists(argv, argv + argc, "-quantization_level"))
-        {
-            result.quantization_level =std::stof(std::string(get_command_option(argv, argv + argc, "-quantization_level")));
-        }
+    if(command_option_exists(argv, argv + argc, "-quantization_level"))
+    {
+        result.quantization_level =std::stof(std::string(get_command_option(argv, argv + argc, "-quantization_level")));
+    }
 
+    if(command_option_exists(argv, argv + argc, "-compress_level"))
+    {
+        result.compress_level = (unsigned int)std::stoi(std::string(get_command_option(argv, argv + argc, "-compress_level")));
+    }
 
 
-        return result;
+    return result;
 
-    }
+}
 
 

examples/Example_compress_apr.h

@@ -15,6 +15,7 @@ struct cmdLineOptions{
     unsigned int compress_type=1;
     float quantization_level=1;
     bool stats_file = false;
+    unsigned int compress_level = 2;
 };
 
 cmdLineOptions read_command_line_options(int argc, char **argv);