Struct SpatialIndexN 

pub struct SpatialIndexN<const D: usize, T> { /* private fields */ }

A spatial index backed by an R-tree for efficient region and nearest-neighbor queries in D-dimensional space.

Implementations

impl<const D: usize, T> SpatialIndexN<D, T>

pub const fn new() -> Self

Creates a new, empty spatial index with default configuration.

pub const fn with_config(config: SpatialConfig) -> Self

Creates a new, empty spatial index with the given configuration.

pub const fn config(&self) -> SpatialConfig

Returns the configuration used by this index.

pub fn insert(&mut self, entry: SpatialEntryN<D, T>)

Inserts an entry into the index.

pub fn remove<F>( &mut self, region: BoundingBoxN<D>, pred: F, ) -> Result<(), SpatialError>

where F: Fn(&SpatialEntryN<D, T>) -> bool,

Removes the first entry whose bounding box and data match the predicate.

The region hint narrows the search to nodes overlapping it. After removal, underflowing nodes are condensed and their entries reinserted to maintain tree quality (Guttman’s condense_tree).

Errors

Returns SpatialError::NotFound if no matching entry exists.

pub fn query_region(&self, region: BoundingBoxN<D>) -> Vec<&SpatialEntryN<D, T>>

Returns all entries whose bounding box intersects region.

pub fn query_nearest_nd( &self, point: [f32; D], k: usize, ) -> Vec<&SpatialEntryN<D, T>>

Returns the k entries nearest to point, ordered nearest-first.

Distance is measured from the query point to the nearest edge of each entry’s bounding box. If fewer than k entries exist, all are returned.

pub fn query_nearest_by_centroid_nd( &self, point: [f32; D], k: usize, ) -> Vec<&SpatialEntryN<D, T>>

Returns the k entries whose bounding-box center is nearest to point, ordered nearest-first.

Unlike query_nearest_nd, which measures to the bbox edge (returning 0 for elements containing the point), this measures to each element’s centroid. Large containers whose center is far from the query point are naturally deprioritized.

pub fn query_within_radius_nd( &self, point: [f32; D], r: f32, ) -> Vec<&SpatialEntryN<D, T>>

Returns all entries within r of point, sorted nearest-first.

Returns an empty vector if r < 0.0.

pub fn query_within_radius_with_distances_nd( &self, point: [f32; D], r: f32, ) -> Vec<(&SpatialEntryN<D, T>, f32)>

Returns all entries within r of point with their distances, sorted nearest-first.

Each tuple contains (entry, distance) where distance is measured from the query point to the nearest edge of the bounding box (0 when inside). Returns an empty vector if r < 0.0.

pub const fn len(&self) -> usize

Returns the number of entries in the index.

pub const fn is_empty(&self) -> bool

Returns true if the index contains no entries.

pub fn clear(&mut self)

Removes all entries from the index.

pub fn bulk_load(entries: Vec<SpatialEntryN<D, T>>) -> Self

Builds a spatial index from a pre-collected set of entries using the Sort-Tile-Recursive (STR) bulk-loading algorithm.

The resulting tree has tighter bounding boxes and less overlap than one-at-a-time insertion, yielding better query performance for static datasets. The index can still be modified with insert and remove afterwards.

pub fn bulk_load_with_config( entries: Vec<SpatialEntryN<D, T>>, config: SpatialConfig, ) -> Self

Builds a spatial index with the given configuration using the Sort-Tile-Recursive (STR) bulk-loading algorithm.

pub fn iter(&self) -> SpatialIterN<'_, D, T>

Returns an iterator over references to all entries in the index.

impl<T> SpatialIndexN<2, T>

pub fn query_nearest( &self, x: f32, y: f32, k: usize, ) -> Vec<&SpatialEntryN<2, T>>

Returns the k entries nearest to the point (x, y), ordered from nearest to farthest.

Distance is measured from the query point to the nearest edge of each entry’s bounding box. Elements containing the query point have distance 0. If fewer than k entries exist, all entries are returned.

pub fn query_nearest_by_centroid( &self, x: f32, y: f32, k: usize, ) -> Vec<&SpatialEntryN<2, T>>

Returns the k entries whose bounding-box center is nearest to the point (x, y), ordered nearest-first.

Unlike query_nearest, which measures to the bbox edge, this measures to each element’s centroid so that large containers are naturally deprioritized.

pub fn query_within_radius( &self, x: f32, y: f32, r: f32, ) -> Vec<&SpatialEntryN<2, T>>

Returns all entries within r pixels of the point (x, y), sorted nearest-first by edge distance.

Distance is measured from the query point to the nearest edge of each entry’s bounding box. Elements containing the query point have distance 0. Returns an empty vector if r < 0.0.

pub fn query_within_radius_with_distances( &self, x: f32, y: f32, r: f32, ) -> Vec<(&SpatialEntryN<2, T>, f32)>

Returns all entries within r pixels of the point (x, y) with their distances, sorted nearest-first.

Each tuple contains (entry, distance) where distance is measured from the query point to the nearest edge of the bounding box (0 when inside). Returns an empty vector if r < 0.0.

impl<T> SpatialIndexN<3, T>

pub fn query_nearest( &self, x: f32, y: f32, z: f32, k: usize, ) -> Vec<&SpatialEntryN<3, T>>

Returns the k entries nearest to the point (x, y, z), ordered from nearest to farthest.

Distance is measured from the query point to the nearest edge of each entry’s bounding box. Elements containing the query point have distance 0. If fewer than k entries exist, all entries are returned.

pub fn query_nearest_by_centroid( &self, x: f32, y: f32, z: f32, k: usize, ) -> Vec<&SpatialEntryN<3, T>>

Returns the k entries whose bounding-box center is nearest to the point (x, y, z), ordered nearest-first.

Unlike query_nearest, which measures to the bbox edge, this measures to each element’s centroid so that large containers are naturally deprioritized.

pub fn query_within_radius( &self, x: f32, y: f32, z: f32, r: f32, ) -> Vec<&SpatialEntryN<3, T>>

Returns all entries within r units of the point (x, y, z), sorted nearest-first by edge distance.

Distance is measured from the query point to the nearest edge of each entry’s bounding box. Elements containing the query point have distance 0. Returns an empty vector if r < 0.0.

pub fn query_within_radius_with_distances( &self, x: f32, y: f32, z: f32, r: f32, ) -> Vec<(&SpatialEntryN<3, T>, f32)>

Returns all entries within r units of the point (x, y, z) with their distances, sorted nearest-first.

Each tuple contains (entry, distance) where distance is measured from the query point to the nearest edge of the bounding box (0 when inside). Returns an empty vector if r < 0.0.

Trait Implementations

impl<const D: usize, T: Clone> Clone for SpatialIndexN<D, T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const D: usize, T> Default for SpatialIndexN<D, T>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, const D: usize, T: Deserialize<'de>> Deserialize<'de> for SpatialIndexN<D, T>

fn deserialize<De: Deserializer<'de>>( deserializer: De, ) -> Result<Self, De::Error>

Deserialize this value from the given Serde deserializer.

impl<'a, const D: usize, T> IntoIterator for &'a SpatialIndexN<D, T>

type Item = &'a SpatialEntryN<D, T>

The type of the elements being iterated over.

type IntoIter = SpatialIterN<'a, D, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<const D: usize, T: Serialize> Serialize for SpatialIndexN<D, T>

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.