Add example notebook for interfacing with Numpy

[tbirdso]

• Demonstrate initializing a numpy array and converting to ITK image format with itk.image_from_array and itk.image_view_from_array
• Demonstrate manipulating an ITK image as a numpy array with itk.array_from_image and itk.array_view_from_image
• Demonstrate ITK's ~KJI~ IJK notation vs numpy's ~IJK~ KJI notation with itk.size(image) vs image.shape

EDIT: Fixed image_view_from_array and array_view_from_image

[dzenanz]

I believe that ITK uses IJK and numpy KJI, not the other way around.

[Leengit]

Perhaps we are already thinking along these lines, but just in case ... we may want to go all verbose and say that there are two distinct cases here, depending on whether the "third dimension" represents multiple planes (Z) or time points (T), or represents multiple colors (C, such as R, G, & B).

1. For planes Z and time points T, and sometimes for colors C, the ITK order is [X, Y, Z], [X, Y, T], [X, Y, C], where the last case is applicable if each color of the image is treated as if it were its own monochromatic image. The corresponding numpy indexing is reversed. Both ITK and numpy consider these to be 3-dimensional.
2. For "vector pixels" such as RGB, this is a 2-dimensional image according to ITK, the ITK index order is [X, Y] and each pixel retrieved is multiple numeric values. Numpy considers this to be a 3-dimensional array and the numpy order is [Y, X, C], which differs from the previous paragraph. Furthermore, in this case, itk.image_from_array and itk.image_from_array_view require a second parameter is_vector=True.

And of course there are monochromatic 2-dimensional images.

[tbirdso]

@dzenanz Maybe my thinking is backwards. In ITK the fastest element is the first index while in numpy it is the last index. When we say "IJK" is "K" the fastest or slowest index?

Relevant discourse discussion

[Leengit]

In calculus (x, y, z) is usually associated with unit vectors (i, j, k) respectively. If that's the convention to stick with then ITK is [IJK].

[tbirdso]

Works for me, updated the description.

[tbirdso]

Assigned to @andinet per request