Simbody  3.7
SimTK::CablePath Class Reference

This class represents the path of a frictionless cable from an origin point fixed to a body, through via points and over geometric obstacles fixed to other bodies, to a final termination point. More...

Public Member Functions

 CablePath (CableTrackerSubsystem &cables, const MobilizedBody &originBody, const Vec3 &defaultOriginPoint, const MobilizedBody &terminationBody, const Vec3 &defaultTerminationPoint)
 Create a straight-line cable path connecting a point fixed on one body with one fixed on another body. More...
 
 CablePath (CableTrackerSubsystem &cables, const MobilizedBody &originBody, const MobilizedBody &terminationBody)
 Constructor taking only the origin and terminal bodies with the expectation that you'll set the end point locations later. More...
 
 CablePath (const CablePath &source)
 Copy constructor is shallow and reference counted. More...
 
CablePathoperator= (const CablePath &source)
 Copy assignment is shallow and reference counted. More...
 
 ~CablePath ()
 Delete the cable path if this handle was the last reference to it. More...
 
void solveForInitialCablePath (State &state) const
 TODO: Calculate the initial cable path, without using any prior solution. More...
 
int getNumObstacles () const
 Return the total number of obstacles (origin point, surfaces and via points, and termination point) that were provided for this cable path, regardless of whether they are currently in use. More...
 
const CableObstaclegetObstacle (CableObstacleIndex obstacleIx) const
 Return a const reference to one of the obstacles along this path, given by its index starting at zero for the origin point. More...
 
Real getCableLength (const State &state) const
 Return the total length of the cable that was calculated for the configuration supplied in state. More...
 
Real getCableLengthDot (const State &state) const
 Return the cable rate (time derivative of cable length) that was calculated for the configuration and velocities supplied in state. More...
 
void applyBodyForces (const State &state, Real tension, Vector_< SpatialVec > &bodyForcesInG) const
 Given a tension > 0 acting uniformly along this cable, apply the resulting forces to the bodies it touches. More...
 
Real calcCablePower (const State &state, Real tension) const
 Calculate the power this cable would apply or dissipate at the given tension (>0) value, using the velocities provided in the given state, which must already have been realized to Velocity stage. More...
 
Real getIntegratedCableLengthDot (const State &state) const
 (Advanced) Get the time integral of cable length dot. More...
 
void setIntegratedCableLengthDot (State &state, Real value) const
 (Advanced) Initialize the integral of the cable length rate. More...
 
 CablePath ()
 Default constructor creates an empty cable path not associated with any subsystem; don't use this. More...
 
const Impl & getImpl () const
 
Impl & updImpl ()
 

Detailed Description

This class represents the path of a frictionless cable from an origin point fixed to a body, through via points and over geometric obstacles fixed to other bodies, to a final termination point.

The cable ends are attached at the origin and termination points while the cable is free to slide through the via points and along the obstacle surfaces. The cable follows a geodesic curve (usually the shortest path) over each surface.

During initialization, if there is more than one possible geodesic over a surface, or if a straight line path would miss the surface altogether, we'll take the shortest route unless the user has provided a "near point" on the surface. In that case whichever of the possible path segments runs closest to the near point is chosen. During continuation, only local path movement is allowed so the path segment will not flip from one side to the other once it has been initialized, even if that means it does not follow the shortest possible geodesic. The near point is ignored during continuation.

Note that a CablePath is a geometric object, not a force or constraint element. That is, a CablePath alone will not influence the behavior of a simulation. However, forces and constraint elements can be constructed that make use of a CablePath to generate forces. For an example, see CableSpring.

The auxiliary class CableObstacle and its subclasses are used to specify the via points and obstacles that affect a particular CablePath. CablePath objects must be registered with a CablePathSubsystem which manages their runtime evaluation.

Notation

For convenience, we include the origin and termination points as obstacles, with the origin being obstacle zero, followed by m via point and surface obstacles numbered 1 to m, followed by the termination point as obstacle t=m+1. Every obstacle is represented by two "contact points", P and Q, which we'll number Pi and Qi for obstacle i. The obstacles are separated by straight-line segments running from Qi-1 to Pi. Starting at the origin Q0, the path first touches the surface of obstacle 1 at P1, travels over the surface to Q1, and then leaves the surface towards the termination point Pt. That is, Pi's path coordinate must be less than Qi's. The segment from P to Q is a geodesic over the surface. For via points, points P and Q are in the same location but there are two different tangents associated with them in the incoming and outgoing straight-line directions. For the origin obstacle, only point Q is relevant and for the termination obstacle only point P is relevant.

See also
CableObstacle, CableSpring, CableTrackerSubsystem

Constructor & Destructor Documentation

◆ CablePath() [1/4]

