chrono::collision::ch_utils Namespace Reference

Description

Utilities for Chrono multicore collision detection.

Functions

Hashing functions
template<class T >
vec3 HashMin (const T &A, const real3 &inv_bin_size_vec)
 Convert a position into bin coordinates ("lower" corner).
 
template<class T >
vec3 HashMax (const T &A, const real3 &inv_bin_size_vec)
 Convert a position into bin coordinates ("upper" corner).
 
uint Hash_Index (const vec3 &A, const vec3 &bins_per_axis)
 Convert bin coordinates into a unique bin index value.
 
vec3 Hash_Decode (uint hash, const vec3 &bins_per_axis)
 Decode a bin index into its associated bin coordinates.
 
AABB collision functions
bool collide (const short2 &fam_data_A, const short2 &fam_data_B)
 Check if two bodies interact using their collision family data.
 
bool overlap (const real3 &Amin, const real3 &Amax, const real3 &Bmin, const real3 &Bmax)
 Check if two AABBs overlap using their min/max corners.
 
bool current_bin (const real3 &Amin, const real3 &Amax, const real3 &Bmin, const real3 &Bmax, const real3 &inv_bin_size_vec, const vec3 &bins_per_axis, uint bin)
 
Utility functions for broadphase
ChApi vec3 Compute_Grid_Resolution (uint num_aabb, const real3 &d, real k)
 Compute broadphase grid resolution, given the total number of AABBs, the grid dimension (diagonal), and the desired density.
 
ChApi void f_Count_AABB_BIN_Intersection (const uint index, const real3 &inv_bin_size, const std::vector< real3 > &aabb_min, const std::vector< real3 > &aabb_max, std::vector< uint > &bins_intersected)
 Function to Count AABB-Bin intersections.
 
ChApi void f_Store_AABB_BIN_Intersection (const uint index, const vec3 &bins_per_axis, const real3 &inv_bin_size, const std::vector< real3 > &aabb_min_data, const std::vector< real3 > &aabb_max_data, const std::vector< uint > &bins_intersected, std::vector< uint > &bin_number, std::vector< uint > &aabb_number)
 Function to Store AABB-Bin Intersections.
 
ChApi void f_Count_AABB_AABB_Intersection (const uint index, const real3 inv_bin_size_vec, const vec3 bins_per_axis, const std::vector< real3 > &aabb_min_data, const std::vector< real3 > &aabb_max_data, const std::vector< uint > &bin_number, const std::vector< uint > &aabb_number, const std::vector< uint > &bin_start_index, const std::vector< short2 > &fam_data, const std::vector< char > &body_active, const std::vector< char > &body_collide, const std::vector< uint > &body_id, std::vector< uint > &num_contact)
 Function to count AABB-AABB intersection.
 
ChApi void f_Store_AABB_AABB_Intersection (const uint index, const real3 inv_bin_size_vec, const vec3 bins_per_axis, const std::vector< real3 > &aabb_min_data, const std::vector< real3 > &aabb_max_data, const std::vector< uint > &bin_number, const std::vector< uint > &aabb_number, const std::vector< uint > &bin_start_index, const std::vector< uint > &num_contact, const std::vector< short2 > &fam_data, const std::vector< char > &body_active, const std::vector< char > &body_collide, const std::vector< uint > &body_id, std::vector< long long > &potential_contacts)
 Function to store AABB-AABB intersections.
 
Utility functions for MPR narrowphase
real3 GetSupportPoint_Sphere (const real radius, const real3 &n)
 Support point for a sphere (for GJK and MPR).
 
real3 GetSupportPoint_Triangle (const real3 *t, const real3 &n)
 Support point for a triangle (for GJK and MPR).
 
real3 GetSupportPoint_Box (const real3 &B, const real3 &n)
 Support point for a box (for GJK and MPR).
 
real3 GetSupportPoint_Ellipsoid (const real3 &B, const real3 &n)
 Support point for an ellipsoid (for GJK and MPR).
 
