Collision · repose-collision

Collision

repose-collision answers one question fast and without allocating: at these joint values, does the robot hit itself or anything around it, and by how much does it clear everything? Planners ask it thousands of times per plan; your program asks it before every move.

The pieces

Shapes & distancesSpheres and capsules, and exact signed distances between them.
Robot collision modelsCuRobotCollisionModel<N, M>: shapes attached to the chain's joint frames, the safety margin, and which link pairs are checked.
Checking configurationsCuCollisionEnv, check_configuration, the report, and segment checks.
Planning scenesCuPlanningScene: a versioned, fixed-capacity store of obstacles and attached objects.
Attached objects & exclusionsGrasping, releasing, and telling the checker which contacts are intended.
Copper taskCuCollisionCheckTask, its inputs and config.

How a check works

text
joint values q ──► chain.forward_frames ──► link frames
                                              │
robot model: shapes on frames ────────────────┼──► world-space robot shapes
                                              ▼
           ┌─────────── self:   robot shape × robot shape   (enabled pairs only)
 check ────┼─────────── world:  robot shape × obstacle
           └─────────── attached: attached × robot / obstacle / attached  (minus exclusions)
                                              │
                                              ▼
              CuCollisionReport: contacts + minimum signed distance

A pair collides when its surface-to-surface distance is below the model's safety margin. Penetration has a negative distance. The report keeps the closest distance over all checked pairs, which planners use as clearance.

Why only spheres and capsules

Sphere and capsule distances are exact, closed-form and branch-light, so a check costs the same every time and needs no memory. A capsule (a sphere swept along a segment) fits robot links well. The price is that geometry must be approximated conservatively: boxes and meshes are not supported directly. Cover them with capsules and spheres, as the URDF importer does for cylinders.

What it does not do

  • No swept volumes. Motion between two configurations is checked by sampling at a joint resolution. A thin obstacle can slip between samples if the resolution is coarse.
  • No runtime monitoring. Nothing watches the moving robot for collisions. Checks happen at plan and pre-flight time against the scene you provide.
  • No perception. Obstacles come from your configuration or your own tasks.

API reference