usdrt::PhysxSchemaPhysxTendonAttachmentRootAPI

Defined in usdrt/scenegraph/usd/physxSchema/physxTendonAttachmentRootAPI.h

Functions

Variables

class PhysxSchemaPhysxTendonAttachmentRootAPI : public usdrt::UsdAPISchemaBase

WARNING: Draft API, this design is not fixed and may change in the future.

Applied to an articulation-link rigid-body Xformable.

The root API creates a new spatial tendon tree. The root tendon attachment is the only attachment in a tendon tree that does not have a parent, so the parentLink, parentAttachment, and gearing attributes inherited from PhysxTendonAttachmentAPI are ignored for a root.

Spatial tendons create line-of-sight distance constraints between links of a single articulation. In particular, spatial tendons run through attachments that are positioned relative to a rigid-body link, and their length is defined as a weighted sum of the distance between the attachments in the tendon.

Spatial tendons may branch, in which case the tendon splits up into multiple conceptual sub-tendons, one for each root-to-leaf path in the tendon tree. The tendon tree starts at the root, and its topology is defined by the attachments’ parentLink rel and parentAttachment token.

It is possible to create multiple attachments per link, see PhysxTendonAttachmentAPI.

Details on dynamics:

The length of a sub-tendon in the tree is

subTendonLength = sum(gearing[i] * |p[i] - p_parent[i]|)

where the sum is evaluated along the unique tree path between root and leaf. The gearing[i] is the i-th attachment’s gearing, and |p[i] - p_parent[i]| is the distance between the positions of the i-th attachment and its parent attachment.

Each subtendon has spring-damper dynamics acting on the length constraint

constraint = 0 = offset + subTendonLength - restLength

where the offset is a common summand for all sub-tendons of a spatial tendon, and the restLength is specific to a sub-tendon, see the PhysxTendonAttachmentLeafAPI.

If limits are not active, the sub-tendon force that acts on the leaf is

F = stiffness * constraint + damping * tendonVelocity

where tendonVelocity is the sum of the time derivatives of the line-of-sight distances between 1) the leaf and its parent attachment and 2) the tendon root and its first child attachment on the path to the leaf. Stiffness and damping are common parameters for all sub-tendons.

The 3D force applied at the leaf attachment is equal to

F * (p_parent - p_leaf).

where p_leaf and p_parent are the leaf’s position and its parent’s position, respectively. The reaction force acting on the root attachment is

F * (p_child_leaf - p_root)

where p_child_leaf is the position of the root’s child attachment that leads to the leaf that produces F, and p_root is the root attachment position. The tendon force is not further propagated through the tendon, so at intermediate attachments (i.e. created by PhysxTendonAttachmentAPI) no forces are applied.

Note that a spatial tendon may both pull and push on the leaf and root attachments. A string-like, one-sided constraint can be implemented using the sub-tendon’s length limits.

Sub-tendon length limits constrain the offset length

lowerLimit <= subTendonLength + offset<= upperLimit

and, when active, add a restoring spring force parametrized by limitStiffness to the tendon force, analogous to the length constraint force above. Limit dynamics are damped by the tendon-length damping that is applied regardless of a limit being active. Limit parameters are attributes of the PhysxTendonAttachmentLeafAPI.

Public Functions

inline explicit PhysxSchemaPhysxTendonAttachmentRootAPI(const UsdPrim &prim = UsdPrim(), const TfToken &name = TfToken())

Construct a PhysxSchemaPhysxTendonAttachmentRootAPI on UsdPrim prim with name name . Equivalent to PhysxSchemaPhysxTendonAttachmentRootAPI::Get( prim.GetStage(), prim.GetPath().AppendProperty( “physxTendon:name”));.

for a valid prim , but will not immediately throw an error for an invalid prim

inline explicit PhysxSchemaPhysxTendonAttachmentRootAPI(const UsdSchemaBase &schemaObj, const TfToken &name)

Construct a PhysxSchemaPhysxTendonAttachmentRootAPI on the prim held by schemaObj with name name . Should be preferred over PhysxSchemaPhysxTendonAttachmentRootAPI(schemaObj.GetPrim(), name), as it preserves SchemaBase state.

inline virtual ~PhysxSchemaPhysxTendonAttachmentRootAPI()

Destructor.

inline operator bool() const

Boolean operator.

Returns

Return true if the contained prim is has this api schema applied using HasAPI, and false otherwise.

inline TfToken GetName() const

Returns the name of this multiple-apply schema instance.

inline UsdAttribute GetTendonEnabledAttr() const

Enables/disables the tendon from contributing to the articulation dynamics.

Declaration

bool tendonEnabled = 1

C++ Type

bool

Usd Type

SdfValueTypeNames->Bool

inline UsdAttribute CreateTendonEnabledAttr() const

See GetTendonEnabledAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetStiffnessAttr() const

Common sub-tendon length spring stiffness. Range: [0, inf) Units: force / distance = mass / time / time.

Declaration

float stiffness = 0

C++ Type

float

Usd Type

SdfValueTypeNames->Float

inline UsdAttribute CreateStiffnessAttr() const

See GetStiffnessAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetDampingAttr() const

Common sub-tendon length damping. Range: [0, inf) Units: force / distance * time = mass / time.

Declaration

float damping = 0

C++ Type

float

Usd Type

SdfValueTypeNames->Float

inline UsdAttribute CreateDampingAttr() const

See GetDampingAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetLimitStiffnessAttr() const

Common sub-tendon length-limit spring stiffness. Range: [0, inf) Units: force / distance = mass / time / time.

Declaration

float limitStiffness = 0

C++ Type

float

Usd Type

SdfValueTypeNames->Float

inline UsdAttribute CreateLimitStiffnessAttr() const

See GetLimitStiffnessAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetOffsetAttr() const

Common sub-tendon length offset. Range: (-inf, inf) Units: distance.

Declaration

float offset = 0

C++ Type

float

Usd Type

SdfValueTypeNames->Float

inline UsdAttribute CreateOffsetAttr() const

See GetOffsetAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

UsdPrim GetPrim() const

Return this schema object’s held prim.

SdfPath GetPath() const

Return the SdfPath to this schema object’s held prim.

Public Static Functions

static inline PhysxSchemaPhysxTendonAttachmentRootAPI Apply(const UsdPrim &prim, const TfToken &name)

Applies this multiple-apply API schema to the given prim along with the given instance name, name.

This information is stored by adding “PhysxTendonAttachmentRootAPI:<i>name</i>” to the token-valued, listOp metadata apiSchemas on the prim. For example, if name is ‘instance1’, the token ‘PhysxTendonAttachmentRootAPI:instance1’ is added to ‘apiSchemas’.

See also

UsdPrim::GetAppliedSchemas()

See also

UsdPrim::HasAPI()

See also

UsdPrim::ApplyAPI()

See also

UsdPrim::RemoveAPI()

Returns

A valid PhysxSchemaPhysxTendonAttachmentRootAPI object is returned upon success. An invalid (or empty) PhysxSchemaPhysxTendonAttachmentRootAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

Public Static Attributes

static const UsdSchemaType schemaType = UsdSchemaType::MultipleApplyAPI

Compile time constant representing what kind of schema this class is.

See also

UsdSchemaType

Protected Functions

inline const TfToken &_GetInstanceName() const

Returns the instance name of the API schema object belonging to a multiple-apply API schema.

The returned instance name will be empty for non-applied and single-apply API schemas.