Struct Capt

Source

pub struct Capt<const K: usize, A = f32, I = usize> { /* private fields */ }

Expand description

A collision-affording point tree (CAPT), which allows for efficient collision-checking in a SIMD-parallel manner between spheres and point clouds.

§Generic parameters

K: The dimension of the space.
L: The lane size of this tree. Internally, this is the upper bound on the width of a SIMD lane that can be used in this data structure. The alignment of this structure must be a power of two.
A: The value of the axes of each point. This should typically be f32 or f64. This should implement Axis.
I: The index integer. This should generally be an unsigned integer, such as usize or u32. This should implement Index.

§Examples

// list of points in cloud
let points = [[0.0, 0.1], [0.4, -0.2], [-0.2, -0.1]];

// query radii must be between 0.0 and 0.2
let t = capt::Capt::<2>::new(&points, (0.0, 0.2));

assert!(!t.collides(&[0.0, 0.3], 0.1));
assert!(t.collides(&[0.0, 0.2], 0.15));

Implementations§

Source §

impl<A, I, const K: usize> Capt<K, A, I>
where A: Axis, I: Index,

Source

pub fn new(points: &[[A; K]], r_range: (A, A), n_lanes: usize) -> Self

Construct a new CAPT containing all the points in points.

r_range is a (minimum, maximum) pair containing the lower and upper bound on the radius of the balls which will be queried against the tree. n_lanes is the number of SIMD lanes to be used by this tree, and may be 1 for single-element batch requests.

§Panics

This function will panic if there are too many points in the tree to be addressed by I, or if any points contain non-finite non-real value. This can even be the case if there are fewer points in points than can be addressed by I as the CAPT may duplicate points for efficiency.

§Examples

let points = [[0.0]];

let capt = capt::Capt::<1>::new(&points, (0.0, f32::INFINITY));

assert!(capt.collides(&[1.0], 1.5));
assert!(!capt.collides(&[1.0], 0.5));

If there are too many points in points, this could cause a panic!

let points = [[0.0]; 256];

// note that we are using `u8` as our index type
let capt = capt::Capt::<1, 8, f32, u8>::new(&points, (0.0, f32::INFINITY));

Source

pub fn with_point_radius( points: &[[A; K]], r_range: (A, A), r_point: A, n_lanes: usize, ) -> Self

Construct a new CAPT containing all the points in points with a point radius r_point.

r_range is a (minimum, maximum) pair containing the lower and upper bound on the radius of the balls which will be queried against the tree. n_lanes is the number of SIMD lanes to be used by this tree, and may be 1 for single-element batch requests.

§Panics

This function will panic if there are too many points in the tree to be addressed by I, or if any points contain non-finite non-real value. This can even be the case if there are fewer points in points than can be addressed by I as the CAPT may duplicate points for efficiency.

§Examples

let points = [[0.0]];

let capt = capt::Capt::<1>::with_point_radius(&points, (0.0, f32::INFINITY), 0.2);

assert!(capt.collides(&[1.0], 1.5));
assert!(!capt.collides(&[1.0], 0.5));

If there are too many points in points, this could cause a panic!

let points = [[0.0]; 256];

// note that we are using `u8` as our index type
let capt = capt::Capt::<1, 8, f32, u8>::with_point_radius(&points, (0.0, f32::INFINITY), 0.2);

Source

pub fn try_new( points: &[[A; K]], r_range: (A, A), n_lanes: usize, ) -> Result<Self, NewCaptError>

Construct a new CAPT containing all the points in points, checking for index overflow.

r_range is a (minimum, maximum) pair containing the lower and upper bound on the radius of the balls which will be queried against the tree. n_lanes is the number of SIMD lanes to be used by this tree, and may be 1 for single-element batch requests.

§Errors

This function will return Err(NewCaptError::TooManyPoints) if there are too many points to be indexed by I. It will return Err(NewCaptError::NonFinite) if any element of points is non-finite.

§Examples

Unwrapping the output from this function is equivalent to calling Capt::new.

let points = [[0.0]];

let capt = capt::Capt::<1>::try_new(&points, (0.0, f32::INFINITY)).unwrap();

In failure, we get an Err.

let points = [[0.0]; 256];

// note that we are using `u8` as our index type
let opt = capt::Capt::<1, 8, f32, u8>::try_new(&points, (0.0, f32::INFINITY));

assert!(opt.is_err());

Source

pub fn try_with_point_radius( points: &[[A; K]], r_range: (A, A), r_point: A, n_lanes: usize, ) -> Result<Self, NewCaptError>

Construct a new CAPT containing all the points in points with a point radius r_point, checking for index overflow.

r_range is a (minimum, maximum) pair containing the lower and upper bound on the radius of the balls which will be queried against the tree. n_lanes is the number of SIMD lanes to be used by this tree, and may be 1 for single-element batch requests.

§Errors

This function will return Err(NewCaptError::TooManyPoints) if there are too many points to be indexed by I. It will return Err(NewCaptError::NonFinite) if any element of points is non-finite.

§Examples

Unwrapping the output from this function is equivalent to calling Capt::with_point_radius.

let points = [[0.0]];

let capt = capt::Capt::<1>::try_with_point_radius(&points, (0.0, f32::INFINITY), 0.01).unwrap();

In failure, we get an Err.

let points = [[0.0]; 256];

// note that we are using `u8` as our index type
let opt =
    capt::Capt::<1, 8, f32, u8>::try_with_point_radius(&points, (0.0, f32::INFINITY), 0.01);

assert!(opt.is_err());

Source

pub fn collides(&self, center: &[A; K], radius: A) -> bool

Determine whether a point in this tree is within a distance of radius to center.

Note that this function will accept query radii outside of the range r_range passed to the construction for this CAPT in Capt::new or Capt::try_new. However, if the query radius is outside this range, the tree may erroneously return false (that is, erroneously report non-collision).

§Examples

let points = [[0.0; 3], [1.0; 3], [0.1, 0.5, 1.0]];
let capt = capt::Capt::<3>::new(&points, (0.0, 1.0));

assert!(capt.collides(&[1.1; 3], 0.2));
assert!(!capt.collides(&[2.0; 3], 1.0));

// no guarantees about what this is, since the radius is greater than the construction range
println!(
    "collision check result is {:?}",
    capt.collides(&[100.0; 3], 100.0)
);