Merge pull request #18 from joeljonsson/develop_joel

Bump master: Significant update.

Author: cheesema

.gitignore

@@ -108,3 +108,4 @@ venv.bak/
 .DS_Store
 
 data/
+/processing

CMakeLists.txt

@@ -88,19 +88,25 @@ endif()
 ###############################################################################
 message(STATUS "PyAPR: Building PYTHON wrappers")
 
-set(PYTHON_VERSION 3)
+set(PYBIND11_PYTHON_VERSION 3)
 find_package( PythonInterp ${PYTHON_VERSION} REQUIRED )
 find_package( PythonLibs ${PYTHON_VERSION} REQUIRED )
 
 add_subdirectory("pybind11")
+add_library(maxflow SHARED
+            external/maxflow-v3.04.src/graph.cpp
+            external/maxflow-v3.04.src/maxflow.cpp)
+
+#set(MAXFLOW_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/external/maxflow-v3.04.src)
 
 include_directories("pyapr")
+include_directories("external")
 
 set(APR_PYTHON_MODULE_NAME _pyaprwrapper)
 add_definitions(-DAPR_PYTHON_MODULE_NAME=${APR_PYTHON_MODULE_NAME})
-add_library(${APR_PYTHON_MODULE_NAME} MODULE wrappers/pythonBind.cpp)
-target_include_directories(${APR_PYTHON_MODULE_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/wrappers ${CMAKE_CURRENT_SOURCE_DIR}/pyapr)
-target_link_libraries(${APR_PYTHON_MODULE_NAME} PRIVATE staticLib pybind11::module ${HDF5_LIBRARIES} ${TIFF_LIBRARIES} ${BLOSC_LIBRARIES} ${ZLIB_LIBRARIES})
+pybind11_add_module(${APR_PYTHON_MODULE_NAME} MODULE wrappers/pythonBind.cpp)
+target_include_directories(${APR_PYTHON_MODULE_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/wrappers ${CMAKE_CURRENT_SOURCE_DIR}/pyapr ${CMAKE_CURRENT_SOURCE_DIR}/external)
+target_link_libraries(${APR_PYTHON_MODULE_NAME} PRIVATE staticLib pybind11::module ${HDF5_LIBRARIES} ${TIFF_LIBRARIES} ${BLOSC_LIBRARIES} ${ZLIB_LIBRARIES} maxflow)
 set_target_properties(${APR_PYTHON_MODULE_NAME} PROPERTIES OUTPUT_NAME ${APR_PYTHON_MODULE_NAME})
 set_target_properties(${APR_PYTHON_MODULE_NAME} PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}"
         SUFFIX "${PYTHON_MODULE_EXTENSION}")

LibAPR

@@ -1,87 +1,104 @@
 # PyLibAPR
 
-Externalized Python wrappers for LibAPR
+Python wrappers for [LibAPR](https://github.com/AdaptiveParticles/LibAPR) - Library for producing and processing on 
+the Adaptive Particle Representation (APR).
+
+For article see: https://www.nature.com/articles/s41467-018-07390-9
+
+## Exclusive features
+
+In addition to providing wrappers for most of the functionality of LibAPR, we provide a number of
+new features that simplify the generation and handling of the APR. For example:
+
+* Interactive APR conversion (see [get_apr_interactive_demo](demo/get_apr_interactive_demo.py) and 
+  [get_apr_by_block_interactive_demo](demo/get_apr_by_block_interactive_demo.py))
+* Interactive APR z-slice viewer (see [viewer_demo](demo/viewer_demo.py))
+* Interactive APR raycast (maximum intensity projection) viewer (see [raycast_demo](demo/raycast_demo.py))
+* Interactive lossy compression of particle intensities (see [compress_particles_demo](demo/compress_particles_demo.py))
 
 ## Dependencies
 
+[LibAPR](https://github.com/AdaptiveParticles/LibAPR) is included as a submodule, and built alongside the wrappers. 
+This requires the following packages:
+
 * HDF5 1.8.20 or higher
-* OpenMP > 3.0 (optional, but suggested)
+* OpenMP > 3.0 (optional, but recommended)
 * CMake 3.6 or higher
 * LibTIFF 4.0 or higher
 
-## Building
+The Python library additionally requires Python 3.
 
-The repository requires sub-modules, so the repository needs to be cloned recursively:
+### Installing dependencies on Linux
 
-```
-git clone --recursive https://github.com/joeljonsson/PyLibAPR.git
-```
+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.
 
-If you need to update your clone at any point later, run
+### Installing dependencies on OSX
 
-```
-git pull
-git submodule update
-```
+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 (this can also be done using homebrew), 
+as the clang version shipped by Apple currently does not support OpenMP.
 
-### Building manually
+### Note for windows users
 
-The library can be built manually using CMake. Note that, when built in this way, the path to the build folder must be specified when importing the library in a Python script. 
+The simplest way to utilise the library from Windows is through Windows Subsystem for Linux; see: 
+https://docs.microsoft.com/en-us/windows/wsl/install-win10 then follow linux instructions.
 
-#### Building on Linux
+The viewers and demos use a Graphical User Interface. In order to use these features from WSL, you
+may additionally need to install an X server.
 
-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.
+## Building
 
-In the directory of the cloned repository, run
+The repository requires submodules, so the repository needs to be cloned recursively:
 
 ```
-mkdir build
-cd build
-cmake ..
-make
+git clone --recursive https://github.com/joeljonsson/PyLibAPR.git
 ```
 
-This will create the `pyApr.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.
-
-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
+It is recommended to use a virtual environment, such as `virtualenv`. To set this up, use e.g.
 
 ```
-mkdir build
-cd build
-cmake ..
-make
+pip3 install virtualenv
+python3 -m virtualenv myenv
+source myenv/bin/activate
 ```
 
-This will create the `pyApr.so` library in the `build` directory.
-
-In case you want to use the homebrew-installed clang (OpenMP support), modify the call to `cmake` above to
-
+The required Python packages can be installed via the command
 ```
-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 ..
+pip install -r requirements.txt 
 ```
 
-### Build using the setup script
-
-It is recommended to do this in a virtual environment. First, install the dependencies for your operating system as described in the instructions for the manual build. Additionally, install `cmake-setuptools`, e.g. through
-
+Once the dependencies are installed, PyLibAPR can be built via the setup.py script:
 ```
-pip install cmake-setuptools
+python setup.py install
 ```
 
-Then simply run the `setup.py` script:
+### CMake build options
 
+There are two CMake options that can be given to enable or disable OpenMP and CUDA:
+
+| Option | Description | Default value |
+|:--|:--|:--|
+| PYAPR_USE_OPENMP | Enable multithreading via OpenMP | ON |
+| PYAPR_USE_CUDA | Build available CUDA functionality | OFF |
+
+When building via the setup.py script, these options can be set via the environment variable `CMAKE_COMMON_VARIABLES`. For example,
 ```
-python setup.py install
+CMAKE_COMMON_VARIABLES="-DPYAPR_USE_OPENMP=OFF -DPYAPR_USE_CUDA=OFF" python setup.py install
 ```
+should install the package with both OpenMP and CUDA disabled.
 
-To use the homebrew-installed clang for OpenMP support on OSX, modify the call above to
+### OpenMP support on OSX
 
+To use the homebrew-installed clang for OpenMP support on OSX, modify the call above to
 ```
 CPPFLAGS="-I/usr/local/opt/llvm/include" LDFLAGS="-L/usr/local/opt/llvm/lib -Wl,-rpath,/usr/local/opt/llvm/lib" CXX="/usr/local/opt/llvm/bin/clang++" CC="/usr/local/opt/llvm/bin/clang" python setup.py install 
 ```
+
+## 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 happy to 
+assist you!

README.md

@@ -4,13 +4,17 @@
 
 
 def main():
+    """
+    This demo converts a selected TIFF image to an APR, writes the result to file and then reads the file.
+    """
 
-    # Read in an image
     io_int = pyapr.filegui.InteractiveIO()
+
+    # Read in an image
     fpath = io_int.get_tiff_file_name()
     img = skio.imread(fpath).astype(np.uint16)
 
-    # Initialize objects
+    # Instantiate objects
     apr = pyapr.APR()
     parts = pyapr.ShortParticles()
     par = pyapr.APRParameters()
@@ -20,54 +24,40 @@ def main():
     par.auto_parameters = False
     par.rel_error = 0.1
     par.Ip_th = 10
-    par.grad_th = 50
+    par.grad_th = 1
     par.gradient_smoothing = 2
-    par.sigma_th = 100
-    par.sigma_th_max = 50
+    par.sigma_th = 20
+    par.sigma_th_max = 10
     converter.set_parameters(par)
     converter.set_verbose(False)
 
     # Compute APR and sample particle values
     converter.get_apr(apr, img)
+    parts.sample_image(apr, img)
 
     # Compute and display the computational ratio
     numParts = apr.total_number_particles()
     numPix = img.size
-    CR = numPix / numParts
-
-    print('input image size: {} pixels, APR size: {} particles --> Computational Ratio: {}'.format(numPix, numParts, CR))
-
-    # Sample particle intensities
-    parts.sample_image(apr, img)
+    cr = numPix / numParts
+    print('Input image size: {} pixels, APR size: {} particles --> Computational Ratio: {}'.format(numPix, numParts, cr))
 
     # Save the APR to file
-    fpath_apr = io_int.save_apr_file_name()
-
-    # Initialize APRFile for I/O
-    aprfile = pyapr.io.APRFile()
-    aprfile.set_read_write_tree(True)
-
-    # Write APR and particles to file
-    aprfile.open(fpath_apr, 'WRITE')
-    aprfile.write_apr(apr)
-    aprfile.write_particles('particles', parts)
-    aprfile.close()
+    fpath_apr = io_int.save_apr_file_name()  # get save path from gui
+    pyapr.io.write(fpath_apr, apr, parts)    # write apr and particles to file
 
     # Read the newly written file
-
-    # Initialize objects for reading in data
     apr2 = pyapr.APR()
     parts2 = pyapr.ShortParticles()
+    pyapr.io.read(fpath_apr, apr2, parts2)
 
-    # Read from APR file
-    aprfile.open(fpath_apr, 'READ')
-    aprfile.read_apr(apr2)
-    aprfile.read_particles(apr2, 'particles', parts2)
-    aprfile.close()
+    # check that particles are equal at a single, random index
+    ri = np.random.randint(0, numParts-1)
+    assert parts[ri] == parts2[ri]
 
-    # Reconstruct pixel image
-    tmp = pyapr.numerics.reconstruction.recon_pc(apr, parts)
-    recon = np.array(tmp, copy=False)
+    # check some APR properties
+    assert apr.total_number_particles() == apr2.total_number_particles()
+    assert apr.level_max() == apr2.level_max()
+    assert apr.level_min() == apr2.level_min()
 
 
 if __name__ == '__main__':

demo/apr_io_demo.py

@@ -4,40 +4,48 @@
 
 
 def main():
+    """
+    This demo implements a piecewise constant reconstruction using the wrapped PyLinearIterator. The Python reconstruction
+    is timed and compared to the internal C++ version.
+
+    Note: The current Python reconstruction is very slow and needs to be improved. For now, this demo is best used as a
+    coding example of the loop structure to access particles and their spatial properties.
+    """
 
     io_int = pyapr.filegui.InteractiveIO()
     fpath_apr = io_int.get_apr_file_name()  # get APR file path from gui
 
-    aprfile = pyapr.io.APRFile()
-    aprfile.set_read_write_tree(True)
-
-    # Initialize APR and particle objects
+    # Instantiate APR and particle objects
     parts = pyapr.ShortParticles()
     apr = pyapr.APR()
 
     # Read from APR file
-    aprfile.open(fpath_apr, 'READ')
-    aprfile.read_apr(apr)
-    aprfile.read_particles(apr, 'particles', parts)
-    aprfile.close()
+    pyapr.io.read(fpath_apr, apr, parts)
 
+    # Illustrates the usage of the Python-wrapped linear iterator by computing the piecewise constant reconstruction
     start = time()
-
-    org_dims = apr.org_dims()  # (Ny, Nx, Nz)
+    org_dims = apr.org_dims()  # dimension order (y, x, z)
     py_recon = np.empty((org_dims[2], org_dims[1], org_dims[0]), dtype=np.uint16)
     max_level = apr.level_max()
 
-    apr_it = apr.iterator()
+    apr_it = apr.iterator()  # PyLinearIterator
+
+    # particles at the maximum level coincide with pixels
+    level = max_level
+    for z in range(apr_it.z_num(level)):
+        for x in range(apr_it.x_num(level)):
+            for idx in range(apr_it.begin(level, z, x), apr_it.end()):
+                py_recon[z, x, apr_it.y(idx)] = parts[idx]
 
     # loop over levels up to level_max-1
     for level in range(apr_it.level_min(), apr_it.level_max()):
 
-        step_size = 2 ** (max_level - level)
+        step_size = 2 ** (max_level - level)    # this is the size (in pixels) of the particle cells at level
 
         for z in range(apr_it.z_num(level)):
             for x in range(apr_it.x_num(level)):
                 for idx in range(apr_it.begin(level, z, x), apr_it.end()):
-                    y = apr_it.y(idx)  # this is slow
+                    y = apr_it.y(idx)
 
                     y_start = y * step_size
                     x_start = x * step_size
@@ -49,30 +57,25 @@ def main():
 
                     py_recon[z_start:z_end, x_start:x_end, y_start:y_end] = parts[idx]
 
-    # particles at the maximum level coincide with pixels
-    level = max_level
-    for z in range(apr_it.z_num(level)):
-        for x in range(apr_it.x_num(level)):
-            for idx in range(apr_it.begin(level, z, x), apr_it.end()):
-                py_recon[z, x, apr_it.y(idx)] = parts[idx]
-
     py_time = time()-start
     print('python reconstruction took {} seconds'.format(py_time))
 
+    # Compare to the c++ reconstruction
     start = time()
     tmp = pyapr.numerics.reconstruction.recon_pc(apr, parts)
     cpp_recon = np.array(tmp, copy=False)
     cpp_time = time()-start
     print('c++ reconstruction took {} seconds'.format(cpp_time))
     print('c++ was {} times faster'.format(py_time / cpp_time))
 
+    # check that both methods produce the same results (on a subset of the image if it is larger than 128^3 pixels)
     zm = min(org_dims[2], 128)
     xm = min(org_dims[1], 128)
     ym = min(org_dims[0], 128)
 
     success = np.allclose(py_recon[:zm, :xm, :ym], cpp_recon[:zm, :xm, :ym])
     if not success:
-        print('Python and C++ reconstructions give different results...')
+        print('Python and C++ reconstructions seem to give different results...')
 
 
 if __name__ == '__main__':