Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consume and produce Numpy arrays #1136

Open
mrocklin opened this issue Aug 4, 2019 · 5 comments

Comments

@mrocklin
Copy link

commented Aug 4, 2019

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?

@mrocklin

This comment has been minimized.

Copy link
Author

commented Aug 5, 2019

cc @jakirkham

@jakirkham

This comment has been minimized.

Copy link
Member

commented Aug 7, 2019

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 given function with that image
  3. 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.

@thewtex thewtex added this to the ITK v5.1b01 milestone Aug 9, 2019

@thewtex thewtex self-assigned this Aug 9, 2019

@thewtex

This comment has been minimized.

Copy link
Member

commented Aug 9, 2019

@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.

@mrocklin

This comment has been minimized.

Copy link
Author

commented Aug 9, 2019

we can automatically apply this decorator to every function that is derived from an itk::ImageToImageFilter class.

That sounds really powerful :)

thewtex added a commit to thewtex/ITK that referenced this issue Aug 19, 2019

ENH: Support NumPy array-like inputs to image filters
When a NumPy array-like is passed into Python snake_case interface to
filters, the array-like arguments or standard image keyword arguments
are converted into itk.Image views, and passed to the filter. All image
outputs are converted to NumPy ndarray's if array's where used as
inputs.

Addresses InsightSoftwareConsortium#1136

thewtex added a commit to thewtex/ITK that referenced this issue Aug 19, 2019

ENH: Support NumPy array-like inputs to image filters
When a NumPy array-like is passed into Python snake_case interface to
filters, the array-like arguments or standard image keyword arguments
are converted into itk.Image views, and passed to the filter. All image
outputs are converted to NumPy ndarray's if array's were used as
inputs.

Addresses InsightSoftwareConsortium#1136
@thewtex

This comment has been minimized.

Copy link
Member

commented Aug 19, 2019

Addressed by #1176

thewtex added a commit to thewtex/ITK that referenced this issue Aug 19, 2019

ENH: Support NumPy array-like inputs to image filters
When a NumPy array-like is passed into Python snake_case interface to
filters, the array-like arguments or standard image keyword arguments
are converted into itk.Image views, and passed to the filter. All image
outputs are converted to NumPy ndarray's if array's were used as
inputs.

Addresses InsightSoftwareConsortium#1136
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.