Simbody
3.6

(Advanced) This is the underlying constraint for unilateral contact with friction but must be combined with contact and friction conditions. More...
Public Member Functions  
Construction  
Methods in this section refer both to constructors, and to methods that can be used to set or change construction (Topologystage) parameters; these specify the values assigned by default to the corresponding state variables. Note:
 
PointOnPlaneContact (MobilizedBody &planeBody, const Transform &defaultPlaneFrame, MobilizedBody &followerBody, const Vec3 &defaultFollowerPoint)  
Construct a pointinplane normal constraint and two noslip friction constraints as described in the Constraint::PointOnPlaneContact class documentation. More...  
PointOnPlaneContact ()  
Default constructor creates an empty handle that can be used to reference any PointOnPlaneContact Constraint. More...  
PointOnPlaneContact &  setDefaultPlaneFrame (const Transform &defaultPlaneFrame) 
Replace the default plane frame that was supplied on construction. More...  
PointOnPlaneContact &  setDefaultFollowerPoint (const Vec3 &defaultFollowerPoint) 
Replace the default follower point that was supplied on construction. More...  
MobilizedBodyIndex  getPlaneMobilizedBodyIndex () const 
Return the MobilizedBodyIndex of the plane MobilizedBody. More...  
MobilizedBodyIndex  getFollowerMobilizedBodyIndex () const 
Return the MobilizedBodyIndex of the follower MobilizedBody. More...  
const Transform &  getDefaultPlaneFrame () const 
Return the default plane frame as set during construction or by the most recent call to setDefaultPlaneFrame(). More...  
const Vec3 &  getDefaultFollowerPoint () const 
Return the default follower point as set during construction or by the most recent call to setDefaultFollowerPoint(). More...  
Visualization  
If you are allowing the SimbodyMatterSubsystem to generate default geometry, this constraint element will attempt to represent the plane and sphere that it connects. Methods here give you some limited control over the generated default geometry; if you need more control you should disable the generation of default geometry and make your own.  
PointOnPlaneContact &  setPlaneDisplayHalfWidth (Real halfWidth) 
This affects only generated decorative geometry for default visualization; the plane is really infinite in extent. More...  
PointOnPlaneContact &  setPointDisplayRadius (Real radius) 
This affects only generated decorative geometry for default visualization; the point is really zero radius. More...  
Real  getPlaneDisplayHalfWidth () const 
Return the plane halfwidth that will be used if we're asked to generate default visualization geometry. More...  
Real  getPointDisplayRadius () const 
Return the sphere radius that will be used to visualize the follower point if we're asked to generate default visualization geometry. More...  
Runtime Changes  
These refer to Positionstage discrete state variables that determine the sphere and plane 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 corresponding setDefault...() methods. Note:
 
