neighborhoodRange{*image, location, offsets};
```
Please have a look: [http://review.source.kitware.com/#/c/23389](http://review.source.kitware.com/#/c/23389)
P.S. The patch does not yet present any other shapes, but @phcerdan already suggested another one, that we are still discussing at [itk::NeighborhoodRange: a new class for efficient modern C++ style iteration](https://discourse.itk.org/t/itk-neighborhoodrange-a-new-class-for-efficient-modern-c-style-iteration/833/55)
---
### Author:  [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [May 18, 2018, 8:08pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/2 "2018-05-18T20:08:51Z")
Thanks @dzenanz for [merging](https://github.com/Kitware/ITK/commit/54033a1752c06fec92206948f03c0024d529de98) the patch, [ENH: Added class to create offsets for a hyperrectangular neighborhood shape](http://review.source.kitware.com/#/c/23389/)!
I think this could pave the way for the [topological connectivity shape class](https://gist.github.com/N-Dekker/0f17c0473b29494faea93244bbb43393), that Pablo and I have been discussing at [itk::NeighborhoodRange: a new class for efficient modern C++ style iteration](https://discourse.itk.org/t/itk-neighborhoodrange-a-new-class-for-efficient-modern-c-style-iteration/833/54)
This class should support generating the offsets for N-connected neighborhoods: 4- and 8-connected neighborhoods in 2-D, 6-, 18-, and 26-connected neighborhoods in 3-D, etc.
@phcerdan Would it be OK to you if I would simply name the shape class _ConnectedImageNeighborhoodShape_, with the initial patch set? I find something like “TopologicalConnectivityImageNeighborhoodShape” a bit too verbose. And I think it’s basically just a connected neighborhood: a neighborhood of pixels that are connected to one specific center pixel. What do you think?
---
### Author:  [@phcerdan](https://discourse.itk.org/u/phcerdan)
#### Post date: [May 18, 2018, 8:15pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/3 "2018-05-18T20:15:21Z")
> [@Niels\_Dekker](#):
>
> ConnectedImageNeighborhoodShape, with the initial patch set? I find something like “TopologicalConnectivityImageNeighborhoodShape” a bit too verbose. And I think it’s basically just a connected neighborhood: a neighborhood of pixels that are connected to one specific center pixel. What do you think?
It sounds ok to me! Thanks Niels.
---
### Author:  [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [May 22, 2018, 5:10pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/4 "2018-05-22T17:10:22Z")
@phcerdan Thanks for your initial review of [itk::Experimental::ConnectedImageNeighborhoodShape](http://review.source.kitware.com/#/c/23452/), while it was still in WIP state (work in progress). I think it’s fully functional now, and correctly implemented. However, I wonder if an extra parameter would be needed, to optionally include the center pixel. What do you think? Would you use it? Or would you always choose to exclude the center pixel anyway?
---
### Author:  [@dzenanz](https://discourse.itk.org/u/dzenanz)
#### Post date: [May 22, 2018, 10:16pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/5 "2018-05-22T22:16:57Z")
I think you mostly want center pixel. The option to exclude it seems fine to me.
---
### Author:  [@phcerdan](https://discourse.itk.org/u/phcerdan)
#### Post date: [May 23, 2018, 12:01am UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/6 "2018-05-23T00:01:27Z")
If the user wants the center pixel, the existing HyperrectangularImageNeighborhoodShape can be used. I wouldn’t add extra complexity to the class.
The purpose of this class, at least in my mind, is to visit neighbors assuming the center pixel is occupied, for example in Label or Binary images.
But of course, if you think it is worth, I can be convinced!
---
### Author:  [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [May 23, 2018, 6:48am UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/7 "2018-05-23T06:48:56Z")
Thanks for your feedback, @dzenanz and @phcerdan
Yes I do believe that it could be useful to (optionally) include the center pixel. The shape would then still be different from the existing `HyperrectangularImageNeighborhoodShape`, at least when `maximumDistance < ImageDimension`. For example, a 4-connected neighborhood is not rectangular. (Or at least, it is not supported by `HyperrectangularImageNeighborhoodShape`.)
For erosion or dilation, I think you would want to include the center pixel.
> [@phcerdan](#):
>
> The purpose of this class, at least in my mind, is to visit neighbors assuming the center pixel is occupied, for example in Label or Binary images.
Pablo, I can certainly imagine that that’s an interesting use case. Still I’m curious, do you have a specific filter of morphological operation in mind?
---
### Author:  [@phcerdan](https://discourse.itk.org/u/phcerdan)
#### Post date: [May 23, 2018, 1:22pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/8 "2018-05-23T13:22:34Z")
> [@Niels\_Dekker](#):
>
> do you have a specific filter of morphological operation in mind?
Good question! I have an incomplete picture in my mind to categorize pixels/voxels based on the occupancy configuration of its nearest neighbors. I see `ConnectedImageNeighborhoodShape` as a way to select the adjacency relationship of the pixel, -4 or 8- in 2D, -6 or 18 or 26- in 3D.
For each adjacency relationship, we can query each spel (i.e. pixel or voxel) for properties like: IsConnected, IsSimple (i.e does the removal of the spel changes the topology of the original object?), isEndPoint, isBranchPoint, IsIsthmus, etc. These properties depend on the adjacency relationship, and the neighborhood occupancy.
And I think you are right @dzenanz , the center pixel is useful if we are talking about adjacency because any pixel is adjacent to itself. Convinced! 😃
---
### Author:  [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [May 24, 2018, 11:33am UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/9 "2018-05-24T11:33:36Z")
Update: Yesterday I added a boolean `includeCenterPixel` parameter to the explicit `ConnectedImageNeighborhoodShape` constructor. To be used as follows (for example):
```
bool includeCenterPixel = true;
std::size_t maximumDistance = 2;
constexpr unsigned int dimension = 3;
ConnectedImageNeighborhoodShape shape{maximumDistance,includeCenterPixel};
std::vector> offsets = GenerateImageNeighborhoodOffsets(shape);
```
Please review: [ENH: Added ConnectedImageNeighborhoodShape, for N-connected neighborhoods](http://review.source.kitware.com/#/c/23452) Kitware Build Robot gave [it](http://review.source.kitware.com/#/c/23452/7) a **+1** already. 😃
---
### Author:  [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [May 31, 2018, 2:11pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/10 "2018-05-31T14:11:38Z")
Very glad to see that [ConnectedImageNeighborhoodShape](http://review.source.kitware.com/#/c/23452/14) now has +1 from Dzenan (@dzenanz), Pablo (@phcerdan), and the Build Robot. 😃 Now I just noticed that a subset of the functionality of `ConnectedImageNeighborhoodShape` is already there, from the existing function `itk::setConnectivity(it, fullyConnected)`:
>
Just for your information, here is how `itk::setConnectivity(it, fullyConnected)` could have been implemented by using `ConnectedImageNeighborhoodShape`:
```
template< typename TIterator >
TIterator *
setConnectivity(TIterator *it, bool fullyConnected = false)
{
using ShapeType =
Experimental::ConnectedImageNeighborhoodShape;
const bool includeCenterPixel = false;
const std::size_t maximumCityblockDistance = fullyConnected ? SIZE_MAX : 1;
const ShapeType shape{ maximumCityblockDistance, includeCenterPixel };
it->ClearActiveList();
for (const auto& offset : Experimental::GenerateImageNeighborhoodOffsets(shape))
{
it->ActivateOffset(offset);
}
return it;
}
```
Fortunately, `ConnectedImageNeighborhoodShape` still has a few more features that are not yet available with `itk::setConnectivity(it, fullyConnected)`:
- It has an option to include the center pixel (`bool includeCenterPixel = true`)
- Its `maximumCityblockDistance` parameter allows more fine-tuning than just `fullyConnected = true` or `false`
- It supports both the original [itk::ShapedNeighborhoodIterator](https://itk.org/Doxygen/html/classitk_1_1ShapedNeighborhoodIterator.html) and the new [itk::Experimental::ShapedImageNeighborhoodRange](https://itk.org/Doxygen/html/classitk_1_1Experimental_1_1ShapedImageNeighborhoodRange.html)
I hope it will still get into ITK 5.0! Please check [http://review.source.kitware.com/#/c/23452](http://review.source.kitware.com/#/c/23452) !
---
### Author:  [@phcerdan](https://discourse.itk.org/u/phcerdan)
#### Post date: [May 31, 2018, 2:38pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/11 "2018-05-31T14:38:47Z")
Good search… It’s pretty good that we have this functionality compatible with range iterators, and as you said, this also allows 18 connected neighbors in 3D, and clear and tweakable set of offsets in any dimension.
---
### Author:  [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [June 2, 2018, 1:12pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/12 "2018-06-02T13:12:10Z")
@phcerdan My latest patch [ENH: Documented + tested order offsets ConnectedImageNeighborhoodShape](http://review.source.kitware.com/#/c/23500/2) was very much inspired by your earlier remarks on the order of the offsets, already on April 14, at [itk::NeighborhoodRange: a new class for efficient modern C++ style iteration](https://discourse.itk.org/t/itk-neighborhoodrange-a-new-class-for-efficient-modern-c-style-iteration/833/11) Now I think I found a proper term to describe the way the offsets are sorted: _colexicographic order_
> **[Lexicographical order | Colexicographic order](https://en.wikipedia.org/wiki/Lexicographical_order#Colexicographic_order)**
>
> The colexicographic or colex order is a variant of the lexicographical order, which is obtained by reading finite sequences from the right to the left instead of reading them from the left to the right. More precisely, while the lexicographical order between two sequences is defined by
The unit test included with the patch compares the offsets based on colexicographic order, by passing _reverse-iterators_ of `itk::Offset` to `std::lexicographical_compare`. See [itkConnectedImageNeighborhoodShapeGTest.cxx](http://review.source.kitware.com/#/c/23500/2/Modules/Core/Common/test/itkConnectedImageNeighborhoodShapeGTest.cxx@125)
Please check: [http://review.source.kitware.com/#/c/23500](http://review.source.kitware.com/#/c/23500)
---
### Author:  [@phcerdan](https://discourse.itk.org/u/phcerdan)
#### Post date: [June 3, 2018, 7:27pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/13 "2018-06-03T19:27:48Z")
Nice! That’s the proper name then. You should propose a [std::colexicographical\_compare](http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare) for c++20 🙂. Cool trick with the reverse iterators.
---
### Author:  [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [June 5, 2018, 9:57pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/14 "2018-06-05T21:57:31Z")
Cool: @dzenanz just merged the patch, which documents and tests that the offsets from `ConnectedImageNeighborhoodShape` are in _colexicographic_ order:
[Merge topic 'docConnectedImageNeighborhoodShape' · InsightSoftwareConsortium/ITK@22d2200 · GitHub](https://github.com/InsightSoftwareConsortium/ITK/commit/22d2200d6ca8b4f58eee63434ab95fd125dd34e8)
😃
> [@phcerdan](#):
>
> You should propose a std::colexicographical\_compare for c++20
Hmm, I’ll think about it. Writing a proposal for the C++ Standard is usually a lot of work! But you _could_ propose a **_ColexicographicCompare_** functor class for ITK, of course! Which could be helpful if we would want to test the order of other generated offsets (from other shapes) as well. There’s an `itk::LexicographicCompare` functor class already, added by @hjmjohnson
>
What do you think?
---
### Author:  [@phcerdan](https://discourse.itk.org/u/phcerdan)
#### Post date: [June 6, 2018, 3:17am UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/15 "2018-06-06T03:17:46Z")
Sounds a good idea Niels, but running short of time lately here! I am thinking maybe it is a good exercise as a first contribution for somebody interested in learning the how-tos of patch submission in ITK.
Something like this will work for TAggregateTypes with reverse iterators, right Niels? A few lines more, a test file, and we will have a new functor class in ITK that will be useful in the short future 🤩
```auto
template< class TAggregateType1, class TAggregateType2 = TAggregateType1 >
class ITK_TEMPLATE_EXPORT ColexicographicCompare
{
public:
bool operator()(const TAggregateType1 &lhs, const TAggregateType2 &rhs) const
{
return std::lexicographical_compare( lhs.rbegin(), lhs.rend(), rhs.rbegin(), rhs.rend() );
}
};
```
---
### Author:  [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [June 6, 2018, 2:31pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/16 "2018-06-06T14:31:53Z")
> [@phcerdan](#):
>
> Something like this will work for TAggregateTypes with reverse iterators, right Niels? A few lines more, a test file, and we will have a new functor class in ITK that will be useful in the short future
Your suggested `ColexicographicCompare` implementation, based on the existing `LexicographicCompare` looks very much like what I had in mind, Pablo! You didn’t read my mind, did you? 😉
However, before copying from `itk::Functor::LexicographicCompare`, maybe it could still be slightly improved… I just submitted a proposed patch: [ENH: Made Functor::LexicographicCompare more generic and easier to use](http://review.source.kitware.com/#/c/23505/1)
And then, would you suggest adding the colexicographic version to the very same header file, [itkLexicographicCompare.h](https://github.com/InsightSoftwareConsortium/ITK/blob/549a19c956bab2b41489816d8bb8d4bd09161583/Modules/Core/Common/include/itkLexicographicCompare.h)? (I guess it will be about 20 extra lines of code.) Or do you think it’s preferable to have a separate header file for the _colex_ functor?
---
### Author:  [@phcerdan](https://discourse.itk.org/u/phcerdan)
#### Post date: [June 6, 2018, 3:16pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/17 "2018-06-06T15:16:05Z")
> [@Niels\_Dekker](#):
>
> You didn’t read my mind, did you?
I read your code! 🤣
> [@Niels\_Dekker](#):
>
> Or do you think it’s preferable to have a separate header file for the colex functor?
I am not sure, we should ask @matt.mccormick and @dzenanz, but I think maybe better to have it on its own file? Or merge both in a new header named: `itkComparisonFunctors`
---
### Author:  [@dzenanz](https://discourse.itk.org/u/dzenanz)
#### Post date: [June 6, 2018, 4:49pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/18 "2018-06-06T16:49:54Z")
My preference is to use existing `itkLexicographicCompare.h` for colex functor.
---
### Author:  [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [June 7, 2018, 3:04pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/19 "2018-06-07T15:04:09Z")
> [@dzenanz](#):
>
> My preference is to use existing itkLexicographicCompare.h for colex functor.
+1
If the colex functor would be added to _itkLexicographicCompare.h_, it might be clearer that it belongs there, together with `LexicographicCompare`, when the colex class name would be spelled with uppercase L: `CoLexicographicCompare`. (The ordering is also sometimes referred to as “CoLex”, with uppercase L.) What do you think?
---
### Author:  [@Niels\_Dekker](https://discourse.itk.org/u/Niels_Dekker)
#### Post date: [July 6, 2018, 6:11pm UTC](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924/20 "2018-07-06T18:11:46Z")
Just submitted, please review: [ENH: Added Functor::CoLexicographicCompare](http://review.source.kitware.com/#/c/23556)
I think such a functor is very useful, to ensure that the sequence of offsets (instances of `itk::Offset`) of a neighborhood shape are ordered in the preferred way. Usually when doing neighborhood based pixel operations, a CoLex ordered sequence of shape offsets offers the best performance.
[Next page](https://discourse.itk.org/t/a-shape-class-for-shapedimageneighborhoodrange-and-shapedneighborhooditerator/924.md?page=2)