feat: add pure-Go local IJ coordinates & grid metrics to x/h3go

Add CellToLocalIJ/LocalIJToCell, GridDistance, GridPath (and Cell method
forms) plus the CoordIJ type, implementing the local IJK/IJ coordinate
machinery, cube-coordinate line interpolation, and the pentagon rotation
tables. Verified against the cgo reference over the shared corpus with full
in-package coverage.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: justinhwang

x/h3go/faceijk.go

@@ -227,6 +227,49 @@ func (c coordIJK) rotate60cw() coordIJK {
 	return out
 }
 
+// sub returns the component-wise difference c - b.
+func (c coordIJK) sub(b coordIJK) coordIJK {
+	return coordIJK{i: c.i - b.i, j: c.j - b.j, k: c.k - b.k}
+}
+
+// distance returns the grid distance between two IJK coordinates: the largest
+// component of their normalized difference (normalization leaves all components
+// non-negative).
+func (c coordIJK) distance(b coordIJK) int {
+	diff := c.sub(b)
+	diff.normalize()
+
+	return max(diff.i, diff.j, diff.k)
+}
+
+// unitToDigit maps an IJK coordinate to its digit if, once normalized, it is the
+// center or one of the six unit neighbors, returning invalidDigit otherwise.
+func (c coordIJK) unitToDigit() int {
+	c.normalize()
+
+	if c.i < 0 || c.i > 1 || c.j < 0 || c.j > 1 || c.k < 0 || c.k > 1 {
+		return invalidDigit
+	}
+
+	return unitIjkToDigitLUT[c.i][c.j][c.k]
+}
+
+// toCube converts an IJK coordinate in place to cube coordinates, suitable for
+// linear interpolation along a grid line.
+func (c *coordIJK) toCube() {
+	c.i = -c.i + c.k
+	c.j = c.j - c.k
+	c.k = -c.i - c.j
+}
+
+// fromCube converts cube coordinates in place back to a normalized IJK
+// coordinate, the inverse of toCube.
+func (c *coordIJK) fromCube() {
+	c.i = -c.i
+	c.k = 0
+	c.normalize()
+}
+
 // downAp3 transforms an IJK coordinate to the next finer resolution on the
 // Class II aperture-3 substrate grid (counterclockwise), then re-normalizes.
 func (c *coordIJK) downAp3() {
@@ -528,6 +571,27 @@ func (c Cell) rotatePent60ccw() Cell {
 	return c
 }
 
+// rotatePent60cw rotates c 60° clockwise about a pentagon base cell center,
+// skipping the deleted k-axis subsequence as the leading digit is first
+// encountered so the index stays canonical.
+func (c Cell) rotatePent60cw() Cell {
+	foundFirstNonZero := false
+
+	for r := 1; r <= c.Resolution(); r++ {
+		c = c.setIndexDigit(r, rotate60cw(c.indexDigit(r)))
+
+		if !foundFirstNonZero && c.indexDigit(r) != centerDigit {
+			foundFirstNonZero = true
+
+			if c.leadingNonZeroDigit() == kAxesDigit {
+				c = c.rotate60cw()
+			}
+		}
+	}
+
+	return c
+}
+
 // --- FaceIJK to H3 index ---
 
 // toH3 encodes a face-centered IJK coordinate at the given resolution into an H3

x/h3go/h3go.go

@@ -134,6 +134,7 @@ const (
 	ikAxesDigit  = 5
 	ijAxesDigit  = 6
 	invalidDigit = 7
+	numDigits    = 7
 
 	// H3 index bit-layout offsets and masks, shared with the cgo h3 package.
 	cellMode         = h3core.CellMode
@@ -892,3 +893,68 @@ var baseCellNeighbor60CCWRots = [numBaseCells][7]int{
 	{0, 5, 0, 0, 5, 5, 0},  // base cell 120
 	{0, 0, 1, 0, 1, 5, 1},  // base cell 121
 }
+
+// pentagonRotations maps the base-cell direction (or leading digit) to the
+// number of 60° clockwise index rotations needed when unfolding a pentagon,
+// indexed by [origin leading digit][direction]. A -1 marks an invalid k-axis
+// combination.
+var pentagonRotations = [7][7]int{
+	{0, -1, 0, 0, 0, 0, 0},
+	{-1, -1, -1, -1, -1, -1, -1},
+	{0, -1, 0, 0, 0, 1, 0},
+	{0, -1, 0, 0, 1, 1, 0},
+	{0, -1, 0, 5, 0, 0, 0},
+	{0, -1, 5, 5, 0, 0, 0},
+	{0, -1, 0, 0, 0, 0, 0},
+}
+
+// pentagonRotationsReverse reverses the rotation pentagonRotations introduces
+// when the origin is on a pentagon, indexed by [leading digit][direction].
+var pentagonRotationsReverse = [7][7]int{
+	{0, 0, 0, 0, 0, 0, 0},
+	{-1, -1, -1, -1, -1, -1, -1},
+	{0, 1, 0, 0, 0, 0, 0},
+	{0, 1, 0, 0, 0, 1, 0},
+	{0, 5, 0, 0, 0, 0, 0},
+	{0, 5, 0, 5, 0, 0, 0},
+	{0, 0, 0, 0, 0, 0, 0},
+}
+
+// pentagonRotationsReverseNonpolar reverses the pentagon rotation when the index
+// is on a non-polar pentagon and the origin is not, indexed by
+// [reverse direction][leading digit].
+var pentagonRotationsReverseNonpolar = [7][7]int{
+	{0, 0, 0, 0, 0, 0, 0},
+	{-1, -1, -1, -1, -1, -1, -1},
+	{0, 1, 0, 0, 0, 0, 0},
+	{0, 1, 0, 0, 0, 1, 0},
+	{0, 5, 0, 0, 0, 0, 0},
+	{0, 1, 0, 5, 1, 1, 0},
+	{0, 0, 0, 0, 0, 0, 0},
+}
+
+// pentagonRotationsReversePolar reverses the pentagon rotation when the index is
+// on a polar pentagon and the origin is not, indexed by
+// [reverse direction][leading digit].
+var pentagonRotationsReversePolar = [7][7]int{
+	{0, 0, 0, 0, 0, 0, 0},
+	{-1, -1, -1, -1, -1, -1, -1},
+	{0, 1, 1, 1, 1, 1, 1},
+	{0, 1, 0, 0, 0, 1, 0},
+	{0, 1, 0, 0, 1, 1, 1},
+	{0, 1, 0, 5, 1, 1, 0},
+	{0, 1, 1, 0, 1, 1, 1},
+}
+
+// failedDirections marks the direction pairs that cannot be unfolded across a
+// pentagon (any unfolding across more than one icosahedron face), indexed by
+// [origin direction][index direction].
+var failedDirections = [7][7]bool{
+	{false, false, false, false, false, false, false},
+	{false, false, false, false, false, false, false},
+	{false, false, false, false, true, true, false},
+	{false, false, false, false, true, false, true},
+	{false, false, true, true, false, false, false},
+	{false, false, true, false, false, false, true},
+	{false, false, false, true, false, true, false},
+}