Class: PointIndex

Experimental

Static 2D spatial index over a point cloud, backed by a packed Hilbert R-tree (flatbush). Used for CPU picking of 2D traces (ADR-010): hover (nearest), box select (withinRect), lasso (withinPolygon) and brush-radius queries.

The index is unit-agnostic: all distances are Euclidean in the units of the input arrays. For hover hit-testing pass pixel-space coordinates (or data pre-scaled so both axes share a unit), otherwise anisotropic axes make "nearest" meaningless.

Non-finite points (NaN gaps, ±Infinity) are skipped and never returned; every returned index refers to the ORIGINAL position in the x/y arrays. If the arrays differ in length, the shorter length is used.

Construction is O(1): the tree is built lazily on the first query, and invalidate simply marks it dirty, so frequently-updated data only pays for a rebuild when actually queried.

Constructors

Constructor

new PointIndex(
   x,
   y,
   options?
): PointIndex;

Experimental

Parameters

Parameter	Type
x	ArrayLike<number>
y	ArrayLike<number>
options	PointIndexOptions

Returns

PointIndex

Accessors

built

Get Signature

get built(): boolean;

Experimental

Whether the tree is currently built (false until the first query, and after invalidate).

Returns

boolean

---

size

Get Signature

get size(): number;

Experimental

Number of valid (finite) points indexed. Triggers a build if needed.

Returns

number

Methods

invalidate()

invalidate(x?, y?): void;

Experimental

Mark the index stale, optionally swapping in new coordinate arrays. The rebuild happens lazily on the next query. Call this after mutating the arrays in place, too.

Parameters

Parameter	Type
x?	ArrayLike<number>
y?	ArrayLike<number>

Returns

void

---

nearest()

nearest(
   x,
   y,
   maxDistance?
): number;

Experimental

Original index of the point closest to (x, y) within maxDistance, or -1 if none.

Parameters

Parameter	Type	Default value
x	number	undefined
y	number	undefined
maxDistance	number	Infinity

Returns

number

---

nearestK()

nearestK(
   x,
   y,
   k,
   maxDistance?
): number[];

Experimental

Original indices of up to k points closest to (x, y), sorted by increasing distance.

Parameters

Parameter	Type	Default value
x	number	undefined
y	number	undefined
k	number	undefined
maxDistance	number	Infinity

Returns

number[]

---

withinPolygon()

withinPolygon(polygon): number[];

Experimental

Original indices of points inside a flat [x0, y0, x1, y1, ...] polygon (even-odd rule), ascending. The polygon's bounding box prefilters candidates through the tree; only those get the exact point-in-polygon test. Fewer than 3 vertices returns [].

Parameters

Parameter	Type
polygon	ArrayLike<number>

Returns

number[]

---

withinRadius()

withinRadius(
   x,
   y,
   r
): number[];

Experimental

Original indices of points within distance r (inclusive) of (x, y), ascending.

Parameters

Parameter	Type
x	number
y	number
r	number

Returns

number[]

---

withinRect()

withinRect(
   x0,
   y0,
   x1,
   y1
): number[];

Experimental

Original indices of points inside the rectangle, ascending. Corners may be given in any order; edges are inclusive.

Parameters

Parameter	Type
x0	number
y0	number
x1	number
y1	number

Returns

number[]