@truelies/osm-dybuf 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,63 @@
+# @truelies/osm-dybuf
+
+Gridex `osm.dybuf` parser utilities shared by the exporter, inspection scripts, and Next.js frontend.  
+This package wraps the shared schema tables (`schema_ids`) and exposes a high-level `parseOsmDybuf` helper.  
+It depends on the published [`dybuf`](https://www.npmjs.com/package/dybuf) runtime (≥ 0.4.2).
+
+## Usage
+
+```bash
+# from another project (Next.js, Node, etc.)
+npm install @truelies/osm-dybuf
+```
+
+```ts
+import { parseOsmDybuf } from "@truelies/osm-dybuf";
+import {
+  FEATURE_KIND_IDS,
+  REGION_NUMERIC_CODES,
+} from "@truelies/osm-dybuf/schema_ids";
+
+const data = await fetch("/tiles/08/213/161/osm.dybuf").then((res) => res.arrayBuffer());
+const cell = { level: 8, londex: 213, latdex: 161 };
+const parsed = parseOsmDybuf(data, cell);
+```
+
+- CLI inspection (development only):
+  ```bash
+  node js/inspect_dybuf.mjs \
+      --file /path/to/osm.dybuf \
+      --level 8 --londex 213 --latdex 161 --limit 5
+  ```
+
+### Grid helpers (grid_index)
+
+`grid_index.ts` exposes the minimal Gridex helpers (integers, pole triangles) aligned with the exporter:
+
+```ts
+import { GridUnit, Gridex, INT_COORD_SCALE } from "@truelies/osm-dybuf/grid_index";
+
+const unit = new GridUnit(8); // level 8
+const cell = new Gridex(213, 161);
+const [minLon, minLat, maxLon, maxLat] = unit.boundsOfGrid(cell);
+```
+
+## Local Development
+
+```bash
+cd js
+npm install      # installs dybuf runtime for this package
+```
+
+- `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)
+- `npm publish --access public`: publish to npm (requires the `@truelies` scope). If the scope is not available, rename `package.json` → `"name": "truelies-osm-dybuf"` and publish without a scope.
+
+## Files
+
+- `osm_dybuf.mjs` / `.d.mts`: DyBuf parser entry points
+- `schema_ids.mjs` / `.d.mts`: shared identifiers (geometry, feature, region, segment roles)
+- `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.

package/grid_index.d.ts

@@ -0,0 +1,47 @@
+export declare const INT_COORD_SCALE: number;
+export declare const GRID_FINE_RES: number;
+export declare const GRID_LV0_UNIT: number;
+export declare class Gridex {
+  readonly londex: number;
+  readonly latdex: number;
+  constructor(londex: number, latdex: number);
+  toString(): string;
+  equals(other: Gridex): boolean;
+}
+export declare class GridexAtLv extends Gridex {
+  readonly level: number;
+  constructor(unit: GridUnit, londex: number, latdex: number);
+  boundsInt(applyTriangle?: boolean): [number, number, number, number];
+  boundsFine(applyTriangle?: boolean): [number, number, number, number];
+  boundsFloat(applyTriangle?: boolean): {
+    minLon: number;
+    minLat: number;
+    maxLon: number;
+    maxLat: number;
+  };
+}
+export declare class GridUnit {
+  readonly unitFine: number;
+  readonly level: number;
+  readonly minLondex: number;
+  readonly maxLondex: number;
+  readonly minLatdex: number;
+  readonly maxLatdex: number;
+  constructor(level: number);
+  makeGridex(londex: number, latdex: number): GridexAtLv;
+  gridexesAt(longitudeInt: number, latitudeInt: number): GridexAtLv[];
+  gridexesWithExt(longitudeInt: number, latitudeInt: number, ext?: number): GridexAtLv[];
+  boundsOfGridFine(gridex: Gridex, applyTriangle?: boolean): [number, number, number, number];
+  boundsOfGrid(gridex: Gridex, applyTriangle?: boolean): [number, number, number, number];
+  gridexRangeForBounds(
+    minLon: number,
+    minLat: number,
+    maxLon: number,
+    maxLat: number
+  ): {
+    minLondex: number;
+    maxLondex: number;
+    minLatdex: number;
+    maxLatdex: number;
+  };
+}

package/grid_index.mjs

@@ -0,0 +1,190 @@
+// Gridex helpers (integer math) aligned with Python grid_index.py
+
+export const INT_COORD_SCALE = 1_000_000_000; // 1e9
+export const GRID_FINE_RES = 64;
+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;
+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 class Gridex {
+  constructor(londex, latdex) {
+    this.londex = londex;
+    this.latdex = latdex;
+  }
+  toString() {
+    return `(${this.londex},${this.latdex})`;
+  }
+  equals(other) {
+    return this.londex === other.londex && this.latdex === other.latdex;
+  }
+}
+
+export class GridexAtLv extends Gridex {
+  constructor(unit, londex, latdex) {
+    super(londex, latdex);
+    this.unit = unit;
+  }
+  get level() {
+    return this.unit.level;
+  }
+  boundsInt(applyTriangle = false) {
+    return this.unit.boundsOfGrid(this, applyTriangle);
+  }
+  boundsFine(applyTriangle = false) {
+    return this.unit.boundsOfGridFine(this, applyTriangle);
+  }
+  boundsFloat(applyTriangle = false) {
+    const [minLon, minLat, maxLon, maxLat] = this.boundsInt(applyTriangle);
+    return {
+      minLon: minLon / INT_COORD_SCALE,
+      minLat: minLat / INT_COORD_SCALE,
+      maxLon: maxLon / INT_COORD_SCALE,
+      maxLat: maxLat / INT_COORD_SCALE,
+    };
+  }
+}
+
+export class GridUnit {
+  constructor(level) {
+    if (!Number.isInteger(level) || level < 0 || level > MAX_LEVEL) {
+      throw new Error(`level must be an integer between 0 and ${MAX_LEVEL}`);
+    }
+    this.level = level;
+    this.unitFine = GRID_LV0_UNIT_FINE >> level;
+    this.maxLondex = MAX_LONGITUDE_FINE / this.unitFine;
+    this.minLondex = -this.maxLondex;
+    this.maxLatdex = MAX_LATITUDE_FINE / this.unitFine;
+    this.minLatdex = -this.maxLatdex;
+  }
+
+  makeGridex(londex, latdex) {
+    return new GridexAtLv(this, londex, latdex);
+  }
+
+  _axisIndices(valueFine, axis) {
+    const max = axis === "lon" ? this.maxLondex : this.maxLatdex;
+    const min = axis === "lon" ? this.minLondex : this.minLatdex;
+    const unit = this.unitFine;
+
+    if (valueFine === 0) return [-1, 1];
+    if (valueFine === max * unit) return [max];
+    if (valueFine === min * unit) return [min];
+    if (valueFine % unit === 0) {
+      const idx = valueFine / unit;
+      return [idx, idx + (idx > 0 ? 1 : -1)];
+    }
+    return [Math.ceil(valueFine / unit)];
+  }
+
+  gridexesAt(longitudeInt, latitudeInt) {
+    const lonFine = longitudeInt * GRID_FINE_RES;
+    const latFine = latitudeInt * GRID_FINE_RES;
+    if (lonFine < MIN_LONGITUDE_FINE || lonFine > MAX_LONGITUDE_FINE) {
+      throw new Error("longitude out of range");
+    }
+    if (latFine < MIN_LATITUDE_FINE || latFine > MAX_LATITUDE_FINE) {
+      throw new Error("latitude out of range");
+    }
+    if (Math.abs(latFine) === MAX_LATITUDE_FINE) {
+      const latdex = latFine > 0 ? this.maxLatdex : this.minLatdex;
+      const res = [];
+      for (let i = 0; i < this.maxLondex; i++) {
+        res.push(this.makeGridex(i + 1, latdex));
+        res.push(this.makeGridex(-(i + 1), latdex));
+      }
+      return res;
+    }
+    const lonIdx = this._axisIndices(lonFine, "lon");
+    const latIdx = this._axisIndices(latFine, "lat");
+    const res = [];
+    for (const lx of lonIdx) {
+      for (const ly of latIdx) {
+        res.push(this.makeGridex(lx, ly));
+      }
+    }
+    return res;
+  }
+
+  gridexesWithExt(longitudeInt, latitudeInt, ext = 0) {
+    const radius = Number(ext);
+    if (!Number.isInteger(radius) || radius < 0) {
+      throw new Error("ext must be a non-negative integer");
+    }
+    const baseLonFine = longitudeInt * GRID_FINE_RES;
+    const baseLatFine = latitudeInt * GRID_FINE_RES;
+    const seen = new Set();
+    const result = [];
+
+    const wrapLon = (lonFine) => {
+      const span = 2 * MAX_LONGITUDE_FINE;
+      let v = lonFine;
+      while (v > MAX_LONGITUDE_FINE) v -= span;
+      while (v < MIN_LONGITUDE_FINE) v += span;
+      return v;
+    };
+    const clampLat = (latFine) => {
+      if (latFine > MAX_LATITUDE_FINE) return MAX_LATITUDE_FINE;
+      if (latFine < MIN_LATITUDE_FINE) return MIN_LATITUDE_FINE;
+      return latFine;
+    };
+
+    for (let dx = -radius; dx <= radius; dx++) {
+      for (let dy = -radius; dy <= radius; dy++) {
+        const lonFine = wrapLon(baseLonFine + dx * this.unitFine);
+        const latFine = clampLat(baseLatFine + dy * this.unitFine);
+        const lonInt = lonFine / GRID_FINE_RES;
+        const latInt = latFine / GRID_FINE_RES;
+        const cells = this.gridexesAt(lonInt, latInt);
+        for (const cell of cells) {
+          const key = `${cell.level}:${cell.londex},${cell.latdex}`;
+          if (!seen.has(key)) {
+            seen.add(key);
+            result.push(cell);
+          }
+        }
+      }
+    }
+    return result;
+  }
+
+  boundsOfGridFine(gridex, applyTriangle = false) {
+    const { londex, latdex } = gridex;
+    const minLonFine = (londex - (londex > 0 ? 1 : 0)) * this.unitFine;
+    const minLatFine = (latdex - (latdex > 0 ? 1 : 0)) * this.unitFine;
+    const maxLonFine = (londex + (londex > 0 ? 0 : 1)) * this.unitFine;
+    const maxLatFine = (latdex + (latdex > 0 ? 0 : 1)) * this.unitFine;
+
+    if (applyTriangle) {
+      if (latdex === this.maxLatdex) {
+        return [minLonFine, minLatFine, maxLonFine, minLatFine];
+      }
+      if (latdex === this.minLatdex) {
+        return [minLonFine, minLatFine, maxLonFine, maxLatFine];
+      }
+    }
+    return [minLonFine, minLatFine, maxLonFine, maxLatFine];
+  }
+
+  boundsOfGrid(gridex, applyTriangle = false) {
+    const [a, b, c, d] = this.boundsOfGridFine(gridex, applyTriangle);
+    return [a / GRID_FINE_RES, b / GRID_FINE_RES, c / GRID_FINE_RES, d / GRID_FINE_RES];
+  }
+
+  gridexRangeForBounds(minLon, minLat, maxLon, maxLat) {
+    if (minLon > maxLon || minLat > maxLat) {
+      throw new Error("min must be <= max");
+    }
+    const unit = this.unitFine;
+    const minLondex = Math.max(this.minLondex, Math.floor((minLon * GRID_FINE_RES) / unit) - 1);
+    const maxLondex = Math.min(this.maxLondex, Math.ceil((maxLon * GRID_FINE_RES) / unit) + 1);
+    const minLatdex = Math.max(this.minLatdex, Math.floor((minLat * GRID_FINE_RES) / unit) - 1);
+    const maxLatdex = Math.min(this.maxLatdex, Math.ceil((maxLat * GRID_FINE_RES) / unit) + 1);
+    return { minLondex, maxLondex, minLatdex, maxLatdex };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truelies/osm-dybuf",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Gridex OSM DyBuf parser and schema utilities",
   "type": "module",
   "main": "./osm_dybuf.mjs",
@@ -15,6 +15,10 @@
       "import": "./schema_ids.mjs",
       "types": "./schema_ids.d.mts"
     },
+    "./grid_index": {
+      "import": "./grid_index.mjs",
+      "types": "./grid_index.d.ts"
+    },
     "./region_numeric_codes.json": "./region_numeric_codes.json"
   },
   "files": [
@@ -22,7 +26,9 @@
     "osm_dybuf.d.mts",
     "schema_ids.mjs",
     "schema_ids.d.mts",
-    "region_numeric_codes.json"
+    "region_numeric_codes.json",
+    "grid_index.mjs",
+    "grid_index.d.ts"
   ],
   "keywords": [
     "dybuf",