@truelies/osm-dybuf 0.4.1 → 0.4.3

package/README.md

@@ -28,7 +28,7 @@ Current frontend-facing schema notes:
 - Breaking change in `0.4.x`: `GridFeature.featureId` is numeric. Consumers should map it with `ID_TO_FEATURE_KIND[String(featureId)]` or `unpackFeatureId(featureId)` when string/debug output is needed.
 - `road_express` covers motorway corridors plus `trunk` ways tagged with `motorroad=yes` (for example many Taiwan expressway mainlines).
 - `water_wetland` separates marsh / bog / fen / wetland polygons from deeper open water.
-- Current project max level is `13`; newer exports no longer emit `lv14~16`.
+- Geometry payload exports currently stop at `lv13`, but Gridex/index helpers remain valid through `lv16` for higher-detail indexing metadata.
 
 ## Usage
 
@@ -88,7 +88,18 @@ Feature ID usage notes:
 `grid_index.mjs` exposes Gridex helpers (integers, pole triangles) aligned with the exporter:
 
 ```ts
-import { GridUnit, Gridex, INT_COORD_SCALE } from "@truelies/osm-dybuf/grid_index";
+import {
+  GridUnit,
+  Gridex,
+  INT_COORD_SCALE,
+  GRID16_LEVEL,
+  GRID16_LON_MAG_BITS,
+  GRID16_LAT_MAG_BITS,
+  grid16CodesFromLonLat,
+  buildGrid16LonLatRangeForLevelCell,
+  encodeSignedGridIndex,
+  decodeSignedGridIndex,
+} from "@truelies/osm-dybuf/grid_index";
 
 const unit = new GridUnit(8); // level 8
 const cell = new Gridex(213, 161);
@@ -97,14 +108,35 @@ const [minLon, minLat, maxLon, maxLat] = unit.boundsOfGrid(cell);
 // parent/child conversion (same rules as Python GridUnit)
 const children = unit.toLowerLevelGridexes(cell);   // level 9, 4 cells
 const parent = new GridUnit(9).toUpperLevelGridex(children[0]); // back to level 8
+
+// canonical lv16 codes for Firestore / Redis
+const codes = grid16CodesFromLonLat(121.56, 25.03);
+console.log(codes.grid16LonCode, codes.grid16LatCode);
+
+// query a lv15 cell by expanding it into a lv16 numeric range
+const range = buildGrid16LonLatRangeForLevelCell(15, -3, 4);
+console.log(range.lon.from, range.lon.to, range.lat.from, range.lat.to);
+
+// signed code roundtrip
+const lonCode = encodeSignedGridIndex(-123, GRID16_LON_MAG_BITS);
+console.log(decodeSignedGridIndex(lonCode, GRID16_LON_MAG_BITS)); // -123
 ```
 
 - `toLowerLevelGridexes(gridex)`:
   - returns 4 child cells at `level + 1`
-  - throws when current unit is already max level (`13`)
+  - throws when current unit is already max level (`16`)
 - `toUpperLevelGridex(gridex)`:
   - returns the parent cell at `level - 1`
   - throws when current unit is level `0`
+- `grid16CodesFromLonLat(lon, lat)`:
+  - converts GPS directly to canonical `lv16` codes
+  - returns `{ grid16LonCode, grid16LatCode, londex16, latdex16 }`
+- `buildGrid16LonLatRangeForLevelCell(level, londex, latdex)`:
+  - converts any `lv <= 16` cell into the corresponding `lv16` prefix range
+  - intended for Firestore numeric range query / Redis derived bucket lookup
+- `encodeSignedGridIndex(index, magnitudeBits)` / `decodeSignedGridIndex(code, magnitudeBits)`:
+  - encodes grid index as `sign bit + (abs(index) - 1)`
+  - for `lv16`, use `GRID16_LON_MAG_BITS = 19` and `GRID16_LAT_MAG_BITS = 18`
 
 ## Local Development
 
@@ -117,7 +149,10 @@ npm test         # runs unit tests (node:test)
 Unit test example (`tests/grid_index.test.mjs`) covers:
 - `gridexesAt` near axis (no zero index cell)
 - `toLowerLevelGridexes` and `toUpperLevelGridex` roundtrip
