@truelies/osm-dybuf 0.4.6 → 0.4.7

package/README.md

@@ -95,6 +95,7 @@ import {
   CANONICAL_CODE_LEVEL,
   gridexAtLonLat,
   gridCodeAtLonLat,
+  gridCodeNeighbors,
   gridCodeComponentsAtLonLat,
   lonCodeFromLondex,
   latCodeFromLatdex,
@@ -124,6 +125,7 @@ const lonCode = lonCodeFromLondex(16, -123);
 const latCode = latCodeFromLatdex(16, 456);
 console.log(lonCode, latCode);
 console.log(gridCodeAtLonLat(16, 121.56, 25.03));
+console.log(gridCodeNeighbors(9, gridCodeAtLonLat(9, 121.56, 25.03)));
 
 // canonical prefix / range for coarser level query
 const lonPrefix = londexPrefixCodeFromLonCode(15, lonCode, CANONICAL_CODE_LEVEL);
@@ -154,6 +156,10 @@ console.log(decodeAxisCode(axisCode, lonBits)); // -123
   - expands any `lv <= sourceLevel` cell into the corresponding canonical axis-code range
 - `gridCodeAtLonLat(level, lon, lat)` / `gridCodeFromGridex(level, gridex)`:
   - returns the packed `gridCode`
+- `GridUnit.neighbors(gridex)` / `gridexNeighbors(level, gridex, radius?)` / `gridCodeNeighbors(level, gridCode, radius?)`:
+  - returns one-ring neighbors for an existing cell/code
+  - currently only supports `radius=1`
+  - crosses the zero axis without returning zero-index cells; longitude wraps and latitude clamps at poles
 - `encodeAxisCode(index, magnitudeBits)` / `decodeAxisCode(code, magnitudeBits)`:
   - encodes grid index as `sign bit + (abs(index) - 1)`
 

package/grid_index.d.ts

@@ -33,6 +33,7 @@ export declare class GridUnit {
   makeGridex(londex: number, latdex: number): GridexAtLv;
   gridexesAt(longitudeInt: number, latitudeInt: number): GridexAtLv[];
   gridexesWithExt(longitudeInt: number, latitudeInt: number, ext?: number): GridexAtLv[];
+  neighbors(gridex: Gridex, includeSelf?: boolean): GridexAtLv[];
   toLowerLevelGridexes(gridex: Gridex): GridexAtLv[];
   toUpperLevelGridex(gridex: Gridex): GridexAtLv;
   boundsOfGridFine(gridex: Gridex, applyTriangle?: boolean): [number, number, number, number];
@@ -102,6 +103,8 @@ export declare function lonLatCodesFromGridCode(
 };
 export declare function gridCodeFromGridex(level: number, gridex: Gridex | number, latdex?: number): number;
 export declare function gridexFromGridCode(level: number, gridCode: number): GridexAtLv;
+export declare function gridexNeighbors(level: number, gridex: Gridex, radius?: number): GridexAtLv[];
+export declare function gridCodeNeighbors(level: number, gridCode: number, radius?: number): number[];
 export declare function gridCodeAtLonLat(level: number, longitude: number, latitude: number): number;
 export declare function gridCodeComponentsAtLonLat(
   level: number,

package/grid_index.mjs

@@ -159,6 +159,52 @@ export class GridUnit {
     return result;
   }
 
+  _neighborAxisIndices(index, axis) {
+    const min = axis === "lon" ? this.minLondex : this.minLatdex;
+    const max = axis === "lon" ? this.maxLondex : this.maxLatdex;
+
+    const prev = () => {
+      if (index === min) return axis === "lon" ? max : min;
+      if (index === 1) return -1;
+      return index - 1;
+    };
+    const next = () => {
+      if (index === max) return axis === "lon" ? min : max;
+      if (index === -1) return 1;
+      return index + 1;
+    };
+
+    return [...new Set([prev(), index, next()])];
+  }
+
+  neighbors(gridex, includeSelf = false) {
+    if (!Number.isInteger(gridex.londex) || !Number.isInteger(gridex.latdex)) {
+      throw new Error("neighbors expects a Gridex-like object");
+    }
+    if (gridex.londex === 0 || gridex.latdex === 0) {
+      throw new Error("gridex indices must be non-zero");
+    }
+    if (gridex.londex < this.minLondex || gridex.londex > this.maxLondex) {
+      throw new Error(`londex out of range for level ${this.level}: ${gridex.londex}`);
+    }
+    if (gridex.latdex < this.minLatdex || gridex.latdex > this.maxLatdex) {
+      throw new Error(`latdex out of range for level ${this.level}: ${gridex.latdex}`);
+    }
+
+    const lonIndices = this._neighborAxisIndices(gridex.londex, "lon");
+    const latIndices = this._neighborAxisIndices(gridex.latdex, "lat");
+    const result = [];
+    for (const londex of lonIndices) {
+      for (const latdex of latIndices) {
+        if (!includeSelf && londex === gridex.londex && latdex === gridex.latdex) {
+          continue;
+        }
+        result.push(this.makeGridex(londex, latdex));
+      }
+    }
+    return result;
+  }
+
   toLowerLevelGridexes(gridex) {
     if (this.level >= MAX_LEVEL) {
       throw new Error(`No lower level exists for level ${this.level}`);
@@ -420,6 +466,23 @@ export function gridexFromGridCode(level, gridCode) {
   );
 }
 
+function ensureSingleNeighborRadius(radius) {
+  if (radius !== 1) {
+    throw new Error("Only radius=1 is currently supported");
+  }
+}
+
+export function gridexNeighbors(level, gridex, radius = 1) {
+  ensureSingleNeighborRadius(radius);
+  return new GridUnit(level).neighbors(gridex);
+}
+
+export function gridCodeNeighbors(level, gridCode, radius = 1) {
+  ensureSingleNeighborRadius(radius);
+  return gridexNeighbors(level, gridexFromGridCode(level, gridCode), radius)
+    .map((neighbor) => gridCodeFromGridex(level, neighbor));
+}
+
 export function gridCodeAtLonLat(level, longitude, latitude) {
   const gridex = gridexAtLonLat(level, longitude, latitude);
   return gridCodeFromGridex(level, gridex);

package/package.json

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