@thi.ng/distance 2.2.13 → 2.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-04-08T11:09:50Z
+- **Last updated**: 2023-05-28T09:56:37Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,13 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/distance@2.3.0) (2023-05-28)
+
+#### 🚀 Features
+
+- add Radial neighborhood impls ([667fed9](https://github.com/thi-ng/umbrella/commit/667fed9))
+  - add radial/2/3/N() factories
+
 ## [2.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/distance@2.2.0) (2023-02-05)
 
 #### 🚀 Features

package/README.md

@@ -14,6 +14,7 @@ This project is part of the
   - [Neighborhoods](#neighborhoods)
     - [Nearest](#nearest)
     - [KNearest](#knearest)
+    - [Radial](#radial)
 - [Status](#status)
 - [Support packages](#support-packages)
 - [Related packages](#related-packages)
@@ -81,6 +82,12 @@ results can be optionally returned in order of proximity (via `.deref()` or
 `.values()`). For K=1 it will be more efficient to use `Nearest` to avoid the
 additional overhead.
 
+#### Radial
+
+An unbounded and unsorted version of [`KNearest`](#knearest), selecting _all_
+items around the target location and given search radius. Qualifying neighbors
+will be accumulated in order of processing via an internal array.
+
 ## Status
 
 **STABLE** - used in production
@@ -122,7 +129,7 @@ For Node.js REPL:
 const distance = await import("@thi.ng/distance");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.15 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.24 KB
 
 ## Dependencies
 

package/index.d.ts

@@ -5,5 +5,6 @@ export * from "./haversine.js";
 export * from "./knearest.js";
 export * from "./manhattan.js";
 export * from "./nearest.js";
+export * from "./radial.js";
 export * from "./squared.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -5,4 +5,5 @@ export * from "./haversine.js";
 export * from "./knearest.js";
 export * from "./manhattan.js";
 export * from "./nearest.js";
+export * from "./radial.js";
 export * from "./squared.js";

package/knearest.d.ts

@@ -5,7 +5,8 @@ import type { IDistance, INeighborhood, Neighbor } from "./api.js";
 /**
  * A {@link INeighborhood} implementation for K-nearest neighbor queries around
  * a given target location, initial query radius and {@link IDistance} metric to
- * determine proximity.
+ * determine proximity. See {@link Radial} for an unbounded and unsorted
+ * version.
  *
  * @remarks
  * The K-nearest neighbors will be accumulated via an internal

package/knearest.js

@@ -5,7 +5,8 @@ import { DIST_SQ, DIST_SQ1, DIST_SQ2, DIST_SQ3 } from "./squared.js";
 /**
  * A {@link INeighborhood} implementation for K-nearest neighbor queries around
  * a given target location, initial query radius and {@link IDistance} metric to
- * determine proximity.
+ * determine proximity. See {@link Radial} for an unbounded and unsorted
+ * version.
  *
  * @remarks
  * The K-nearest neighbors will be accumulated via an internal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/distance",
-  "version": "2.2.13",
+  "version": "2.3.0",
   "description": "N-dimensional distance metrics & K-nearest neighborhoods for point queries",
   "type": "module",
   "module": "./index.js",
@@ -34,19 +34,19 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.8.0",
-    "@thi.ng/checks": "^3.3.12",
-    "@thi.ng/errors": "^2.2.15",
-    "@thi.ng/heaps": "^2.1.31",
-    "@thi.ng/math": "^5.4.9",
-    "@thi.ng/vectors": "^7.6.13"
+    "@thi.ng/api": "^8.8.1",
+    "@thi.ng/checks": "^3.3.13",
+    "@thi.ng/errors": "^2.2.16",
+    "@thi.ng/heaps": "^2.1.32",
+    "@thi.ng/math": "^5.4.10",
+    "@thi.ng/vectors": "^7.6.14"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.34.4",
-    "@thi.ng/testament": "^0.3.15",
-    "rimraf": "^4.4.1",
+    "@microsoft/api-extractor": "^7.34.8",
+    "@thi.ng/testament": "^0.3.16",
+    "rimraf": "^5.0.0",
     "tools": "^0.0.1",
-    "typedoc": "^0.23.28",
+    "typedoc": "^0.24.6",
     "typescript": "^5.0.4"
   },
   "keywords": [
@@ -97,6 +97,9 @@
     "./nearest": {
       "default": "./nearest.js"
     },
+    "./radial": {
+      "default": "./radial.js"
+    },
     "./squared": {
       "default": "./squared.js"
     }
@@ -109,5 +112,5 @@
     ],
     "year": 2021
   },
-  "gitHead": "ca22f02a137c0a4e3a38ef81e82e2bc7e3c43849\n"
+  "gitHead": "065e40c90123541fcb126b825a07f84975431fb6\n"
 }

package/radial.d.ts

@@ -0,0 +1,93 @@
+import type { IDeref } from "@thi.ng/api";
+import type { ReadonlyVec } from "@thi.ng/vectors";
+import type { IDistance, INeighborhood, Neighbor } from "./api.js";
+/**
+ * A {@link INeighborhood} implementation for radial neighbor queries around a
+ * given target location, initial query radius and {@link IDistance} metric to
+ * determine proximity. Unbounded and unsorted version of {@link KNearest}.
+ *
+ * @remarks
+ * Qualifying neighbors will be accumulated in order of processing via an
+ * internal array and can be obtained via {@link Radial.deref} or
+ * {@link Radial.values}.
+ *
+ * @typeParam D - spatial position for distance metric
+ * @typeParam T - indexed value
+ */
+export declare class Radial<D, T> implements INeighborhood<D, T>, IDeref<Neighbor<T>[]> {
+    readonly dist: IDistance<D>;
+    target: D;
+    radius: number;
+    protected _r: number;
+    protected _items: [number, T][];
+    constructor(dist: IDistance<D>, target: D, radius?: number);
+    /**
+     * Clears current results.
+     */
+    reset(): this;
+    /**
+     * Resets search/reference position and clears current results.
+     *
+     * @param target
+     */
+    setTarget(target: D): void;
+    /**
+     * Resets search/query radius and clears current results.
+     *
+     * @param r
+     */
+    setRadius(r: number): void;
+    /**
+     * Returns an array of current neighbor result tuples (each `[dist, val]`).
+     *
+     * @remarks
+     * Use {@link Radial.values} to obtain result values **without** their
+     * distance metrics.
+     */
+    deref(): [number, T][];
+    /**
+     * Similar to {@link Radial.deref}, but returns array of result values **without**
+     * their distance metrics.
+     */
+    values(): T[];
+    includesDistance(d: number, eucledian?: boolean): boolean;
+    consider(pos: D, val: T): number;
+}
+/**
+ * Defines a {@link Radial} instance for arbitrary length vector positions
+ * and, by default, using an infinite region radius and {@link DIST_SQ} distance
+ * metric.
+ *
+ * @param p -
+ * @param r -
+ * @param dist -
+ */
+export declare const radial: <T>(p: ReadonlyVec, r?: number, dist?: import("./squared.js").Squared<ReadonlyVec>) => Radial<ReadonlyVec, T>;
+/**
+ * Defines a {@link Radial} instance for 2D vector positions and, by default,
+ * using an infinite region radius and {@link DIST_SQ2} distance metric.
+ *
+ * @param p -
+ * @param r -
+ * @param dist -
+ */
+export declare const radial2: <T>(p: ReadonlyVec, r?: number, dist?: import("./squared.js").Squared<ReadonlyVec>) => Radial<ReadonlyVec, T>;
+/**
+ * Defines a {@link Radial} instance for 3D vector positions, by default,
+ * using an infinite region radius and {@link DIST_SQ3} distance metric.
+ *
+ * @param p -
+ * @param r -
+ * @param dist -
+ */
+export declare const radial3: <T>(p: ReadonlyVec, r?: number, dist?: import("./squared.js").Squared<ReadonlyVec>) => Radial<ReadonlyVec, T>;
+/**
+ * Defines a {@link KNearest} instance for numeric positions and, by default,
+ * using an infinite region radius and {@link DIST_SQ1} distance metric.
+ *
+ * @param p -
+ * @param r -
+ * @param dist -
+ */
+export declare const radialN: <T>(p: number, r?: number, dist?: import("./squared.js").Squared<number>) => Radial<number, T>;
+//# sourceMappingURL=radial.d.ts.map

package/radial.js

@@ -0,0 +1,113 @@
+import { clamp0 } from "@thi.ng/math/interval";
+import { DIST_SQ, DIST_SQ1, DIST_SQ2, DIST_SQ3 } from "./squared.js";
+/**
+ * A {@link INeighborhood} implementation for radial neighbor queries around a
+ * given target location, initial query radius and {@link IDistance} metric to
+ * determine proximity. Unbounded and unsorted version of {@link KNearest}.
+ *
+ * @remarks
+ * Qualifying neighbors will be accumulated in order of processing via an
+ * internal array and can be obtained via {@link Radial.deref} or
+ * {@link Radial.values}.
+ *
+ * @typeParam D - spatial position for distance metric
+ * @typeParam T - indexed value
+ */
+export class Radial {
+    constructor(dist, target, radius = Infinity) {
+        this.dist = dist;
+        this.target = target;
+        this.radius = radius;
+        this.setRadius(radius);
+    }
+    /**
+     * Clears current results.
+     */
+    reset() {
+        this._items = [];
+        return this;
+    }
+    /**
+     * Resets search/reference position and clears current results.
+     *
+     * @param target
+     */
+    setTarget(target) {
+        this.target = target;
+        this.reset();
+    }
+    /**
+     * Resets search/query radius and clears current results.
+     *
+     * @param r
+     */
+    setRadius(r) {
+        this.radius = clamp0(r);
+        this._r = this.dist.to(this.radius);
+        this.reset();
+    }
+    /**
+     * Returns an array of current neighbor result tuples (each `[dist, val]`).
+     *
+     * @remarks
+     * Use {@link Radial.values} to obtain result values **without** their
+     * distance metrics.
+     */
+    deref() {
+        return this._items;
+    }
+    /**
+     * Similar to {@link Radial.deref}, but returns array of result values **without**
+     * their distance metrics.
+     */
+    values() {
+        return this._items.map((x) => x[1]);
+    }
+    includesDistance(d, eucledian = true) {
+        return (eucledian ? this.dist.to(d) : d) <= this._r;
+    }
+    consider(pos, val) {
+        const d = this.dist.metric(this.target, pos);
+        if (d <= this._r) {
+            this._items.push([d, val]);
+        }
+        return d;
+    }
+}
+/**
+ * Defines a {@link Radial} instance for arbitrary length vector positions
+ * and, by default, using an infinite region radius and {@link DIST_SQ} distance
+ * metric.
+ *
+ * @param p -
+ * @param r -
+ * @param dist -
+ */
+export const radial = (p, r, dist = DIST_SQ) => new Radial(dist, p, r);
+/**
+ * Defines a {@link Radial} instance for 2D vector positions and, by default,
+ * using an infinite region radius and {@link DIST_SQ2} distance metric.
+ *
+ * @param p -
+ * @param r -
+ * @param dist -
+ */
+export const radial2 = (p, r, dist = DIST_SQ2) => new Radial(dist, p, r);
+/**
+ * Defines a {@link Radial} instance for 3D vector positions, by default,
+ * using an infinite region radius and {@link DIST_SQ3} distance metric.
+ *
+ * @param p -
+ * @param r -
+ * @param dist -
+ */
+export const radial3 = (p, r, dist = DIST_SQ3) => new Radial(dist, p, r);
+/**
+ * Defines a {@link KNearest} instance for numeric positions and, by default,
+ * using an infinite region radius and {@link DIST_SQ1} distance metric.
+ *
+ * @param p -
+ * @param r -
+ * @param dist -
+ */
+export const radialN = (p, r, dist = DIST_SQ1) => new Radial(dist, p, r);