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)
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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