Function point_cuboid_find_local_separating_normal_oneway

pub fn point_cuboid_find_local_separating_normal_oneway(
    point1: Point<f32>,
    normal1: Option<Unit<Vector<f32>>>,
    shape2: &Cuboid,
    pos12: &Isometry<f32>,
) -> (f32, Vector<f32>)

Computes the separation distance between a point and a cuboid along a specified normal direction.

This function is used in SAT (Separating Axis Theorem) implementations for shapes that can be treated as having a single representative point with an associated normal vector. Examples include:

• Segments (in 2D, using one endpoint and the segment’s normal)
• Triangles (in 3D, using one vertex and the triangle’s face normal)

Why This Works

For a cuboid centered at the origin with symmetry, we only need to test one direction of the normal (not both +normal and -normal) because the cuboid looks the same from both directions. This optimization makes the function more efficient than the general support map approach.

Parameters

• point1: A point in the first shape’s local coordinate space
• normal1: Optional unit normal vector associated with the point (e.g., triangle face normal)
  • If None, the function returns maximum negative separation (indicating overlap)
• shape2: The cuboid to test against
• pos12: The position of shape2 (cuboid) relative to point1’s coordinate frame

Returns

A tuple containing:

• Real: The separation distance along the normal direction
  • Positive: The point and cuboid are separated
  • Negative: The point penetrates the cuboid (or normal is None)
  • Zero: The point exactly touches the cuboid surface
• Vector<Real>: The oriented normal direction used for the test (pointing from point toward cuboid)

Example

use parry2d::shape::Cuboid;
use parry2d::query::sat::point_cuboid_find_local_separating_normal_oneway;
use nalgebra::{Point2, Vector2, Isometry2, Unit};

let point = Point2::origin();
let normal = Some(Unit::new_normalize(Vector2::x()));
let cuboid = Cuboid::new(Vector2::new(1.0, 1.0));

// Position cuboid 3 units to the right
let pos12 = Isometry2::translation(3.0, 0.0);

let (separation, _dir) = point_cuboid_find_local_separating_normal_oneway(
    point,
    normal,
    &cuboid,
    &pos12
);

// Should be separated by 1.0 (distance 3.0 - cuboid extent 1.0 - point distance 0.0)
assert!(separation > 0.0);

Implementation Note

This function only works correctly when the cuboid is on the right-hand side (as shape2) because it exploits the cuboid’s symmetry around the origin. The cuboid must be centered at its local origin for this optimization to be valid.