Encode "extra" information in unused digits of H3 indexes

[isaacbrodsky]

No description provided.

[ajfriend]

Do we need a separate function for unused digits? I'd be happy with general setDigit and getDigit functions, and leave the used/unused logic up to the user.

And we'd also probably want setResolution and setBaseCell functions, right? Or is the use case you're thinking of here specifically around "extra" information in the unused bits?

[isaacbrodsky]

Do we need a separate function for unused digits? I'd be happy with general setDigit and getDigit functions, and leave the used/unused logic up to the user.

I think it is helpful to have specific functions for this. setDigit doesn't make much sense to modify a standard index, because if you're doing that you are already in the details of H3 so much that modifying the index is the simplest part. This supports users that want to take advantage of the additional bits without getting into details of how precisely that works.

Another value of separate functions here is that they can guide the user how to use the "extra" information. It surfaces that this is something that can actually be done with the indexes because it's a top-level API, it guides the user what the range of valid values to encode are (not obvious without computing the mask), and single-function-call encoding of that data (important for e.g. SQL where multiple H3 API calls is tricky.)

And we'd also probably want setResolution and setBaseCell functions, right? Or is the use case you're thinking of here specifically around "extra" information in the unused bits?

I am thinking specifically of the "extra" information. I don't think setBaseCell makes sense as a function because again, if you need to set the base cell on an index, actually modifying the integer seems like the simplest part of whatever you're doing, so the library helping you do it isn't that useful.

[ajfriend]

Makes sense for this to focus just on the unused bits. I'm just wondering, though, have we seen many use cases for this in the past? Or what use cases do you have in mind?

[isaacbrodsky]

Makes sense for this to focus just on the unused bits. I'm just wondering, though, have we seen many use cases for this in the past? Or what use cases do you have in mind?

I've seen use cases discussed in the context of entity (point of interest) addressing. I am not sure too many implementations of this exist in the wild, I imagine part of that is because it is trickier for an application to understand how to manipulate the H3 indexes. The other concern is the stability of assigned IDs.

[isaacbrodsky]

Another thing I would consider adding here is a "normalize index" function, that takes an index and ORs it with the expected 7 indexing digits, so that doesn't need chained function calls to get back to the spatial (no additional encoded data) version of the H3 index.

[coveralls]

coverage: 98.937% (+0.004%) from 98.933%
when pulling 3864027 on isaacbrodsky:unused-digits
into 745dfdb on uber:master.

[ajfriend]

We discussed offline a few weeks ago and I think we decided that we wanted to avoid having functions that encourage or guide users towards creating invalid cells, because we would then need to keep track of which functions work on "invalid" cells vs "valid" cells only, which could get confusing.

@isaacbrodsky, can we close this?