Simbody  3.5
SimTK::Constraint::SphereOnSphereContact Class Reference

This constraint represents a bilateral connection between a sphere on one body and a sphere on another. More...

+ Inheritance diagram for SimTK::Constraint::SphereOnSphereContact:

Public Member Functions

Construction

Methods in this section refer both to constructors, and to methods that can be used to set or change contruction (Topology-stage) parameters; these specify the values assigned by default to the corresponding state variables.

Note:

  • Changing one of these default parameters invalidates the containing System's topology, meaning that realizeTopology() will have to be called and a new State obtained before subsequent use.
  • The set...() methods return a reference to "this" SphereOnSphereContact element (in the manner of an assignment operator) so they can be chained in a single expression.

The default parameters can be overridden in any given State, and modified without affecting Topology; see the "Runtime Changes" section below.

 SphereOnSphereContact (MobilizedBody &mobod_F, const Vec3 &defaultCenterOnF, Real defaultRadiusOnF, MobilizedBody &mobod_B, const Vec3 &defaultCenterOnB, Real defaultRadiusOnB, bool enforceRolling)
 Construct a sphere-on-sphere constraint as described in the Constraint::SphereOnSphereContact class documentation. More...
 
 SphereOnSphereContact ()
 Default constructor creates an empty handle that can be used to reference any SphereOnSphereContact Constraint. More...
 
const MobilizedBodygetMobilizedBodyF () const
 Return a reference to the first MobilizedBody to which a sphere is attached. More...
 
const MobilizedBodygetMobilizedBodyB () const
 Return a reference to the second MobilizedBody to which a sphere is attached. More...
 
bool isEnforcingRolling () const
 Report whether this Constraint was constructed to generate rolling constraints (otherwise it is frictionless). More...
 
SphereOnSphereContactsetDefaultCenterOnF (const Vec3 &defaultCenter)
 Replace the default center point for the sphere attached to the first body, mobod_F, that was supplied on construction. More...
 
SphereOnSphereContactsetDefaultRadiusOnF (Real defaultRadius)
 Replace the default radius for the sphere attached to the first body, mobod_F, that was supplied on construction. More...
 
SphereOnSphereContactsetDefaultCenterOnB (const Vec3 &defaultCenter)
 Replace the default center point for the sphere attached to the second body, mobod_B, that was supplied on construction. More...
 
SphereOnSphereContactsetDefaultRadiusOnB (Real defaultRadius)
 Replace the default radius for the sphere attached to the second body, mobod_B, that was supplied on construction. More...
 
const Vec3getDefaultCenterOnF () const
 Return the default center point for the sphere attached to the first body, mobod_F, as set during construction or by the most recent call to setDefaultCenterOnF(). More...
 
Real getDefaultRadiusOnF () const
 Return the default radius for the sphere attached to the first body, mobod_F, as set during construction or by the most recent call to setDefaultRadiusF(). More...
 
const Vec3getDefaultCenterOnB () const
 Return the default center point for the sphere attached to the second body, mobod_B, as set during construction or by the most recent call to setDefaultCenterOnB(). More...
 
Real getDefaultRadiusOnB () const
 Return the default radius for the sphere attached to the second body, mobod_B, as set during construction or by the most recent call to setDefaultRadiusB(). More...
 
Runtime Changes

These refer to Position-stage discrete state variables that determine the sphere parameters to be used to calculate constraint forces from a given State object.

If these are not set explicitly, the parameters are set to those provided in the constructor or via the correponding setDefault...() methods. Note:

  • Changing one of these parameters invalidates the given State's Stage::Position, meaning that the State's stage will be no higher than Stage::Time after the parameter change. That ensures that position constraint errors will be recalculated before they are used.
  • The set...() methods here return a const reference to "this" SphereOnSphereContact element (in the manner of an assignment operator, except read-only) so they can be chained in a single expression.

You can also modify and examine the default parameters; see the "Construction" section above.

