Home

Awesome

cudasirecon

Mats Gustafsson & Lin Shao's 3-beam SIM reconstruction software, with CUDA acceleration.

Algorithm as described in Gustafsson et al (2008) Biophys. J. 94(12): 4957–4970. doi: 10.1529/biophysj.107.120345

Installation

Packages for Linux and Windows on conda-forge:

$ conda install -c conda-forge cudasirecon

# you may wish to put it in a new environment ("sim" here):
$ conda create -n sim -y -c conda-forge cudasirecon
$ conda activate sim

In the examples shown above and below, Shell command line is used. The same works mostly in a Anaconda Prompt window on Windows, except for using\in place of/as the folder name dividers

Usage

Forcudasirecon

# the binary will be available as
$ cudasirecon

# for command line help
$ cudasirecon --help
# or:
$ cudasirecon -h

# a typical call for tiff files
$ cudasirecon some/folder file_pattern otf.tif -c config_file

# a typical call for dv/mrc files
$ cudasirecon data.dv data-proc.dv otf.dv -c config_file

Notes

nimm=1.515
background=90
wiener=0.001
# angles of illumination in radians
k0angles=-0.804300,-1.8555,0.238800
ls=0.2035
ndirs=3
nphases=5
na=1.42
otfRA=1
dampenOrder0=1

Full list of options/flags forcudasirecon

$ cudasirecon --help
Usage:
 cudasirecon [--options] [option-arguments] input_file(or folder) output_file(or file name pattern) otf_file

 List of options:
  --input-file arg            input file name (or data folder in TIFF mode)
  --output-file arg           output file name (or filename pattern in TIFF mode)
  --otf-file arg              OTF file name
  -c [ --config ] arg         name of a config file with parameters in place of command-line options
  --ndirs arg (=3)            number of SIM  directions
  --nphases arg (=5)          number of pattern phases per SIM direction
  --nordersout arg (=0)       number of output SIM orders (must be <= nphases//2; safe to ignore usually)
  --angle0 arg (=1.648)       angle of the first SIM angle in radians
  --ls arg (=0.172)           line spacing of SIM pattern in microns
  --na arg (=1.2)             detection objective's numerical aperture
  --nimm arg (=1.33)          refractive index of immersion medium
  --wiener arg (=0.01)        Wiener constant; lower value leads to higher resolution and noise;
                              playing with it extensively is strongly encouraged
  --zoomfact arg (=2)         lateral zoom factor in the output over the input images;
                              leaving it at 2 should be fine in most cases
  --zzoom arg (=1)            axial zoom factor; almost never needed
  --background arg (=0)       camera readout background
  --usecorr arg               use a flat-field correction file if provided
  --forcemodamp arg           modamps to be forced to these values; useful when
                              image quality is low and auto-estimated modamps 
                              are below, say, 0.1
  --k0angles arg              user these pattern vector k0 angles for all 
                              directions (instead of inferring the rest agnles 
                              from angle0)
  --otfRA                     using rotationally averaged OTF; otherwise using 
                              3/2D OTF for 3/2D raw data
  --otfPerAngle               using one OTF per SIM angle; otherwise one OTF is
                              used for all angles, which is how it's been done 
                              traditionally
  --fastSI                    SIM image is organized in Z->Angle->Phase order; 
                              otherwise assuming Angle->Z->Phase image order
  --k0searchAll [=arg(=0)]    search for k0 at all time points
  --norescale [=arg(=0)]      no bleach correction
  --equalizez                 bleach correction for z
  --equalizet                 bleach correction for time
  --dampenOrder0              dampen order-0 in final assembly; do not use for 2D SIM; good choice for high-background images
  --nosuppress [=arg(=0)]     do not suppress DC singularity in the result (good choice for 2D/TIRF data)
  --nokz0                     not using kz=0 plane of the 0th order in the final assembly (mostly for debug)
  --gammaApo arg (=1)         output apodization gamma; 1.0 means triangular 
                              apo; lower value means less dampening of 
                              high-resolution info at the tradeoff of higher 
                              noise
  --explodefact arg (=1)      artificially exploding the reciprocal-space 
                              distance between orders by this factor (for debug)
  --nofilterovlps [=arg(=0)]  not filtering the overlaping region between bands (for debug)
  --saveprefiltered arg       save separated bands (half Fourier space) into a file and exit (for debug)
  --savealignedraw arg        save drift-fixed raw data (half Fourier space) into a file and exit (for debug)
  --saveoverlaps arg          save overlap0 and overlap1 (real-space complex data) into a file and exit (for debug)
  --2lenses                   I5S data
  --bessel                    bessel-SIM data
  --besselExWave arg (=0.488) Bessel SIM excitation wavelength in microns
  --besselNA arg (=0.144)     Bessel SIM excitation NA)
  --deskew arg (=0)           Deskew angle; if not 0.0 then perform deskewing before processing
  --deskewshift arg (=0)      If deskewed, the output image's extra shift in X (positive->left)
  --noRecon                   No reconstruction will be performed; useful when combined with --deskew
  --cropXY arg (=0)           Crop the X-Y dimension to this number; 0 means no cropping
  --xyres arg (=0.1)          x-y pixel size (only used for TIFF files)
  --zres arg (=0.2)           z pixel size (only used for TIFF files)
  --zresPSF arg (=0.15)       z pixel size used in PSF TIFF files)
  --wavelength arg (=530)     emission wavelength in nanometers (only used for TIFF files)
  --writeTitle                Write command line to MRC/DV header (may cause issues with bioformats)
  -h [ --help ]               produce help message
  --version                   show version

