# Proximity queries
Proximity queries are based on low level routines in the math_utils::geometry::primitive
module. These routines are:
- nearest point query -- returns the nearest points in a pair of primitives; this is
only implemented currently for simplex and line types
- intersection -- discrete and continuous intersection query; discrete returns only a
boolean result; continuous returns the intersection geometry
This crate defines a *proximity query* that returns the following information for a pair
of objects:
- distance (or interpenetration depth)
- half_axis -- when objects are not overlapping, this is their separating axis (the
vector between their nearest points) scaled by 0.5; when objects are overlapping, this
vector resolves the intersection exactly by translating object A by this vector and
object B by the negative of this vector
- midpoint -- when objects are not overlapping, this is the point that lies exactly in
the middle of their separating axis; when objects are overlapping, resolving the
intersection by translating each objects relative to the half_axis results in this
point being the contact point of the resolved object pair
- normal -- this defines the orientation of the separating (contact) plane orienated
from object B towards object A
Some additional observations on the relation between these variables:
- given a computed `midpoint` and a `half_axis`:
* `midpoint + half_axis == nearest_b`
* `midpoint - half_axis == nearest_a`
* `nearest_a + half_axis == midpoint`
* `nearest_b - half_axis == midpoint`
- regardless of whether the objects are overlapping or not, translating the object A
by the half_axis and object B by the negative half_axis will result in the points
nearest_a and nearest_b on the respective objects now being identical with the
midpoint
- the midpoint and the normal together define the *planar constraint* for the contact
constraint defined by the proximity query (`constraint_planar` method, and the
Proximity type is convertable into a Planar constraint by the From/Into trait
implementation)
This Proximity query type is useful in most situations, however it may return more
information than is needed. In benchmarks, computing `query_segment_point` is possibly
over 30 times more expensive than doing a simple distance squared query on the output of
`nearest_point`. Some of the cost is due to:
- `distance` almost always requires a `sqrt()` call; we may want to be able to return
squared distance when we only need to compare distances without needing to know the
exact distance
- `normal` -- this is a normalized (unit) vector; similar to distance, we might want to
return a non-normalized normal vector
# Testbed example
Currently the testbed scenarios are mapped to keys 0-9.
However there are now more scenarios than there are number keys, so we would like to
group them together and provide sub-states.
- Simulation tests:
* drop test
* collision test
* stack test
* ball pit
* hull pit (NEW)
* sphere/hull pit (NEW)
- Penetration resolution tests:
* capsule/capsule
* cuboid/cuboid
* capsule/cuboid
* triangle/triangle
* hull/hull
- Bounding volume tests:
* OBBs
