This constraint represents a bilateral connection between a sphere on one body and a plane on another. More...
Inheritance diagram for SimTK::Constraint::SphereOnPlaneContact:
Public Member Functions | |
Construction | |
Methods in this section refer both to constructors, and to methods that can be used to set or change construction (Topology-stage) parameters; these specify the values assigned by default to the corresponding state variables. Note:
| |
| SphereOnPlaneContact (MobilizedBody &planeMobod, const Transform &defaultPlaneFrame, MobilizedBody &sphereMobod, const Vec3 &defaultSphereCenter, Real defaultSphereRadius, bool enforceRolling) | |
| Construct a sphere-on-plane constraint as described in the Constraint::SphereOnPlaneContact class documentation. More... | |
| SphereOnPlaneContact () | |
| Default constructor creates an empty handle that can be used to reference any SphereOnPlaneContact Constraint. More... | |
| const MobilizedBody & | getPlaneMobilizedBody () const |
| Return a reference to the MobilizedBody to which the plane is attached. More... | |
| const MobilizedBody & | getSphereMobilizedBody () const |
| Return a reference to the MobilizedBody to which the sphere is attached. More... | |
| bool | isEnforcingRolling () const |
| Report whether this Constraint was constructed to generate rolling constraints (otherwise it is frictionless). More... | |
| SphereOnPlaneContact & | setDefaultPlaneFrame (const Transform &defaultPlaneFrame) |
| Replace the default plane frame that was supplied on construction. More... | |
| SphereOnPlaneContact & | setDefaultSphereCenter (const Vec3 &defaultSphereCenter) |
| Replace the default center point that was supplied on construction. More... | |
| SphereOnPlaneContact & | setDefaultSphereRadius (Real defaultSphereRadius) |
| Replace the default sphere radius that was supplied on construction. 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 & | getDefaultSphereCenter () const |
| Return the default center point as set during construction or by the most recent call to setDefaultSphereCenter(). More... | |
| Real | getDefaultSphereRadius () const |
| Return the default sphere radius as set during construction or by the most recent call to setDefaultSphereRadius(). 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. | |
| SphereOnPlaneContact & | setPlaneDisplayHalfWidth (Real halfWidth) |
| This affects only generated decorative geometry for default visualization; the plane is really infinite in extent. More... | |
| Real | getPlaneDisplayHalfWidth () const |
| Return the plane half-width that will be used if we're asked to generate default visualization geometry. More... | |
Runtime Changes | |
These refer to Position-stage 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 SphereOnPlaneContact & | setPlaneFrame (State &state, const Transform &planeFrame) const |
| Modify the location of the plane in this state by providing a new transform X_FP giving the plane frame relative to the plane body F's body frame. More... | |
| const SphereOnPlaneContact & | setSphereCenter (State &state, const Vec3 &sphereCenter) const |
| Modify the location of the sphere in this state by providing a new vector p_BS giving the sphere center location relative to the sphere body B's body frame origin, and expressed in the B frame. More... | |
| const SphereOnPlaneContact & | setSphereRadius (State &state, Real sphereRadius) const |
| Modify the radius of the sphere in this state. More... | |
| const Transform & | getPlaneFrame (const State &state) const |
| Return the plane frame X_FP that is currently in effect for this Constraint. More... | |
| const Vec3 & | getSphereCenter (const State &state) const |
| Return the sphere's center point location p_BO that is current in effect for this Constraint. More... | |
| Real | getSphereRadius (const State &state) const |
| Return the sphere radius 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 the signed distance from the lowest point of the sphere to the plane surface. 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 |
| This are the Lagrange multipliers required to enforce the constraint equations generated here. More... | |
| Vec3 | findForceOnSphereInG (const State &state) const |
| Return the force vector currently being applied by this constraint to the contact point on the sphere body, expressed in the Ground frame. More... | |
| Vec3 | findContactPointInG (const State &state) const |
| Return the contact point location in the Ground frame. More... | |
| Real | findSeparation (const State &state) const |
| Calculate the separation distance or penetration depth of the sphere and the plane. 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 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_< 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 non-virtual. 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... | |
Detailed Description
This constraint represents a bilateral connection between a sphere on one body and a plane on another.
On construction you may choose whether the connection enforces rolling; otherwise the sphere will slip along the plane. There is always one position (holonomic) constraint equation: the sphere must touch the plane. That leaves the sphere free to take on any orientation and to be touching at any point in the plane. Optionally, there are also two velocity (nonholonomic) constraint equations that prevent relative slip between the sphere and the plane and thus enforce rolling.
Note that this is a bilateral, unconditional connection and will push or pull as necessary to keep the ball in contact with the plane. If rolling is being enforced then whatever tangential forces are necessary to keep the ball rolling will be generated, regardless of the normal force. These constraints can form the basis for unilateral contact, but additional conditions must be added to determine when they are active.
There are two mobilized bodies involved, we'll call them F ("floor") and B ("ball"). (These names are just mnemonics; both bodies can be free to move or either one could be Ground.) F is a body to which a plane P has been fixed, and B is a body to which a sphere S is fixed. The plane is defined by a frame P given relative to body F by the transform X_FP. The coordinate axes of P 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 slip velocity and tangential forces in case of rolling; the P frame origin Po (given by the vector p_FP) provides the height h=p_FP.Pz of the plane over the floor body's origin (Fo) in the direction of the plane normal Pz.
MobilizedBody B has a sphere fixed to it with center So and radius r, with So given by the vector p_BS in the B frame. Call the point at the bottom (w.r.t. plane normal) of the sphere C, with C=So-r*Pz. The position constraint equation for contact then enforces that the location of the bottom of the sphere (at C) is in the plane P, and all contact forces are applied at the location of point C. Because position constraints cannot be enforced perfectly, contact will occur slightly above or slightly below the plane surface, depending where C is. However, contact will always occur at a radius of exactly r from the sphere center S.
The contact constraints here are enforced by a normal multiplier acting along Pz, and optionally two tangential multipliers acting along Px and Py respectively. Together these can be interpreted as a force acting in a frame C that is always aligned with P, but whose origin is at the contact point Co at the bottom of the ball.
The assembly condition is the same as the position constraint: some point on the surface of the sphere must be touching the plane. There is no assembly condition for the tangential constraints since they do not restrict the allowable pose during assembly.
Constructor & Destructor Documentation
◆ SphereOnPlaneContact() [1/2]
| SimTK::Constraint::SphereOnPlaneContact::SphereOnPlaneContact | ( | MobilizedBody & | planeMobod, |
| const Transform & | defaultPlaneFrame, | ||
| MobilizedBody & | sphereMobod, | ||
| const Vec3 & | defaultSphereCenter, | ||
| Real | defaultSphereRadius, | ||
| bool | enforceRolling | ||
| ) |
Construct a sphere-on-plane constraint as described in the Constraint::SphereOnPlaneContact class documentation.
- Parameters
-
planeMobod
The "floor" MobilizedBody F to which the plane P is attached.defaultPlaneFrame The Transform X_FP that defines the plane relative to the body frame of planeMobod F. This is the value that will be present in a default State; you can modify it later. sphereMobod The "ball" MobilizedBody B to which the sphere S is attached. defaultSphereCenter The center of sphere S defined relative to the body frame of the sphereMobod B. This is a vector p_BS from body B's origin Bo to the sphere center So, expressed in the B frame. This is the value that will be present in a default State; you can modify it later. defaultSphereRadius The radius r of the sphere S. This is the value that will be present in a default State; you can modify it later. enforceRolling Whether 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.
◆ SphereOnPlaneContact() [2/2]
Default constructor creates an empty handle that can be used to reference any SphereOnPlaneContact Constraint.
Member Function Documentation
◆ getPlaneMobilizedBody()
| const MobilizedBody& SimTK::Constraint::SphereOnPlaneContact::getPlaneMobilizedBody | ( | ) | const |
Return a reference to the MobilizedBody to which the plane is attached.
This refers to the planeMobod that was given in the constructor and cannot be changed after construction.
◆ getSphereMobilizedBody()
| const MobilizedBody& SimTK::Constraint::SphereOnPlaneContact::getSphereMobilizedBody | ( | ) | const |
Return a reference to the MobilizedBody to which the sphere is attached.
This refers to the sphereMobod that was given in the constructor and cannot be changed after construction.
◆ isEnforcingRolling()
| bool SimTK::Constraint::SphereOnPlaneContact::isEnforcingRolling | ( | ) | const |
Report whether this Constraint was constructed to generate rolling constraints (otherwise it is frictionless).
This cannot be changed after construction.
◆ setDefaultPlaneFrame()
| SphereOnPlaneContact& SimTK::Constraint::SphereOnPlaneContact::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.
◆ setDefaultSphereCenter()
| SphereOnPlaneContact& SimTK::Constraint::SphereOnPlaneContact::setDefaultSphereCenter | ( | const Vec3 & | defaultSphereCenter | ) |
Replace the default center point that was supplied on construction.
This is a topological change; you'll have to call realizeTopology() again if you call this method.
◆ setDefaultSphereRadius()
| SphereOnPlaneContact& SimTK::Constraint::SphereOnPlaneContact::setDefaultSphereRadius | ( | Real | defaultSphereRadius | ) |
Replace the default sphere radius that was supplied on construction.
This is a topological change; you'll have to call realizeTopology() again if you call this method.
◆ getDefaultPlaneFrame()
| const Transform& SimTK::Constraint::SphereOnPlaneContact::getDefaultPlaneFrame | ( | ) | const |
Return the default plane frame as set during construction or by the most recent call to setDefaultPlaneFrame().
◆ getDefaultSphereCenter()
| const Vec3& SimTK::Constraint::SphereOnPlaneContact::getDefaultSphereCenter | ( | ) | const |
Return the default center point as set during construction or by the most recent call to setDefaultSphereCenter().
◆ getDefaultSphereRadius()
| Real SimTK::Constraint::SphereOnPlaneContact::getDefaultSphereRadius | ( | ) | const |
Return the default sphere radius as set during construction or by the most recent call to setDefaultSphereRadius().
◆ setPlaneDisplayHalfWidth()
| SphereOnPlaneContact& SimTK::Constraint::SphereOnPlaneContact::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.
◆ getPlaneDisplayHalfWidth()
| Real SimTK::Constraint::SphereOnPlaneContact::getPlaneDisplayHalfWidth | ( | ) | const |
Return the plane half-width 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.
◆ setPlaneFrame()
| const SphereOnPlaneContact& SimTK::Constraint::SphereOnPlaneContact::setPlaneFrame | ( | State & | state, |
| const Transform & | planeFrame | ||
| ) | const |
Modify the location of the plane in this state by providing a new transform X_FP giving the plane frame relative to the plane body F's body frame.
This overrides the defaultPlaneFrame in the given state, whose Stage::Position is invalidated.
◆ setSphereCenter()
| const SphereOnPlaneContact& SimTK::Constraint::SphereOnPlaneContact::setSphereCenter | ( | State & | state, |
| const Vec3 & | sphereCenter | ||
| ) | const |
Modify the location of the sphere in this state by providing a new vector p_BS giving the sphere center location relative to the sphere body B's body frame origin, and expressed in the B frame.
This overrides the defaultSphereCenter in the given state, whose Stage::Position is invalidated.
◆ setSphereRadius()
| const SphereOnPlaneContact& SimTK::Constraint::SphereOnPlaneContact::setSphereRadius | ( | State & | state, |
| Real | sphereRadius | ||
| ) | const |
Modify the radius of the sphere in this state.
This overrides the defaultSphereRadius in the given state, whose Stage::Position is invalidated.
◆ getPlaneFrame()
| const Transform& SimTK::Constraint::SphereOnPlaneContact::getPlaneFrame | ( | const State & | state | ) | const |
Return the plane frame X_FP 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 ball may be above or below the surface by position constraint tolerance.
◆ getSphereCenter()
Return the sphere's center point location p_BO that is current in effect for this Constraint.
The location is measured and expressed in the ball body's frame.
◆ getSphereRadius()
Return the sphere radius that is currently in effect for this Constraint.
◆ getPositionError()
The returned position error can be viewed as the signed distance from the lowest point of the sphere to the plane surface.
It is positive when the sphere is above the plane (along the plane normal Pz) and negative when it is penetrating the plane. The given state must have already been realized through Stage::Position.
◆ getVelocityErrors()
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 plane frame P, that is, this is the velocity of the contact point of the sphere body, measured with respect to the plane, and expressed along Px,Py, and Pz. The given state must have already been realized through Stage::Velocity.
◆ getAccelerationErrors()
This vector is the time derivative of the value returned by getVelocityError().
Note that this is different than the acceleration of the point of the sphere at the contact point beceause the contact point moves with respect to the sphere. The given state must have already been realized through Stage::Acceleration.
◆ getMultipliers()
This 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 the sphere at the contact point, expressed in the plane frame P. The x,y coordinates are the forces in the plane 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.
◆ findForceOnSphereInG()
Return the force vector currently being applied by this constraint to the contact point on the sphere body, expressed in the Ground frame.
An equal and opposite force is applied to the plane body, 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.
◆ findContactPointInG()
Return the contact point location in the Ground frame.
We define this to be the Ground location coincident with the bottom of the sphere with respect to the plane normal Pz. Note that this does not imply that the constraint is satisifed; that point could be far from the plane or deeply below the plane. This calculates a valid value even if this constraint is currently disabled. The given state must already be realized to Stage::Position.
◆ findSeparation()
Calculate the separation distance or penetration depth of the sphere and the plane.
This is positive if the lowest point of the sphere is above the plane (in the sense of the plane normal Pz), and negative if the lowest point is below the plane, in which case it measures the maximum 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:
