newton.sensors.SensorFrameTransform#

class newton.sensors.SensorFrameTransform(model, shapes, reference_sites, *, verbose=None)[source]#

Bases: object

Sensor that measures transforms of shapes/sites relative to reference sites.

This sensor computes the relative transform from each reference site to each target shape: X_ro = inverse(X_wr) * X_wo, where X_wo is the world transform of the target, X_wr is the world transform of the reference site, and X_ro expresses the target’s pose in the reference frame.

Objects (shapes) can be any shape index, including both regular shapes and sites. Reference frames (reference_sites) must be sites (validated at initialization). A single reference site broadcasts to all shapes; otherwise the counts must match 1:1.

transforms#

Relative transforms [m, unitless quaternion], shape (N,) (updated after each call to update()).

The shapes and reference_sites parameters accept label patterns – see Label Matching.

Example

Measure a shape’s pose relative to a reference site:

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

builder = newton.ModelBuilder()
body = builder.add_body(xform=wp.transform((0, 0, 1), wp.quat_identity()))
builder.add_shape_box(body, hx=0.1, hy=0.1, hz=0.1, label="box")
builder.add_site(body, label="ref")
model = builder.finalize()

sensor = SensorFrameTransform(model, shapes="box", reference_sites="ref")
state = model.state()

sensor.update(state)
transforms = sensor.transforms.numpy()  # shape: (N, 7)
__init__(model, shapes, reference_sites, *, verbose=None)#

Initialize the SensorFrameTransform.

Parameters:

  • model (Model) – The model to measure.

  • shapes (str | list[str] | list[int]) – List of shape indices, single pattern to match against shape labels, or list of patterns where any one matches.

  • reference_sites (str | list[str] | list[int]) – List of site indices, single pattern to match against site labels, or list of patterns where any one matches. Must expand to one site or the same number as shapes.

  • verbose (bool | None) – If True, print details. If None, uses wp.config.verbose.

Raises:

ValueError – If arguments are invalid or no labels match.

update(state)#

Update sensor measurements based on current state.

Reads state.body_q to compute world-frame shape transforms.

Parameters:

state (State) – The current state. Reads body_q, which is updated by a solver step or eval_fk().