Function cuboid_support_map_compute_separation_wrt_local_line

pub fn cuboid_support_map_compute_separation_wrt_local_line(
    cube1: &Cuboid,
    shape2: &impl SupportMap,
    pos12: &Isometry<f32>,
    axis1: &Unit<Vector<f32>>,
) -> (f32, Unit<Vector<f32>>)

Computes the separation distance between a cuboid and a convex support map shape along a given axis.

This function tests both the positive and negative directions of the axis to find which orientation gives the actual separation between the shapes. This is necessary because we don’t know in advance which direction will show the true separation.

Parameters

• cube1: The cuboid
• shape2: Any convex shape implementing SupportMap (sphere, capsule, convex mesh, etc.)
• pos12: The position of shape2 relative to cube1
• axis1: The unit direction vector (in cube1’s local space) to test

Returns

A tuple containing:

• Real: The separation distance along the better of the two axis directions
  • Positive: Shapes are separated
  • Negative: Shapes are overlapping
• Unit<Vector<Real>>: The axis direction (either axis1 or -axis1) that gives this separation

Why Test Both Directions?

When testing separation along an axis, we need to check both axis1 and -axis1 because:

• The shapes might be oriented such that one direction shows separation while the other shows overlap
• We want to find the direction that gives the maximum (least negative) separation

For symmetric shapes like sphere vs sphere, both directions give the same result, but for asymmetric configurations, testing both is necessary for correctness.

Example

use parry3d::shape::{Cuboid, Ball};
use parry3d::query::sat::cuboid_support_map_compute_separation_wrt_local_line;
use nalgebra::{Isometry3, Vector3, Unit};

let cube = Cuboid::new(Vector3::new(1.0, 1.0, 1.0));
let sphere = Ball::new(0.5);

// Position sphere near the cube
let pos12 = Isometry3::translation(2.0, 0.0, 0.0);

// Test separation along an arbitrary axis
let axis = Unit::new_normalize(Vector3::new(1.0, 1.0, 0.0));
let (separation, chosen_axis) = cuboid_support_map_compute_separation_wrt_local_line(
    &cube,
    &sphere,
    &pos12,
    &axis
);

println!("Separation: {} along axis: {:?}", separation, chosen_axis);

Performance Note

This is a relatively expensive operation as it computes support points in both directions. For specific shape pairs (like cuboid-cuboid), there are optimized versions that avoid this double computation.