@truelies/osm-dybuf 0.4.2 → 0.4.5

package/README.md

@@ -88,7 +88,22 @@ 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,
+  CANONICAL_CODE_LEVEL,
+  gridexAtLonLat,
+  gridCodeAtLonLat,
+  gridCodeComponentsAtLonLat,
+  lonCodeFromLondex,
+  latCodeFromLatdex,
+  londexPrefixCodeFromLonCode,
+  lonLatCodeRangeForGridex,
+  encodeAxisCode,
+  decodeAxisCode,
+  lonCodeMagnitudeBits,
+} from "@truelies/osm-dybuf/grid_index";
 
 const unit = new GridUnit(8); // level 8
 const cell = new Gridex(213, 161);
@@ -97,6 +112,28 @@ 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
+
+// GPS -> gridex / lonCode / latCode / gridCode
+const gridex = gridexAtLonLat(16, 121.56, 25.03);
+const parts = gridCodeComponentsAtLonLat(16, 121.56, 25.03);
+console.log(gridex.londex, gridex.latdex);
+console.log(parts.lonCode, parts.latCode, parts.gridCode);
+
+// gridex <-> code
+const lonCode = lonCodeFromLondex(16, -123);
+const latCode = latCodeFromLatdex(16, 456);
+console.log(lonCode, latCode);
+console.log(gridCodeAtLonLat(16, 121.56, 25.03));
+
+// canonical prefix / range for coarser level query
+const lonPrefix = londexPrefixCodeFromLonCode(15, lonCode, CANONICAL_CODE_LEVEL);
+const range = lonLatCodeRangeForGridex(15, -3, 4, CANONICAL_CODE_LEVEL);
+console.log(lonPrefix, range.lonCode.from, range.lonCode.to);
+
+// axis code roundtrip
+const lonBits = lonCodeMagnitudeBits(CANONICAL_CODE_LEVEL);
+const axisCode = encodeAxisCode(-123, lonBits);
+console.log(decodeAxisCode(axisCode, lonBits)); // -123
 ```
 
 - `toLowerLevelGridexes(gridex)`:
@@ -105,6 +142,20 @@ const parent = new GridUnit(9).toUpperLevelGridex(children[0]); // back to level
 - `toUpperLevelGridex(gridex)`:
   - returns the parent cell at `level - 1`
   - throws when current unit is level `0`
+- `gridexAtLonLat(level, lon, lat)`:
+  - converts GPS directly to a `Gridex`
+- `gridCodeComponentsAtLonLat(level, lon, lat)`:
+  - returns `{ gridex, lonCode, latCode, gridCode }`
+- `lonCodeFromLondex(level, londex)` / `latCodeFromLatdex(level, latdex)`:
+  - converts axis indices to canonical axis codes
+- `londexPrefixCodeFromLonCode(targetLevel, lonCode, sourceLevel?)`:
+  - trims a finer `lonCode` into a coarser-level prefix view
+- `lonLatCodeRangeForGridex(level, londex, latdex, sourceLevel?)`:
+  - expands any `lv <= sourceLevel` cell into the corresponding canonical axis-code range
+- `gridCodeAtLonLat(level, lon, lat)` / `gridCodeFromGridex(level, gridex)`:
+  - returns the packed `gridCode`
+- `encodeAxisCode(index, magnitudeBits)` / `decodeAxisCode(code, magnitudeBits)`:
+  - encodes grid index as `sign bit + (abs(index) - 1)`
 
 ## Local Development
 
@@ -118,6 +169,9 @@ 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, `lv16` has no lower level)
+- canonical axis-code encode/decode roundtrip
+- GPS -> `gridex / lonCode / latCode / gridCode`
+- `lv15` cell -> canonical code 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 +193,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.2` 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 canonical grid conversion helpers shared by Firestore / Redis / frontend indexing.

package/grid_index.d.ts

