# New for ITK 5.0: IndexRange, ZeroBasedIndexRange, ImageRegionIndexRange

**URL:** https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412
**Category:** Engineering
**Created:** [November 12, 2018, 5:31pm UTC](https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412 "2018-11-12T17:31:02Z")
**Posts on this page:** 9
**Page:** 1

<div class="post-metadata">

### Author: ![Niels\_Dekker](https://discourse.itk.org/letter_avatar_proxy/v4/letter/n/9d8465/32.png) [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [November 12, 2018, 5:31pm UTC](https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412/1 "2018-11-12T17:31:02Z")

</div>

FYI, Last weekend, @matt.mccormick merged the `itk::Experimental::IndexRange` template class that I proposed, making it available for ITK 5.0 🥁 🥁 🥁

> <https://github.com/InsightSoftwareConsortium/ITK/commit/8195abb3e12501ceb4c44b5f79bd9564b7111852>

`IndexRange` is a modern C++ range of iterators. It should ease iterating over a sequence of consecutive N-dimensional indices, as it can be used as a _range-expression_ of a C++11 _range-based for-loop_:

```
for (const Index<Dimension>& index : indexRange)
   // Use the 'index' here...! 

```

The order in which the indices are iterated corresponds to the order in which pixels that are stored in a regular `itk::Image`.

There are two `IndexRange` type aliases:

1. `ZeroBasedIndexRange<Dimension>` has its _begin_ iterator at index zero (that’s [0, 0] in 2-D, or [0, 0, 0] in 3-D). The range is specified by `itk::Size<Dimension>`, which is typically the N-dimensional size of an image.

2. `ImageRegionIndexRange<Dimension>` can begin at any arbitrary index, as it can be specified by an `itk::ImageRegion<Dimension>`. (`itk::ImageRegion<Dimension>`consists of an N-dimensional index and an N-dimensional size.)

The iterators of `IndexRange` are _bidirectional_, as they support both forward iteration (`++it`) and backward iteration (`--it`). When using `ZeroBasedIndexRange`, it appears fastest to iterate backward, from the _end_ to the _begin_ of the range:

```
const ZeroBasedIndexRange<Dimension> range{ imageSize };
const auto begin = range.begin();
auto it = range.end();

while (it != begin)
{
  --it;
  const auto& index = *it;
  // Use the 'index' here...! 
  
}

```

However, I think that in most cases, the range-based for-loop is fast enough 🙂

---

<div class="post-metadata">

### Author: ![dzenanz](https://discourse.itk.org/user_avatar/discourse.itk.org/dzenanz/32/1093_2.png) [@dzenanz](https://discourse.itk.org/u/dzenanz)
#### Post date: [November 12, 2018, 6:30pm UTC](https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412/2 "2018-11-12T18:30:14Z")

</div>

