Add Python utility functions: ITK image <-> volume node #7094

dzenanz · 2023-07-14T18:27:48Z

~~This was adapted from https://github.com/KitwareMedical/SlicerITKUltrasound/blob/6d7ea98bc329fc52e9c9bfddccc807cf76806fc2/ITKUltrasoundCommon/ITKUltrasoundCommon.py#L98-L204~~

Update: This was adapted from https://discourse.slicer.org/t/installing-itk-python-package-in-slicer-5-1-and-above/25636

lassoan · 2023-07-15T12:10:58Z

Thank you, this s very useful. Is it only for ITKPython images or SimpleITK as well? Can you make it work for multiple components (such as color images) as well?

dzenanz · 2023-07-15T12:24:26Z

It is only for ITK images, but SimpleITK has methods for converting from and to ITK images.

I didn't need multi-component images so far, so I forgot about them. I just started my 2 week vacation, so it will be a while before I can get to it.

Base/Python/slicer/util.py

This was adapted from SlicerITKUltrasound extension at 6d7ea98bc329fc52e9c9bfddccc807cf76806fc2. Direct link: https://github.com/KitwareMedical/SlicerITKUltrasound/blob/6d7ea98bc329fc52e9c9bfddccc807cf76806fc2/ITKUltrasoundCommon/ITKUltrasoundCommon.py#L98-L204

dzenanz · 2023-08-07T20:08:53Z

The limitation regarding multi-component images comes from https://github.com/InsightSoftwareConsortium/ITK/blob/v5.4rc01/Wrapping/Generators/Python/itk/support/extras.py#L740
I am looking into it.

This is heavily dependent on a fix in ITK: InsightSoftwareConsortium/ITK#4142

For consistency with the existing API: * Remove the "Node" suffix from "VolumeNode" Consistent with arrayFromVolume, arrayFromModel, ... * Append "Array" to "RASAffine". Consistent with vtkMatrixFromArray, vtkMatrixFromArray, ...) Rename the following functions: * volumeNodeFromITKImage - -> addVolumeFromITKImage * itkImageFromVolumeNode -> itkImageFromVolume * _getRASAffineFromITK -> _getRASAffineArrayFromITKImage - _getITKMetadataFromRASAffine -> _getITKMetadataFromRASAffineArray * updateVolumeNodeFromITKImage -> updateVolumeFromITKImage Also fix spacing and add additional empty lines to improve readability.

Base/Python/slicer/util.py

…rLayers Update of the Slice viewer is expected to be done at the application level.

Approach adapted from addVolumeFromArray()

Rely on the fact ITK functions vtk_image_from_image and image_from_vtk_image already account for VTL image direction introduced in VTK 9. Adapted from https://discourse.slicer.org/t/installing-itk-python-package-in-slicer-5-1-and-above/25636

Base/Python/slicer/util.py

dzenanz · 2023-08-10T13:27:11Z

This is quite a big and useful simplification!

Co-authored-by: Dženan Zukić <dzenan.zukic@kitware.com>

…PS<->RAS

jcfr · 2023-08-10T14:58:43Z

This has been tested and is functionally complete.

dzenanz

Looks good!

jcfr · 2023-08-10T15:28:26Z

Remaining:

document how the buffer is shared between ITK and Volume node.
add ITK version check to warn if the ITK version installed does not support a type of MRML Volume node to ITK conversion.

Summary: Buffer is shared between MRML Volume Node and ITK image data using either slicer.util.itkImageFromVolume or slicer.util.updateVolumeFromITKImage

MRML Volume Node -> ITK Image: `slicer.util.itkImageFromVolume`

slicer.util.itkImageFromVolume relies on itk.image_from_vtk_image which internally

(1) uses vtk.util.numpy_support.vtk_to_numpy¹:

point_data = vtk_image.GetPointData()
array = vtk_to_numpy(point_data.GetScalars())

which internally uses numpy.frombuffer ²

This function creates a view into the original object. This should be safe in general, but it may make sense to copy the result when the original object is mutable or untrusted.

(2) also uses itk.image_view_from_array

l_image = itk.image_view_from_array(array, is_vector)

Conclusion: This means that the buffer is shared between MRML Volume Node and ITK image data

ITK Image -> MRML Volume Node: `slicer.util.updateVolumeFromITKImage`

slicer.util.updateVolumeFromITKImage relies on itk.vtk_image_from_image which internally

(1) uses itk.array_view_from_image to get a numpy array view

