Document geometry query result precision

[SeanCurtis-TRI]

In the current master (as of 3/13/2019), the quality of the answers in geometric queries is accurate to machine precision in some cases, and approximate to within some threshold in others. Even as we improve the code so that more and more answers will be precise to machine precision, we know we can't guarantee that universally.

So, the module documentation should discuss this and document the current state of affairs. Users should be able to pull up a set of tables (one per query type) that say:

For shape type A vs shape type B, this query will produce an answer that is within [tolerance] of the true answer.

For example:

	Sphere	Box	Cylinder
Sphere	ε	ε	ε
Box		10e-8	ε
Cylinder			user tolerance¹

• ε represents the machine precision multiplied by the "scale" of the geometry configuration: the scale of the two geometries and the distance between the two objects.
  1. user tolerance is set through SomeClass::set_tolerance().

When we're done, every cell that can be populated with ε will be, all others will be configurable with user-defined tolerances. And, in the interim, it will reflect the current state of the code. (In some cases, the tolerance for the current state of the code may be "unknown".)

---

Update March 12, 2021

I have a PR train that will resolve this for the signed-distance-based queries, e.g., ComputePointPairPenetration, ComputeSignedDistancePairwiseClosestPoints, etc.

• [x] #14775 Introduce the characterization framework and nominally put it to work for the penetration query.
• [x] #14795 Extend the framework to facilitate compact test expression.
• [x] #14818 Finish the framework and the penetration query (including the table in the documentation).
• [x] #14856 Do the same characterization for the shape-shape signed distance queries.
• [x] #14857 Create a comparable table for ComputeSignedDistanceToPoint
• [x] #15040 Full support for AutoDiffXd on hydroelastic contact simplifies documenting scalar support for ComputeContactSurfaces() and ComputeContactSurfacesWithFallback().

Still to be done/scheduled/planned

• [ ] Handle QueryObject::HasCollision(). This will most likely be expressed in terms of PenetrationAsPointPair.
• [ ] Handle QueryObject::FindCollisionCandidates(). This will be very simple, as it has nothing to do with precision. We just need a parallel section so its documentation matches the rest of it.

[DamrongGuoy]

I'm just curious. This documentation issue is for all of these queries, right?

• Collision Queries
  • ComputePointPairPenetration()
  • ComputeContactSurfaces ()
  • ComputeContactSurfacesWithFallback()
  • FindCollisionCandidates ()
  • HasCollisions ()
• Signed Distance Queries
  • ComputeSignedDistancePairwiseClosestPoints()
  • ComputeSignedDistancePairClosestPoints()
  • ComputeSignedDistanceToPoint()

[SeanCurtis-TRI]

That's my intent.

[DamrongGuoy]

This is the content from #12468 "Support shape permutations across scalar types in ComputeSignedDistancePairwiseClosestPoints", which will be resolved as part of this issue #10907.

Following up from #10153, there is still more work required for full proximity engine support. Currently only certain shape permutations are supported and only with certain scalars. Even for doubles, there are varying levels of precision when falling back to using FCL. In distance_to_shape_callback.h, the current supported configurations are:

	Sphere	Box	Cylinder	Halfspace	Capsule	Ellipsoid	Convex	Mesh
Sphere	double Autodiff 1e-14	double Autodiff 1e-14	double 1e-14	double Autodiff 1e-14	double Autodiff 1e-14	double (FCL fallback)	double (FCL fallback)	:x:
Box	double 1e-14	double (FCL fallback)	double (FCL fallback)	:x:	double (FCL fallback)	double (FCL fallback)	double (FCL fallback)	:x:
Cylinder	double 1e-14	double (FCL fallback)	double (FCL fallback)	:x:	double (FCL fallback)	double (FCL fallback)	double (FCL fallback)	:x:
Halfspace	double 1e-14	:x:	:x:	:x:	:x:	:x:	:x:	:x:
Capsule	double Autodiff 1e-14	double (FCL fallback)	double (FCL fallback)	:x:	double (FCL fallback)	double (FCL fallback)	double (FCL fallback)	:x:
Ellipsoid	double (FCL fallback)	double (FCL fallback)	double (FCL fallback)	:x:	double (FCL fallback)	double (FCL fallback)	double (FCL fallback)	:x:
Convex	double (FCL fallback)	double (FCL fallback)	double (FCL fallback)	:x:	double (FCL fallback)	double (FCL fallback)	double (FCL fallback)	:x:
Mesh	:x:	:x:	:x:	:x:	:x:	:x:	:x:	:x:

We should fully support the shapes we care about, i.e. shapes with spheres, by providing our own implementation for sphere-XXX in distance_to_point_callback.h. Otherwise we should provide fallbacks and update the documentation to reflect the latest state.