newton.viewer.Picking#

class newton.viewer.Picking(model, *, pick_stiffness=500.0, pick_damping=45.0, pick_max_acceleration=5.0, world_offsets=None, visible_worlds_mask=None)[source]#

Bases: object

Interactive picking controller that drags a body with a spring toward a ray.

A ray cast picks the closest body and anchors a spring at the hit point. As the ray moves, the spring target follows it at the target’s current depth, and apply_force() adds the resulting force and torque to the picked body. This is useful to move objects around interactively, for example to check solver resilience or how well a policy copes with disturbances.

ViewerGL, ViewerRTX, and ViewerViser create one in set_model(), expose it as viewer.picking, and drive it from the mouse. Use this class directly to add picking to a custom application:

picking = newton.viewer.Picking(model)

# on mouse press, with a world-space ray from the camera
picking.pick(state, ray_start, ray_dir)
# on mouse drag
picking.update(ray_start, ray_dir)
# on mouse release
picking.release()

# every simulation step, after clearing the state's forces
picking.apply_force(state)
solver.step(state, state_next, control, contacts, dt)

To drive the target from a 3D input such as a gizmo, assign pick_target instead of calling update(). Read pick_point and pick_target to draw the spring. Kinematic bodies cannot be picked.

__init__(model, *, pick_stiffness=500.0, pick_damping=45.0, pick_max_acceleration=5.0, world_offsets=None, visible_worlds_mask=None)#

Initializes the picking system.

Parameters:

model (Model) – The model to pick from.
pick_stiffness (float) – Stiffness of the picking spring, in acceleration per unit displacement [1/s^2]. The commanded acceleration is mapped to a force through the operational-space inertia at the pick point, so gains are mass-independent and light distal links stay responsive.
pick_damping (float) – Damping of the picking spring, in acceleration per unit velocity of the pick point [1/s]. The default is close to critical damping, \(2\sqrt{k}\), for the default stiffness.
pick_max_acceleration (float) – Picking limit in multiples of g [9.81 m/s^2]. Caps the force at this acceleration times the mass of the picked articulation, so a light link can still move its chain, and the torque at the equivalent rotational acceleration of the picked body alone, to prevent runaway divergence on low-inertia links.
world_offsets (wp.array[wp.vec3f] | None) – Per-world visual offsets [m], shape [world_count]. Rays are given in the offset (rendered) space, and the offsets are removed before the spring is applied in simulation space. None means no offsets.
visible_worlds_mask (wp.array[wp.int32] | None) – Per-world mask, shape [world_count]; rays only hit shapes in worlds whose entry is nonzero. None makes every world pickable.

Raises:

ValueError – If pick_max_acceleration is negative or non-finite.

apply_force(state)#

Add the picking spring’s force and torque to the picked body.

The wrench is accumulated into State.body_f, so call this after the state’s forces are cleared and before the solver step. Does nothing when no body is picked. The kernel is launched even then, so this call can be captured in a CUDA graph.

Parameters:: state (State) – The simulation state to read the picked body’s pose and velocity from and add the force to.

is_picking()#

Return whether a body is currently picked.

Returns:: True if a body is picked, False otherwise.
Return type:: bool

pick(state, ray_start, ray_dir)#

Pick the body whose shape the ray hits first and anchor the spring at the hit point.

Any previous pick is released first. Shapes in worlds hidden by visible_worlds_mask are ignored. If the ray hits nothing, a static shape, or a kinematic body, nothing is picked and is_picking() returns False. This call synchronizes with the device.

Parameters:

state (State) – The simulation state supplying body poses.
ray_start (vec3f) – Ray origin in the offset (rendered) space [m].
ray_dir (vec3f) – Unit ray direction in the offset (rendered) space.

release()#

Release the picked body so apply_force() stops applying a force.

update(ray_start, ray_dir)#

Move the spring target onto a new ray, keeping its distance from the ray start.

Call this as the cursor is dragged. Does nothing when no body is picked.

Parameters:

ray_start (vec3f) – Ray origin in the offset (rendered) space [m].
ray_dir (vec3f) – Unit ray direction in the offset (rendered) space.

model#: The model whose bodies are picked.

property pick_body: int#: Index of the picked body, or -1 when nothing is picked.

property pick_damping: float#: Damping of the picking spring [1/s]; see the constructor.

property pick_max_acceleration: float#

Picking limit in multiples of g; see the constructor.

Raises:: ValueError – If set to a negative or non-finite value.

property pick_point: vec3f | None#

Attachment point on the picked body as of the last apply_force(), in simulation space [m].

None when nothing is picked.

property pick_stiffness: float#: Stiffness of the picking spring [1/s^2]; see the constructor.

property pick_target: vec3f | None#

Point the spring pulls toward, in simulation space [m], or None when nothing is picked.

Assign it to drive the target from a 3D input instead of update(); the assignment is ignored when nothing is picked.

visible_worlds_mask#: Per-world pick mask, shape [world_count], or None; see the constructor.

world_offsets#: Per-world visual offsets [m], shape [world_count], or None; see the constructor.