# 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

<span id="api-nearestPoint"></span>

### nearestPoint

Finds the nearest defined datum in scaled coordinates, subject to an optional maximum distance.

```ts
nearestPoint: <D>(data: readonly D[], point: Readonly<{ x: number; y: number; }>, options: NearestPointOptions<D>) => NearestPoint<D> | undefined
```

Related API: [nearestPoint](/reference/functions/nearest-point/), [NearestPointOptions](/reference/functions/nearest-point/), [NearestPoint](/reference/functions/nearest-point/).

#### Parameters

- **`data`** — Candidate data records.

- **`point`** — Query point in plotted range coordinates.

- **`options`** — Accessors, scales, eligibility, and distance settings. See
[NearestPointOptions](/reference/functions/nearest-point/) .

#### Returns

The nearest matching point, or undefined when no candidate qualifies. See
[NearestPoint](/reference/functions/nearest-point/) .

#### See also

[NearestPointOptions](/reference/functions/nearest-point/)

[NearestPoint](/reference/functions/nearest-point/)

[View source — packages/core/src/features/viz/lib/nearest.ts:102](/source/packages/core/src/features/viz/lib/nearest-ts/#L102)

<span id="api-NearestPointOptions"></span>

### NearestPointOptions

Coordinate accessors, resolved scales, and candidate filtering for a nearest-point search.

```ts
interface NearestPointOptions<D>
```

Related API: [NearestPointOptions](/reference/functions/nearest-point/).

#### See also

[PointAccessor](/reference/components/point-series/)

[ResolvedContinuousScale](/reference/functions/utc-domains/)

[nearestPoint](/reference/functions/nearest-point/)

[View source — packages/core/src/features/viz/lib/nearest.ts:11](/source/packages/core/src/features/viz/lib/nearest-ts/#L11)

#### Properties and methods

<span id="api-NearestPointOptions-x"></span>
<details>
<summary>x</summary>


```ts
readonly x: PointAccessor<D>
```

Related API: [PointAccessor](/reference/components/point-series/).

Property key or callback extracting the horizontal domain coordinate. See PointAccessor.

[View source — packages/core/src/features/viz/lib/nearest.ts:13](/source/packages/core/src/features/viz/lib/nearest-ts/#L13)

</details>

<span id="api-NearestPointOptions-y"></span>
<details>
<summary>y</summary>


```ts
readonly y: PointAccessor<D>
```

Related API: [PointAccessor](/reference/components/point-series/).

Property key or callback extracting the vertical domain coordinate. See PointAccessor.

[View source — packages/core/src/features/viz/lib/nearest.ts:15](/source/packages/core/src/features/viz/lib/nearest-ts/#L15)

</details>

<span id="api-NearestPointOptions-xScale"></span>
<details>
<summary>xScale</summary>


```ts
readonly xScale: ResolvedContinuousScale
```

Related API: [ResolvedContinuousScale](/reference/functions/utc-domains/).

The scale used to map horizontal data coordinates. See ResolvedContinuousScale.

[View source — packages/core/src/features/viz/lib/nearest.ts:17](/source/packages/core/src/features/viz/lib/nearest-ts/#L17)

</details>

<span id="api-NearestPointOptions-yScale"></span>
<details>
<summary>yScale</summary>


```ts
readonly yScale: ResolvedContinuousScale
```

Related API: [ResolvedContinuousScale](/reference/functions/utc-domains/).

The scale used to map vertical data coordinates. See ResolvedContinuousScale.

[View source — packages/core/src/features/viz/lib/nearest.ts:19](/source/packages/core/src/features/viz/lib/nearest-ts/#L19)

</details>

<span id="api-NearestPointOptions-defined"></span>
<details>
<summary>defined (optional)</summary>


```ts
readonly defined?: ((datum: D, index: number, data: readonly D[]) => boolean) | undefined
```

Returns whether a datum contributes drawable or queryable coordinates. See
NearestPointOptions.

##### Parameters

- **`datum`** — Datum to test.

- **`index`** — Zero-based index in the source data.

- **`data`** — Complete source data array.

##### Returns

Whether this datum should participate in the series or query.

[View source — packages/core/src/features/viz/lib/nearest.ts:28](/source/packages/core/src/features/viz/lib/nearest-ts/#L28)

</details>

<span id="api-NearestPointOptions-maxDistance"></span>
<details>
<summary>maxDistance (optional)</summary>


```ts
readonly maxDistance?: number | undefined
```

Maximum distance accepted by the query. See NearestPointOptions.

[View source — packages/core/src/features/viz/lib/nearest.ts:30](/source/packages/core/src/features/viz/lib/nearest-ts/#L30)

</details>

<span id="api-NearestPoint"></span>

### NearestPoint

The selected datum, source index, mapped coordinates, and distance from the query point.

```ts
interface NearestPoint<D>
```

Related API: [NearestPoint](/reference/functions/nearest-point/).

#### See also

[nearestPoint](/reference/functions/nearest-point/)

[View source — packages/core/src/features/viz/lib/nearest.ts:37](/source/packages/core/src/features/viz/lib/nearest-ts/#L37)

#### Properties and methods

<span id="api-NearestPoint-datum"></span>
<details>
<summary>datum</summary>


```ts
readonly datum: D
```

The original data item selected by this result. See NearestPoint.

[View source — packages/core/src/features/viz/lib/nearest.ts:39](/source/packages/core/src/features/viz/lib/nearest-ts/#L39)

</details>

<span id="api-NearestPoint-index"></span>
<details>
<summary>index</summary>


```ts
readonly index: number
```

Index of the selected datum in its source data. See NearestPoint.

[View source — packages/core/src/features/viz/lib/nearest.ts:41](/source/packages/core/src/features/viz/lib/nearest-ts/#L41)

</details>

<span id="api-NearestPoint-x"></span>
<details>
<summary>x</summary>


```ts
readonly x: number
```

Horizontal coordinate or displacement in the containing coordinate system. See
NearestPoint.

[View source — packages/core/src/features/viz/lib/nearest.ts:46](/source/packages/core/src/features/viz/lib/nearest-ts/#L46)

</details>

<span id="api-NearestPoint-y"></span>
<details>
<summary>y</summary>


```ts
readonly y: number
```

Vertical coordinate or displacement in the containing coordinate system. See
NearestPoint.

[View source — packages/core/src/features/viz/lib/nearest.ts:51](/source/packages/core/src/features/viz/lib/nearest-ts/#L51)

</details>

<span id="api-NearestPoint-distance"></span>
<details>
<summary>distance</summary>


```ts
readonly distance: number
```

Distance measured in this query or guide's coordinate system. See NearestPoint.

[View source — packages/core/src/features/viz/lib/nearest.ts:53](/source/packages/core/src/features/viz/lib/nearest-ts/#L53)

</details>

## Implementation guidance for agents

Read the [Data visualization companion](/agents/topics/visualization/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Nearest-point lookup](/minimal-examples/viz/nearest/): Locate the nearest observation in pixel and domain space. [Plain source](/minimal/viz/nearest.ts)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.