from vtk.util.numpy_support import numpy_to_vtk

array = itk.array_view_from_image(l_image)

(2) and also uses vtk.util.numpy_support.numpy_to_vtk³ to

vtk_image = vtk.vtkImageData()
data_array = numpy_to_vtk(array.reshape(-1))

with the deep parameter of numpy_to_vtk set to 0 (this is the default),

Conclusion: This means that the buffer is shared between ITK image data
and MRML Volume Node

Relevant files

vtkmodules/util/numpy_support.py: https://github.com/Slicer/VTK/blob/slicer-v9.2.20230607-1ff325c54/Wrapping/Python/vtkmodules/util/numpy_support.py
itk/support/extras.py: https://github.com/InsightSoftwareConsortium/ITK/blob/master/Wrapping/Generators/Python/itk/support/extras.py#L683-L783

…mITKImage

…ITKImage

jcfr · 2023-08-10T16:36:39Z

Proposed commit message when squashing:

ENH: Add Python utility functions: ITK image <-> volume node (#7094)

Update `slicer.util` adding these functions:
* itkImageFromVolume
* addVolumeFromITKImage
* updateVolumeFromITKImage
* itkImageFromVolumeModified

Adapted from https://discourse.slicer.org/t/installing-itk-python-package-in-slicer-5-1-and-above/25636

Co-authored-by: Jean-Christophe Fillion-Robin <jchris.fillionr@kitware.com>

jcfr · 2023-08-10T16:41:31Z

@lassoan When you have a chance, could you review the docstings related to memory ownership.

dzenanz

Looks good, thanks JC.

Base/Python/slicer/util.py

Co-authored-by: Andras Lasso <lasso@queensu.ca>

jcfr · 2023-08-16T15:40:58Z

Base/Python/slicer/util.py

+        vtkImageCopy = vtk.vtkImageData()
+        vtkImageCopy.DeepCopy(vtkImage)
+        volumeNode.SetAndObserveImageData(vtkImageCopy)


@lassoan deepCopy is now the default

@dzenanz I tested the changes in the context of SlicerITKUltrasound and it didn't see any issues (with/without speechifying deepCopy to False)

jcfr · 2023-08-16T15:42:52Z

I plan on integrating (by squashing) this afternoon 🚀

and I will be using the following message:

ENH: Add Python utility functions: ITK image <-> volume node (#7094)

Update `slicer.util` adding these functions:
* itkImageFromVolume
* addVolumeFromITKImage
* updateVolumeFromITKImage
* itkImageFromVolumeModified

Adapted from https://discourse.slicer.org/t/installing-itk-python-package-in-slicer-5-1-and-above/25636

Co-authored-by: Jean-Christophe Fillion-Robin <jchris.fillionr@kitware.com>
Co-authored-by: Andras Lasso <lasso@queensu.ca>

dzenanz · 2023-08-16T15:52:54Z

Thanks for taking care of this JC!

dzenanz requested review from jcfr and lassoan July 14, 2023 18:27

dzenanz added this to the Slicer 5.3 milestone Jul 14, 2023

jcfr reviewed Aug 4, 2023

View reviewed changes

dzenanz force-pushed the itkVolumeUtil branch 5 times, most recently from d8049c3 to 2532363 Compare August 7, 2023 17:23

dzenanz mentioned this pull request Aug 7, 2023

Support multi-component images in image_from_vtk_image function InsightSoftwareConsortium/ITK#4142

Merged

2 tasks

dzenanz and others added 4 commits August 8, 2023 09:42

ENH: Review feedback

2799cd5

BUG: Support multi-component images

ed79d60

This is heavily dependent on a fix in ITK: InsightSoftwareConsortium/ITK#4142

ENH: Update slicer.util.addVolumeFromITKImage to accept name parameter

93fbace

jcfr force-pushed the itkVolumeUtil branch from faccaf8 to 93fbace Compare August 8, 2023 14:00

jcfr reviewed Aug 8, 2023

View reviewed changes

Base/Python/slicer/util.py Outdated Show resolved Hide resolved

dzenanz commented Aug 8, 2023

View reviewed changes

Base/Python/slicer/util.py Outdated Show resolved Hide resolved

jcfr added 4 commits August 10, 2023 00:58

ENH: Simplify updateVolumeFromITKImage removing call to setSliceViewe…

3741f34

…rLayers Update of the Slice viewer is expected to be done at the application level.

ENH: Generalize addVolumeFromITKImage to support customizing class name

8a5ae09

Approach adapted from addVolumeFromArray()

ENH: Ensure addVolumeFromITKImage also create default display node

56aac08

dzenanz commented Aug 10, 2023

View reviewed changes

Base/Python/slicer/util.py Outdated Show resolved Hide resolved

jcfr and others added 2 commits August 10, 2023 10:56

BUG: Fix return value in itkImageFromVolume

c871fb5

Co-authored-by: Dženan Zukić <dzenan.zukic@kitware.com>

BUG: Update itkImageFromVolume/addVolumeFromITKImage to account for L…

f58d116

…PS<->RAS

dzenanz commented Aug 10, 2023

View reviewed changes

jcfr added 4 commits August 10, 2023 12:10

DOC: Fix typos in itkImageFromVolume/updateVolumeFromITKImage

8de2825

ENH: Add slicer.util.itkImageFromVolumeModified

fe5a33a

DOC: Document memory ownership for itkImageFromVolume/updateVolumeFro…

4b4fded

…mITKImage

STYLE: Remove extra semicolons in itkImageFromVolume/updateVolumeFrom…

ceb1c57

…ITKImage

jcfr force-pushed the itkVolumeUtil branch from 8594829 to b4b35b1 Compare August 10, 2023 16:36

STYLE: Update slicer.util grouping MRML<->ITKImage functions together

5ef31ef

jcfr force-pushed the itkVolumeUtil branch from b4b35b1 to 5ef31ef Compare August 10, 2023 16:42

dzenanz commented Aug 10, 2023

View reviewed changes

lassoan reviewed Aug 12, 2023

View reviewed changes

jcfr and others added 2 commits August 14, 2023 22:30

DOC: Improve itkImageFromVolume/updateVolumeFromITKImage docstrings

9a1b13d

Co-authored-by: Andras Lasso <lasso@queensu.ca>

ENH: Update (add/update)VolumeFromITKImageto deepCopy by default

50ddbd1

Co-authored-by: Andras Lasso <lasso@queensu.ca>

jcfr reviewed Aug 16, 2023

View reviewed changes

jcfr merged commit 1a6a5a3 into Slicer:main Aug 16, 2023
5 of 6 checks passed

dzenanz deleted the itkVolumeUtil branch August 16, 2023 17:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Python utility functions: ITK image <-> volume node #7094

Add Python utility functions: ITK image <-> volume node #7094

dzenanz commented Jul 14, 2023 •

edited by jcfr

lassoan commented Jul 15, 2023

dzenanz commented Jul 15, 2023

dzenanz commented Aug 7, 2023

dzenanz commented Aug 10, 2023

jcfr commented Aug 10, 2023

dzenanz left a comment

jcfr commented Aug 10, 2023 •

edited

jcfr commented Aug 10, 2023 •

edited by dzenanz

jcfr commented Aug 10, 2023

dzenanz left a comment

jcfr Aug 16, 2023

jcfr commented Aug 16, 2023 •

edited

dzenanz commented Aug 16, 2023

Add Python utility functions: ITK image <-> volume node #7094

Add Python utility functions: ITK image <-> volume node #7094

Conversation

dzenanz commented Jul 14, 2023 • edited by jcfr

lassoan commented Jul 15, 2023

dzenanz commented Jul 15, 2023

dzenanz commented Aug 7, 2023

dzenanz commented Aug 10, 2023

jcfr commented Aug 10, 2023

dzenanz left a comment

Choose a reason for hiding this comment

jcfr commented Aug 10, 2023 • edited

MRML Volume Node -> ITK Image: slicer.util.itkImageFromVolume

ITK Image -> MRML Volume Node: slicer.util.updateVolumeFromITKImage

Relevant files

Footnotes

jcfr commented Aug 10, 2023 • edited by dzenanz

jcfr commented Aug 10, 2023

dzenanz left a comment

Choose a reason for hiding this comment

jcfr Aug 16, 2023

Choose a reason for hiding this comment

jcfr commented Aug 16, 2023 • edited

dzenanz commented Aug 16, 2023

dzenanz commented Jul 14, 2023 •

edited by jcfr

jcfr commented Aug 10, 2023 •

edited

MRML Volume Node -> ITK Image: `slicer.util.itkImageFromVolume`

ITK Image -> MRML Volume Node: `slicer.util.updateVolumeFromITKImage`

jcfr commented Aug 10, 2023 •

edited by dzenanz

jcfr commented Aug 16, 2023 •

edited