# Why to invert the order of the indices between numpy and SimpleITK?

**URL:** <https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809>\
**Category:** Engineering\
**Tags:** simpleitk, python\
**Created:** [March 29, 2018, 8:13pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809 "2018-03-29T20:13:04Z")\
**Posts on this page:** 17\
**Page:** 1

<div class="post-metadata">

**Author:** ![Diego\_C](https://discourse.itk.org/user_avatar/discourse.itk.org/diego_c/32/279_2.png) [@Diego\_C](https://discourse.itk.org/u/Diego_C)\
**Post date:** [March 29, 2018, 8:13pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/1 "2018-03-29T20:13:05Z")

</div>

HI,

Can anyone explain the logic between this:

 ![image](https://discourse.itk.org/uploads/default/original/1X/edd011a5f2d547a78f8d32289438169597335210.png)

This is taken from the SimpleITK Notebooks

It states that the order of the indices is the opposite in numpy. But in fact this is an arbitrary choice. For instance in matplotlib the last index of the numpy array represents the depth:

 ![image](https://discourse.itk.org/uploads/default/original/1X/443806f835f95e9dd05e6153677cbe4b28ecc40a.png)

This type of change back and forth between _channels first_ and _channels last_ is prone to errors if you forget to switch the order of your indices and also reduces interoperability with other libraries (like matplotlib).

Could I suggest to have a way to configure your preferred order for numpy arrays in a similar fashion to other libraries such as keras:

 ![image](https://discourse.itk.org/uploads/default/original/1X/444bc95681ba5ff3252b93a63a42fbf66f0a2501.png)

[https://keras.io/backend/](https://keras.io/backend/)

---

<div class="post-metadata">

**Author:** ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)\
**Post date:** [March 30, 2018, 2:09pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/2 "2018-03-30T14:09:15Z")

</div>

So `imshow` does correctly work with the layout that SimpleITK exports. Here is an RGB example:

```auto
In [14]: img = sitk.ReadImage("simpleitk_logo.png")

In [15]: nda = sitk.GetArrayViewFromImage(img)

In [16]: nda.shape
Out[16]: (53, 200, 4)

In [17]: img.GetSize()
Out[17]: (200, 53)

In [18]: plt.imshow(img)

```

The RGB channels ARE last.

The notebook example may be a little confusing because it is utilizing the size 3 for the z-physical space dimension, it is not an RGB image e.g. a 2-d image with 3 components. Additionally, imshow does not support 3-D spacial images, only 2-D image with 1,3, or 4 channels. The term depth in ambiguous here either referring to the number of channels or the 3rd spacial dimension.

The choices were not arbitrary. SimpleITK was designed to be consistent with ITK. ITK’s indexes are represented as x,y,z, so SimpleITK must reference the images that way too. The `GetArrayViewFromImage` method does not copy the ITK image buffer, so the layout of the data does not change when exporting. Numpy array created is index via C conventions (buffer[z][y][x][c]) vai [row major](https://docs.scipy.org/doc/numpy-1.13.0/glossary.html#term-row-major) with the fastest axis being the last “index”. So this approach is both efficient and compatible with numpy.

But you are correct it is error prone and confusing.

---

<div class="post-metadata">

**Author:** ![Diego\_C](https://discourse.itk.org/user_avatar/discourse.itk.org/diego_c/32/279_2.png) [@Diego\_C](https://discourse.itk.org/u/Diego_C)\
**Post date:** [March 30, 2018, 3:01pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/3 "2018-03-30T15:01:36Z")

</div>

I don’t disagree with you for a second that SimpleITK needs to be compatible with ITK. Why in heavens would not be? That wasn’t the spirit of my question.

I am thinking about interoperability between SimpleITK and Numpy.  
What I am thinking is why do we need to flip the order of the indices when getting the numpy arrays??

Notice that in your example you pass the sitk image to imshow, it makes sense that it works since the internal layout is [x,y,z] as show consistently throughout the sitk image methods. So no problem there.

But there is the expectation operate in the same manner with the numpy array, but you can’t because the indices are reversed.

So if I were going to extract the numpy array and do any kind of operation and then visualize it, you have to be constantly aware of this change or your numpy processing code won’t work or neither the visualization.

Maybe this [z, y, x] ordering is compatible with numpy as you suggest but so are other orderings like [z,x,y] or [y,z,x] but I would debate that computational efficiency is relative to the way the programmer handles his/her arrays.

Every time I pass from sitk to numpy and back I need to be aware of this change. That reduces compatibility, and creates the perfect situation to introduce bugs in your code.

My suggestion is to have an API method that enables you to return numpy arrays with the order that you expect, in a similar fashion to the example I provided earlier for keras.

Something like:

```auto
...
sitk.SetArrayLayout(sitk.DEPTH_FIRST)
narr = sitk.GetArrayFromImage(img) # returns array as [z,y,x]

sitk.SetArrayLayout(sitk.DEPTH_LAST)
narr = sitk.GetArrayFromImage(img) # returns array as [x,y,z]
```

---

<div class="post-metadata">

**Author:** ![phcerdan](https://discourse.itk.org/user_avatar/discourse.itk.org/phcerdan/32/286_2.png) [@phcerdan](https://discourse.itk.org/u/phcerdan)\
**Post date:** [March 30, 2018, 4:13pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/4 "2018-03-30T16:13:30Z")

</div>

No idea about the python bindings so I cannot comment much on this, but if `GetArrayFromImage` is not performing a copy as @blowekamp pointed, I hardly see how this can be implemented. Maybe a method doing a copy with whatever layout `CopyArrayFromImage(img, layout)`, as you suggested can be introduced, but it won’t be able to inter-operate between `numpy` and `itk` without an extra copy back to ITK, `CopyImageFromArray(array, layout)` which would be inefficient, but might still be useful.

> [@Diego\_C](#):
>
> I don’t disagree with you for a second that SimpleITK needs to be compatible with ITK. Why in heavens would not be? That wasn’t the spirit of my question.

Speaking as a fellow user/consumer of ITK, I recommend you to avoid this kind of comments. We all want the toolkit to be the sharpest tool possible, and we do it in a collective manner, in our time, with step-by-step improvements. Stick to pro-active, helpful comment and the continuous process of improvement will be easier and more enjoyable for everybody.

---

<div class="post-metadata">

**Author:** ![phcerdan](https://discourse.itk.org/user_avatar/discourse.itk.org/phcerdan/32/286_2.png) [@phcerdan](https://discourse.itk.org/u/phcerdan)\
**Post date:** [March 30, 2018, 4:33pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/5 "2018-03-30T16:33:51Z")

</div>

> [@phcerdan](#):
>
> CopyImageFromArray(array, layout)

This can be improved with `CopyImageFromArray(array, layout, itk_image_metadata)`  
To create the image with the metadata (origin, spacing, direction) from an existing itk image.

And/or `OverrideImageFromArray(array, layout, image)` to change the data of the image in-place.

---

<div class="post-metadata">

**Author:** ![lassoan](https://discourse.itk.org/user_avatar/discourse.itk.org/lassoan/32/27_2.png) [@lassoan](https://discourse.itk.org/u/lassoan)\
**Post date:** [March 31, 2018, 3:20am UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/6 "2018-03-31T03:20:09Z")

</div>

> [@blowekamp](#):
>
> Numpy array created is index via C conventions (buffer[z][y][c]) vai row major with the fastest axis being the last “index”. So this approach is both efficient and compatible with numpy

You can specify C/Fortran convention for [numpy.asarray](https://docs.scipy.org/doc/numpy/reference/generated/numpy.asarray.html#numpy.asarray) and [reshape](https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.reshape.html#numpy.reshape). Could those be used to get consistent indexes?

---

<div class="post-metadata">

**Author:** ![Diego\_C](https://discourse.itk.org/user_avatar/discourse.itk.org/diego_c/32/279_2.png) [@Diego\_C](https://discourse.itk.org/u/Diego_C)\
**Post date:** [March 31, 2018, 3:51am UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/7 "2018-03-31T03:51:56Z")

</div>

> [@phcerdan](#):
>
> Maybe a method doing a copy with whatever layout CopyArrayFromImage(img, layout), as you suggested can be introduced, but it won’t be able to inter-operate between numpy and itk without an extra copy back to ITK, CopyImageFromArray(array, layout) which would be inefficient, but might still be useful.

Hi Pablo!!

I thought of this as well, but the problem to have another method to do something that is already been done by `GetArrayFromImage` is that now the programmer has two (well, four!) methods to learn and keep track of. So I think a global method for the programmer to decide what order he/she expects from the Numpy arrays returned by SimpleITK (similar to the channels-first, channels-last options in keras) would be useful:

Set it once, at the beginning of your code, so you don’t have to deal with this decision _every time you get a numpy array from SimpleITK_.

Question: if `GetArrayFromImage` is not making a copy… Does that mean that any changes in the data contained by the numpy array, will also be shared if I query the image directly with `GetPixel` or similar methods?

Thanks,

Diego

---

<div class="post-metadata">

**Author:** ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)\
**Post date:** [March 31, 2018, 12:27pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/8 "2018-03-31T12:27:11Z")

</div>

> [@Diego\_C](#):
>
> Question: if GetArrayFromImage is not making a copy… Does that mean that any changes in the data contained by the numpy array, will also be shared if I query the image directly with GetPixel or similar methods?

`GetArrayFromImage` makes a deep copy, but `GetArrayViewFromImage` is a read only buffer in numpy. With the view you must maintain a s`sitk::Image` copy and if you modify the image it could effect the bumpy buffer. There is also SimpleITK’s lazy copying and reference accounting which can affect which image the buffer points to.

---

<div class="post-metadata">

**Author:** ![lassoan](https://discourse.itk.org/user_avatar/discourse.itk.org/lassoan/32/27_2.png) [@lassoan](https://discourse.itk.org/u/lassoan)\
**Post date:** [April 2, 2018, 12:41pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/9 "2018-04-02T12:41:41Z")

</div>

For me it seems that we should be able to get IJK-indexed view (see my comment above, using Fortran ordering) and then everything would work without manually reversing axes.  
@blowekamp Have you tried to use Fortran ordering?

---

<div class="post-metadata">

**Author:** ![fbudin](https://discourse.itk.org/user_avatar/discourse.itk.org/fbudin/32/14_2.png) [@fbudin](https://discourse.itk.org/u/fbudin)\
**Post date:** [April 2, 2018, 2:07pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/10 "2018-04-02T14:07:09Z")

</div>

Based on the little I remember when I implemented this and what I can see in the implementation of `_GetImageViewFromArray()` which allows to import images in ITK from NumPy arrays that have Fortran or C ordering, it should be possible to add an option to `_GetArrayViewFromImage()` to select the ordering in the imported NumPy array. Does anybody want to give it a shot? Potentially it is just a matter of changing the order of the size vector components.

---

<div class="post-metadata">

**Author:** ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)\
**Post date:** [April 2, 2018, 2:33pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/11 "2018-04-02T14:33:22Z")

</div>

The current approach is correct. It follows ITK conventions ( and ITK Python ), and numpy conventions. ITK index via [i,j,k] and numpy index via [k,j,i]. Look at other Python imaging libraries such as PIL or scikit-image.

Yes you can utilize numpy.reshape to convert to fortran order while reversing the shape array, but that may result in a copy. And when you apply algorithms to the fortran array it may have to copy the data so that the buffer is in the proper order. This is not recommended.

Regarding `keras`, you have conflated index order and image data layout options. keras is following numpy conventions for [k,j,i] indexing. For RGB ( multi-components ), it has the option for the RGB to be the fast axis or the slow axis. For the former you can consider the layout as each pixel is a RGB value, while with the latter the data is laid out as the R-image, then G-image, then B-image.

---

<div class="post-metadata">

**Author:** ![lassoan](https://discourse.itk.org/user_avatar/discourse.itk.org/lassoan/32/27_2.png) [@lassoan](https://discourse.itk.org/u/lassoan)\
**Post date:** [April 2, 2018, 6:00pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/12 "2018-04-02T18:00:07Z")

</div>

Thanks for the explanation, it makes sense. We want to keep the common convention of indexing matrices as (row, column), but unfortunately for images it means (y, x) coordinates - kind of inverted. There is nothing else we can do about this, people just have to be aware and pay attention. From the variable type (image or matrix) it is always clear what indexing convention is used.

---

<div class="post-metadata">

**Author:** ![Diego\_C](https://discourse.itk.org/user_avatar/discourse.itk.org/diego_c/32/279_2.png) [@Diego\_C](https://discourse.itk.org/u/Diego_C)\
**Post date:** [April 2, 2018, 10:41pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/13 "2018-04-02T22:41:04Z")

</div>

> [@blowekamp](#):
>
> GetArrayFromImage makes a deep copy, but GetArrayViewFromImage is a read only buffer in numpy.

HI Bradley, thanks for the explanation. I was referring indeed to GetArrayFromImage not to GetArrayViewFromImage, so if it does a deep copy as you say, it would be possible then to return that copy in the expected [x,y,z] (as in SimpleITK and ITK) order, is that correct?

Thanks,

Diego

---

<div class="post-metadata">

**Author:** ![Diego\_C](https://discourse.itk.org/user_avatar/discourse.itk.org/diego_c/32/279_2.png) [@Diego\_C](https://discourse.itk.org/u/Diego_C)\
**Post date:** [April 3, 2018, 12:55am UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/14 "2018-04-03T00:55:21Z")

</div>

I checked on PIL and scikit-image as per @blowekamp suggestion. Bradley is correct in that scikit-image handles operations on 3D images using C-contiguous arrays, where as channels in RGB images go last.

In case you guys are interested, this link explains very clearly the difference between RGB and 3D images in terms of the array layout _for scikit-image_[4. A crash course on NumPy for images — skimage 0.23.0rc0.dev0 documentation](http://scikit-image.org/docs/dev/user_guide/numpy_images.html#coordinate-conventions)

An excerpt explaining everything is here:

 ![image](https://discourse.itk.org/uploads/default/original/1X/d64a95487afcec9191cae38ed1c45caa0753165c.png)

> Perhaps adding some like this to SimpleITK’s documentation could be really helpful? What do you guys think?

On the other hand I didn’t find info on PIL other than when you retrieve data from the image, you get a cordinate-less array in the sense that it is a flattened array instead of multi-indexed.

Regards,

Diego

---

<div class="post-metadata">

**Author:** ![zivy](https://discourse.itk.org/user_avatar/discourse.itk.org/zivy/32/1726_2.png) [@zivy](https://discourse.itk.org/u/zivy)\
**Post date:** [April 3, 2018, 4:29pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/15 "2018-04-03T16:29:52Z")

</div>

@Diego_C, we intend to work on general improvements of the SimpleITK documentation in the next couple of months. Thanks for the pointer to the scikit-image documentation, this is useful for us as a point of reference.

---

<div class="post-metadata">

**Author:** ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)\
**Post date:** [April 3, 2018, 8:33pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/16 "2018-04-03T20:33:30Z")

</div>

Split this topic on April 3, 2018, 8:33pm UTC

4 posts were split to a new topic: [How to Contribute to SimpleITK Documentation](https://discourse.itk.org/t/how-to-contribute-to-simpleitk-documentation/823)

This topic has diverged into a separate issue, so I have split the new conversation out.

---

<div class="post-metadata">

**Author:** ![Jingnan\_Jia](https://discourse.itk.org/user_avatar/discourse.itk.org/jingnan_jia/32/1481_2.png) [@Jingnan\_Jia](https://discourse.itk.org/u/Jingnan_Jia)\
**Post date:** [May 31, 2020, 12:46pm UTC](https://discourse.itk.org/t/why-to-invert-the-order-of-the-indices-between-numpy-and-simpleitk/809/17 "2020-05-31T12:46:35Z")

</div>

Hi, Diego\_C, I noted that in scikit, the order of coordinates is (row, col) or (x, y) no matter for 2D or 3D images. However, in SimpleITK, the order changed from (x, y) to (y, x) after `GetArrayFromImage`. Could you explain if it is correct? Why `x` and `y` need to be exchanged?