const SphereOnSphereContactsetCenterOnF (State &state, const Vec3 &sphereCenter) const
 Modify the location of the sphere on the first body, mobod_F, in this state by providing a new vector p_FSf giving the sphere center location Sf relative to body F's body frame origin Fo, and expressed in the F frame. More...
 
const SphereOnSphereContactsetRadiusOnF (State &state, Real sphereRadius) const
 Modify the radius of the sphere on the first body, mobod_F, in this state. More...
 
const SphereOnSphereContactsetCenterOnB (State &state, const Vec3 &sphereCenter) const
 Modify the location of the sphere on the second body, mobod_B, in this state by providing a new vector p_BSb giving the sphere center location Sb relative to body B's body frame origin Bo, and expressed in the B frame. More...
 
const SphereOnSphereContactsetRadiusOnB (State &state, Real sphereRadius) const
 Modify the radius of the sphere on the second body, mobod_B, in this state. More...
 
const Vec3getCenterOnF (const State &state) const
 Return the position of the center point of the sphere attached to the first body, mobod_F, as currently set in the given state. More...
 
Real getRadiusOnF (const State &state) const
 Return the radius of the sphere attached to the first body, mobod_F, as currently set in the given state. More...
 
const Vec3getCenterOnB (const State &state) const
 Return the position of the center point of the sphere attached to the second body, mobod_B, as currently set in the given state. More...
 
Real getRadiusOnB (const State &state) const
 Return the radius of the sphere attached to the first body, mobod_F, as currently set in the given state. More...
 
Computations

Methods here provide access to values already calculated by this constraint element, and provide operators you can call to calculate related values.

Real getPositionError (const State &state) const
 The returned position error can be viewed as the signed distance between the spheres. More...
 
Vec3 getVelocityErrors (const State &state) const
 The returned velocity error vector has the time derivative of the quantity returned by getPositionError() in its z coordinate, and violation of the rolling constraints in its x and y coordinates. More...
 
Vec3 getAccelerationErrors (const State &state) const
 This vector is the time derivative of the value returned by getVelocityError(). More...
 
Vec3 getMultipliers (const State &state) const
 These are the Lagrange multipliers required to enforce the constraint equations generated here. More...
 
Vec3 findForceOnSphereBInG (const State &state) const
 Return the force vector currently being applied by this constraint to the contact point Co on the sphere attached to body B (the second body in the constructor), expressed in the Ground frame. More...
 
Transform findContactFrameInG (const State &state) const
 Return the instantaneous contact frame C in the Ground frame. More...
 
Real findSeparation (const State &state) const
 Calculate the separation distance or penetration depth of the two spheres. More...
 
- Public Member Functions inherited from SimTK::Constraint
 Constraint ()
 Default constructor creates an empty Constraint handle that can be used to reference any Constraint. More...
 
 Constraint (ConstraintImpl *r)
 For internal use: construct a new Constraint handle referencing a particular implementation object. More...
 
void disable (State &) const
 Disable this Constraint, effectively removing it from the system. More...
 
void enable (State &) const
 Enable this Constraint, without necessarily satisfying it. More...
 
bool isDisabled (const State &) const
 Test whether this constraint is currently disabled in the supplied State. More...
 
bool isDisabledByDefault () const
 Test whether this Constraint is disabled by default in which case it must be explicitly enabled before it will take effect. More...
 
void setDisabledByDefault (bool shouldBeDisabled)
 Normally Constraints are enabled when defined and can be disabled later. More...
 
 operator ConstraintIndex () const
 This is an implicit conversion from Constraint to ConstraintIndex when needed. More...
 
const SimbodyMatterSubsystemgetMatterSubsystem () const
 Get a const reference to the matter subsystem that contains this Constraint. More...
 
SimbodyMatterSubsystemupdMatterSubsystem ()
 Assuming you have writable access to this Constraint, get a writable reference to the containing matter subsystem. More...
 
