Order of returned children

[Sdeimen]

Hi everybody,

I was looking into the order I get back from the h3_to_children function. I only needed the center one and used the h3_to_center_child, but I was wondering if there is general order in which the children are returned. Like for example the first returned is always the top one, the second the one clockwise next to it (and if you go just one resolution down, the seventh always being the center) ?

Thanks!
Sebastian

[nrabinowitz]

There is a deterministic order to the returned cells in h3_to_children, and you can rely on it to be stable, but it's not the order you describe. The children are returned in "digit" order, which is to say child 0, child 1, child 2, and so on - these are the digits set in the hierarchical index (see the indexing docs for more info). Child 0 is the center child, but beyond that you can't make assumptions about either the cardinal direction or even the grid direction of a numbered child.

• Numbered children are not necessarily adjacent. As shown in the image below, the numbering is based on IJK axes, and doesn't go in clockwise or counterclockwise order.

• The orientation of the axes depends on the icosahedron face on which the grid is projected. So in different parts of the world, the axes will align differently with cardinal NESW axes.
• A child of a given cell may be on a different icosahedron face from its parent. So cells are not guaranteed to be in the same grid orientation as their parents or siblings - the order of their own children may be rotated.

So there's a lot of complexity around the indexing numbers that makes them too awkward for spatial reasoning. But the h3_to_children function does give you a stable, easily understandable index-based order, which could allow you to e.g. pick out all of the grandchildren of a cell with 0 index digits, which would be evenly spaced within the ancestor.

[nrabinowitz]

...And I didn't even mention pentagons, which throw another wrench in here when you need to deal with them - they work in the same manner as above, but skip children with the 1 digit.

[Sdeimen]

Thank you so much @nrabinowitz for your explanation!