Simbody
3.5
|
(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 contruction (Topology-stage) 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 point-in-plane normal constraint and two no-slip friction constraints as described in the Constraint::PointOnPlaneContact class documentation. | |
PointOnPlaneContact () | |
Default constructor creates an empty handle that can be used to reference any PointOnPlaneContact Constraint. | |
PointOnPlaneContact & | setDefaultPlaneFrame (const Transform &defaultPlaneFrame) |
Replace the default plane frame that was supplied on construction. | |
PointOnPlaneContact & | setDefaultFollowerPoint (const Vec3 &defaultFollowerPoint) |
Replace the default follower point that was supplied on construction. | |
MobilizedBodyIndex | getPlaneMobilizedBodyIndex () const |
Return the MobilizedBodyIndex of the plane MobilizedBody. | |
MobilizedBodyIndex | getFollowerMobilizedBodyIndex () const |
Return the MobilizedBodyIndex of the follower MobilizedBody. | |
const Transform & | getDefaultPlaneFrame () const |
Return the default plane frame as set during construction or by the most recent call to setDefaultPlaneFrame(). | |
const Vec3 & | getDefaultFollowerPoint () const |
Return the default follower point as set during construction or by the most recent call to setDefaultFollowerPoint(). | |
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. | |
PointOnPlaneContact & | setPointDisplayRadius (Real radius) |
This affects only generated decorative geometry for default visualization; the point is really zero radius. | |
Real | getPlaneDisplayHalfWidth () const |
Return the plane half-width that will be used if we're asked to generate default visualization geometry. | |
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. | |
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 correponding setDefault...() methods. Note:
| |
const Transform & | getPlaneFrame (const State &state) const |
Return the plane frame X_SP that is currently in effect for this Constraint. | |
const Vec3 & | getFollowerPoint (const State &state) const |
Return the plane frame X_SP that is currently in effect for this Constraint. | |
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. | |
Vec3 | getVelocityErrors (const State &state) const |
The velocity error vector is the velocity of the follower point in the contact frame. | |
Vec3 | getAccelerationErrors (const State &state) const |
This vector is the time derivative of the value returned by getVelocityError(). | |
Vec3 | getMultipliers (const State &state) const |
These are the Lagrange multipliers required to enforce the three constraint equations generated here. | |
Vec3 | getForceOnFollowerPoint (const State &state) const |
This is the force applied by the plane body to the follower point, expressed in the contact frame. |
(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 velocity-level no-slip 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 no-slip 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 (non-working) 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 velocity-level constraints are just
(2) verr = v_PF = ~R_SP * v_SF
Equation (2) is the same as the velocity-level constraints for a ball joint between frame P on S and point F on B. The acceleration-level 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 point-in-plane normal constraint and two no-slip 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.
Return the MobilizedBodyIndex of the plane MobilizedBody.
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.
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.
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.
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.
const Transform& SimTK::Constraint::PointOnPlaneContact::getPlaneFrame | ( | const State & | state | ) | const |
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.
const Vec3& SimTK::Constraint::PointOnPlaneContact::getFollowerPoint | ( | const State & | state | ) | const |
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.
Real SimTK::Constraint::PointOnPlaneContact::getPositionError | ( | const State & | state | ) | const |
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.
Vec3 SimTK::Constraint::PointOnPlaneContact::getVelocityErrors | ( | const State & | state | ) | const |
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 x-y-z 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.
Vec3 SimTK::Constraint::PointOnPlaneContact::getAccelerationErrors | ( | const State & | state | ) | const |
This vector is the time derivative of the value returned by getVelocityError().
The given state must have already been realized through Stage::Acceleration.
Vec3 SimTK::Constraint::PointOnPlaneContact::getMultipliers | ( | const State & | state | ) | const |
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.
Vec3 SimTK::Constraint::PointOnPlaneContact::getForceOnFollowerPoint | ( | const State & | state | ) | const |
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.