Trait PointQuery

Source

pub trait PointQuery {
    // Required methods
    fn project_local_point(&self, pt: Vector, solid: bool) -> PointProjection;
    fn project_local_point_and_get_feature(
        &self,
        pt: Vector,
    ) -> (PointProjection, FeatureId);

    // Provided methods
    fn project_local_point_with_max_dist(
        &self,
        pt: Vector,
        solid: bool,
        max_dist: f32,
    ) -> Option<PointProjection> { ... }
    fn project_point_with_max_dist(
        &self,
        m: &Pose,
        pt: Vector,
        solid: bool,
        max_dist: f32,
    ) -> Option<PointProjection> { ... }
    fn distance_to_local_point(&self, pt: Vector, solid: bool) -> f32 { ... }
    fn contains_local_point(&self, pt: Vector) -> bool { ... }
    fn project_point(
        &self,
        m: &Pose,
        pt: Vector,
        solid: bool,
    ) -> PointProjection { ... }
    fn distance_to_point(&self, m: &Pose, pt: Vector, solid: bool) -> f32 { ... }
    fn project_point_and_get_feature(
        &self,
        m: &Pose,
        pt: Vector,
    ) -> (PointProjection, FeatureId) { ... }
    fn contains_point(&self, m: &Pose, pt: Vector) -> bool { ... }
}

Expand description

Trait for shapes that support point projection and containment queries.

This trait provides methods to:

Project points onto the shape’s surface
Calculate distance from a point to the shape
Test if a point is inside the shape

All major shapes implement this trait, making it easy to perform point queries on any collision shape.

§Methods Overview

Projection: project_point(), project_local_point()
Distance: distance_to_point(), distance_to_local_point()
Containment: contains_point(), contains_local_point()

§Local vs World Space

Methods with local_ prefix work in the shape’s local coordinate system:

Local methods: Vector must be in shape’s coordinate frame
World methods: Vector in world space, shape transformation applied

§Solid Parameter

The solid parameter affects how interior points are handled:

solid = true: Shape is filled (has interior volume/area)
solid = false: Shape is hollow (surface only, no interior)

§Example

use parry3d::query::PointQuery;
use parry3d::shape::Cuboid;
use parry3d::math::{Vector, Pose};

let cuboid = Cuboid::new(Vector::splat(1.0));
let cuboid_pos = Pose::translation(5.0, 0.0, 0.0);

let query_point = Vector::ZERO;

// Project point onto cuboid surface
let projection = cuboid.project_point(&cuboid_pos, query_point, true);
println!("Closest point on cuboid: {:?}", projection.point);
println!("Is inside: {}", projection.is_inside);

// Calculate distance to cuboid
let distance = cuboid.distance_to_point(&cuboid_pos, query_point, true);
println!("Distance: {}", distance);

// Test if point is inside cuboid
let is_inside = cuboid.contains_point(&cuboid_pos, query_point);
println!("Contains: {}", is_inside);

Required Methods§

Source

fn project_local_point(&self, pt: Vector, solid: bool) -> PointProjection

Projects a point on self.

The point is assumed to be expressed in the local-space of self.

Source

fn project_local_point_and_get_feature( &self, pt: Vector, ) -> (PointProjection, FeatureId)

Projects a point on the boundary of self and returns the id of the feature the point was projected on.

Provided Methods§

Source

fn project_local_point_with_max_dist( &self, pt: Vector, solid: bool, max_dist: f32, ) -> Option<PointProjection>

Projects a point onto the shape, with a maximum distance limit.

Returns None if the projection would be further than max_dist from the query point. This is useful for optimization when you only care about nearby projections.

The point is in the shape’s local coordinate system.

§Arguments

pt - The point to project (in local space)
solid - Whether to treat the shape as solid (filled)
max_dist - Maximum distance to consider

§Example

use parry3d::query::PointQuery;
use parry3d::shape::Ball;
use parry3d::math::Vector;

let ball = Ball::new(1.0);
let far_point = Vector::new(100.0, 0.0, 0.0);

// Projection exists but is far away
assert!(ball.project_local_point(far_point, true).point.x > 0.0);

// With max distance limit of 10, projection is rejected
assert!(ball.project_local_point_with_max_dist(far_point, true, 10.0).is_none());

// Nearby point is accepted
let near_point = Vector::new(2.0, 0.0, 0.0);
assert!(ball.project_local_point_with_max_dist(near_point, true, 10.0).is_some());