SimTK::CablePath::CablePath ( CableTrackerSubsystem cables,
const MobilizedBody originBody,
const Vec3 defaultOriginPoint,
const MobilizedBody terminationBody,
const Vec3 defaultTerminationPoint 
)

Create a straight-line cable path connecting a point fixed on one body with one fixed on another body.

You can add additional obstacles and move the end points later.

◆ CablePath() [2/4]

SimTK::CablePath::CablePath ( CableTrackerSubsystem cables,
const MobilizedBody originBody,
const MobilizedBody terminationBody 
)

Constructor taking only the origin and terminal bodies with the expectation that you'll set the end point locations later.

The default locations are set to the body frame origins here.

◆ CablePath() [3/4]

SimTK::CablePath::CablePath ( const CablePath source)

Copy constructor is shallow and reference counted.

◆ ~CablePath()

SimTK::CablePath::~CablePath ( )
inline

Delete the cable path if this handle was the last reference to it.

◆ CablePath() [4/4]

SimTK::CablePath::CablePath ( )
inline

Default constructor creates an empty cable path not associated with any subsystem; don't use this.

Member Function Documentation

◆ operator=()

CablePath& SimTK::CablePath::operator= ( const CablePath source)

Copy assignment is shallow and reference counted.

◆ solveForInitialCablePath()

void SimTK::CablePath::solveForInitialCablePath ( State state) const

TODO: Calculate the initial cable path, without using any prior solution.

The result is saved in the supplied State which may then be used as the initial condition for a time simulation. This method will work hard to find a good starting solution, making use of any hints that have been supplied with the obstacles. This is substantially different (and much more time consuming) than the method used during a simulation, which always starts with the previous solution and is intentionally limited to finding a nearby solution.

The initial solution consists of both (a) which of the surface obstacles are active, and (b) the intersection of the cable with the active obstacles and the path taken by the cable over those obstacles (a geodesic curve). For inactive surface obstacles we determine the closest point between the obstacles and the path; that point will be tracked continuously during a simulation. The user-supplied ordering and near points are respected. The cable length and length rate of change are available immediately after this call; state will have been realized through Velocity stage.

An exception is thrown if no acceptable cable path can be found. In that case the state is still initialized and can be examined to see where the algorithm got stuck.

◆ getNumObstacles()

int SimTK::CablePath::getNumObstacles ( ) const

Return the total number of obstacles (origin point, surfaces and via points, and termination point) that were provided for this cable path, regardless of whether they are currently in use.

◆ getObstacle()

const CableObstacle& SimTK::CablePath::getObstacle ( CableObstacleIndex  obstacleIx) const

Return a const reference to one of the obstacles along this path, given by its index starting at zero for the origin point.

◆ getCableLength()

Real SimTK::CablePath::getCableLength ( const State state) const

Return the total length of the cable that was calculated for the configuration supplied in state.

State must have been realized through Position stage.

◆ getCableLengthDot()

Real SimTK::CablePath::getCableLengthDot ( const State state) const

Return the cable rate (time derivative of cable length) that was calculated for the configuration and velocities supplied in state.

State must have been realized through Velocity stage. Calculation of the cable rate may be initiated if necessary the first time this is called at this state but will be saved in the cache for subsequent accesses.

◆ applyBodyForces()

void SimTK::CablePath::applyBodyForces ( const State state,
Real  tension,
Vector_< SpatialVec > &  bodyForcesInG 
) const

Given a tension > 0 acting uniformly along this cable, apply the resulting forces to the bodies it touches.

The body forces are added into the appropriate slots in the supplied Array which has one entry per body in the same format as is supplied to the calcForce() method of force elements. If the supplied tension is <= 0, signifying a slack cable, this method does nothing.

◆ calcCablePower()

Real SimTK::CablePath::calcCablePower ( const State state,
Real  tension 
) const

Calculate the power this cable would apply or dissipate at the given tension (>0) value, using the velocities provided in the given state, which must already have been realized to Velocity stage.

Power is positive if the cable is adding energy to the system; negative when dissipating. If the supplied tension is <= 0, power may still be dissipated while the cable shortens even though it can't apply forces to the system.

◆ getIntegratedCableLengthDot()

Real SimTK::CablePath::getIntegratedCableLengthDot ( const State state) const

(Advanced) Get the time integral of cable length dot.

This should be the total change in cable length since start of a simulation. This is mostly useful for debugging and testing of cables.

◆ setIntegratedCableLengthDot()

void SimTK::CablePath::setIntegratedCableLengthDot ( State state,
Real  value 
) const

(Advanced) Initialize the integral of the cable length rate.

This is used at the start of a simulation to initilize the integral to the value returned by getCableLength() so that getIntegratedCableLengthDot() will return the same values as getCableLength() during the simulations.

◆ getImpl()

const Impl& SimTK::CablePath::getImpl ( ) const
inline

◆ updImpl()

Impl& SimTK::CablePath::updImpl ( )
inline

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