Itk: Consume and produce Numpy arrays

Created on 4 Aug 2019 · 6Comments · Source: InsightSoftwareConsortium/ITK

I would find it convenient if itk functions optionally consumed and produced numpy arrays. Here is a motivating example function that I'm working with:

Current code

import itk

image = np.array(...)  # 3d array
kernel = np.array(...)  # 3d array    

image = itk.image_view_from_array(image)   # Convert to ITK object
kernel = itk.image_view_from_array(kernel)  # Convert to ITK object

deconvolved = itk.richardson_lucy_deconvolution_image_filter(
    image,
    kernel_image=kernel,
    number_of_iterations=iterations
)

result = itk.array_from_image(deconvolved)  # Convert back to Numpy array

Desired code

import itk

image = np.array(...)  # 3d array
kernel = np.array(...)  # 3d array    

deconvolved = itk.richardson_lucy_deconvolution_image_filter(
    image,
    kernel_image=kernel,
    number_of_iterations=iterations
)

Discussion

It would be nice for itk functions to consume and produce Numpy arrays. This would help them compose with the rest of the SciPy ecosystem. However I suspect that there is a good reason why this isn't done today. For example maybe they have important metadata. However, if a user presents with a Numpy array then maybe there are some things that we can do? For example maybe the itk.image_view_from_array function could be called automatically on all inputs that are expected to be ITK Image objects but are actually NumPy arrays. Additionally, perhaps if the user presents with a Numpy array then we might automatically call itk.array_from_image on our result?

Python wrapping Enhancement

Source

mrocklin

❤2 🚀1

All 6 comments

cc @jakirkham

mrocklin on 5 Aug 2019

👍1

Probably as a first pass it would be useful to have a function (maybe a decorator?) that takes an existing ITK function and does the following.

Converts the input array into an ITK image
Calls the given function with that image
Computes the result as a NumPy array, to return

This would at least make it easier to wrap ITK function to match this idiom with hopefully minimal work.

Edit: Here's what this wrapper function might look like.

jakirkham on 7 Aug 2019

👍1

@mrocklin brilliant idea! We will definitely do this!

For example maybe they have important metadata.

Yes. Spatial metadata is critical in practice. There is more discussion on this metadata and NumPy-array-like-interface's in this Discourse thread.

itk.image_view_from_array function could be called automatically on all inputs that are expected to be ITK Image objects but are actually NumPy arrays.

Yes!

Additionally, perhaps if the user presents with a Numpy array then we might automatically call itk.array_from_image on our result?

Yes!

Probably as a first pass it would be useful to have a function (maybe a decorator?) that takes an existing ITK function and does the following.
1. Converts the input array into an ITK image

2. Calls the give function with that image

3. Computes the result as a NumPy array, to return

Yes!

The Python wrapping is generated with a Python script, and we parse the AST -- we can automatically apply this decorator to every function that is derived from an itk::ImageToImageFilter class.