real3 GetSupportPoint_Cylinder (const real3 &B, const real3 &n)
 Support point for a cylinder (for GJK and MPR).
 
real3 GetSupportPoint_Plane (const real3 &B, const real3 &n)
 Support point for a plane (for GJK and MPR).
 
real3 GetSupportPoint_Cone (const real3 &B, const real3 &n)
 Support point for a cone (for GJK and MPR).
 
real3 GetSupportPoint_Seg (const real B, const real3 &n)
 Support point for a line segment (for GJK and MPR).
 
real3 GetSupportPoint_Capsule (const real2 &B, const real3 &n)
 Support point for a capsule (for GJK and MPR).
 
real3 GetSupportPoint_Disk (const real B, const real3 &n)
 Support point for a disk (for GJK and MPR).
 
real3 GetSupportPoint_Rect (const real3 &B, const real3 &n)
 Support point for a rectangle (for GJK and MPR).
 
real3 GetSupportPoint_RoundedBox (const real4 &B, const real3 &n)
 Support point for a rounded box, i.e. a sphere-swept box (for GJK and MPR).
 
real3 GetSupportPoint_RoundedCylinder (const real4 &B, const real3 &n)
 Support point for a rounded cylinder, i.e. a sphere-swept cylinder (for GJK and MPR).
 
real3 GetSupportPoint_CylindricalShell (const real3 &B, const real3 &n)
 Support point for a cylindrical shell (for GJK and MPR).
 
real3 GetSupportPoint_RoundedCone (const real4 &B, const real3 &n)
 Support point for a rounded cone, i.e. a sphere-swept cone (for GJK and MPR).
 
real3 GetSupportPoint_Convex (const int size, const real3 *convex_data, const real3 &n)
 Support point for a generic convex shape (for GJK and MPR).
 
real3 GetSupportPoint_Tetrahedron (const uvec4 &indices, const real3 *nodes, const real3 &n)
 Support point for a tetrahedron (for GJK and MPR).
 
real3 GetCenter_Sphere ()
 
real3 GetCenter_Triangle (const real3 *t)
 
real3 GetCenter_Box ()
 
real3 GetCenter_Ellipsoid ()
 
real3 GetCenter_Cylinder ()
 
real3 GetCenter_Plane ()
 
real3 GetCenter_Cone (const real3 &B)
 
real3 GetCenter_Convex (const int size, const real3 *convex_data)
 
real3 GetCenter_Tetrahedron (const uvec4 &indices, const real3 *nodes)
 
ChApi real3 SupportVertNoMargin (const chrono::collision::ConvexBase *Shape, const real3 &nv, const real &envelope)
 
ChApi real3 LocalSupportVert (const chrono::collision::ConvexBase *Shape, const real3 &n, const real &envelope)
 
ChApi real3 TransformSupportVert (const chrono::collision::ConvexBase *Shape, const real3 &n, const real &envelope)
 
ChApi bool snap_to_triangle_bary (const real3 &A, const real3 &B, const real3 &C, const real3 &P, real3 &res, real3 &barycentric)
 This utility function takes the location 'P' and snaps it to the closest point on the triangular face with given vertices (A, B, and C). More...
 
ChApi void FindTriIndex (const real3 &P, const uvec4 &T, const real3 *pos_node, int &face, real3 &cb)
 Given a contact point P and a tetrahedron T compute the closest triangle to that point.
 
Utility functions for PRIMS narrowphase.
real3 triangle_normal (const real3 &A, const real3 &B, const real3 &C)
 This utility function returns the normal to the triangular face defined by the vertices A, B, and C. More...
 
ChApi bool snap_to_triangle (const real3 &A, const real3 &B, const real3 &C, const real3 &P, real3 &res)
 This utility function takes the location 'P' and snaps it to the closest point on the triangular face with given vertices (A, B, and C). More...
 
ChApi bool point_in_triangle (const real3 &A, const real3 &B, const real3 &C, const real3 &loc)
 This utility function returns a boolean indicating whether or not the specified 'loc' is inside the given triangle (with vertices A, B, C and outwards 'normal'). More...
 