-- level boundary errors (`lv0` has no upper level, `lv13` has no lower level)
+- level boundary errors (`lv0` has no upper level, `lv16` has no lower level)
+- canonical signed grid index encode/decode roundtrip
+- GPS -> `lv16` code conversion
+- `lv15` cell -> `lv16` range expansion correctness
 
 - `npm pack`: build a tarball so other repos can install via `npm install ./path/to/osm-dybuf-*.tgz`
 - `npm link`: link the package locally (`npm link` here, then `npm link @truelies/osm-dybuf` in the consumer repo)
@@ -139,4 +174,4 @@ Unit test example (`tests/grid_index.test.mjs`) covers:
 - `region_numeric_codes.json`: latest region ID table (generated via `scripts/dump_region_codes.py`)
 - `inspect_dybuf.mjs`: CLI tool that uses the package locally
 
-When schema IDs or DyBuf layouts change in the exporter, remember to bump the version here and re-publish/install so frontends and tools stay in sync. Version `0.4.1` aligns the package with the current `lv0~13` export range, the current frontend feature set (`water_wetland`, `building`, derived `label_*`, no exported `place_label`), and the numeric `featureId` parser contract.
+When schema IDs or DyBuf layouts change in the exporter, remember to bump the version here and re-publish/install so frontends and tools stay in sync. Version `0.4.3` aligns the package with the current `lv0~13` export range, the current frontend feature set (`water_wetland`, `building`, derived `label_*`, no exported `place_label`), the numeric `featureId` parser contract, and the new `lv16` canonical grid code helpers for Firestore / Redis indexing.

package/grid_index.d.ts

@@ -1,6 +1,10 @@
 export declare const INT_COORD_SCALE: number;
 export declare const GRID_FINE_RES: number;
 export declare const GRID_LV0_UNIT: number;
+export declare const MAX_LEVEL: number;
+export declare const GRID16_LEVEL: number;
+export declare const GRID16_LON_MAG_BITS: number;
+export declare const GRID16_LAT_MAG_BITS: number;
 export declare class Gridex {
   readonly londex: number;
   readonly latdex: number;
@@ -47,3 +51,38 @@ export declare class GridUnit {
     maxLatdex: number;
   };
 }
+export declare function gridexAtLonLat(level: number, longitude: number, latitude: number): GridexAtLv;
+export declare function gridexStringAtLonLat(level: number, longitude: number, latitude: number): string;
+export declare function encodeSignedGridIndex(index: number, magnitudeBits: number): number;
+export declare function decodeSignedGridIndex(code: number, magnitudeBits: number): number;
+export declare function grid16CodesFromLonLat(
+  longitude: number,
+  latitude: number
+): {
+  grid16LonCode: number;
+  grid16LatCode: number;
+  londex16: number;
+  latdex16: number;
+};
+export declare function buildGrid16RangeForLevelIndex(
+  level: number,
+  index: number,
+  magnitudeBits: number
+): {
+  from: number;
+  to: number;
+};
+export declare function buildGrid16LonLatRangeForLevelCell(
+  level: number,
+  londex: number,
+  latdex: number
+): {
+  lon: {
+    from: number;
+    to: number;
+  };
+  lat: {
+    from: number;
+    to: number;
+  };
+};

package/grid_index.mjs

@@ -6,11 +6,14 @@ export const GRID_LV0_UNIT = 30 * INT_COORD_SCALE;
 const GRID_LV0_UNIT_FINE = GRID_LV0_UNIT * GRID_FINE_RES;
 const GRID_LV0_LONDEX = 6;
 const GRID_LV0_LATDEX = 3;
-const MAX_LEVEL = 13;
+export const MAX_LEVEL = 16;
 const MAX_LONGITUDE_FINE = 180 * INT_COORD_SCALE * GRID_FINE_RES;
 const MIN_LONGITUDE_FINE = -MAX_LONGITUDE_FINE;
 const MAX_LATITUDE_FINE = 90 * INT_COORD_SCALE * GRID_FINE_RES;
 const MIN_LATITUDE_FINE = -MAX_LATITUDE_FINE;
