uber / uber/h3

Better depiction of bits in bit layout. (Also place all api names on left side panel, like java documentation to make it easier/quicker to find them)

Open
#665 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C
Stars
6.5k
Forks
627
Avg merge
3d 21h
Merged PRs (30d)
6

Description

https://h3geo.org/docs/core-library/h3Indexing/

Problem with "Bit layout of H3Index" table is the non-usage of 1 block per bit.

Instead the entire field is one big block. The colors chosen are also very vague, very hard to see where a block begins and ends.

For example I did not notice initially that digit 10 is actually 1 bits on the bottom row and 2 bits on the row above it.

One cause of this is the usage of hexadecimal and the x in front of it, hexadecimal adds very little to this and confuses more than is worth it, simply decimal usage would have made the table more compact. Now because of 3 letters per box, instead of just 1 or 2, it's unnecessary wide and needs scrolling on a 1600x900 monitor.

Recommendation is to switch to decimal, and use 1 box per bit, and use a legend and letters to depict the bits more clearly.
Using both is best. One layout to clearly surround the fields and put the words into them, but also one where the bits are crystal clear placed. I would even go so far as to put a row of offset numbers below each row to make it more practical usefull to quickly find the correct offset, without having to do strange hexadecimal calculations.

In case one wants to only store on depiction, adding boxes around the bits that belong together would be a very recommendation. One big box with black thick lines, and one thin little gray box per letter/bit so that it can clearly be seen that it's one bit.

Better or extra depiction of bit positions:

LEGEND:
. = Reserved
M = Mode
MD = Mode Dependent
R = Resolution
B = Base Cell
DX = D=Digit X=Number

64 BIT DATA FIELD:

        63  62  61  60  59  58  57  56  55  54  53  52  51  50  49  48
0063    .   M   M   M   M   MD  MD  MD  R   R   R   R   B   B   B   B    0048

	47  46  45  44  43  42  41  40  39  38  37  36  35  34  33  32
0047    B   B   B   D1  D1  D1  D2  D2  D2  D3  D3  D3  D4  D4  D4  D5   0032

	31  30  29  28  27  26  25  24  23  22  21  20  19  18  17  16
0031    D5  D5  D6  D6  D6  D7  D7  D7  D8  D8  D8  D9  D9  D9  D10 D10  0016

        15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
0015    D10 D11 D11 D12 D12 D12 D13 D13 D13 D14 D14 D14 D14 D15 D15 D15  0000

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the H3 Indexing page at https://h3geo.org/docs/core-library/h3Indexing/ and inspect the current “Bit layout of H3Index” table and API navigation. Done means the bit fields, individual bits, legend, and offsets are clearly visible without confusing hexadecimal labels or unnecessary scrolling, with API names easier to find in a left-side panel.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.