uint snap_to_cylinder (const real &rad, const real &hlen, real3 &loc)
 This utility function snaps the specified location to a point on a cylinder with given radius and half-length. More...
 
uint box_closest_feature (const real3 &dir, const real3 &hdims)
 This utility function returns a code that indicates the closest feature of a box in the specified direction. More...
 
uint snap_to_box (const real3 &hdims, real3 &loc)
 This utility function snaps the specified location to a point on a box with given half-dimensions. More...
 
real3 snap_to_box_face (const real3 &hdims, const real3 &pt_on_box, uint code, const real3 &pt_to_snap)
 This utility function snaps the location 'pt_to_snap' to a location on the face of this box identified by the specified 'code' and 'pt_on_box'. More...
 
real3 snap_to_box_edge (const real3 &hdims, const real3 &pt_on_box, uint code, const real3 &pt_to_snap)
 This utility function snaps the location 'pt_to_snap' to a location on the edge of this box identified by the specified 'code' and 'pt_on_box'. More...
 
void get_edge_corners (const real3 &pt_on_edge, uint code, real3 *corners)
 This utility function fill out 'corners' with the corners of the box edge specified by 'code' and 'pt_on_edge'. More...
 
void get_face_corners (const real3 &pt_on_face, uint code, real3 *corners)
 This utility function fill out 'corners' with the corners of the face specified by 'code' and 'pt_on_face'. More...
 
real3 get_face_normal (const real3 &pt_on_face, uint code)
 This utility function returns the box face normal (expressed in the box local frame) for the face specified by 'code' and 'pt_on_face'. More...
 
ChApi bool point_vs_face (const real3 &hdims, const real3 &pt_on_face, uint code, const real3 &point, const real &separation, real3 &result, real3 &normal, real &dist)
 This utility function returns true if 'point' is no farther than 'separation' from the face of this box identified by 'pt_on_face' and 'code'; and returns false otherwise. More...
 
ChApi bool segment_vs_edge (const real3 &hdims, const real3 &pt_on_edge, uint code, const real3 &pt1, const real3 &pt2, real3 &locE, real3 &locS)
 This utility function calculates the closest points between the box edge identified by 'pt_on_edge' and 'code' and a line segment between 'pt1' and 'pt2'. More...
 
real3 box_farthest_corner (const real3 &hdims, const real3 &dir)
 This utility function returns the corner of a box of given dimensions that is farthest in the direction 'dir', which is assumed to be given in the frame of the box.
 
real3 box_closest_corner (const real3 &hdims, const real3 &dir)
 This utility function returns the corner of a box of given dimensions that is closest in the direction 'dir', which is assumed to be given in the frame of the box.
 
ChApi int box_intersects_box (const real3 &hdims1, const real3 &hdims2, const real3 &pos, const quaternion &rot, real separation, real3 &dir)
 This function returns an integer indicating whether or not a box1 with dimensions hdims1 intersects (or is close enough to) a second box with dimensions hdims2. More...
 
ChApi int box_intersects_triangle (const real3 &hdims, const real3 &v0, const real3 &v1, const real3 &v2, real separation)
 This function returns an integer indicating whether or not a box with dimensions hdims intersects (or is close enough to) a triangle given by its vertices v0, v1, v2. More...
 

Function Documentation

◆ box_closest_feature()

uint chrono::collision::ch_utils::box_closest_feature ( const real3 dir,
const real3 hdims 
)
inline

This utility function returns a code that indicates the closest feature of a box in the specified direction.

The direction 'dir' is assumed to be given in the frame of the box. The return code encodes the box axes that define the closest feature:

  • first bit (least significant) corresponds to x-axis
  • second bit corresponds to y-axis
  • third bit corresponds to z-axis

Therefore:

  • code = 0 indicates a degenerate direction (within a threshold)
  • code = 1 or code = 2 or code = 4 indicates a face
  • code = 3 or code = 5 or code = 6 indicates an edge
  • code = 7 indicates a corner