+export const GRID16_LEVEL = 16;
+export const GRID16_LON_MAG_BITS = 19;
+export const GRID16_LAT_MAG_BITS = 18;
 
 export class Gridex {
   constructor(londex, latdex) {
@@ -230,3 +233,97 @@ export class GridUnit {
     return { minLondex, maxLondex, minLatdex, maxLatdex };
   }
 }
+
+function wrapLongitudeDegrees(longitude) {
+  let value = longitude;
+  while (value > 180) value -= 360;
+  while (value < -180) value += 360;
+  return value;
+}
+
+function clampLatitudeDegrees(latitude) {
+  return Math.max(-90, Math.min(90, latitude));
+}
+
+function normalizeLonLatDegrees(longitude, latitude) {
+  return {
+    longitudeInt: Math.round(wrapLongitudeDegrees(longitude) * INT_COORD_SCALE),
+    latitudeInt: Math.round(clampLatitudeDegrees(latitude) * INT_COORD_SCALE),
+  };
+}
+
+export function gridexAtLonLat(level, longitude, latitude) {
+  const unit = new GridUnit(level);
+  const { longitudeInt, latitudeInt } = normalizeLonLatDegrees(longitude, latitude);
+  const candidates = unit.gridexesAt(longitudeInt, latitudeInt);
+  return candidates.find((candidate) => candidate.londex !== 0 && candidate.latdex !== 0)
+    ?? candidates[0]
+    ?? unit.makeGridex(0, 0);
+}
+
+export function gridexStringAtLonLat(level, longitude, latitude) {
+  const gridex = gridexAtLonLat(level, longitude, latitude);
+  return `${gridex.londex},${gridex.latdex}`;
+}
+
+export function encodeSignedGridIndex(index, magnitudeBits) {
+  if (!Number.isInteger(index) || index === 0) {
+    throw new Error(`Grid index must be a non-zero integer: ${index}`);
+  }
+  const signBit = index > 0 ? 1 : 0;
+  const magnitude = Math.abs(index) - 1;
+  const maxMagnitude = (1 << magnitudeBits) - 1;
+  if (magnitude < 0 || magnitude > maxMagnitude) {
+    throw new Error(`Grid index ${index} exceeds ${magnitudeBits} magnitude bits`);
+  }
+  return (signBit << magnitudeBits) | magnitude;
+}
+
+export function decodeSignedGridIndex(code, magnitudeBits) {
+  if (!Number.isInteger(code) || code < 0) {
+    throw new Error(`Grid code must be a non-negative integer: ${code}`);
+  }
+  const signBit = code >> magnitudeBits;
+  const magnitudeMask = (1 << magnitudeBits) - 1;
+  const magnitude = code & magnitudeMask;
+  return (magnitude + 1) * (signBit === 1 ? 1 : -1);
+}
+
+export function grid16CodesFromLonLat(longitude, latitude) {
+  const gridex16 = gridexAtLonLat(GRID16_LEVEL, longitude, latitude);
+  return {
+    grid16LonCode: encodeSignedGridIndex(gridex16.londex, GRID16_LON_MAG_BITS),
+    grid16LatCode: encodeSignedGridIndex(gridex16.latdex, GRID16_LAT_MAG_BITS),
+    londex16: gridex16.londex,
+    latdex16: gridex16.latdex,
+  };
+}
+
+export function buildGrid16RangeForLevelIndex(level, index, magnitudeBits) {
+  if (!Number.isInteger(level) || level < 0 || level > GRID16_LEVEL) {
+    throw new Error(`Level must be an integer between 0 and ${GRID16_LEVEL}: ${level}`);
+  }
+  if (!Number.isInteger(index) || index === 0) {
+    throw new Error(`Grid index must be a non-zero integer: ${index}`);
+  }
+  const signBit = index > 0 ? 1 : 0;
+  const shift = GRID16_LEVEL - level;
+  const magnitude = Math.abs(index) - 1;
+  const fromMagnitude = magnitude << shift;
+  const toMagnitude = ((magnitude + 1) << shift) - 1;
+  const maxMagnitude = (1 << magnitudeBits) - 1;
+  if (toMagnitude > maxMagnitude) {
+    throw new Error(`Grid index ${index} at level ${level} exceeds lv16 range`);
+  }
+  return {
+    from: (signBit << magnitudeBits) | fromMagnitude,
+    to: (signBit << magnitudeBits) | toMagnitude,
+  };
+}
+
+export function buildGrid16LonLatRangeForLevelCell(level, londex, latdex) {
+  return {
+    lon: buildGrid16RangeForLevelIndex(level, londex, GRID16_LON_MAG_BITS),
+    lat: buildGrid16RangeForLevelIndex(level, latdex, GRID16_LAT_MAG_BITS),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truelies/osm-dybuf",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Gridex OSM DyBuf parser and schema utilities",
   "type": "module",
   "main": "./osm_dybuf.mjs",