Struct Joint 

pub struct Joint {

    pub joint_type: JointType,
    pub parent_to_joint: SpatialTransform,
    pub axis: Vec3,
    pub damping: f64,
    pub limits: Option<[f64; 2]>,
    pub limit_stiffness: f64,
    pub limit_damping: f64,
    pub armature: f64,
    pub stiffness: f64,
    pub spring_ref: f64,
    pub friction_loss: f64,
    pub effort_limit: Option<f64>,
    pub velocity_limit: Option<f64>,
    pub name: String,
}

A joint connecting two bodies.

Fields

joint_type: JointType

Joint type.

parent_to_joint: SpatialTransform

Transform from parent body frame to joint frame (constant).

pos is the joint origin expressed in parent-body coordinates and rot is the coordinate transform parent → joint, i.e. the joint’s orientation in the parent frame is rot.transpose().

axis: Vec3

Joint axis, expressed in the joint frame (for revolute: typically Z).

damping: f64

Damping coefficient (force = -damping * qd).

limits: Option<[f64; 2]>

Joint position limits [lower, upper] (None = unlimited).

Only meaningful for single-DOF joints (revolute/prismatic). Limits on ball and free joints are ignored — MuJoCo expresses those as a cone limit, which this model does not represent yet.

limit_stiffness: f64

Stiffness of the soft joint-limit force (force per unit of violation).

limit_damping: f64

Damping of the soft joint-limit force (force per unit of inward velocity).

armature: f64

Rotor / armature inertia added to this joint’s diagonal of the mass matrix.

MuJoCo’s armature. Physically it is the reflected inertia of the motor rotor; numerically it also regularises the mass matrix.

stiffness: f64

Passive spring stiffness (force = -stiffness * (q - spring_ref)).

spring_ref: f64

Rest position of the passive spring (MuJoCo’s springref).

friction_loss: f64

Dry (Coulomb) friction magnitude — MuJoCo’s frictionloss, and where URDF’s <dynamics friction="..."> lands.

effort_limit: Option<f64>

Actuation effort limit (torque or force), if the source declares one.

Descriptive only: nothing in the solver clamps to it yet.

velocity_limit: Option<f64>

Velocity limit, if the source declares one. Descriptive only.

name: String

Name of the joint in the source file (empty if unnamed).

Implementations

impl Joint

pub fn revolute(parent_to_joint: SpatialTransform) -> Self

Create a revolute joint with the given parent-to-joint transform.

pub fn prismatic(parent_to_joint: SpatialTransform, axis: Vec3) -> Self

Create a prismatic joint with the given parent-to-joint transform and axis.

pub fn spherical(parent_to_joint: SpatialTransform) -> Self

Create a spherical (ball) joint with the given parent-to-joint transform.

pub fn free(parent_to_joint: SpatialTransform) -> Self

Create a free joint with the given parent-to-joint transform.

pub fn fixed(parent_to_joint: SpatialTransform) -> Self

Create a fixed joint (rigid attachment).

pub fn with_name(self, name: &str) -> Self

Set the joint name (builder style).

pub fn ndof(&self) -> usize

Number of degrees of freedom for this joint type.

pub fn limit_force(&self, q: f64, qd: f64) -> f64

Soft joint-limit force for a single-DOF joint at position q, velocity qd.

Returns a generalized force along the joint’s DOF (positive = pushes q up). Zero when the joint is unlimited, multi-DOF, or inside its range.

Why a penalty force

The contact layer is currently a penalty method, so limits are modelled the same way for consistency: a one-sided spring-damper on the violation depth. The damping term is gated — it only ever resists motion deeper into the limit, never pulls the joint back toward the violation — so this force is strictly dissipative and cannot inject energy at the boundary (which is what makes naive -d * qd limit damping oscillate).

Migration to a constraint

This is deliberately expressed as a pure function of (q, qd) returning a force, with the violation depth and its sign computed by Joint::limit_violation. When the solver gains unilateral constraints, limit_violation becomes the constraint function g(q) >= 0 and its Jacobian row is the joint’s motion subspace; only the force assembly here is replaced, not the model or the parsing that feeds it.

pub fn limit_violation(&self, q: f64) -> Option<(f64, f64)>

Limit violation at position q, as (depth, restoring_direction).

depth is a non-negative penetration past the limit; the direction is +1.0 past the lower bound and -1.0 past the upper bound. Returns None when the joint is unlimited, multi-DOF, or within range.

This is the constraint function a future unilateral solver would use.

pub fn passive_force(&self, k: usize, q: f64, qd: f64) -> f64

Total passive generalized force on DOF k of this joint.

Combines viscous damping, the passive spring, dry friction and the soft joint limit. q/qd are this DOF’s position and velocity.

pub fn joint_transform_slice(&self, q: &[f64]) -> SpatialTransform

Compute the joint transform for the given joint position(s).

Returns the Plücker transform from predecessor to successor frame. q slice should have length >= ndof().

pub fn joint_transform(&self, q: f64) -> SpatialTransform

Compute the joint transform for a single-DOF joint (backward compat). For multi-DOF joints, use joint_transform_slice instead.

pub fn motion_subspace_matrix(&self) -> DMat

Motion subspace matrix S for this joint. Returns a matrix of size 6 × ndof. For single-DOF joints, returns a 6×1 column vector.

pub fn motion_subspace(&self) -> SpatialVec

Motion subspace for single-DOF joints (backward compat). For multi-DOF joints, use motion_subspace_matrix instead. Fixed joints return a zero vector.

Trait Implementations

impl Clone for Joint

fn clone(&self) -> Joint

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Joint

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Joint

fn default() -> Self

Returns the “default value” for a type.