Notes on the essential flags

Formakeotf

The utility of makeotf is to generate rotationally averaged OTFs for all SIM orders. The input to it is a single-direction SIM data set acquire with one point-like object as the sample. In general this OTF can be used for reconstructing multi-angle SIM data.

# And example of how to call makeotf:

$ makeotf /path/to/psf.dv otf.dv -angle -1.855500 -ls 0.2075 -na 1.4 -nimm 1.515 -fixorigin 3 20 -leavekz 7 11 3

# The example above shows practically all flags that are needed for generating a 3D SIM OTF; if 2D SIM or LLSM-SIM you should skip the last two flags.

Essential flags

GPU requirements

This software requires a CUDA-compatible NVIDIA GPU.

The libraries available on conda-forge have been compiled against different versions of the CUDA toolkit. The required CUDA libraries are bundled in the conda distributions so you don't need to install the CUDA toolkit separately. If desired, you can pick which version of CUDA you'd like based on your needs, but please note that different versions of the CUDA toolkit have different GPU driver requirements:

To specify a specific cudatoolkit version, install as follows (for instance, to use cudatoolkit=10.2):

# NOTE: conda-forge coming soon... not available yet.
conda install -c conda-forge cudasirecon cudatoolkit=10.2
CUDALinux driverWin driver
10.2≥ 440.33≥ 441.22
11.0≥ 450.36.06≥ 451.22
11.1≥ 455.23≥ 456.38
11.2≥ 460.27.03≥ 460.82

If your CUDA Driver version is too low for the version of cudasirecon that you have installed, you may get an error that looks like: !!Error occurred: cudaSetDevice failed

If you run into trouble, feel free to open an issue and describe your setup.

Multichannel reconstruction

cudasirecon does not currently accept multi-channel files. So it is necessary to temporarily pull out each channel into a new file prior to reconstruction. The provided recon.py script is an example of how to use the mrc package to extract individual channels from a .dv file, reconstruct them, and merge them back (and clean up the intermediate file). It is used as follows (note, mrc, numpy, and cudasirecon must be in your path):

python recon.py /path/to/raw_data.dv

recon.py will also accept any key value pairs that cudasirecon also accepts (to see that full list, type cudasirecon -h at the command prompt). For instance, to override just a couple of the reconstruction parameters, you could do something like this:

python recon.py /path/to/raw_data.dv wiener 0.001 background 150

There are a couple of hard-coded filepaths in recon.py. Specifically, it currently expects to find the OTFs and config files in the same directory as the recon.py script. You can change that by putting in an absolute directory to some other folder for the variables at the top of the file:

# path to your otf directory.  Defaults to the same as the recon.py file
OTF_DIR = os.path.abspath(os.path.dirname(__file__))
# path to your config directory.  Defaults to the same as the recon.py file
CONFIG_DIR = os.path.abspath(os.path.dirname(__file__))

Note also, that the config and OTF files must be named with the emission wavelength in the filenames. For example: config528.txt and otf528.otf

Compiling locally from source

on linux:

conda env create -f environment-linux.yml
conda activate simbuild
./build.sh  # see build.sh for cmake details

# test it:
./test_data/run.sh

on windows:

conda env create -f environment-windows.yml
conda activate simbuild
bld.bat  # see bld.bat for cmake details

Building with MRC support

The IVE/Priism libraries (for MRC/DV support), are not distributed with this source code and must be acquired seperately from UCSF. Place them in a folder called IVE at the top level of the source folder (same folder as the cudaSirecon folder). It should minimally have the following files and folders (example shown for linux, use .a or .lib as necessary for osx or windows)

then build with cmake -DBUILD_MRC=ON ....

<details> <summary>required IVE folder structure</summary> 
cudasirecon
├── ...
└── IVE/
    ├── darwin64/
    │   ├── INCLUDE/
    │   └── LIB/
    ├── linux64/
    │   ├── INCLUDE/
    │   │   ├── IM.h
    │   │   ├── IMInclude.h
    │   │   └── IWApiConstants.h
    │   └── LIB/
    │       ├── libimlib.a
    │       └── libive.a
    └── win64/
        ├── INCLUDE/
        └── LIB/
</details>