A summary of the clearance – a collection of distance measurements – between the robot and everything in the world.
This data can be used to define collision avoidance strategies.
Conceptually, this class represents a table:
| body index R | body index O | type | ϕᴼ(R) | Jq_ϕᴼ(R) |
| :----------: | :----------: | :--: | :---: | :------: |
| ... | ... | .. | ... | ... |
Member functions return each column of the table as an ordered collection. The iᵗʰ entry in each collection belongs to the iᵗʰ row.
Each row characterizes the relationship between a particular robot body (annotated as body R) and some "other" body (annotated as body O) in the model. That other body O may be part of the robot or the environment.
body index R is the BodyIndex of body R.body index O is the BodyIndex of body O.type implies the type of body O. Given that we know body R is a robot body, type indicates that body O is also a robot body with the value RobotCollisionType::kSelfCollision or an environment body with the value RobotCollisionType::kEnvironmentCollision. For a correct implementation of CollisionChecker, it will never be RobotCollisionType::kEnvironmentAndSelfCollision.ϕᴼ(R) is the signed distance function of the other body O evaluated on body R. The reported distance is offset by the padding value for the body pair recorded in the CollisionChecker. It is the minimum padded distance between bodies O and R. A point on the padded surface of body O would report a distance of zero. Points inside that boundary report negative distance and points outside have positive distance.Jqᵣ_ϕᴼ(R) is the Jacobian of ϕᴼ(R) with respect to the robot configuration vector qᵣ. The Jacobian is the derivative as observed in the world frame.
- The vector
qᵣ will be a subset of the plant's full configuration q when there are floating bodies or joints in the plant other than the robot. The Jacobian is only taken with respect to the robot.
- The
jacobians() matrix has plant.num_positions() columns and the column order matches up with the full plant.GetPositions() order. The columns associated with non-robot joints will be zero.
Several important notes:
- A single robot body index can appear many times as there may be many measured distances between that robot body and other bodies in the model.
- A row may contain a zero-valued Jacobian Jqᵣ_ϕᴼ(R). Appropriately filtering collisions will cull most of these Jacobians. But depending on the structure of the robot and its representative collision geometry, it is still possible to evaluate the Jacobian at a configuration that represents a local optimum (zero-valued Jacobian).
