newton.sensors.SensorContact#

class newton.sensors.SensorContact(model, *, sensing_bodies=None, sensing_shapes=None, counterpart_bodies=None, counterpart_shapes=None, measure_total=True, verbose=None, request_contact_attributes=True, **kwargs)[source]#

Bases: object

Measures contact forces on a set of sensing objects (bodies or shapes).

In its simplest form the sensor reports total_force — the total contact force on each sensing object. Optionally, specify counterparts to get a per-counterpart breakdown in force_matrix.

total_force and force_matrix are each nullable: total_force is None when measure_total=False; force_matrix is None when no counterparts are specified. Their friction counterparts total_force_friction and force_matrix_friction follow the same rules.

Multi-world behavior

When the model contains multiple worlds, counterpart mappings are resolved per-world. The collision pipeline and solver are expected to produce only within-world contacts, so cross-world force accumulation does not arise in practice. Global counterparts (e.g. ground plane) contribute to every world they contact.

In single-world models where no add_world() call was made (all entities are global / world=-1), the sensor treats the entire model as one implicit world and all entities are valid sensing objects.

When counterparts are specified, the force matrix has shape (sum_of_sensors_across_worlds, max_counterparts) where max_counterparts is the maximum counterpart count of any single world. Row order matches sensing_indices. Columns beyond a world’s own counterpart count are zero-padded.

sensing_indices and counterpart_indices are flat lists that describe the structure of the output arrays.

Terms

Sensing object – body or shape carrying a contact sensor.
Counterpart – the other body or shape in a contact interaction.

Construction and update order

SensorContact requests the force extended attribute from the model at init, so a Contacts object created afterwards (via Model.contacts() or directly) will include it automatically.

update() reads from contacts.force. Call solver.update_contacts(contacts) before sensor.update() so that contact forces are current.

Parameters that select bodies or shapes accept label patterns – see Label Matching.

Example

Measure total contact force on a sphere resting on the ground:

import warp as wp
import newton
from newton.sensors import SensorContact

builder = newton.ModelBuilder()
builder.add_ground_plane()
body = builder.add_body(xform=wp.transform((0, 0, 0.1), wp.quat_identity()))
builder.add_shape_sphere(body, radius=0.1, label="ball")
model = builder.finalize()

sensor = SensorContact(model, sensing_shapes="ball")
solver = newton.solvers.SolverMuJoCo(model)
state = model.state()
contacts = model.contacts()

solver.step(state, state, None, None, dt=1.0 / 60.0)
solver.update_contacts(contacts)
sensor.update(state, contacts)
force = sensor.total_force.numpy()  # (n_sensing, 3)

Raises:: ValueError – If the configuration of sensing/counterpart objects is invalid.

__init__(model, *, sensing_bodies=None, sensing_shapes=None, counterpart_bodies=None, counterpart_shapes=None, measure_total=True, verbose=None, request_contact_attributes=True, **kwargs)#

Initialize the SensorContact.

Exactly one of sensing_bodies or sensing_shapes must be specified to define the sensing objects. At most one of counterpart_bodies or counterpart_shapes may be specified. If neither is specified, only total_force and total_force_friction are available (no per-counterpart breakdown).

Parameters:

model (Model) – The simulation model providing shape/body definitions and world layout.
sensing_bodies (str | list[str] | list[int] | None) – List of body indices, single pattern to match against body labels, or list of patterns where any one matches.
sensing_shapes (str | list[str] | list[int] | None) – List of shape indices, single pattern to match against shape labels, or list of patterns where any one matches.
counterpart_bodies (str | list[str] | list[int] | None) – List of body indices, single pattern to match against body labels, or list of patterns where any one matches.
counterpart_shapes (str | list[str] | list[int] | None) – List of shape indices, single pattern to match against shape labels, or list of patterns where any one matches.
measure_total (bool) – If True (default), total_force and total_force_friction are allocated. If False, both are None.
verbose (bool | None) – If True, print details. If False, suppress details. If None, print details when wp.config.log_level is configured for debug logging.
request_contact_attributes (bool) – If True (default), transparently request the extended contact attribute force from the model.

update(state, contacts)#

Update the contact sensor readings based on the provided state and contacts.

Computes world-frame transforms for all sensing objects and evaluates contact forces and their friction (tangential) components (total and/or per-counterpart, depending on sensor configuration).

Parameters:

state (State | None) – The simulation state providing body transforms, or None to skip the transform update.
contacts (Contacts) – The contact data to evaluate.

Raises:

ValueError – If contacts.force is None.
ValueError – If contacts.device does not match the sensor’s device.

counterpart_indices: list[list[int]]#: Counterpart body or shape indices per sensing object. counterpart_indices[i] lists the counterparts for row i. Global counterparts appear first, followed by per-world locals in ascending index order.

counterpart_type: Literal['body', 'shape'] | None#: Whether counterpart_indices contains body indices ("body") or shape indices ("shape"). None when no counterparts are specified.

force_matrix: wp.array(dtype=wp.vec3f, ndim=2) | None#: Per-counterpart contact forces [N], shape (n_sensing, max_counterparts), dtype vec3. Entry [i, j] is the force on sensing object i from counterpart counterpart_indices[i][j], in world frame. None when no counterparts are specified.

force_matrix_friction: wp.array(dtype=wp.vec3f, ndim=2) | None#: Per-counterpart friction (tangential) contact forces [N], shape (n_sensing, max_counterparts), dtype vec3. Entry [i, j] is the friction force on sensing object i from counterpart counterpart_indices[i][j], in world frame. None when no counterparts are specified.

sensing_indices: list[int]#: Body or shape index per sensing object, matching the row of output arrays. For list[int] inputs the caller’s order is preserved; for string patterns the order follows ascending body/shape index.

property sensing_obj_idx: list[int]#: Deprecated alias for sensing_indices.

Deprecated since version 1.4: Use sensing_indices instead.

property sensing_obj_transforms: wp.array(dtype=wp.transformf, ndim=1)#: Deprecated alias for sensing_transforms.

Deprecated since version 1.4: Use sensing_transforms instead.

property sensing_obj_type: Literal['body', 'shape']#: Deprecated alias for sensing_type.

Deprecated since version 1.4: Use sensing_type instead.

sensing_transforms: wp.array(dtype=wp.transformf, ndim=1)#: World-frame transforms of sensing objects [m, unitless quaternion], shape (n_sensing,), dtype transform.

sensing_type: Literal['body', 'shape']#: Whether sensing_indices contains body indices ("body") or shape indices ("shape").

total_force: wp.array(dtype=wp.vec3f, ndim=1) | None#: Total contact force [N] per sensing object, shape (n_sensing,), dtype vec3. None when measure_total=False.

total_force_friction: wp.array(dtype=wp.vec3f, ndim=1) | None#: Total friction (tangential) contact force [N] per sensing object, shape (n_sensing,), dtype vec3. None when measure_total=False.