◆ box_intersects_box()

int chrono::collision::ch_utils::box_intersects_box ( const real3 hdims1,
const real3 hdims2,
const real3 pos,
const quaternion rot,
real  separation,
real3 dir 
)

This function returns an integer indicating whether or not a box1 with dimensions hdims1 intersects (or is close enough to) a second box with dimensions hdims2.

The check is performed in the local frame of box1. The transform from the other box is given through 'pos' and 'rot'.

The return value is -1 if the two boxes overlap, +1 if they are within a distance of 'separation' from each other, and 0 if they are "far" from each other. If returning -1 or +1, 'dir' contains the direction of smallest intersection (or closest separation).

This check is performed by testing 15 possible separating planes between the two boxes (Gottschalk, Lin, Manocha - Siggraph96).

If not considering a separation value, the 15 tests use an overlap of the form: overlap = r1 + r2 - D, where r1 and r2 are the half-projections of the two boxes on the current direction and D is the projected distance between the box centers. If there's no overlap (overlap <= 0) in any direction, then the boxes do not intersect. Otherwise, we keep track of the direction of minimum overlap.

If considering a separation > 0, we simply use an overlap of the form: overlap = r1 + r2 - D + separation and use the exact same checks.

◆ box_intersects_triangle()

int chrono::collision::ch_utils::box_intersects_triangle ( const real3 hdims,
const real3 v0,
const real3 v1,
const real3 v2,
real  separation 
)

This function returns an integer indicating whether or not a box with dimensions hdims intersects (or is close enough to) a triangle given by its vertices v0, v1, v2.

The check is performed in the box frame and it is assumed that the triangle vertices are expressed in the box frame.

The return value is -1 if the box and triangle overlap, +1 if they are within a distance of 'separation' from each other, and 0 if they are "far" from each other.

This check is performed by testing 13 possible separating planes between the box and triangle (see Ericson).

◆ get_edge_corners()

void chrono::collision::ch_utils::get_edge_corners ( const real3 pt_on_edge,
uint  code,
real3 corners 
)
inline

This utility function fill out 'corners' with the corners of the box edge specified by 'code' and 'pt_on_edge'.

See box_closest_feature for definition of 'code.

◆ get_face_corners()

void chrono::collision::ch_utils::get_face_corners ( const real3 pt_on_face,
uint  code,
real3 corners 
)
inline

This utility function fill out 'corners' with the corners of the face specified by 'code' and 'pt_on_face'.

See box_closest_feature for definition of 'code.

◆ get_face_normal()

real3 chrono::collision::ch_utils::get_face_normal ( const real3 pt_on_face,
uint  code 
)
inline

This utility function returns the box face normal (expressed in the box local frame) for the face specified by 'code' and 'pt_on_face'.

See box_closest_feature for definition of 'code.

◆ point_in_triangle()

bool chrono::collision::ch_utils::point_in_triangle ( const real3 A,
const real3 B,
const real3 C,
const real3 loc 
)

This utility function returns a boolean indicating whether or not the specified 'loc' is inside the given triangle (with vertices A, B, C and outwards 'normal').

Locations on a triangle edge are considered to be inside.

◆ point_vs_face()

bool chrono::collision::ch_utils::point_vs_face ( const real3 hdims,
const real3 pt_on_face,
uint  code,
const real3 point,
const real &  separation,
real3 result,
real3 normal,
real &  dist 
)

This utility function returns true if 'point' is no farther than 'separation' from the face of this box identified by 'pt_on_face' and 'code'; and returns false otherwise.

If the point is close enough, its projection onto the box face is returned in 'result' and the height of the point relative to the box face is returned in 'dist' (with a negative value indicating penetration, i.e. the point inside the box). 'normal' is set to the box face (pointing outwards). See box_closest_feature for definition of 'code.

◆ segment_vs_edge()

bool chrono::collision::ch_utils::segment_vs_edge ( const real3 hdims,
const real3 pt_on_edge,
uint  code,
const real3 pt1,
const real3 pt2,
real3 locE,
real3 locS 
)