ConstraintIndex getConstraintIndex () const
 Get the ConstraintIndex that was assigned to this Constraint when it was added to the matter subsystem. More...
 
bool isInSubsystem () const
 Test whether this Constraint is contained within a matter subsystem. More...
 
bool isInSameSubsystem (const MobilizedBody &mobod) const
 Test whether the supplied MobilizedBody is in the same matter subsystem as this Constraint. More...
 
int getNumConstrainedBodies () const
 Return the number of unique bodies directly restricted by this constraint. More...
 
const MobilizedBodygetMobilizedBodyFromConstrainedBody (ConstrainedBodyIndex consBodyIx) const
 Return a const reference to the actual MobilizedBody corresponding to one of the Constrained Bodies included in the count returned by getNumConstrainedBodies(). More...
 
const MobilizedBodygetAncestorMobilizedBody () const
 Return a const reference to the actual MobilizedBody which is serving as the Ancestor body for the constrained bodies in this Constraint. More...
 
int getNumConstrainedMobilizers () const
 Return the number of unique mobilizers directly restricted by this Constraint. More...
 
const MobilizedBodygetMobilizedBodyFromConstrainedMobilizer (ConstrainedMobilizerIndex consMobilizerIx) const
 Return a const reference to the actual MobilizedBody corresponding to one of the Constrained Mobilizers included in the count returned by getNumConstrainedMobilizers(). More...
 
const SimbodyMatterSubtreegetSubtree () const
 Return a subtree object indicating which parts of the multibody tree are potentially affected by this Constraint. More...
 
int getNumConstrainedQ (const State &, ConstrainedMobilizerIndex) const
 Return the number of constrainable generalized coordinates q associated with a particular constrained mobilizer. More...
 
int getNumConstrainedU (const State &, ConstrainedMobilizerIndex) const
 Return the number of constrainable mobilities u associated with a particular constrained mobilizer. More...
 
ConstrainedUIndex getConstrainedUIndex (const State &, ConstrainedMobilizerIndex, MobilizerUIndex which) const
 Return the index into the constrained mobilities u array corresponding to a particular mobility of the indicated ConstrainedMobilizer. More...
 
ConstrainedQIndex getConstrainedQIndex (const State &, ConstrainedMobilizerIndex, MobilizerQIndex which) const
 Return the index into the constrained coordinates q array corresponding to a particular coordinate of the indicated ConstrainedMobilizer. More...
 
int getNumConstrainedQ (const State &) const
 Return the sum of the number of coordinates q associated with each of the constrained mobilizers. More...
 
int getNumConstrainedU (const State &) const
 Return the sum of the number of mobilities u associated with each of the constrained mobilizers. More...
 
QIndex getQIndexOfConstrainedQ (const State &state, ConstrainedQIndex consQIndex) const
 Map one of this Constraint's constrained q's to the corresponding index within the matter subsystem's whole q vector. More...
 
UIndex getUIndexOfConstrainedU (const State &state, ConstrainedUIndex consUIndex) const
 Map one of this Constraint's constrained U's (or mobilities) to the corresponding index within the matter subsystem's whole u vector. More...
 
void getNumConstraintEquationsInUse (const State &state, int &mp, int &mv, int &ma) const
 Find out how many holonomic (position), nonholonomic (velocity), and acceleration-only constraint equations are currently being generated by this Constraint. More...
 
void getIndexOfMultipliersInUse (const State &state, MultiplierIndex &px0, MultiplierIndex &vx0, MultiplierIndex &ax0) const
 Return the start of the blocks of multipliers (or acceleration errors) assigned to this Constraint. More...
 
void setMyPartInConstraintSpaceVector (const State &state, const Vector &myPart, Vector &constraintSpace) const
 Set the part of a complete constraint-space vector that belongs to this constraint. More...
 
void getMyPartFromConstraintSpaceVector (const State &state, const Vector &constraintSpace, Vector &myPart) const
 Get the part of a complete constraint-space vector that belongs to this constraint. More...
 
