[−][src]Trait rstar::PointDistance

```pub trait PointDistance: RTreeObject {
fn distance_2(        &self,         point: &<Self::Envelope as Envelope>::Point    ) -> <<Self::Envelope as Envelope>::Point as Point>::Scalar;

fn contains_point(        &self,         point: &<Self::Envelope as Envelope>::Point    ) -> bool { ... }
fn distance_2_if_less_or_equal(        &self,         point: &<Self::Envelope as Envelope>::Point,         max_distance_2: <<Self::Envelope as Envelope>::Point as Point>::Scalar    ) -> Option<<<Self::Envelope as Envelope>::Point as Point>::Scalar> { ... }
}```

Defines objects which can calculate their minimal distance to a point.

This trait is most notably necessary for support of nearest_neighbor queries.

Example

```use rstar::{RTreeObject, PointDistance, AABB};

struct Circle
{
origin: [f32; 2],
}

impl RTreeObject for Circle {
type Envelope = AABB<[f32; 2]>;

fn envelope(&self) -> Self::Envelope {
AABB::from_corners(corner_1, corner_2)
}
}

impl PointDistance for Circle
{
fn distance_2(&self, point: &[f32; 2]) -> f32
{
let d_x = self.origin[0] - point[0];
let d_y = self.origin[1] - point[1];
let distance_to_origin = (d_x * d_x + d_y * d_y).sqrt();
let distance_to_ring = distance_to_origin - self.radius;
let distance_to_circle = f32::max(0.0, distance_to_ring);
// We must return the squared distance!
distance_to_circle * distance_to_circle
}

// This implementation is not required but more efficient since it
// omits the calculation of a square root
fn contains_point(&self, point: &[f32; 2]) -> bool
{
let d_x = self.origin[0] - point[0];
let d_y = self.origin[1] - point[1];
let distance_to_origin_2 = (d_x * d_x + d_y * d_y);
}
}

fn main() {
let circle = Circle {
origin: [1.0, 0.0],
};

assert_eq!(circle.distance_2(&[-1.0, 0.0]), 1.0);
assert_eq!(circle.distance_2(&[-2.0, 0.0]), 4.0);
assert!(circle.contains_point(&[1.0, 0.0]));
}```

Required methods

`fn distance_2(    &self,     point: &<Self::Envelope as Envelope>::Point) -> <<Self::Envelope as Envelope>::Point as Point>::Scalar`

Returns the squared euclidean distance of an object to a point.

Provided methods

`fn contains_point(&self, point: &<Self::Envelope as Envelope>::Point) -> bool`

Returns true if a point is contained within this object.

By default, any point returning a `distance_2` less than or equal to zero is considered to be contained within `self`. Changing this default behavior is advised if calculating the squared distance is more computational expensive a point containment check.

`fn distance_2_if_less_or_equal(    &self,     point: &<Self::Envelope as Envelope>::Point,     max_distance_2: <<Self::Envelope as Envelope>::Point as Point>::Scalar) -> Option<<<Self::Envelope as Envelope>::Point as Point>::Scalar>`

Returns the squared distance to this object or `None` if the distance is larger than a given maximum value.

Some algorithms do need to know an object's distance only if it is less than or equal to a maximum value. In these cases, it may be faster to calculate a lower bound of the distance first and returning early if the object cannot be closer than the given maximum.

The provided default implementation will use the distance to the object's envelope as a lower bound.

If performance is critical and the object's distance calculation is fast, it may be beneficial to overwrite this implementation.