newton.eval_rigid_contact_kinematics#

newton.eval_rigid_contact_kinematics(model, state, contacts, *, out_distance=None, out_point0_world=None, out_point1_world=None)[source]#

Evaluate selected rigid-contact kinematic quantities in caller-provided arrays.

Reconstructs world-space contact points from the body-local points produced by collision detection and computes signed contact distance from those points, the frozen world-space contact normal, and the contact margins. The launch is recorded by wp.Tape, so gradients can flow through state.body_q when the provided outputs require gradients. Gradients do not flow through the contact normal or the discrete contact set.

Pass None for quantities that are not needed. The world-space contact normal is already available as newton.Contacts.rigid_contact_normal and does not need a derived output.

Parameters:

  • model (Model) – Model providing the shape-to-body mapping.

  • state (newton.State) – State providing body transforms.

  • contacts (Contacts) – Populated contacts whose rigid-contact geometry is evaluated.

  • out_distance (wp.array[wp.float32] | None) – Optional signed contact distance [m], shape (contacts.rigid_contact_max,), dtype float. Positive values are gaps and negative values are penetrations.

  • out_point0_world (wp.array[wp.vec3f] | None) – Optional world-space support point on shape 0 [m], shape (contacts.rigid_contact_max,), dtype wp.vec3.

  • out_point1_world (wp.array[wp.vec3f] | None) – Optional world-space support point on shape 1 [m], shape (contacts.rigid_contact_max,), dtype wp.vec3.

Raises:

  • ValueError – If no output is provided or an output has an unexpected shape or device.

  • TypeError – If an output is not a Warp array or has an unexpected dtype.

Experimental

The contact set and normal are frozen outputs of non-differentiable collision detection. Resulting gradients are a first-order tangent approximation and may change without prior notice.