Vector getPositionErrorsAsVector (const State &) const
 Get a Vector containing the position errors. More...
 
Vector calcPositionErrorFromQ (const State &, const Vector &q) const
 
Matrix calcPositionConstraintMatrixP (const State &) const
 
Matrix calcPositionConstraintMatrixPt (const State &) const
 
Matrix calcPositionConstraintMatrixPNInv (const State &) const
 
void calcConstraintForcesFromMultipliers (const State &, const Vector &lambda, Vector_< SpatialVec > &bodyForcesInA, Vector &mobilityForces) const
 This operator calculates this constraint's body and mobility forces given the complete set of multipliers lambda for this Constraint. More...
 
Vector getVelocityErrorsAsVector (const State &) const
 Get a Vector containing the velocity errors. More...
 
Vector calcVelocityErrorFromU (const State &, const Vector &u) const
 
Matrix calcVelocityConstraintMatrixV (const State &) const
 
Matrix calcVelocityConstraintMatrixVt (const State &) const
 
Vector getAccelerationErrorsAsVector (const State &) const
 Get a Vector containing the acceleration errors. More...
 
Vector calcAccelerationErrorFromUDot (const State &, const Vector &udot) const
 
Vector getMultipliersAsVector (const State &) const
 Get a Vector containing the Lagrange multipliers. More...
 
void getConstraintForcesAsVectors (const State &state, Vector_< SpatialVec > &bodyForcesInG, Vector &mobilityForces) const
 Given a State realized through Acceleration stage, return the forces that were applied to the system by this Constraint, with body forces expressed in Ground. More...
 
Vector_< SpatialVecgetConstrainedBodyForcesAsVector (const State &state) const
 For convenience, returns constrained body forces as the function return. More...
 
Vector getConstrainedMobilityForcesAsVector (const State &state) const
 For convenience, returns constrained mobility forces as the function return. More...
 
Real calcPower (const State &state) const
 Calculate the power being applied by this Constraint to the system. More...
 
Matrix calcAccelerationConstraintMatrixA (const State &) const
 
Matrix calcAccelerationConstraintMatrixAt (const State &) const
 
void setIsConditional (bool isConditional)
 (Advanced) Mark this constraint as one that is only conditionally active. More...
 
bool isConditional () const
 (Advanced) Get the value of the isConditional flag. More...
 
- Public Member Functions inherited from SimTK::PIMPLHandle< Constraint, ConstraintImpl, true >
bool isEmptyHandle () const
 Returns true if this handle is empty, that is, does not refer to any implementation object. More...
 
bool isOwnerHandle () const
 Returns true if this handle is the owner of the implementation object to which it refers. More...
 
bool isSameHandle (const Constraint &other) const
 Determine whether the supplied handle is the same object as "this" PIMPLHandle. More...
 
void disown (Constraint &newOwner)
 Give up ownership of the implementation to an empty handle. More...
 
PIMPLHandlereferenceAssign (const Constraint &source)
 "Copy" assignment but with shallow (pointer) semantics. More...
 
PIMPLHandlecopyAssign (const Constraint &source)
 This is real copy assignment, with ordinary C++ object ("value") semantics. More...
 
void clearHandle ()
 Make this an empty handle, deleting the implementation object if this handle is the owner of it. More...
 
const ConstraintImpl & getImpl () const
 Get a const reference to the implementation associated with this Handle. More...
 
ConstraintImpl & updImpl ()
 Get a writable reference to the implementation associated with this Handle. More...
 
int getImplHandleCount () const
 Return the number of handles the implementation believes are referencing it. More...
 

Additional Inherited Members

- Public Types inherited from SimTK::Constraint
typedef Rod ConstantDistance
 Synonym for Rod constraint. More...
 
typedef Ball CoincidentPoints
 Synonym for Ball constraint. More...
 
