How to produce Z7 hex64 indices?

[jerstlouis]

I've tried:

output_cell_label_type OUTPUT_ADDRESS_TYPE
output_address_type HIERNDX
output_hier_ndx_system Z7
output_hier_ndx_form int64

But that seems to produce the same result as output_hier_ndx_form digit_string.

In the IGEO7 paper, the description of the 64-bit integer Z7 format is ambiguous, with no mention of endianness or of Least / Most Significant Bits:

The first four bits of the integer indicate the base cell number (0 to 11), and the remaining 60 bits encode the digits for each resolution, using 3 bits per resolution.

Would the following bit organization (from Google AI) be correct in implying big-endian order, meaning that the padding 7/f s are the LSBs? So that 0234605201064053664 would be 0x2730A811A0AF69FF?

The 64-bit integer index for the DGGRID Z7 system is organized in big-endian bit order, from most significant bit (MSB) to least significant bit (LSB). The index is a hierarchy-based identifier composed of two main parts:
Base Cell ID: The first four bits (bits 63 through 60) identify one of the 12 base cells (0 to 11) of the initial icosahedral division of the globe.
Hierarchical Digits: The remaining 60 bits (bits 59 through 0) encode the sub-cell indices, with 3 bits per level of refinement (aperture 7). Each 3-bit digit specifies which of the seven child cells to navigate to at the next resolution level. A value of 7 for a refinement digit is used to signify that the cell's resolution is less than the maximum Z7 resolution.

Structure of the 64-bit Z7 index

Bit Range	Value	Purpose
63–60	0–11	Base cell number from the icosahedron.
59–57	0–6	Refinement digit for resolution 1.
56–54	0–6	Refinement digit for resolution 2.
...	...	...
2–0	0–6	Refinement digit for resolution 20.

Thanks!

cc. @allixender @tik65536 @sahrk @fmigneault

[sahrk]

@jerstlouis the lower case int64 parameter value was not being correctly handled. It has been fixed.

[jerstlouis]

Thank you very much for the fix @sahrk!

Also confirming that the above description was correct, although the example I provided was wrong due to a bug in my code that I've now fixed. I've corrected the example: 0234605201064053664 is 0x2730A811A0AF69FF.

I could not validate that particular one due to difficulties generating Level 17 grids (#93), but I validated the Z7 64-bit integers with level 10 zones. (EDIT: Now validated with the clipper_scale_factor fix)

[fmigneault]

@jerstlouis
Just to be extra sure about how everything ties together. The int64 form with this fix must be used for IGEO7 / ISEA7H+Z7? When exposing this value to the API, should the full int64 value or the hex representation be used in the path endpoints?

[jerstlouis]

@fmigneault In OGC API - DGGS, the text representation is used in most places. In the case of IGEO7 / ISEA7H_Z7, the text representation should be the digit_string of DGGRID (e.g., 0234605201064053664) , as it is the more human-friendly / intuitive, database-friendly, and generally shorter than the hexadecimal string of the int64 up to level 15 or so (since it's padded at the right with ffff...).

The only place that the int64 is used in the API is for the 64-bit zone list encoding to respond to zone queries (.../dggs/{dggrsId}/zones) requested with Accept: application/x-binary, and in some of the DGGS-optimized profiles of raster encodings where IDs are explicitly listed instead of being implied from the deterministic sub-zone order, and either the 64-bit integer or textual IDs are allowed, like zarr2-dggs-zoneids, netcdf4-dggs-zoneids, and covjson-dggs-zoneids (in those cases they should be actual integers to distinguish them, not stringified hexadecimal versions). Also as one option recommended for features IDs of GeoJSON zone lists and GeoJSON zone information (again should be an actual 64-bit integer number rather than a stringified hexadecimal representation), as an alternative to sequences of integer starting at 1 or textual IDs (digit_string).

The one other place it could also be useful is for sorting sub-zone establishing the deterministic sub-zone order, although in our implementation of ISEA7H_Z7 we still still use the scanline-based sub-zone ordering that facilitate convolution kernels. A different sub-zone order would mean yet another DGGRS like ISEA7H_Z7_I64SZ or something (alpha numeric sorting based on the digit_string instead would be yet another option, e.g., ISEA7H_Z7_ANSZ). Possibly there's yet another option for Z7 based on the space-filling Z-order curve?