Software for Template-Free 3D Particle Fusion in Localization Microscopy.

This software implements a template-free particle fusion algorithm based on an all-to-all registration, which provides robustness against individual mis-registrations and underlabeling. The method does not assume any prior knowledge about the structure to be reconstructed (template-free) and directly works on localization data not pixelated images.

Requirements

• MATLAB (version>2018a)
  • distrib_computing_toolbox
  • statistics_toolbox
• CMake (version>3.14.3)
• CUDA toolkit (version>8.0)
• CUB library (version>1.8.0)
• The DIPImage toolbox (version>2.9)
• GNU C compiler (version>5.5.0, for Linux)
• Visual Studio (Visual Studio 15 2017, for Windows)

Note! For CUDA versions ≥ 11.0, the CUB library is included in the CUDA distribution. In this case the CUB_ROOT_DIR is automatically set to the cub directory within the CUDA installation (typically located in the include path).

The installation and test has been successfully done with:

• Matlab R2023b
• GCC 10.5.0
• CUDA 12.6.1
• DIPlib 3.5.1

Installation and usage on Linux

Get the sources

The Git repository uses submodules. Include them in a git clone action using the --recursive option.

git clone --single-branch --branch develop https://github.com/imphys/smlm_datafusion3d.git --recursive
cd smlm_datafusion3d/

Compile the code

In the following:

• BUILD_DIRECTORY is the directory where the project will be built
• SOURCE_DIRECTORY is the root directory of the sources
• CUB_DIRECTORY is the root directory of the downloaded CUB library sources. Only needed for CUDA versions < 11.0!
• MATLAB_DIRECTORY is the root of MATLAB installation directory (e.g. /usr/local/MATLAB/R2019a)

Use the following commands to build the necessary libraries for this software:

For CUDA versions < 11.0:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=RELEASE -DCMAKE_C_COMPILER=gcc-5 -DCUB_ROOT_DIR=CUB_DIRECTORY SOURCE_DIRECTORY
make

For CUDA versions ≥ 11.0:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=RELEASE SOURCE_DIRECTORY
make

Use the code

Next, we need to locate the built libraries for MATLAB:

cd ..
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:MATLAB_DIRECTORY/runtime/glnxa64:MATLAB_DIRECTORY/bin/glnxa64:MATLAB_DIRECTORY/sys/os/glnxa64:MATLAB_DIRECTORY/sys/opengl/lib/glnxa64:BUILD_DIRECTORY/mex

Then, run MATLAB and the demo script

matlab
>> demo1.m

Installation and usage on Windows

Get the sources

The Git repository uses submodules. Include them in a git clone action using the --recursive option.

git clone --single-branch --branch develop [email protected]:berndrieger/alltoall3D.git --recursive

Compile the code

In the following

• BUILD_DIRECTORY is the directory where the project will be built
• SOURCE_DIRECTORY is the root directory of the sources
• CUB_DIRECTORY is the root directory of the downloaded CUB library sources

Use the following commands from Command Prompt (type cmd in Run) to build the necessary libraries for this software:

mkdir build
cd build
cmake -G "Visual Studio 15 2017 Win64" -DCUB_ROOT_DIR=CUB_DIRECTORY SOURCE_DIRECTORY
make

Then open MS Visual Studio, by double clicking on ALL_BUILD.vcxproj and build all the targets (press F7). You might need to manually build the targets expdist and gausstransform before building the other targets.

Use the code

Open MATLAB and comment/uncomment the lines which add mex files to MATLAB path. Then, run the demo script

>> demo1.m

Troubleshooting

• Matlab mex headers not found
  The Makefile tries to find the directories in which MATLAB was installed on your system. If this fails, you can manually insert the path to your MATLAB installation (ending with /extern/include) inside the Makefile.

• CUDA headers not found
  The Makefile also tries to automatically find the directories with headers and libraries needed to compile the CUDA codes. If this fails, these can as well be inserted at the top of the Makefile.

• <cub/cub.cuh> not found
  The GPU code has only one external dependency, which is the CUB library. You can download it from: https://nvlabs.github.io/cub/index.html. The easiest way to install CUB is to add the top-level directory of where you've unpacked the CUB source codes to your $CPATH environment variable. For example, if you've unzipped the CUB sources into a directory called /home/username/cub-version.number, you can use export CPATH=$CPATH:/home/username/cub-version.number/: to install CUB. In this way the nvcc compiler is able to find the CUB headers.

• Program tries to run GPU code when no GPU is present
  Note that the mex files for the GPU code will be produced by make if your machine has nvcc. Once the mex files for the GPU code have been produced, the MATLAB code will prefer to use the GPU functions instead of the CPU functions. If you have no GPU available but did compile the mex files for the GPU code, you will get errors and MATLAB will exit. To disable the use of the GPU code type make clean and use make cpu instead of make or make all.

Developer instructions

The testing and tuning scripts for the GPU code have been written in Python, using Kernel Tuner. This section provides information on how to setup a development environment. Note that these steps are only needed if you are interested in modifying the CUDA and C++ codes.

Python 3

The tests for the GPU code and several of the C functions are written in Python, to run these a Python 3 installation is required. The easiest way to get this is using Miniconda.

On Linux systems one could type the following commands to download and install Python 3 using Miniconda:

wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

All the required Python packages can be installed using the following command, before you run it make sure that you have CUDA installed:

pip install -r requirements.txt

The tests can be run using nose, for example by typing the following in the top-level or test directory:

nosetests -v

Further questions

For any other questions regarding this software, you can:

• Search issues section or open a new topic there.
• Contact the authors:
  • (Hamidreza Heydarian) [email protected]
  • (Ben van Werkhoven) [email protected]
  • (Bernd Rieger) [email protected]

Acknowledgement

Some files have been reused and adapted from the following sources:

• GMM registration
  [1] Jian, B. & Vemuri, B. C. Robust point set registration using Gaussian mixture models. IEEE PAMI 33, 16331645 (2011).
• Lie-algebraic averaging
  [2] Govindu, V. Lie-algebraic averaging for globally consistent motion estimation. In Proc. IEEE Conf. on Computer Vision and Pattern Recognition (2004).
  [3] Chatterjee, A. Geometric calibration and shape refinement for 3D reconstruction PhD thesis. Indian Institute of Science (2015).
• l1-magic optimization toolbox
• Natural-Order Filename Sort