typedef Ball Spherical
 Synonym for Ball constraint. More...
 
typedef Weld CoincidentFrames
 
- Public Types inherited from SimTK::PIMPLHandle< Constraint, ConstraintImpl, true >
typedef PIMPLHandle< Constraint, ConstraintImpl, PTR > HandleBase
 
typedef HandleBase ParentHandle
 
- Protected Member Functions inherited from SimTK::PIMPLHandle< Constraint, ConstraintImpl, true >
 PIMPLHandle ()
 The default constructor makes this an empty handle. More...
 
 PIMPLHandle (ConstraintImpl *p)
 This provides consruction of a handle referencing an existing implementation object. More...
 
 PIMPLHandle (const PIMPLHandle &source)
 The copy constructor makes either a deep (value) or shallow (reference) copy of the supplied source PIMPL object, based on whether this is a "pointer semantics" (PTR=true) or "object (value) semantics" (PTR=false, default) class. More...
 
 ~PIMPLHandle ()
 Note that the destructor is non-virtual. More...
 
PIMPLHandleoperator= (const PIMPLHandle &source)
 Copy assignment makes the current handle either a deep (value) or shallow (reference) copy of the supplied source PIMPL object, based on whether this is a "pointer sematics" (PTR=true) or "object (value) semantics" (PTR=false, default) class. More...
 
void setImpl (ConstraintImpl *p)
 Set the implementation for this empty handle. More...
 
bool hasSameImplementation (const Constraint &other) const
 Determine whether the supplied handle is a reference to the same implementation object as is referenced by "this" PIMPLHandle. More...
 

Detailed Description

This constraint represents a bilateral connection between a sphere on one body and a sphere on another.

On construction you may choose whether the connection enforces rolling; otherwise the spheres will slip against each other. There is always one position (holonomic) constraint equation: the sphere surfaces must touch at some point. That leaves the spheres with five unconstrained degrees of freedom (dofs) to take on any relative orientation and to be touching at any point on their surfaces. Optionally, there are also two velocity (nonholonomic) constraint equations that prevent relative slip between the spheres and thus enforce rolling. In that case there can be five position dofs but only three unconstrained velocity dofs.

Note that this is a bilateral, unconditional connection and will push or pull as necessary to keep the spheres in contact. If rolling is being enforced then whatever tangential forces are necessary to keep the spheres rolling will be generated, regardless of the normal force. These constraints can form the basis for unilateral contact with Coulomb friction, but additional conditions must be added to determine when they are active.

There are two mobilized bodies involved, we'll call them F and B. Either body can move or either can be Ground; however, we will orient the signs in our calculations so that we treat F as though it were "fixed"; for example, the contact normal will be considered to point from F towards B, as though F were Ground. F has a sphere attached to it with center point Sf and radius rf. B has a sphere attached to it with center Sb and radius rb. The line between the centers is p_SfSb, oriented from body F's sphere center to body B's sphere center. The contact normal will be a unit vector aligned with p_SfSb.

Let d=||p_SfSb|| be the separation between the sphere centers. We define the contact point Co to be located on the center-to-center line so that it divides the line into two segments whose lengths are proportional to the size of the sphere nearest each segment:

    Co = Sf + (rf/(rf+rb)) * p_SfSb

If the contact constraint is satisfied (so that the spheres are touching), then d=rf+rb and Co will be located at the point of contact, at a distance rf from Sf and rb from Sb. Otherwise Co will be located along the center line with the error distributed in proportion to the radii. Since position constraints cannot be satisifed perfectly, this ensures that the fractional torque error produced by applying tangential forces at a point away from the sphere surfaces is the same for each sphere.

