Skip to content

Commit

Permalink
Merge pull request #23 from tlambert03/update-readme
Browse files Browse the repository at this point in the history 
update docs and readme
  • Loading branch information
@tlambert03
tlambert03 committed May 31, 2021
2 parents 83742af + a4812a9 commit 6ef2a1d
Show file tree
Hide file tree
Showing 3 changed files with 92 additions and 79 deletions.
81 changes: 46 additions & 35 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,68 +1,79 @@
# pyCUDAdecon

This package provides a python wrapper and convenience functions for
[cudaDecon](https://github.com/scopetools/cudaDecon), which is a CUDA/C++
implementation of an accelerated Richardson Lucy Deconvolution
algorithm<sup>1</sup>.


This package provides a python wrapper and convenience functions for [cudaDecon](https://github.com/scopetools/cudaDecon), which is a CUDA/C++ implementation of an accelerated Richardson Lucy Deconvolution algorithm<sup>1</sup>.

It is suitable for general deconvolution of 3D microscopy data, but also has functionality for stage-scanning light sheet applications such as Lattice Light Sheet. cudaDeconv was originally written by [Lin Shao](https://github.com/linshaova) and modified by [Dan Milkie](https://github.com/dmilkie), at Janelia Research campus. This package makes use of a cross-platform shared library interface that I wrote for cudaDecon while developing [LLSpy](https://github.com/tlambert03/LLSpy) (a Lattice light-sheet post-processing utility), that adds a couple additional kernels for affine transformations and camera corrections. The code here is mostly extracted from that package and cleaned up to allow it to be used independently of LLSpy.

Features include:
* radially averaged OTF generation
* OTF interpolation for voxel size independence between PSF and data volumes
* CUDA accelerated deconvolution with a handful of artifact-reducing features.
* Deskew, Rotation, and general affine transformations
* radially averaged OTF generation with interpolation for voxel size
independence between PSF and data volumes
* 3D deskew, rotation, general affine transformations
* CUDA-based camera-correction for [sCMOS artifact correction](https://llspy.readthedocs.io/en/latest/camera.html)
* a few context managers for setup/breakdown of GPU-I/O-heavy tasks and convenience functions

Supports: Windos and Linux (macOS support has been dropped)

#### Documentation
[Documentation](https://pycudadecon.readthedocs.io/en/latest/index.html) generously hosted by [Read the Docs](https://readthedocs.org/)
### Install

The conda package includes the required pre-compiled libraries for Windows and Linux. See GPU driver requirements [below](#gpu-requirements)

## Installation
```sh
conda install -c conda-forge pycudadecon
```

**WORK IN PROGRESS**: `pycudadecon` will be available at conda-forge soon...
*macOS is not supported*

### 📖 Documentation
[Documentation](https://pycudadecon.readthedocs.io/en/latest/index.html)
generously hosted by [readthedocs](https://readthedocs.org/)

The precompiled C-libraries underlying this package are available for windows and linux, via conda-forge:

```sh
conda install -c conda-forge cudadecon
```

### GPU requirements

This software requires a CUDA-compatible NVIDIA GPU.
The underlying cudadecon libraries 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:
This software requires a CUDA-compatible NVIDIA GPU. The underlying cudadecon
libraries 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`)
To specify a specific cudatoolkit version, install as follows (for instance, to
use `cudatoolkit=10.2`)

```sh
conda install -c conda-forge cudadecon cudatoolkit=10.2
```

| CUDA | Linux driver | Win 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 |
| CUDA | Linux driver | Win 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 you run into trouble, feel free to [open an
issue](https://github.com/tlambert03/pycudadecon/issues) and describe your
setup.

If you run into trouble, feel free to [open an issue](https://github.com/tlambert03/pycudadecon/issues) and describe your setup.

## Usage

If you have a PSF and an image volume and you just want to get started, check out the [`pycudadecon.decon()`](https://pycudadecon.readthedocs.io/en/latest/deconvolution.html#pycudadecon.decon) function, which is designed be able to handle most basic applications.

The [`pycudadecon.decon()`](https://pycudadecon.readthedocs.io/en/latest/deconvolution.html#pycudadecon.decon) function is designed be able to handle most basic applications:

```python
from pycudadecon import decon

image_path = '/path/to/some_image.tif'
psf_path = '/path/to/psf_3D.tif'
result = decon(image_path, psf_path)
# pass filenames of an image and a PSF
result = decon('/path/to/3D_image.tif', '/path/to/3D_psf.tif')

# decon also accepts numpy arrays
result = decon(img_array, psf_array)

# the image source can also be a sequence of arrays or paths
result = decon([img_array, '/path/to/3D_image.tif'], psf_array)

# see docstrings for additional parameter options
```

For finer-tuned control, you may wish to make an OTF file from your PSF using [`pycudadecon.make_otf()`](https://pycudadecon.readthedocs.io/en/latest/otf.html?highlight=make_otf#pycudadecon.make_otf), and then use the [`pycudadecon.RLContext`](https://pycudadecon.readthedocs.io/en/latest/deconvolution.html?highlight=RLContext#pycudadecon.RLContext) context manager to setup the GPU for use with the [`pycudadecon.rl_decon()`](https://pycudadecon.readthedocs.io/en/latest/deconvolution.html?highlight=RLContext#pycudadecon.rl_decon) function. (Note all images processed in the same context must have the same input shape).
Expand Down
28 changes: 25 additions & 3 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,30 @@
pyCUDAdecon
===========

pyCUDAdecon is a python wrapper and set of convenience functions for `cudaDeconv <https://github.com/dmilkie/cudaDecon>`_ (which is a CUDA/C++ implementation of an accelerated Richardson Lucy Deconvolution [#f1]_). cudaDeconv was originally written by `Lin Shao <https://github.com/linshaova>`_ and modified by `Dan Milkie <https://github.com/dmilkie>`_, at Janelia Research campus. This package makes use of a shared library interface that I wrote for cudaDecon while developing `LLSpy <https://github.com/tlambert03/LLSpy>`_, that adds a couple additional kernels for affine transformations and camera corrections.
This package provides a python wrapper and convenience functions for
`cudaDeconv <https://github.com/scopetools/cudaDecon>`_, which is a CUDA/C++
implementation of an accelerated Richardson Lucy Deconvolution
algorithm [#f1]_. ``cudaDeconv`` was originally
written by `Lin Shao <https://github.com/linshaova>`_ and modified by `Dan
Milkie <https://github.com/dmilkie>`_, at Janelia Research campus. This package
makes use of a shared library interface that I wrote for cudaDecon while
developing `LLSpy <https://github.com/tlambert03/LLSpy>`_, that adds a couple
additional kernels for affine transformations and camera corrections.

- CUDA accelerated deconvolution with a handful of artifact-reducing features.
- radially averaged OTF generation with interpolation for voxel size
independence between PSF and data volumes
- 3D deskew, rotation, general affine transformations
- CUDA-based camera-correction for
`sCMOS artifact correction <https://llspy.readthedocs.io/en/latest/camera.html>`_


Quickstart
----------

If you have a PSF and an image volume and you just want to get started, check out the :func:`pycudadecon.decon` function, which should be able to handle most basic applications.
If you have a PSF and an image volume and you just want to get started, check
out the :func:`pycudadecon.decon` function, which should be able to handle most
basic applications.

.. code-block:: python
Expand All @@ -16,7 +34,11 @@ If you have a PSF and an image volume and you just want to get started, check ou
>>> result = decon(image_path, psf_path)
For finer-tuned control, you may wish to make an OTF file from your PSF using :func:`pycudadecon.make_otf`, and then use the :class:`pycudadecon.RLContext` context manager to setup the GPU for use with the :func:`pycudadecon.rl_decon` function. (Note all images processed in the same context must have the same input shape).
For finer-tuned control, you may wish to make an OTF file from your PSF using
:func:`pycudadecon.make_otf`, and then use the :class:`pycudadecon.RLContext`
context manager to setup the GPU for use with the :func:`pycudadecon.rl_decon`
function. (Note all images processed in the same context must have the same
input shape).

.. code-block:: python
Expand Down
62 changes: 21 additions & 41 deletions docs/installation.rst
View file
Original file line number Diff line number Diff line change
@@ -1,57 +1,37 @@
Installation
============

Via conda
---------

Precompiled libraries are available for Windows, Linux, and Mac via the conda package manager

Install `anaconda <https://www.anaconda.com/distribution/#download-section>`_ or `miniconda <https://docs.conda.io/en/latest/miniconda.html>`_, add a couple channels to your config, then install pycudadecon:
The conda package includes the required pre-compiled libraries for Windows and Linux.
*macOS is not supported*

.. code-block:: bash
$ conda config --add channels conda-forge
$ conda config --add channels talley
# in some cases, installing into the base environment has
# prevented pycudadecon from functioning properly...
# best to install into a clean environment along with
# whatever other packges you want (e.g. ipython, jupyter, etc)
$ conda create -n decon_env pycudadecon
# then activate that environment each time before using
$ conda activate decon_env
conda install -c conda-forge pycudadecon
GPU requirements
----------------

This software requires a CUDA-compatible NVIDIA GPU.
The underlying libraries (llspylibs) 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 (the OS X build has only been compiled for CUDA 9.0). To see which version you have installed currently, use `conda list llspylibs`, and to manually select a specific version of llspylibs:
This software requires a CUDA-compatible NVIDIA GPU. The underlying cudadecon
libraries 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:

====== ============ ========== ============
CUDA Linux driver Win driver Install With
====== ============ ========== ============
10.0 ≥ 410.48 ≥ 411.31 ``conda install llspylibs=<version>=cu10.0``
9.0 ≥ 384.81 ≥ 385.54 ``conda install llspylibs=<version>=cu9.0``
====== ============ ========== ============
To specify a specific cudatoolkit version, install as follows (for instance, to use
``cudatoolkit=10.2``)

...where ``<version>`` is the version of llspylibs you'd like to install (use ``conda search llspylibs`` to list available versions)

If you run into trouble, feel free to `open an issue on github <https://github.com/tlambert03/pycudadecon/issues>`_ and describe your setup.
====== ============ ==========
CUDA Linux driver Win 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
====== ============ ==========


For development
---------------

If you'd like to contribute to pycudadecon, pull requests are welcome! Minimally, you will want to have llspylibs installed in your conda environment. Here's an example for creating a new environment (here: `pycdenv`), installing some dependencies, cloning the repo from github, then running the tests.

.. code-block:: bash
$ conda create -n pycdenv -c talley llspylibs tifffile numpy pytest python=3.7
$ git clone https://github.com/tlambert03/pycudadecon.git
$ cd pycudadecon
# run tests with pytest
$ pytest
# or with unittest
$ python -m unittest discover test
If you run into trouble, feel free to `open an issue on github
<https://github.com/tlambert03/pycudadecon/issues>`_ and describe your setup.

0 comments on commit 6ef2a1d

Please sign in to comment.