Imops

Efficient parallelizable algorithms for multidimensional arrays to speed up your data pipelines.

• Documentation
• Benchmarks

Install

pip install imops  # default install with Cython backend
pip install imops[numba]  # additionally install Numba backend

How fast is it?

Time comparisons (ms) for Intel(R) Xeon(R) Silver 4114 CPU @ 2.20GHz using 8 threads. All inputs are C-contiguous NumPy arrays. For morphology functions bool dtype is used and float64 for all others.

We use airspeed velocity to benchmark our code. For detailed results visit benchmark page.

Features

Fast Radon transform

from imops import radon, inverse_radon

Fast 0/1-order zoom

from imops import zoom, zoom_to_shape

# fast zoom with optional fallback to scipy's implementation
y = zoom(x, 2, axis=[0, 1])
# a handy function to zoom the array to a given shape 
# without the need to compute the scale factor
z = zoom_to_shape(x, (4, 120, 67))

Works faster only for ndim<=4, dtype=float32 or float64 (and bool-int16-32-64-uint8-16-32 if order == 0), output=None, order=0 or 1, mode='constant', grid_mode=False

Fast 1d linear interpolation

from imops import interp1d  # same as `scipy.interpolate.interp1d`

Works faster only for ndim<=3, dtype=float32 or float64, order=1

Fast 2d linear interpolation

import numpy as np
from imops.interp2d import Linear2DInterpolator
n, m = 1024, 2
points = np.random.randint(low=0, high=1024, size=(n, m))
points = np.unique(points, axis=0)
x_points = points[: n // 2]
values = np.random.uniform(low=0.0, high=1.0, size=(len(x_points),))
interp_points = points[n // 2:]
num_threads = -1 # will be equal to num of CPU cores
# You can optionally pass your own triangulation as an np.array of shape [num_triangles, 3], element at (i, j) position is an index of a point from x_points
interpolator = Linear2DInterpolator(x_points, values, num_threads=num_threads, triangles=None)
# Also you can pass values to __call__ and rewrite the ones that were passed to __init__
interp_values = interpolator(interp_points, values + 1.0, fill_value=0.0)

Fast binary morphology

from imops import binary_dilation, binary_erosion, binary_opening, binary_closing

These functions mimic scikit-image counterparts

Padding

from imops import pad, pad_to_shape

y = pad(x, 10, axis=[0, 1])
# `ratio` controls how much padding is applied to left side:
# 0 - pad from right
# 1 - pad from left
# 0.5 - distribute the padding equally
z = pad_to_shape(x, (4, 120, 67), ratio=0.25)

Cropping

from imops import crop_to_shape

# `ratio` controls the position of the crop
# 0 - crop from right
# 1 - crop from left
# 0.5 - crop from the middle
z = crop_to_shape(x, (4, 120, 67), ratio=0.25)

Labeling

from imops import label

# same as `skimage.measure.label`
labeled, num_components = label(x, background=1, return_num=True)

Backends

For all heavy image routines except label you can specify which backend to use. Backend can be specified by a string or by an instance of Backend class. The latter allows you to customize some backend options:

from imops import Cython, Numba, Scipy, zoom

y = zoom(x, 2, backend='Cython')
y = zoom(x, 2, backend=Cython(fast=False))  # same as previous
y = zoom(x, 2, backend=Cython(fast=True))  # -ffast-math compiled cython backend
y = zoom(x, 2, backend=Scipy())  # use scipy original implementation
y = zoom(x, 2, backend='Numba')
y = zoom(x, 2, backend=Numba(parallel=True, nogil=True, cache=True))  # same as previous

Also backend can be specified globally or locally:

from imops import imops_backend, set_backend, zoom

set_backend('Numba')  # sets Numba as default backend
with imops_backend('Cython'):  # sets Cython backend via context manager
    zoom(x, 2)

Note that for Numba backend setting num_threads argument has no effect for now and you should use NUMBA_NUM_THREADS environment variable. Available backends:

Acknowledgements

Some parts of our code for radon/inverse radon transform as well as the code for linear interpolation are inspired by the implementations from scikit-image and scipy. Also we used fastremap, edt and cc3d out of the box.