This utility function calculates the closest points between the box edge identified by 'pt_on_edge' and 'code' and a line segment between 'pt1' and 'pt2'.

It returns true if the closest points are within the extent of the edge and the segment, respecively, and false otherwise. The closest points are returned in 'locE' and 'locS', respectively. This function uses the parametric solution of the two support lines to solve for the closest points, simplified as we work in the local frame of the box. See box_closest_feature for definition of 'code.

◆ snap_to_box()

uint chrono::collision::ch_utils::snap_to_box ( const real3 hdims,
real3 loc 
)
inline

This utility function snaps the specified location to a point on a box with given half-dimensions.

The in/out location is assumed to be specified in the frame of the box (which is therefore assumed to be an AABB centered at the origin). The return code indicates the box axes that caused snapping.

  • first bit (least significant) corresponds to x-axis
  • second bit corresponds to y-axis
  • third bit corresponds to z-axis

Therefore:

  • code = 0 indicates an interior point
  • code = 1 or code = 2 or code = 4 indicates snapping to a face
  • code = 3 or code = 5 or code = 6 indicates snapping to an edge
  • code = 7 indicates snapping to a corner

◆ snap_to_box_edge()

real3 chrono::collision::ch_utils::snap_to_box_edge ( const real3 hdims,
const real3 pt_on_box,
uint  code,
const real3 pt_to_snap 
)
inline

This utility function snaps the location 'pt_to_snap' to a location on the edge of this box identified by the specified 'code' and 'pt_on_box'.

The resulting location is returned. See box_closest_feature for definition of 'code.

◆ snap_to_box_face()

real3 chrono::collision::ch_utils::snap_to_box_face ( const real3 hdims,
const real3 pt_on_box,
uint  code,
const real3 pt_to_snap 
)
inline

This utility function snaps the location 'pt_to_snap' to a location on the face of this box identified by the specified 'code' and 'pt_on_box'.

The resulting location is returned. See box_closest_feature for definition of 'code.

◆ snap_to_cylinder()

uint chrono::collision::ch_utils::snap_to_cylinder ( const real &  rad,
const real &  hlen,
real3 loc 
)
inline

This utility function snaps the specified location to a point on a cylinder with given radius and half-length.

The in/out location is assumed to be specified in the frame of the cylinder (in this frame the cylinder is assumed to be centered at the origin and aligned with the Y axis). The return code indicates the feature of the cylinder that caused snapping.

  • code = 0 indicates and interior point
  • code = 1 indicates snapping to one of the cylinder caps
  • code = 2 indicates snapping to the cylinder side
  • code = 3 indicates snapping to one of the cylinder edges

◆ snap_to_triangle()

bool chrono::collision::ch_utils::snap_to_triangle ( const real3 A,
const real3 B,
const real3 C,
const real3 P,
real3 res 
)

This utility function takes the location 'P' and snaps it to the closest point on the triangular face with given vertices (A, B, and C).

The result is returned in 'res'. Both 'P' and 'res' are assumed to be specified in the same frame as the face vertices. This function returns 'true' if the result is on an edge of this face and 'false' if the result is inside the triangle. Code from Ericson, "Real-time collision detection", 2005, pp. 141

◆ snap_to_triangle_bary()

bool chrono::collision::ch_utils::snap_to_triangle_bary ( const real3 A,
const real3 B,
const real3 C,
const real3 P,
real3 res,
real3 barycentric 
)

This utility function takes the location 'P' and snaps it to the closest point on the triangular face with given vertices (A, B, and C).

Additionally, it also returns the barycentric coordinates of the result point. See snap_to_triangle for additional details.

◆ triangle_normal()

real3 chrono::collision::ch_utils::triangle_normal ( const real3 A,
const real3 B,
const real3 C 
)
inline

This utility function returns the normal to the triangular face defined by the vertices A, B, and C.

The face is assumed to be non-degenerate. Note that order of vertices is important!