nearestPoint
Import from @pibbl/core/viz. Call nearestPoint(data, {x,y}, options) with numeric
x/y accessors, resolved xScale/yScale snapshots, optional defined, and an
optional inclusive nonnegative maxDistance. Returns {datum,index,x,y,distance}
or undefined. Returned coordinates are mapped local positions; datum is the
original reference and index is the original source index.
An unsorted O(n) scan minimizes Euclidean distance, choosing the earliest row on exact ties. Invalid coordinates skip rows. It does not call a renderer or inspect custom shapes, radius, opacity, or clips. A custom renderer returning null does not exclude that datum. Invalid query values or arithmetic overflow throw. The helper owns no signal observers, scheduler work, or retained index.
Pibbl events expose root-logical coordinates. Convert them to the shared local scale frame first (subtract the plot origin for a translation-only plot). Nonuniform transforms can make local nearest differ from screen-space nearest. Use matching data/scale snapshots from the displayed render for inspection.
API details from source
Section titled “API details from source”
nearestPoint
Section titled “nearestPoint”Finds the nearest defined datum in scaled coordinates, subject to an optional maximum distance.
nearestPoint: <D>(data: readonly D[], point: Readonly<{ x: number; y: number; }>, options: NearestPointOptions<D>) => NearestPoint<D> | undefinedRelated API: nearestPoint, NearestPointOptions, NearestPoint.
Parameters
Section titled “Parameters”-
data— Candidate data records. -
point— Query point in plotted range coordinates. -
options— Accessors, scales, eligibility, and distance settings. See NearestPointOptions .
Returns
Section titled “Returns”The nearest matching point, or undefined when no candidate qualifies. See NearestPoint .
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/nearest.ts:102
NearestPointOptions
Section titled “NearestPointOptions”Coordinate accessors, resolved scales, and candidate filtering for a nearest-point search.
interface NearestPointOptions<D>Related API: NearestPointOptions.
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/nearest.ts:11
Properties and methods
Section titled “Properties and methods”
x
readonly x: PointAccessor<D>Related API: PointAccessor.
Property key or callback extracting the horizontal domain coordinate. See PointAccessor.
View source — packages/core/src/features/viz/lib/nearest.ts:13
y
readonly y: PointAccessor<D>Related API: PointAccessor.
Property key or callback extracting the vertical domain coordinate. See PointAccessor.
View source — packages/core/src/features/viz/lib/nearest.ts:15
xScale
readonly xScale: ResolvedContinuousScaleRelated API: ResolvedContinuousScale.
The scale used to map horizontal data coordinates. See ResolvedContinuousScale.
View source — packages/core/src/features/viz/lib/nearest.ts:17
yScale
readonly yScale: ResolvedContinuousScaleRelated API: ResolvedContinuousScale.
The scale used to map vertical data coordinates. See ResolvedContinuousScale.
View source — packages/core/src/features/viz/lib/nearest.ts:19
defined (optional)
readonly defined?: ((datum: D, index: number, data: readonly D[]) => boolean) | undefinedReturns whether a datum contributes drawable or queryable coordinates. See NearestPointOptions.
Parameters
Section titled “Parameters”-
datum— Datum to test. -
index— Zero-based index in the source data. -
data— Complete source data array.
Returns
Section titled “Returns”Whether this datum should participate in the series or query.
View source — packages/core/src/features/viz/lib/nearest.ts:28
maxDistance (optional)
readonly maxDistance?: number | undefinedMaximum distance accepted by the query. See NearestPointOptions.
View source — packages/core/src/features/viz/lib/nearest.ts:30
NearestPoint
Section titled “NearestPoint”The selected datum, source index, mapped coordinates, and distance from the query point.
interface NearestPoint<D>Related API: NearestPoint.
See also
Section titled “See also”View source — packages/core/src/features/viz/lib/nearest.ts:37
Properties and methods
Section titled “Properties and methods”
datum
readonly datum: DThe original data item selected by this result. See NearestPoint.
View source — packages/core/src/features/viz/lib/nearest.ts:39
index
readonly index: numberIndex of the selected datum in its source data. See NearestPoint.
View source — packages/core/src/features/viz/lib/nearest.ts:41
x
readonly x: numberHorizontal coordinate or displacement in the containing coordinate system. See NearestPoint.
View source — packages/core/src/features/viz/lib/nearest.ts:46
y
readonly y: numberVertical coordinate or displacement in the containing coordinate system. See NearestPoint.
View source — packages/core/src/features/viz/lib/nearest.ts:51
distance
readonly distance: numberDistance measured in this query or guide’s coordinate system. See NearestPoint.
View source — packages/core/src/features/viz/lib/nearest.ts:53
Implementation guidance for agents
Section titled “Implementation guidance for agents”Read the Data visualization companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.
Complete minimal examples
Section titled “Complete minimal examples”- Nearest-point lookup: Locate the nearest observation in pixel and domain space. Plain source
Documentation version
Section titled “Documentation version”Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.