For any given pose, we will define a contact frame C with origin Co whose z axis Cz is aligned with the center-to-center line, pointing from Co towards Sb. If Sf and Sb are coincident (as can happen prior to assembly), Cz will be chosen arbitrarily. The x and y axes Cx and Cy define the contact plane. They are always somewhat arbitrary except for being perpendicular to Cz; don't expect them to change smoothly. However, once chosen for a new pose, Cx and Cy are held constant during subsequent velocity and acceleration calculations using the same pose. Cx and Cy are used to parameterize the slip velocity and the tangential forces; the two tangential multipliers are measure numbers in the Cx and Cy directions. The instantaneous contact frame in Ground is available as the transform X_GC.

The contact constraints here are enforced by a normal multiplier acting along Cz, and optionally two tangential multipliers acting along Cx and Cy respectively. Together these three multipliers can be interpreted as a force expressed in frame C, and applied equal and opposite to bodies F and B at their material points coincident with contact point Co.

The assembly condition is the same as the position constraint: the surfaces of the spheres must meet at some point. There is no assembly condition for the tangential constraints since they do not restrict the allowable pose during assembly.

Constructor & Destructor Documentation

SimTK::Constraint::SphereOnSphereContact::SphereOnSphereContact ( MobilizedBody mobod_F,
const Vec3 defaultCenterOnF,
Real  defaultRadiusOnF,
MobilizedBody mobod_B,
const Vec3 defaultCenterOnB,
Real  defaultRadiusOnB,
bool  enforceRolling 
)

Construct a sphere-on-sphere constraint as described in the Constraint::SphereOnSphereContact class documentation.

Parameters
mobod_FThe first MobilizedBody object to which a contacting sphere is attached. We'll call it F, the "fixed" body just to orient the contact; actually either or both bodies can be moving.
defaultCenterOnFThis is the location of the sphere center on mobod_F, given as a vector from the F frame origin Fo to the sphere center Sf, expressed in F. This is the center location that will be present in a default State; you can modify it later.
defaultRadiusOnFThe radius rf of the sphere attached to mobod_F. This is the value that will be present in a default State; you can modify it later.
mobod_BThe second MobilizedBody object to which a second contacting sphere is attached. We'll call this mobilized body B. It can be Ground or a moving body.
defaultCenterOnBThis is the location of the sphere center on mobod_B, given as a vector from the B frame origin Bo to the sphere center Sb, expressed in B. This is the center location that will be present in a default State; you can modify it later.
defaultRadiusOnBThe radius rb of the sphere attached to mobod_B. This is the value that will be present in a default State; you can modify it later.
enforceRollingWhether to generate tangential forces to make the sphere roll on the plane. Otherwise only a normal force is generated and the sphere is free to slip.

Default constructor creates an empty handle that can be used to reference any SphereOnSphereContact Constraint.

Member Function Documentation

const MobilizedBody& SimTK::Constraint::SphereOnSphereContact::getMobilizedBodyF ( ) const

Return a reference to the first MobilizedBody to which a sphere is attached.

This refers to the mobod_F that was given in the constructor and cannot be changed after construction.

const MobilizedBody& SimTK::Constraint::SphereOnSphereContact::getMobilizedBodyB ( ) const

Return a reference to the second MobilizedBody to which a sphere is attached.

This refers to the mobod_B that was given in the constructor and cannot be changed after construction.

bool SimTK::Constraint::SphereOnSphereContact::isEnforcingRolling ( ) const

Report whether this Constraint was constructed to generate rolling constraints (otherwise it is frictionless).

This cannot be changed after construction.

SphereOnSphereContact& SimTK::Constraint::SphereOnSphereContact::setDefaultCenterOnF ( const Vec3 defaultCenter)

Replace the default center point for the sphere attached to the first body, mobod_F, that was supplied on construction.

This is a topological change; you'll have to call realizeTopology() again if you call this method.

See also
setCenterOnF()
SphereOnSphereContact& SimTK::Constraint::SphereOnSphereContact::setDefaultRadiusOnF ( Real  defaultRadius)

Replace the default radius for the sphere attached to the first body, mobod_F, that was supplied on construction.

This is a topological change; you'll have to call realizeTopology() again if you call this method.

