Feature: Add cellToChildPos and childPosToCell #719

nrabinowitz · 2022-10-24T19:09:50Z

Adds two new functions:

cellToChildPos gives the position of the child in an ordered list of all the children of the cell's parent at a given resolution. The "ordered list" here is the same order as returned by cellToChildren, which I believe is numerically sorted by index. Essentially, this function allows you to determine the numeric index of the cell among its siblings, given a parent resolution that defines the sibling list.
childPosToCell offers the reverse functionality, returning a child cell given a parent, a child resolution, and a child index.

This pair of functions opens up several new use cases:

Easy iteration through all children of some parent, with no need to allocate memory for cellToChildren. I think we can do this internally in the library using iterators, but this offers an ergonomic API for external consumers (simply iterate for (int i = 0; i < cellToChildrenSize(parent, res); i++) and take childPosToCell(i, parent, res)).
Compact representations for sets of common-ancestor cells, including arrays of small bit-width integers (e.g. uint16 if the parent/child res difference is <= 5) and bit arrays (e.g. 16807 bits / 2101 bytes to indicate yes/no whether each child 5 steps down is included in the set). This is likely more effective than compact if there's no particular likelihood that the cells are contiguous.
Association between data arrays and H3 indexes without the need to store the H3 indexes themselves (e.g. a list of 16807 values corresponding by position to each child 5 steps down from some parent)

Notes

I'm open to suggestions on the name. childPosition might be clearer (but longer), childIndex makes sense but risked confusion with H3 indexes.
I included exhaustive tests for 0-3 resolution steps for all cells up to res 2. Let me know if you think any further tests are needed here.

coveralls · 2022-10-24T19:12:58Z

Coverage increased (+0.04%) to 98.64% when pulling 1172251 on nrabinowitz:child-pos-functions into 139e5bf on uber:master.

nrabinowitz · 2022-10-25T18:20:30Z

src/h3lib/lib/h3Index.c

+        // different from hexagons
+        for (int res = childRes; res > parentRes; res--) {
+            // It shouldn't be possible to get an error here, so we don't check
+            H3_EXPORT(cellToParent(child, res - 1, &parent));


This is probably a good spot for NEVER once #720 lands

isaacbrodsky

I understand how these functions are used so they look helpful.

Please add website API documentation for these functions.

isaacbrodsky · 2022-10-26T18:34:32Z

src/apps/testapps/testCellToChildPos.c

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2017-2021 Uber Technologies, Inc.


Suggested change

* Copyright 2017-2021 Uber Technologies, Inc.

* Copyright 2022 Uber Technologies, Inc.

Suggested change

* Copyright 2017-2021 Uber Technologies, Inc.

* Copyright 2017-2022 Uber Technologies, Inc.

isaacbrodsky · 2022-10-26T18:40:39Z

src/h3lib/lib/h3Index.c

+        }
+    }
+
+    return E_SUCCESS;


What happens if the passed in childPos is abnormally high or low? E.g. if idx > 0 here or if childPos < 0?

Another good question. You'd get an invalid digit for output; I'm not sure there would be other issues. Probably worth validating childPos and returning an error for bad cases.

isaacbrodsky · 2022-10-26T18:41:17Z

src/h3lib/lib/h3Index.c

+            H3_EXPORT(cellToParent(child, res - 1, &parent));
+            parentIsPentagon = H3_EXPORT(isPentagon)(parent);
+            int rawDigit = H3_GET_INDEX_DIGIT(child, res);
+            int digit =


What happens for invalid indexes into the deleted K subsequence of a pentagon, or indexes with INVALID_DIGIT (7)?

Good questions:

Invalid indexes into the K subsequence will be treated as 0 per the logic on the next line

INVALID_DIGIT will result in an offset that's too high, and the resulting number might be greater than the number of max children

This might be okay, on the principle of GIGO, but I could imagine attacks on systems using H3 that would use poor output here to trigger random memory access. Possible failsafes:

We could validate the digit and return an error

We could clamp output to the max possible child index for the given parent

Validating the digits is probably worthwhile. If we do that we don't need to clamp output, but we could (after #720) add an assertion at the end of the function like

if (NEVER(out > cellToChildrenSize(parent, childRes))) { return E_FAILED; }

isaacbrodsky · 2022-10-26T18:42:20Z