@@ -1,6 +1,8 @@
 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 CANONICAL_CODE_LEVEL: number;
 export declare class Gridex {
   readonly londex: number;
   readonly latdex: number;
@@ -47,3 +49,67 @@ 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 lonCodeMagnitudeBits(level: number): number;
+export declare function latCodeMagnitudeBits(level: number): number;
+export declare function encodeAxisCode(index: number, magnitudeBits: number): number;
+export declare function decodeAxisCode(code: number, magnitudeBits: number): number;
+export declare function lonCodeFromLondex(level: number, londex: number): number;
+export declare function latCodeFromLatdex(level: number, latdex: number): number;
+export declare function londexFromLonCode(level: number, lonCode: number): number;
+export declare function latdexFromLatCode(level: number, latCode: number): number;
+export declare function londexPrefixCodeFromLonCode(targetLevel: number, lonCode: number, sourceLevel?: number): number;
+export declare function latdexPrefixCodeFromLatCode(targetLevel: number, latCode: number, sourceLevel?: number): number;
+export declare function lonCodeRangeForLondex(
+  level: number,
+  londex: number,
+  sourceLevel?: number
+): {
+  from: number;
+  to: number;
+};
+export declare function latCodeRangeForLatdex(
+  level: number,
+  latdex: number,
+  sourceLevel?: number
+): {
+  from: number;
+  to: number;
+};
+export declare function lonLatCodeRangeForGridex(
+  level: number,
+  londex: number,
+  latdex: number,
+  sourceLevel?: number
+): {
+  lonCode: {
+    from: number;
+    to: number;
+  };
+  latCode: {
+    from: number;
+    to: number;
+  };
+};
+export declare function gridCodeFromLonLatCodes(level: number, lonCode: number, latCode: number): number;
+export declare function lonLatCodesFromGridCode(
+  level: number,
+  gridCode: number
+): {
+  lonCode: number;
+  latCode: number;
+};
+export declare function gridCodeFromGridex(level: number, gridex: Gridex | number, latdex?: number): number;
+export declare function gridexFromGridCode(level: number, gridCode: number): GridexAtLv;
+export declare function gridCodeAtLonLat(level: number, longitude: number, latitude: number): number;
+export declare function gridCodeComponentsAtLonLat(
+  level: number,
+  longitude: number,
+  latitude: number
+): {
+  gridex: GridexAtLv;
+  lonCode: number;
+  latCode: number;
+  gridCode: number;
+};

package/grid_index.mjs

@@ -6,11 +6,12 @@ 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 = 16;
+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 CANONICAL_CODE_LEVEL = MAX_LEVEL;
 
 export class Gridex {
   constructor(londex, latdex) {
@@ -230,3 +231,208 @@ 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 lonCodeMagnitudeBits(level) {
+  const unit = new GridUnit(level);
+  return Math.ceil(Math.log2(unit.maxLondex));
+}
+
+export function latCodeMagnitudeBits(level) {
+  const unit = new GridUnit(level);
+  return Math.ceil(Math.log2(unit.maxLatdex));
+}
+
+export function encodeAxisCode(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 decodeAxisCode(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 lonCodeFromLondex(level, londex) {
+  return encodeAxisCode(londex, lonCodeMagnitudeBits(level));
+}
+
+export function latCodeFromLatdex(level, latdex) {
+  return encodeAxisCode(latdex, latCodeMagnitudeBits(level));
+}
+
+export function londexFromLonCode(level, lonCode) {
+  return decodeAxisCode(lonCode, lonCodeMagnitudeBits(level));
+}
+
+export function latdexFromLatCode(level, latCode) {
+  return decodeAxisCode(latCode, latCodeMagnitudeBits(level));
+}
+
+function axisCodePrefixFromCode(targetLevel, axisCode, sourceLevel, magnitudeBits) {
+  if (!Number.isInteger(targetLevel) || targetLevel < 0 || targetLevel > sourceLevel) {
+    throw new Error(`targetLevel must be an integer between 0 and ${sourceLevel}: ${targetLevel}`);
+  }
+  const signBase = 2 ** magnitudeBits;
+  const signBit = Math.floor(axisCode / signBase);
+  const magnitude = axisCode % signBase;
+  const shift = sourceLevel - targetLevel;
+  const prefixMagnitude = shift === 0 ? magnitude : Math.floor(magnitude / (2 ** shift)) * (2 ** shift);
+  return signBit * signBase + prefixMagnitude;
+}
+
+export function londexPrefixCodeFromLonCode(targetLevel, lonCode, sourceLevel = CANONICAL_CODE_LEVEL) {
+  return axisCodePrefixFromCode(targetLevel, lonCode, sourceLevel, lonCodeMagnitudeBits(sourceLevel));
+}
+
+export function latdexPrefixCodeFromLatCode(targetLevel, latCode, sourceLevel = CANONICAL_CODE_LEVEL) {
+  return axisCodePrefixFromCode(targetLevel, latCode, sourceLevel, latCodeMagnitudeBits(sourceLevel));
+}
+
+function axisCodeRangeForIndex(targetLevel, index, sourceLevel, magnitudeBits) {
+  if (!Number.isInteger(sourceLevel) || sourceLevel < 0 || sourceLevel > MAX_LEVEL) {
+    throw new Error(`sourceLevel must be an integer between 0 and ${MAX_LEVEL}: ${sourceLevel}`);
+  }
+  if (!Number.isInteger(targetLevel) || targetLevel < 0 || targetLevel > sourceLevel) {
+    throw new Error(`targetLevel must be an integer between 0 and ${sourceLevel}: ${targetLevel}`);
+  }
+  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 = sourceLevel - targetLevel;
+  const magnitude = Math.abs(index) - 1;
+  const fromMagnitude = magnitude << shift;
+  const toMagnitude = ((magnitude + 1) << shift) - 1;
+  const maxMagnitude = (2 ** magnitudeBits) - 1;
+  if (toMagnitude > maxMagnitude) {
+    throw new Error(`Grid index ${index} at level ${targetLevel} exceeds source level ${sourceLevel} range`);
+  }
+  const signBase = 2 ** magnitudeBits;
+  return {
+    from: signBit * signBase + fromMagnitude,
+    to: signBit * signBase + toMagnitude,
+  };
+}
+
+export function lonCodeRangeForLondex(level, londex, sourceLevel = CANONICAL_CODE_LEVEL) {
+  return axisCodeRangeForIndex(level, londex, sourceLevel, lonCodeMagnitudeBits(sourceLevel));
+}
+
+export function latCodeRangeForLatdex(level, latdex, sourceLevel = CANONICAL_CODE_LEVEL) {
+  return axisCodeRangeForIndex(level, latdex, sourceLevel, latCodeMagnitudeBits(sourceLevel));
+}
+
+export function lonLatCodeRangeForGridex(level, londex, latdex, sourceLevel = CANONICAL_CODE_LEVEL) {
+  return {
+    lonCode: lonCodeRangeForLondex(level, londex, sourceLevel),
+    latCode: latCodeRangeForLatdex(level, latdex, sourceLevel),
+  };
+}
+
+export function gridCodeFromLonLatCodes(level, lonCode, latCode) {
+  const latCodeWidth = latCodeMagnitudeBits(level) + 1;
+  const latCodeSpan = 2 ** latCodeWidth;
+  if (!Number.isInteger(lonCode) || lonCode < 0) {
+    throw new Error(`lonCode must be a non-negative integer: ${lonCode}`);
+  }
+  if (!Number.isInteger(latCode) || latCode < 0 || latCode >= latCodeSpan) {
+    throw new Error(`latCode out of range for level ${level}: ${latCode}`);
+  }
+  return lonCode * latCodeSpan + latCode;
+}
+
+export function lonLatCodesFromGridCode(level, gridCode) {
+  if (!Number.isInteger(gridCode) || gridCode < 0) {
+    throw new Error(`gridCode must be a non-negative integer: ${gridCode}`);
+  }
+  const latCodeWidth = latCodeMagnitudeBits(level) + 1;
+  const latCodeSpan = 2 ** latCodeWidth;
+  return {
+    lonCode: Math.floor(gridCode / latCodeSpan),
+    latCode: gridCode % latCodeSpan,
+  };
+}
+
+export function gridCodeFromGridex(level, gridex, latdex) {
+  const londex = typeof gridex === "object" ? gridex.londex : gridex;
+  const resolvedLatdex = typeof gridex === "object" ? gridex.latdex : latdex;
+  if (!Number.isInteger(londex) || !Number.isInteger(resolvedLatdex)) {
+    throw new Error("gridCodeFromGridex expects londex/latdex integers or a Gridex-like object");
+  }
+  return gridCodeFromLonLatCodes(
+    level,
+    lonCodeFromLondex(level, londex),
+    latCodeFromLatdex(level, resolvedLatdex),
+  );
+}
+
+export function gridexFromGridCode(level, gridCode) {
+  const { lonCode, latCode } = lonLatCodesFromGridCode(level, gridCode);
+  const unit = new GridUnit(level);
+  return unit.makeGridex(
+    londexFromLonCode(level, lonCode),
+    latdexFromLatCode(level, latCode),
+  );
+}
+
+export function gridCodeAtLonLat(level, longitude, latitude) {
+  const gridex = gridexAtLonLat(level, longitude, latitude);
+  return gridCodeFromGridex(level, gridex);
+}
+
+export function gridCodeComponentsAtLonLat(level, longitude, latitude) {
+  const gridex = gridexAtLonLat(level, longitude, latitude);
+  const lonCode = lonCodeFromLondex(level, gridex.londex);
+  const latCode = latCodeFromLatdex(level, gridex.latdex);
+  return {
+    gridex,
+    lonCode,
+    latCode,
+    gridCode: gridCodeFromLonLatCodes(level, lonCode, latCode),
+  };
+}

package/package.json

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