See also
setRadiusOnF()
SphereOnSphereContact& SimTK::Constraint::SphereOnSphereContact::setDefaultCenterOnB ( const Vec3 defaultCenter)

Replace the default center point for the sphere attached to the second body, mobod_B, that was supplied on construction.

This is a topological change; you'll have to call realizeTopology() again if you call this method.

See also
setCenterOnB()
SphereOnSphereContact& SimTK::Constraint::SphereOnSphereContact::setDefaultRadiusOnB ( Real  defaultRadius)

Replace the default radius for the sphere attached to the second body, mobod_B, that was supplied on construction.

This is a topological change; you'll have to call realizeTopology() again if you call this method.

See also
setRadiusOnB()
const Vec3& SimTK::Constraint::SphereOnSphereContact::getDefaultCenterOnF ( ) const

Return the default center point for the sphere attached to the first body, mobod_F, as set during construction or by the most recent call to setDefaultCenterOnF().

See also
getCenterOnF()
Real SimTK::Constraint::SphereOnSphereContact::getDefaultRadiusOnF ( ) const

Return the default radius for the sphere attached to the first body, mobod_F, as set during construction or by the most recent call to setDefaultRadiusF().

See also
getRadiusOnF()
const Vec3& SimTK::Constraint::SphereOnSphereContact::getDefaultCenterOnB ( ) const

Return the default center point for the sphere attached to the second body, mobod_B, as set during construction or by the most recent call to setDefaultCenterOnB().

See also
getCenterOnB()
Real SimTK::Constraint::SphereOnSphereContact::getDefaultRadiusOnB ( ) const

Return the default radius for the sphere attached to the second body, mobod_B, as set during construction or by the most recent call to setDefaultRadiusB().

See also
getRadiusOnB()
const SphereOnSphereContact& SimTK::Constraint::SphereOnSphereContact::setCenterOnF ( State state,
const Vec3 sphereCenter 
) const

Modify the location of the sphere on the first body, mobod_F, in this state by providing a new vector p_FSf giving the sphere center location Sf relative to body F's body frame origin Fo, and expressed in the F frame.

This overrides the defaultCenterOnF in the given state, whose Stage::Position is invalidated.

const SphereOnSphereContact& SimTK::Constraint::SphereOnSphereContact::setRadiusOnF ( State state,
Real  sphereRadius 
) const

Modify the radius of the sphere on the first body, mobod_F, in this state.

This overrides the defaultRadiusOnF in the given state, whose Stage::Position is invalidated.

const SphereOnSphereContact& SimTK::Constraint::SphereOnSphereContact::setCenterOnB ( State state,
const Vec3 sphereCenter 
) const

Modify the location of the sphere on the second body, mobod_B, in this state by providing a new vector p_BSb giving the sphere center location Sb relative to body B's body frame origin Bo, and expressed in the B frame.

This overrides the defaultCenterOnB in the given state, whose Stage::Position is invalidated.

const SphereOnSphereContact& SimTK::Constraint::SphereOnSphereContact::setRadiusOnB ( State state,
Real  sphereRadius 
) const

Modify the radius of the sphere on the second body, mobod_B, in this state.

This overrides the defaultRadiusOnB in the given state, whose Stage::Position is invalidated.

const Vec3& SimTK::Constraint::SphereOnSphereContact::getCenterOnF ( const State state) const

Return the position of the center point of the sphere attached to the first body, mobod_F, as currently set in the given state.

The value is returned as a vector p_FSf from body F's origin Fo to its sphere center Sf, expressed in the F frame.

Real SimTK::Constraint::SphereOnSphereContact::getRadiusOnF ( const State state) const

Return the radius of the sphere attached to the first body, mobod_F, as currently set in the given state.

const Vec3& SimTK::Constraint::SphereOnSphereContact::getCenterOnB ( const State state) const

Return the position of the center point of the sphere attached to the second body, mobod_B, as currently set in the given state.