src/h3lib/lib/h3Index.c

+ * children at the specified resolution */
+H3Error H3_EXPORT(childPosToCell)(int64_t childPos, H3Index parent,
+                                  int childRes, H3Index *child) {
+    if (childRes < 0 || childRes > MAX_H3_RES) {


This would also be a good place for testcase from #720 to ensure boundary conditions work as expected.

isaacbrodsky · 2022-11-20T20:24:33Z

website/docs/api/hierarchy.mdx

+<TabItem value="c">
+
+```c
+H3Index cellToChildPos(H3Index child, int parentRes, int64_t *out);


All the other bindings say "cell" - maybe they should also have the parameter named "child"?

This is all prospective, of course, as the binding owners may have other ideas, but I can update all to child for now

isaacbrodsky · 2022-11-20T20:26:05Z

src/h3lib/lib/h3Index.c

+    int64_t maxChildCount;
+    H3Error sizeError =
+        H3_EXPORT(cellToChildrenSize)(parent, childRes, &maxChildCount);
+    if (NEVER(sizeError)) {


In the future, we should require fuzzers be added too to try to exercise these. I am fine with merging this without the fuzzer and then adding it in a follow up PR.

nrabinowitz requested review from dfellis, ajfriend and isaacbrodsky October 24, 2022 19:09

nrabinowitz commented Oct 25, 2022

View reviewed changes

isaacbrodsky reviewed Oct 26, 2022

View reviewed changes

nrabinowitz mentioned this pull request Oct 28, 2022

Sample indexes from the index structure rather than sphere isaacbrodsky/h3measurements#6

Open

Nick Rabinowitz added 9 commits November 18, 2022 15:47

Implement cellToChildPos and childPosToCell

2e45840

Add exhaustive tests

65697d5

Add tests for res errors

aac88a0

Update CHANGELOG

2820258

Missing free

828c0ac

format

2d8711b

Add additional guards for invalid input, with tests

775baba

Add NEVER macros to check for unexpected errors

1c15902

Update website docs with new functions

ba5ed53

nrabinowitz force-pushed the child-pos-functions branch from 8b48a58 to ba5ed53 Compare November 19, 2022 01:07

Typo fix

5e04abe

dfellis approved these changes Nov 19, 2022

View reviewed changes

isaacbrodsky approved these changes Nov 20, 2022

View reviewed changes

Update proposed binding arguments to child

1172251

nrabinowitz merged commit e84cfa0 into uber:master Nov 28, 2022

nrabinowitz deleted the child-pos-functions branch November 28, 2022 22:18

isaacbrodsky mentioned this pull request Nov 29, 2022

add fuzzer for cellToChildPos #732

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature: Add cellToChildPos and childPosToCell #719

Feature: Add cellToChildPos and childPosToCell #719

nrabinowitz commented Oct 24, 2022 •

edited

Loading

coveralls commented Oct 24, 2022 •

edited

Loading

nrabinowitz Oct 25, 2022

isaacbrodsky left a comment

isaacbrodsky Oct 26, 2022

dfellis Oct 26, 2022

isaacbrodsky Oct 26, 2022

nrabinowitz Oct 26, 2022

isaacbrodsky Oct 26, 2022

nrabinowitz Oct 26, 2022

isaacbrodsky Oct 26, 2022

isaacbrodsky Nov 20, 2022

nrabinowitz Nov 28, 2022

isaacbrodsky Nov 20, 2022

		@@ -0,0 +1,95 @@
		/*
		* Copyright 2017-2021 Uber Technologies, Inc.

	* Copyright 2017-2021 Uber Technologies, Inc.
	* Copyright 2022 Uber Technologies, Inc.

	* Copyright 2017-2021 Uber Technologies, Inc.
	* Copyright 2017-2022 Uber Technologies, Inc.

Feature: Add cellToChildPos and childPosToCell #719

Feature: Add cellToChildPos and childPosToCell #719

Conversation

nrabinowitz commented Oct 24, 2022 • edited Loading

coveralls commented Oct 24, 2022 • edited Loading

Choose a reason for hiding this comment

isaacbrodsky left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nrabinowitz commented Oct 24, 2022 •

edited

Loading

coveralls commented Oct 24, 2022 •

edited

Loading