[Feature] Add getGridMaxDistance() — True maximum distance from vertex to farthest vertex in gridDisk(k)

[leilton-zildus]

🧭 Problem: The term “Effective radius” is misleading

The H3 documentation and many examples describe the effective radius of a gridDisk(k) as:

However, this underestimates the real coverage when the origin is a vertex of the central cell —
a very common case in ride-matching, geospatial search, and proximity filtering.

For example, at resolution 9:

k	“Effective radius” (center-to-center)	Real max distance (vertex-to-vertex)
0	~200 m	402 m
1	~348 m	724 m
2	~695 m	1,062 m

Users typically expect “up to X meters” to mean the farthest possible point,
not merely to the center of the farthest cell.

---

✅ Solution: Exact maximum distance formula

We derived the exact maximum distance from a vertex of the central hexagon to the farthest vertex in gridDisk(k)
using pure hexagonal geometry:

Let:

• L = average edge length at resolution r (from getHexagonEdgeLengthAvgM(r))

Then, for all resolutions and any integer k ≥ 0:

This formula was derived using the Law of Cosines on an equilateral triangle
with sides (2k + 2)L.

---

🔍 Verified values (Resolution 9, L = 200.786148 m)

k	Formula	Distance
0	2 L	401.57 m
1	√13 L	723.82 m
2	√28 L	1,062.40 m
3	7 L	1,405.50 m

These match real H3 boundary distances, verified via cellToBoundary() and greatCircleDistance().

---

🧩 Proposed API addition (C + bindings)

/**
 * Returns the maximum distance (in meters) from a vertex of the origin cell
 * to the farthest vertex in gridDisk(k).
 *
 * @param resolution H3 resolution (0–15)
 * @param k          Ring distance
 * @return           Maximum distance in meters
 */
double h3_get_grid_max_distance_m(int resolution, int k) {
    if (resolution < 0 || resolution > 15) return -1;
    if (k < 0) return -1;
    double L = getHexagonEdgeLengthAvgM(resolution);
    return sqrt(3.0 * k * k + 6.0 * k + 4.0) * L;
}

🚀 Use cases

• Ride-matching → Display “Searching up to 724 m” instead of “350 m radius”
• Geofencing → Guarantee complete coverage of intended search area
• UX clarity → Provide an honest and transparent range to users

📚 References

• H3 Edge Length Table
• Law of Cosines applied to triangle △APC with
  (PA = (k+2)L,\ AC = (2k+2)L,\ \angle A = 60°)

🙏 Proposal

Please consider adding
h3_get_grid_max_distance_m()
to the core H3 library.

It’s a small but high-impact improvement for real-world geospatial applications.

Thanks!
— Leilton Ribeiro, Alfenas, MG, Brazil