Changelog

All notable changes to the qdgc and qdgc_postgis extensions.

Encoding output is stable within a major version. Any change to a code this library produces is a major bump, flagged loudly — see CLAUDE.md in the repository root.

0.1.0 — unreleased

First release.

qdgc (pure SQL, no dependencies, trusted)

  • Encoding: qdgc_encode, qdgc_latlng_to_cell, qdgc_degree_prefix, qdgc_normalize_fraction.
  • Decoding: qdgc_cell_to_bounds, qdgc_cell_to_lonlat, qdgc_cell_to_latlng, qdgc_get_level, qdgc_is_valid_cell, qdgc_code_pattern.
  • Hierarchy: qdgc_cell_to_parent, qdgc_cell_to_children.
  • Metrics: qdgc_level_degrees, qdgc_get_num_cells, qdgc_average_cell_area, qdgc_version.
  • Bounding-box fills: qdgc_bbox_to_cells, qdgc_bbox_cell_count, qdgc_wrap_lon, qdgc_index_range. Antimeridian-crossing boxes are supported by passing min_lon > max_lon.

qdgc_postgis (requires PostGIS)

  • Geometry and geography bindings: qdgc_latlng_to_cell(geometry|geography), qdgc_cell_to_geometry, qdgc_cell_to_geography, qdgc_cell_to_boundary_geometry, qdgc_cell_to_boundary_geography, qdgc_cell_area_km2.
  • Area fills: qdgc_polygon_to_cells with intersects, centroid and contains predicates, implemented as a pruning quadtree descent; and qdgc_estimate_cell_count as a guard before a large fill.

Compatibility

Encoding, decoding, hierarchy and area fills are bit-for-bit identical to the qdgc-py reference implementation, enforced by a fixture generated from it — 22 053 encode vectors and 6 581 decode cells, weighted towards exact quadrant midpoints, signed zeros, the poles, the antimeridian, and the legacy convention that exactly ±1.0 is not reduced to a fraction.

Cell-count estimates differ slightly by design: this extension measures polygon area on the WGS84 spheroid, while qdgc-py uses an equirectangular approximation. Both are guards, and both are capped by the exact envelope count.

Areas are measured with geography, replacing the earlier scripts' hardcoded ST_Transform(geom, 102022) (ESRI Africa Albers), which was applied to every region regardless of location and is absent from a stock PostGIS spatial_ref_sys.