> [@Niels\_Dekker](#):
>
> for (const Index\<Dimension\>& index : indexRange)

Would `for (auto index : indexRange)` work? How about `for (const auto& index : indexRange)`?

---

<div class="post-metadata">

### Author: ![Niels\_Dekker](https://discourse.itk.org/letter_avatar_proxy/v4/letter/n/9d8465/32.png) [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [November 12, 2018, 8:46pm UTC](https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412/3 "2018-11-12T20:46:23Z")

</div>

> [@dzenanz](#):
>
> Would `for (auto index : indexRange)` work? How about `for (const auto& index : indexRange)` ?

Sure!

```
for (auto index : indexRange)
    // 'index' is of type 'itk::Index<Dimension>'

```

And

```
for (const auto& index : indexRange)
    // 'index' is of type 'const itk::Index<Dimension> &'

```

Kind regards, Niels

---

<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: [November 14, 2018, 2:28pm UTC](https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412/4 "2018-11-14T14:28:26Z")

</div>

This looks really great!

Do we have any filters that could converted to use this new iterator?

It would be good to come to some kind of recommendation for best practice for performance and style for this type of loop.

I also feel compelled to give a **strong word of caution** about the ZeroBasedIndexRange this strategy is not suitable for using in **most** ITK filters. Yes, it will work most of the time but it won’t work all of the time. Filters are expected to work with images or regions that don’t have a zero starting index unless they override the `VerifyInputInformation` with a check. Non-zero based images or regions can occur with streaming, or as a result of filters like the `ExtractImageFilter`. These complicated features and situations are not well tested in ITK, but I have encountered and fixed them many times.

---

<div class="post-metadata">

### Author: ![Niels\_Dekker](https://discourse.itk.org/letter_avatar_proxy/v4/letter/n/9d8465/32.png) [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [November 14, 2018, 3:48pm UTC](https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412/5 "2018-11-14T15:48:55Z")

</div>

Actually my first use case was to ease comparing the “old-school” ITK neighborhood iterators with the new `ShapedImageNeighborhoodRange`, when iterating on an image region.

Old-school ITK neighborhood iteration:

```
neighborhoodIterator.GoToBegin();

while (!neighborhoodIterator.IsAtEnd())
{
  for (itk::SizeValueType i = 0; i < numberOfNeigbors; ++i)
  {
    auto neighbor = neighborhoodIterator.GetPixel(i);
    // Process neighbor pixel here... 
  }
  ++neighborhoodIterator;
}

```

And the corresponding iteration when using ShapedImageNeighborhoodRange + IndexRange:

```
for (const auto& index : indexRange)
{
  shapedImageNeighborhoodRange.SetLocation(index);

  for (PixelType neighbor : shapedImageNeighborhoodRange)
  {
    // Process neighbor pixel here... 
  }
}

```

So IndexRange makes it easier to interchange between “old-school” and range-based neighborhood iteration, and it also eases comparing both the performance and the result, for testing purposes.

---

<div class="post-metadata">

### Author: ![matt.mccormick](https://discourse.itk.org/user_avatar/discourse.itk.org/matt.mccormick/32/7_2.png) [@matt.mccormick](https://discourse.itk.org/u/matt.mccormick)
#### Post date: [November 14, 2018, 7:27pm UTC](https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412/6 "2018-11-14T19:27:38Z")

</div>

> [@Niels\_Dekker](#):
>
> `itk::Experimental::IndexRange` template class

This is awesome. 🎆

> [@Niels\_Dekker](#):
>
> ```auto
> for (const auto& index : indexRange)
> {
> shapedImageNeighborhoodRange.SetLocation(index);
> 
> for (PixelType neighbor : shapedImageNeighborhoodRange)
> {
> // Process neighbor pixel here... 
> }
> }
> 
> ```
> 
> So IndexRange makes it easier to interchange between “old-school” and range-based neighborhood iteration, and it also eases comparing both the performance and the result, for testing purposes.

How do you think a class would be designed to works on an `itk::Image`, but does not need to iterate over the neighborhood, i.e. `*it` is the pixel value?

---

<div class="post-metadata">

### Author: ![Niels\_Dekker](https://discourse.itk.org/letter_avatar_proxy/v4/letter/n/9d8465/32.png) [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [November 15, 2018, 9:50am UTC](https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412/7 "2018-11-15T09:50:50Z")

</div>

> [@matt.mccormick](#):
>
> How do you think a class would be designed to works on an `itk::Image` , but does not need to iterate over the neighborhood, i.e. `*it` is the pixel value?

`itk::Experimental::IndexRange` does already support iterating on an `itk::Image` to retrieve and modify its pixel values, for example:

```
for (const auto& index : indexRange)
{
  auto pixelValue = image1.GetPixel(index);
  image2.SetPixel(index, pixelValue);
}

```

Unfortunately `itk::Image::GetPixel` and `itk::Image::SetPixel` may not be superfast, because they have to compute the offset value into the image buffer.

---

<div class="post-metadata">

### Author: ![Niels\_Dekker](https://discourse.itk.org/letter_avatar_proxy/v4/letter/n/9d8465/32.png) [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [November 20, 2018, 8:04pm UTC](https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412/8 "2018-11-20T20:04:25Z")

</div>

> [@matt.mccormick](#):
>
> How do you think a class would be designed to works on an `itk::Image` , but does not need to iterate over the neighborhood, i.e. `*it` is the pixel value?

Still very much _Work In Progress_: This `itk::Experimental::ImageRange` should support range-based iteration on the pixels on an `itk::Image`: [https://github.com/N-Dekker/ITK/tree/ImageRange](https://github.com/N-Dekker/ITK/tree/ImageRange) Please tell me what you think!

Initial commit: [WIP: Added ImageRange for itk::Image iteration. · N-Dekker/ITK@e1dd5ab · GitHub](https://github.com/N-Dekker/ITK/commit/e1dd5ab95bb8c2e4a181c6abd2d090a61249e729)

---

<div class="post-metadata">

### Author: ![matt.mccormick](https://discourse.itk.org/user_avatar/discourse.itk.org/matt.mccormick/32/7_2.png) [@matt.mccormick](https://discourse.itk.org/u/matt.mccormick)
#### Post date: [November 20, 2018, 8:11pm UTC](https://discourse.itk.org/t/new-for-itk-5-0-indexrange-zerobasedindexrange-imageregionindexrange/1412/9 "2018-11-20T20:11:15Z")

</div>

Beautiful @Niels_Dekker!

```auto
   ImageRange<ImageType> range{ *image };

   for (auto&& pixel : range)
   {
     pixel = pixel + 42;
   }

```

`for_each`, `std::inner_product` tested – extremely exciting!!