const Transform &  getPlaneFrame (const State &state) const 
Return the plane frame X_SP that is currently in effect for this Constraint. More...  
const Vec3 &  getFollowerPoint (const State &state) const 
Return the plane frame X_SP that is currently in effect for this Constraint. 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 a signed distance. More...  
Vec3  getVelocityErrors (const State &state) const 
The velocity error vector is the velocity of the follower point in the contact frame. 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 three constraint equations generated here. More...  
Vec3  getForceOnFollowerPoint (const State &state) const 
This is the force applied by the plane body to the follower point, expressed in the contact frame. 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 SimbodyMatterSubsystem &  getMatterSubsystem () const 
Get a const reference to the matter subsystem that contains this Constraint. More...  
SimbodyMatterSubsystem &  updMatterSubsystem () 
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 MobilizedBody &  getMobilizedBodyFromConstrainedBody (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 MobilizedBody &  getAncestorMobilizedBody () 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 MobilizedBody &  getMobilizedBodyFromConstrainedMobilizer (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 SimbodyMatterSubtree &  getSubtree () 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 accelerationonly 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 constraintspace vector that belongs to this constraint. More...  
void  getMyPartFromConstraintSpaceVector (const State &state, const Vector &constraintSpace, Vector &myPart) const 
Get the part of a complete constraintspace 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_< SpatialVec >  getConstrainedBodyForcesAsVector (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...  
PIMPLHandle &  referenceAssign (const Constraint &source) 
"Copy" assignment but with shallow (pointer) semantics. More...  
PIMPLHandle &  copyAssign (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 nonvirtual. More...  
PIMPLHandle &  operator= (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...  
(Advanced) This is the underlying constraint for unilateral contact with friction but must be combined with contact and friction conditions.
This enforces the same normal condition as Constraint::PointInPlane but also adds two velocitylevel noslip constraints. Thus there are three constraints, one position (holonomic) constraint and two velocity (nonholonomic) constraints. Note that this is a bilateral constraint and will push or pull as necessary to keep the point in contact with the plane, and that sticking is enforced regardless of the amount of normal force being generated. If you want to make this unilateral, you must handle switching it on and off separately; when this constraint is enabled it always enforces the contact and noslip conditions.
There are two mobilized bodies involved. MobiliedBody S, the plane "surface" body, has a plane P fixed to it, with the plane defined by a frame P given relative to body S by the transform X_SP. MobiliedBody B, the "follower" body has a station point F (a vertex) fixed to it, given with respect to body B at location p_BF. The coordinate axes of the plane frame P (fixed in S) are used for parameterization of the Constraint. The z direction Pz of that frame is the plane normal; the Px,Py directions are used to express the tangential velocity; the P frame origin Po provides the height h=dot(Po,Pz) of the plane over the surface body's origin in the direction of the plane normal Pz.
The position constraint equation for contact enforces that the follower point F must always be in the plane P, that is, pz_PF=p_PF[2]=0, or equivalently
(1) perr = pz_PF = dot(p_SF,Pz)h
That constraint equation is enforced by an internal (nonworking) scalar force acting at the spatial location of the follower point, directed along the plane normal, and equal and opposite on the two bodies at F on B and at the instantaneously coincident point p_SF on S. Because position constraints are not enforced perfectly, contact will occur slightly above or slightly below the plane surface, wherever the follower point is.
The two velocity constraint equations enforce that the follower point has no relative tangential velocity when measured in the plane frame P, that is we want to enforce vx_PF=vy_PF=0. The time derivative of the normal constraint is also enforced at the velocity level so we have vz_PF=0. Taken together the velocitylevel constraints are just
(2) verr = v_PF = ~R_SP * v_SF
Equation (2) is the same as the velocitylevel constraints for a ball joint between frame P on S and point F on B. The accelerationlevel constraints are just the time derivative of (2), i.e.
(3) aerr = a_PF = ~R_SP * a_SF
The assembly condition is that the follower point must be in the plane; there is no assembly condition in the tangential direction since those constraints are at the velocity level only.
SimTK::Constraint::PointOnPlaneContact::PointOnPlaneContact  (  MobilizedBody &  planeBody, 
const Transform &  defaultPlaneFrame,  
MobilizedBody &  followerBody,  
const Vec3 &  defaultFollowerPoint  
) 
Construct a pointinplane normal constraint and two noslip friction constraints as described in the Constraint::PointOnPlaneContact class documentation.
Default constructor creates an empty handle that can be used to reference any PointOnPlaneContact Constraint.
PointOnPlaneContact& SimTK::Constraint::PointOnPlaneContact::setDefaultPlaneFrame  (  const Transform &  defaultPlaneFrame  ) 
Replace the default plane frame that was supplied on construction.
This is a topological change; you'll have to call realizeTopology() again if you call this method.
PointOnPlaneContact& SimTK::Constraint::PointOnPlaneContact::setDefaultFollowerPoint  (  const Vec3 &  defaultFollowerPoint  ) 
Replace the default follower point that was supplied on construction.
This is a topological change; you'll have to call realizeTopology() again if you call this method.
MobilizedBodyIndex SimTK::Constraint::PointOnPlaneContact::getPlaneMobilizedBodyIndex  (  )  const 
Return the MobilizedBodyIndex of the plane MobilizedBody.
MobilizedBodyIndex SimTK::Constraint::PointOnPlaneContact::getFollowerMobilizedBodyIndex  (  )  const 
Return the MobilizedBodyIndex of the follower MobilizedBody.
const Transform& SimTK::Constraint::PointOnPlaneContact::getDefaultPlaneFrame  (  )  const 
Return the default plane frame as set during construction or by the most recent call to setDefaultPlaneFrame().
const Vec3& SimTK::Constraint::PointOnPlaneContact::getDefaultFollowerPoint  (  )  const 
Return the default follower point as set during construction or by the most recent call to setDefaultFollowerPoint().
PointOnPlaneContact& SimTK::Constraint::PointOnPlaneContact::setPlaneDisplayHalfWidth  (  Real  halfWidth  ) 
This affects only generated decorative geometry for default visualization; the plane is really infinite in extent.
If you don't set this the default half width is 1 length unit. Set this to zero to disable any attempt to generate default visualization for the plane.
PointOnPlaneContact& SimTK::Constraint::PointOnPlaneContact::setPointDisplayRadius  (  Real  radius  ) 
This affects only generated decorative geometry for default visualization; the point is really zero radius.
If you don't set this the default radius is .05 length unit. Set this to zero to disable any attempt to generate default visualization for the point.
Real SimTK::Constraint::PointOnPlaneContact::getPlaneDisplayHalfWidth  (  )  const 
Return the plane halfwidth that will be used if we're asked to generate default visualization geometry.
If this is zero we won't generate any plane visualization geometry.
Real SimTK::Constraint::PointOnPlaneContact::getPointDisplayRadius  (  )  const 
Return the sphere radius that will be used to visualize the follower point if we're asked to generate default visualization geometry.
If this is zero we won't generate any point visualization geometry.
Return the plane frame X_SP that is currently in effect for this Constraint.
Note that the origin of the returned frame will be exactly on the plane surface; that is not necessarily where contact occurs since the follower point may be above or below the surface by position constraint tolerance.
Return the plane frame X_SP that is currently in effect for this Constraint.
Note that the origin of the returned frame will be exactly on the plane surface; that is not necessarily where contact occurs since the follower point may be above or below the surface by position constraint tolerance.
The returned position error can be viewed as a signed distance.
It is positive when the follower point is above the plane and negative when it is below the plane. The given state must have already been realized through Stage::Position.
The velocity error vector is the velocity of the follower point in the contact frame.
The contact frame is parallel to the plane frame but with its origin shifted to the spatial location as the follower point. Note that the coordinates are ordered xyz so the first two numbers are the tangential slip velocity and the third is the velocity in the normal direction, with positive indicating separation and negative indicating approach. The z value here is the time derivative of the quantity returned by getPositionError(). The given state must have already been realized through Stage::Velocity.
This vector is the time derivative of the value returned by getVelocityError().
The given state must have already been realized through Stage::Acceleration.
These are the Lagrange multipliers required to enforce the three constraint equations generated here.
For this Constraint they have units of force, but the sign convention for multipliers is the opposite of that for applied forces. Thus the returned vector may be considered the force applied by the follower point to the coincident point of the plane body, expressed in the contact frame.
This is the force applied by the plane body to the follower point, expressed in the contact frame.
For this Constraint, the value returned here is identical to the vector returned by getMultipliers(), but with the opposite sign.