The value is returned as a vector p_BSb from body B's origin Bo to its sphere center Sb, expressed in the B frame.

Real SimTK::Constraint::SphereOnSphereContact::getRadiusOnB ( const State state) const

Return the radius of the sphere attached to the first body, mobod_F, as currently set in the given state.

Real SimTK::Constraint::SphereOnSphereContact::getPositionError ( const State state) const

The returned position error can be viewed as the signed distance between the spheres.

It is positive when the spheres are separated and measures their closest approach distance. It is negative when the spheres are interpenetrating and measures the penetration depth. The given state must have already been realized through Stage::Position.

Vec3 SimTK::Constraint::SphereOnSphereContact::getVelocityErrors ( const State state) const

The returned velocity error vector has the time derivative of the quantity returned by getPositionError() in its z coordinate, and violation of the rolling constraints in its x and y coordinates.

If rolling is not being enforced then the x and y components are returned zero; they will not contain the slip velocity in that case since any slip velocity is acceptable. Note that the returned vector is expressed in the instantaneous contact frame C, considered as fixed on body F. That is, this is the velocity of the contact point on body B's sphere in the F frame, expressed in C. The given state must have already been realized through Stage::Velocity.

Vec3 SimTK::Constraint::SphereOnSphereContact::getAccelerationErrors ( const State state) const

This vector is the time derivative of the value returned by getVelocityError().

Note that this is different than the acceleration of the point of sphere B at the contact point because the contact point moves with respect to that sphere. The given state must have already been realized through Stage::Acceleration.

Vec3 SimTK::Constraint::SphereOnSphereContact::getMultipliers ( const State state) const

These are the Lagrange multipliers required to enforce the constraint equations generated here.

For this Constraint it has units of force, but recall that the sign convention for multipliers is the opposite of that for applied forces. Thus the returned value is the negative of the force being applied to sphere B at the contact point, expressed in the contact frame C. The x,y coordinates are the tangential force used to enforce rolling (or zero if rolling is not being enforced), and the z coordinate is the force needed to enforce contact. Since this is an unconditional, bilateral constraint the multipliers may have any sign and magnitude. The given state must already be realized to Stage::Acceleration.

Vec3 SimTK::Constraint::SphereOnSphereContact::findForceOnSphereBInG ( const State state) const

Return the force vector currently being applied by this constraint to the contact point Co on the sphere attached to body B (the second body in the constructor), expressed in the Ground frame.

An equal and opposite force is applied to the sphere attached to body F, to its material point that is at that same location in space. This is zero if the constraint is not currently enabled. Tangential forces are generated only when rolling is being enforced, but since this result is in the Ground frame all the vector measure numbers may be non-zero regardless. The given state must already be realized to Stage::Acceleration.

Transform SimTK::Constraint::SphereOnSphereContact::findContactFrameInG ( const State state) const

Return the instantaneous contact frame C in the Ground frame.

The actual contact point is the origin Co of the returned frame, which is placed at a point along the center-to-center line segment as described in the class documentation for this SphereOnSphereContact class. Note that this does not imply that the normal constraint is satisifed; point Co could be far from the sphere surfaces or embedded beneath them. The z direction of this frame is the contact normal; it lies along the center-to-center direction unless the centers are coincident, in which case it is arbitrary. The x-y directions Cx and Cy are always somewhat arbitrary except for being perpendicular to z; don't expect them to change smoothly. This method calculates a valid value even if this constraint is currently disabled. The given state must already be realized to Stage::Position.

Real SimTK::Constraint::SphereOnSphereContact::findSeparation ( const State state) const

Calculate the separation distance or penetration depth of the two spheres.

It is positive when the spheres are separated and measures their closest approach distance. It is negative when the spheres are interpenetrating and measures the penetration depth. This calculates a valid value even if this constraint is currently disabled. The given state must be realized to Stage::Position.


The documentation for this class was generated from the following file: