CUDA implementation of the SLIC segmentaion algorithm.
Project description
cuda-slic: A CUDA implementation of the SLIC Superpixel algorithm
SLIC
SLIC stands for simple linear iterative clustering. SLIC uses tiled k-means clustering to segment an input image into a set of superpixels/supervoxels.
This library was designed to segment large 2D/3D images coming from different detectors at the Diamond Light Source. These images can be very large so using a serial CPU code is out of the question.
To speed up processing we use GPU acceleration to achieve great speed
improvements over alternative implementations. cuda-slic
borrows its API
from skimage.segmentation.slic
.
Benchmark
Machine: 8 Core Intel Xeon(R) W-2123 CPU @ 3.60GHz with NVIDIA Quadro P2000
from skimage import data
from cuda_slic.slic import slic as cuda_slic
from skimage.segmentation import slic as skimage_slic
blob = data.binary_blobs(length=500, n_dim=3, seed=2)
n_segments = 500**3/5**3 # super pixel shape = (5,5,5)
%timeit -r1 -n1 skimage_slic(blob, n_segments=n_segments, multichannel=False, max_iter=5)
# 2min 28s ± 0 ns per loop (mean ± std. dev. of 1 run, 1 loop each)
%timeit -r1 -n1 cuda_slic(blob, n_segments=n_segments, multichannel=False, max_iter=5)
# 13.1 s ± 0 ns per loop (mean ± std. dev. of 1 run, 1 loop each)
CUDA JIT Compilation
cuda-slic
uses JIT compilation to covert CUDA kernels into GPU machine-code (PTX).
Two options are available for JIT compiliing CUDA code with python: Cupy or PyCUDA.
If PyCUDA is installed in the virtutalenv it is used by default. Otherwise Cupy is
used.
To ease distribution cuda-slic
is packaged into two independent packages that share
the same source-code but depend on a different libraries for JIT compilation:
cuda-slic
uses pycuda for JIT compilation.gpu-slic
uses cupy for JIT compilation.
Installing cuda-slic (with PyCUDA)
pip install cuda-slic
cuda-slic
uses pycuda which has the following non-python
build dependencies:
- gcc and g++/gcc-c++ on Linux. MSVC++ compiler and C++ build-tools on Windows.
- the cudatoolkit for linking with
cuda.h
.
and the following runtime dependencies:
- gcc and g++/gcc-c++ on Linux. MSVC++ compiler and C++ build-tools on Windows.
- the cudatoolkit for linking with cuda libraries.
- the nvcc compiler. Ships with newer cudatoolkit versions.
See the pycuda docs for installation instructions.
Installing gpu-slic (with Cupy)
pip install gpu-slic
gpu-slic
uses Cupy which has the following non-python
build dependencies:
- gcc and g++/gcc-c++ on Linux.
- the cudatoolkit for linking with cuda libraries.
- the nvcc compiler. Ships with newer cudatoolkit versions.
Note that when pip installing gpu-slic, cupy is installed as an sdist
meaning that your host must meet the compiling and linking requirements
of cupy.
Check if gpu-slic is available on conda-forge to get precompiled binaries of Cupy.
See also cupy docs for installation instructions.
Usage
from cuda_slic import slic
from skimage import data
# 2D RGB image
img = data.astronaut()
labels = slic(img, n_segments=100, compactness=10)
# 3D gray scale
vol = data.binary_blobs(length=50, n_dim=3, seed=2)
labels = slic(vol, n_segments=100, multichannel=False, compactness=0.1)
# 3D multi-channel
# volume with dimentions (z, y, x, c)
# or video with dimentions (t, y, x, c)
vol = data.binary_blobs(length=33, n_dim=4, seed=2)
labels = slic(vol, n_segments=100, multichannel=True, compactness=1)
Development
Prerequisites:
- gcc and g++/gcc-c++ installed and available on PATH.
- cudatoolkit installed and CUDA_HOME pointing to its location.
nvcc
compiler. Ships with recent versions of cudatoolkit.
Dependency Management
We use conda
as a dependency installer and virtual env manager.
A development environment can be created with
conda env create -f environment.yml
now you can activate the virtual env with conda activate cuda-slic
,
and deactivate with conda deactivate
.
To add a dependency, add it to the environment.yml file, then you can run
conda env update -f environment.yml
to keep environment.yml
file as lean as possible, development dependencies
are kept in requirements_dev.txt
and can be installed with
conda install --file requirements_dev.txt -c conda-forge
or
pip install -r requirements_dev.txt
Tests
In the notebooks folder there are Jupyter notebooks where the segmentation algorithm can be visually inspected.
Our unit-testing framework of choice is Py.test. The unit-tests can be run with
conda activate cuda-slic
pip install pytest
pytest
or
conda activate cuda-slic
pip install tox
tox
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for gpu_slic-0.0.1a3-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 63dfeafb279cc2fd94caa00a4e312513fea663a4a1ce56c63cf487408076a493 |
|
MD5 | 0f8c536fe3d4fd404fad5d687243ae83 |
|
BLAKE2b-256 | 2ee739bb17855f8db573de7221263778cafa2ee3ae1de2cb2b4f7633276117f0 |