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

#include <CableSpan.h>

Public Member Functions
	CableSpan ()
	Construct a new cable that can be configured later.

	~CableSpan () noexcept=default
	Delete the cable if this handle was the last reference to it.

	CableSpan (const CableSpan &)=default
	Copy constructor is shallow and reference counted.

CableSpan &	operator= (const CableSpan &source)=default
	Copy assignment is shallow and reference counted.

	CableSpan (CableSpan &&) noexcept=default

CableSpan &	operator= (CableSpan &&) noexcept=default

Cable construction
	CableSpan (CableSubsystem &subsystem, MobilizedBodyIndex originBody, const Vec3 &originStation, MobilizedBodyIndex terminationBody, const Vec3 &terminationStation)
	Create a straight-line cable spanning between a point fixed on one body to one fixed on another body.

CableSpanObstacleIndex	addObstacle (MobilizedBodyIndex obstacleBody, const Transform &X_BS, std::shared_ptr< const ContactGeometry > obstacleGeometry)
	Add an obstacle to the cable's path that must be wrapped over.

CableSpanObstacleIndex	addObstacle (MobilizedBodyIndex obstacleBody, const Transform &X_BS, std::shared_ptr< const ContactGeometry > obstacleGeometry, const Vec3 &contactPointHint_S)
	Add an obstacle to the cable's path that must be wrapped over.

int	getNumObstacles () const
	Get the number of obstacles added to the path.

CableSpanViaPointIndex	addViaPoint (MobilizedBodyIndex viaPointBody, const Vec3 &station_B)
	Add a via point that the cable's path must pass through.

int	getNumViaPoints () const
	Get the number of via points added to the path.

CableSpanIndex	getIndex () const
	Get the cable's index in the CableSubsystem.

End points configuration
MobilizedBodyIndex	getOriginBodyIndex () const
	Get the index of the mobilized body that the cable's origin point is attached to.

void	setOriginBodyIndex (MobilizedBodyIndex originBody)
	Set the index of the mobilized body that the cable's origin point is attached to.

MobilizedBodyIndex	getTerminationBodyIndex () const
	Get the index of the mobilized body that the cable's termination point is attached to.

void	setTerminationBodyIndex (MobilizedBodyIndex terminationBody)
	Set the index of the mobilized body that the cable's termination point is attached to.

Vec3	getOriginStation () const
	Get the cable's origin point defined in body fixed coordinates.

void	setOriginStation (const Vec3 &originStation)
	Set the cable's origin point defined in body fixed coordinates.

Vec3	getTerminationStation () const
	Get the cable's termination point defined in body fixed coordinates.

void	setTerminationStation (const Vec3 &terminationStation)
	Set the cable's termination point defined in body fixed coordinates.

End point computations
UnitVec3	calcOriginTangentDirection (const State &state) const
	Calculate the cable span tangent direction at the origin.

void	calcOriginUnitForce (const State &state, SpatialVec &unitForce_G) const
	Calculate the unit force exerted by the cable at the cable origin (in ground frame).

UnitVec3	calcTerminationTangentDirection (const State &state) const
	Calculate the cable span tangent direction at the termination.

void	calcTerminationUnitForce (const State &state, SpatialVec &unitForce_G) const
	Calculate the unit force exerted by the cable at the cable termination (in ground frame).

Obstacle configuration
const MobilizedBodyIndex &	getObstacleMobilizedBodyIndex (CableSpanObstacleIndex ix) const
	Get the index of the mobilized body that the obstacle is attached to.

void	setObstacleMobilizedBodyIndex (CableSpanObstacleIndex ix, MobilizedBodyIndex body)
	Set the index of the mobilized body that the obstacle is attached to.

const Transform &	getObstacleTransformSurfaceToBody (CableSpanObstacleIndex ix) const
	Get the orientation and position of the obstacle's surface with respect to its mobilized body.

void	setObstacleTransformSurfaceToBody (CableSpanObstacleIndex ix, const Transform &X_BS)
	Set the orientation and position of the obstacle's surface with respect to its mobilized body.

const ContactGeometry &	getObstacleContactGeometry (CableSpanObstacleIndex ix) const
	Get the obstacle's ContactGeometry.

void	setObstacleContactGeometry (CableSpanObstacleIndex ix, std::shared_ptr< const ContactGeometry > obstacleGeometry)
	Set the obstacle's ContactGeometry.

Vec3	getObstacleContactPointHint (CableSpanObstacleIndex ix) const
	Get the point on the obstacle used to compute the initial path.

void	setObstacleContactPointHint (CableSpanObstacleIndex ix, Vec3 contactPointHint_S)
	Set the point on the obstacle used to compute the initial path.

Via point configuration
const MobilizedBodyIndex &	getViaPointMobilizedBodyIndex (CableSpanViaPointIndex ix) const
	Get the index of the mobilized body that the via point is attached to.

void	setViaPointMobilizedBodyIndex (CableSpanViaPointIndex ix, MobilizedBodyIndex body)
	Set the index of the mobilized body that the via point is attached to.

Vec3	getViaPointStation (CableSpanViaPointIndex ix) const
	Get the station of the via point in body fixed coordinates.

void	setViaPointStation (CableSpanViaPointIndex ix, const Vec3 &station_B)
	Set the station of the via point in body fixed coordinates.

Solver configuration
Real	getCurveSegmentAccuracy () const
	Get the accuracy used by the numerical integrator when computing a geodesic over an obstacle.

void	setCurveSegmentAccuracy (Real accuracy)
	Set the accuracy used by the numerical integrator when computing a geodesic over an obstacle.

int	getSolverMaxIterations () const
	Get the maximum number of solver iterations for finding the optimal path.

void	setSolverMaxIterations (int maxIterations)
	Set the maximum number of solver iterations for finding the optimal path.

int	getNumSolverIterations (const State &state) const
	Number of solver iterations used to compute the current cable's path.

Real	getSmoothnessTolerance () const
	Get the smoothness tolerance used to compute the optimal path.

void	setSmoothnessTolerance (Real tolerance)
	Set the smoothness tolerance used to compute the optimal path.

Real	getSmoothness (const State &state) const
	The smoothness of the current cable's path.

void	setAlgorithm (CableSpanAlgorithm algorithm)
	Set the algorithm used to compute the optimal path.

bool	getUseWarmStart () const
	Whether the solver uses the previously computed path as a warm start to compute the next path solution.

void	setUseWarmStart (bool useWarmStart)
	Set whether the solver uses the previously computed path as a warm start to compute the next path solution.

Path computations
Real	calcLength (const State &state) const
	Get the total cable length.

Real	calcLengthDot (const State &state) const
	Get the derivative of the total cable length.

void	applyBodyForces (const State &state, Real tension, Vector_< SpatialVec > &bodyForcesInG) const
	Given a tension > 0 acting uniformly along this cable, compute the resulting forces applied to the bodies it touches.

Real	calcCablePower (const State &state, Real tension) const
	Compute the cable power.

void	calcDecorativePathPoints (const State &state, const std::function< void(Vec3 point_G)> &sink) const
	Compute points on the path spanned by this cable suitable for visualization purposes.

void	calcResampledDecorativePathPoints (const State &state, int numCurveSegmentSamples, const std::function< void(Vec3 point_G)> &sink) const
	Compute `numCurveSegmentSamples` equally-spaced points for each curve segment along the path spanned by this cable and emit them to `sink`.

Curve segment computations
bool	isInContactWithObstacle (const State &state, CableSpanObstacleIndex ix) const
	Returns true when the cable is in contact with the obstacle.

Transform	calcCurveSegmentInitialFrenetFrame (const State &state, CableSpanObstacleIndex ix) const
	Compute the Frenet frame associated with the obstacle's curve segment at the initial contact point on that obstacle.

Transform	calcCurveSegmentFinalFrenetFrame (const State &state, CableSpanObstacleIndex ix) const
	Compute the Frenet frame associated with the obstacle's curve segment at the final contact point on that obstacle.

Real	calcCurveSegmentArcLength (const State &state, CableSpanObstacleIndex ix) const
	Get the arc length of the obstacle's curve segment.

void	calcCurveSegmentResampledPoints (const State &state, CableSpanObstacleIndex ix, int numSamples, const std::function< void(Vec3 point_G)> &sink) const
	Compute points along the obstacle's curve segment at equal length intervals.

void	calcCurveSegmentUnitForce (const State &state, CableSpanObstacleIndex ix, SpatialVec &unitForce_G) const
	Calculate the unit force exerted by the cable at the specified obstacle (in ground frame).

Via point computations
Vec3	calcViaPointLocation (const State &state, CableSpanViaPointIndex ix) const
	Compute the location of a via point in the ground frame.

void	calcViaPointUnitForce (const State &state, CableSpanViaPointIndex ix, SpatialVec &unitForce_G) const
	Calculate the unit force exerted by the cable at the specified via point (in ground frame).

UnitVec3	calcViaPointIncomingTangentDirection (const State &state, CableSpanViaPointIndex ix) const
	Calculate the incoming tangent direction of the cable span at the specified via point.

UnitVec3	calcViaPointOutgoingTangentDirection (const State &state, CableSpanViaPointIndex ix) const
	Calculate the outgoing tangent direction of the cable span at the specified via point.

Detailed Description

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

The CableSpan's path can be seen as consisting of straight line segments and curved line segments: A curved segment over each obstacle, and straight segments connecting them to each other and to via points and the end points. Each curved segment is computed as a geodesic to give (in some sense) a shortest path over the surface. During a simulation the cable can slide freely over the obstacle surfaces. It can lose contact with a surface and miss that obstacle in a straight line. Similarly the cable can touchdown on the obstacle if the surface obstructs the straight line segment again. The cable will always slide freely through any via points present in the path.

The path is computed as an optimization problem by computing natural geodesic corrections for each curve segment to compute the locally shortest path, as described in the following publication:

Scholz, A., Sherman, M., Stavness, I. et al (2015). A fast multi-obstacle
muscle wrapping method using natural geodesic variations. Multibody System
Dynamics 36, 195–219.

The overall path is locally the shortest, allowing winding over an obstacle multiple times, without flipping to the other side. The wrapping solver can optionally use the solution from the previous time step as a warm start to improve performance during forward dynamics simulations (see method getUseWarmStart() for more information).

During initialization the path is assumed to be in contact with each obstacle at the user defined contact-point-hint. At each contact point a zero-length-geodesic is computed with the tangent estimated as pointing from the previous path point to the next path point. From this configuration, the solver is started, and the geodesics will be corrected until the entire path is smooth.

Important to note is that the cable's interaction with the obstacles is ordered based on the order in which they were added. That is, if three obstacles are added to a cable, then, the cable can wrap over the first, then the second, and then the third. If the first obstacle spatially collides with the path twice it will not actually wrap over it twice. Use CablePath if this is not the desired behavior.

When via points are present in the cable, the cable is internally divided into cable segments separated by the via points. Obstacles separated by via points have no interaction when geodesic corrections are applied during optimization, and therefore the path for each cable segment is solved independently. This approach is advantageous since cable segments with different sets of wrap obstacles may require a different number of optimization iterations to converge.

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

A CableSpan must be registered with a CableSubsystem which manages their runtime evaluation.

Constructor & Destructor Documentation

◆ CableSpan() [1/4]

SimTK::CableSpan::CableSpan ( )

Construct a new cable that can be configured later.

◆ ~CableSpan()

SimTK::CableSpan::~CableSpan ( )

defaultnoexcept

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

◆ CableSpan() [2/4]

SimTK::CableSpan::CableSpan ( const CableSpan & )

default

Copy constructor is shallow and reference counted.

◆ CableSpan() [3/4]

SimTK::CableSpan::CableSpan ( CableSpan && )

defaultnoexcept

◆ CableSpan() [4/4]

SimTK::CableSpan::CableSpan	(	CableSubsystem &	subsystem,
		MobilizedBodyIndex	originBody,
		const Vec3 &	originStation,
		MobilizedBodyIndex	terminationBody,
		const Vec3 &	terminationStation
	)

Create a straight-line cable spanning between a point fixed on one body to one fixed on another body.

You can add obstacles and move the end points later.

Parameters

subsystem	The subsystem that this cable is adopted by.
originBody	The mobilized body that the origin point is rigidly attached to.
originStation	The origin point of the cable defined in body fixed coordinates.
terminationBody	The mobilized body that the termination point is rigidly attached to.
terminationStation	The termination point of the cable defined in body fixed coordinates.

Member Function Documentation

◆ operator=() [1/2]

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

default

Copy assignment is shallow and reference counted.

◆ operator=() [2/2]

CableSpan & SimTK::CableSpan::operator= ( CableSpan && )

defaultnoexcept

◆ addObstacle() [1/2]

CableSpanObstacleIndex SimTK::CableSpan::addObstacle	(	MobilizedBodyIndex	obstacleBody,
		const Transform &	X_BS,
		std::shared_ptr< const ContactGeometry >	obstacleGeometry
	)

Add an obstacle to the cable's path that must be wrapped over.

Parameters

obstacleBody	The body that the contact geometry is rigidly attached to.
X_BS	Transform specifying the location and orientation of the contact geometry's origin frame with respect to the mobilized body.
obstacleGeometry	The geometry of the obstacle's surface.

Returns: The index of the added obstacle in this cable.

◆ addObstacle() [2/2]

CableSpanObstacleIndex SimTK::CableSpan::addObstacle	(	MobilizedBodyIndex	obstacleBody,
		const Transform &	X_BS,
		std::shared_ptr< const ContactGeometry >	obstacleGeometry,
		const Vec3 &	contactPointHint_S
	)

Add an obstacle to the cable's path that must be wrapped over.

Parameters

obstacleBody	The body that the contact geometry is rigidly attached to.
X_BS	Transform specifying the location and orientation of the contact geometry's origin frame with respect to the mobilized body.
obstacleGeometry	The geometry of the obstacle's surface.
contactPointHint_S	A guess for the cable's initial contact point on the obstacle, in local surface frame coordinates. The point will be used as a starting point when computing the initial cable path. As such, it does not have to lie on the contact geometry's surface, nor does it have to belong to a valid cable path. If a smooth path cannot be made through the hint, the contact point is placed instead where the straight line between the neighboring path points comes closest to the surface.

Returns: The index of the added obstacle in this cable.

◆ getNumObstacles()

int SimTK::CableSpan::getNumObstacles ( ) const

Get the number of obstacles added to the path.

◆ addViaPoint()

CableSpanViaPointIndex SimTK::CableSpan::addViaPoint	(	MobilizedBodyIndex	viaPointBody,
		const Vec3 &	station_B
	)

Add a via point that the cable's path must pass through.

Parameters

viaPointBody	The body that the via point is rigidly attached to.
station_B	The via point's station in body fixed coordinates.

Returns: The index of the added via point in this cable.

◆ getNumViaPoints()

int SimTK::CableSpan::getNumViaPoints ( ) const

Get the number of via points added to the path.

◆ getIndex()

CableSpanIndex SimTK::CableSpan::getIndex ( ) const

Get the cable's index in the CableSubsystem.

◆ getOriginBodyIndex()

MobilizedBodyIndex SimTK::CableSpan::getOriginBodyIndex ( ) const

Get the index of the mobilized body that the cable's origin point is attached to.

◆ setOriginBodyIndex()

void SimTK::CableSpan::setOriginBodyIndex ( MobilizedBodyIndex originBody )

Set the index of the mobilized body that the cable's origin point is attached to.

◆ getTerminationBodyIndex()

MobilizedBodyIndex SimTK::CableSpan::getTerminationBodyIndex ( ) const

Get the index of the mobilized body that the cable's termination point is attached to.

◆ setTerminationBodyIndex()

void SimTK::CableSpan::setTerminationBodyIndex ( MobilizedBodyIndex terminationBody )

Set the index of the mobilized body that the cable's termination point is attached to.

◆ getOriginStation()

Vec3 SimTK::CableSpan::getOriginStation ( ) const

Get the cable's origin point defined in body fixed coordinates.

◆ setOriginStation()

void SimTK::CableSpan::setOriginStation ( const Vec3 & originStation )

Set the cable's origin point defined in body fixed coordinates.

◆ getTerminationStation()

Vec3 SimTK::CableSpan::getTerminationStation ( ) const

Get the cable's termination point defined in body fixed coordinates.

◆ setTerminationStation()

void SimTK::CableSpan::setTerminationStation ( const Vec3 & terminationStation )

Set the cable's termination point defined in body fixed coordinates.

◆ calcOriginTangentDirection()

UnitVec3 SimTK::CableSpan::calcOriginTangentDirection ( const State & state ) const

Calculate the cable span tangent direction at the origin.

The direction points along the path from the origin towards the termination. State must be realized to Stage::Position.

Parameters

state State of the system.

◆ calcOriginUnitForce()

void SimTK::CableSpan::calcOriginUnitForce	(	const State &	state,
		SpatialVec &	unitForce_G
	)		const

Calculate the unit force exerted by the cable at the cable origin (in ground frame).

The force is applied tangent to the cable span pointing towards the termination, i.e., the same direction as returned by calcOriginTangentDirection(). The effect of a tensile force applied to the cable can be obtained by multiplying the returned unit force by the cable tension. State must be realized to Stage::Position.

Parameters

	state	State of the system.
[out]	unitForce_G	The resulting unit spatial force in ground frame.

◆ calcTerminationTangentDirection()

UnitVec3 SimTK::CableSpan::calcTerminationTangentDirection ( const State & state ) const

Calculate the cable span tangent direction at the termination.

The direction points along the path from the origin towards the termination. State must be realized to Stage::Position.

Parameters

state State of the system.

◆ calcTerminationUnitForce()

void SimTK::CableSpan::calcTerminationUnitForce	(	const State &	state,
		SpatialVec &	unitForce_G
	)		const

Calculate the unit force exerted by the cable at the cable termination (in ground frame).

The force is applied tangent to the cable span pointing towards the origin, i.e., the opposite of the direction returned by calcTerminationTangentDirection(). The effect of a tensile force applied to the cable can be obtained by multiplying the returned unit force by the cable tension. State must be realized to Stage::Position.

Parameters

	state	State of the system.
[out]	unitForce_G	The resulting unit spatial force in ground frame.

◆ getObstacleMobilizedBodyIndex()

const MobilizedBodyIndex & SimTK::CableSpan::getObstacleMobilizedBodyIndex ( CableSpanObstacleIndex ix ) const

Get the index of the mobilized body that the obstacle is attached to.

Parameters

ix	The index of the obstacle in this CableSpan.

Returns: The index of the mobilized body that the obstacle is attached to.

◆ setObstacleMobilizedBodyIndex()

void SimTK::CableSpan::setObstacleMobilizedBodyIndex	(	CableSpanObstacleIndex	ix,
		MobilizedBodyIndex	body
	)

Set the index of the mobilized body that the obstacle is attached to.

Parameters

ix	The index of the obstacle in this CableSpan.
body	The index of the mobilized body that the obstacle is attached to.

◆ getObstacleTransformSurfaceToBody()

const Transform & SimTK::CableSpan::getObstacleTransformSurfaceToBody ( CableSpanObstacleIndex ix ) const

Get the orientation and position of the obstacle's surface with respect to its mobilized body.

Parameters

ix	The index of the obstacle in this CableSpan.

Returns: The orientation and position of the obstacle's surface with respect to it's mobilized body.

◆ setObstacleTransformSurfaceToBody()

void SimTK::CableSpan::setObstacleTransformSurfaceToBody	(	CableSpanObstacleIndex	ix,
		const Transform &	X_BS
	)

Set the orientation and position of the obstacle's surface with respect to its mobilized body.

Parameters

ix	The index of the obstacle in this CableSpan.
X_BS	The orientation and position of the obstacle's surface with respect to it's mobilized body.

◆ getObstacleContactGeometry()

const ContactGeometry & SimTK::CableSpan::getObstacleContactGeometry ( CableSpanObstacleIndex ix ) const

Get the obstacle's ContactGeometry.

Parameters

ix	The index of the obstacle in this CableSpan.

Returns: The obstacle's surface geometry.

◆ setObstacleContactGeometry()

void SimTK::CableSpan::setObstacleContactGeometry	(	CableSpanObstacleIndex	ix,
		std::shared_ptr< const ContactGeometry >	obstacleGeometry
	)

Set the obstacle's ContactGeometry.

Parameters

ix	The index of the obstacle in this CableSpan.
obstacleGeometry	The obstacle's surface geometry.

◆ getObstacleContactPointHint()

Vec3 SimTK::CableSpan::getObstacleContactPointHint ( CableSpanObstacleIndex ix ) const

Get the point on the obstacle used to compute the initial path.

Parameters

ix	The index of the obstacle in this CableSpan.

Returns: The point in the obstacle's local surface coordinates.

◆ setObstacleContactPointHint()

void SimTK::CableSpan::setObstacleContactPointHint	(	CableSpanObstacleIndex	ix,
		Vec3	contactPointHint_S
	)

Set the point on the obstacle used to compute the initial path.

Parameters

ix The index of the obstacle in this CableSpan.

contactPointHint_S A guess for the cable's initial contact point on the obstacle, in local surface frame coordinates. The point will be used as a starting point when computing the initial cable path. As such, it does not have to lie on the contact geometry's surface, nor does it have to belong to the optimal cable path. If a smooth path cannot be made through the hint, the contact point is placed instead where the straight line between the neighboring path points comes closest to the surface.

◆ getViaPointMobilizedBodyIndex()

const MobilizedBodyIndex & SimTK::CableSpan::getViaPointMobilizedBodyIndex ( CableSpanViaPointIndex ix ) const

Get the index of the mobilized body that the via point is attached to.

Parameters

ix	The index of the via point in this CableSpan.

Returns: The index of the mobilized body that the via point is attached to.

◆ setViaPointMobilizedBodyIndex()

void SimTK::CableSpan::setViaPointMobilizedBodyIndex	(	CableSpanViaPointIndex	ix,
		MobilizedBodyIndex	body
	)

Set the index of the mobilized body that the via point is attached to.

Parameters

ix	The index of the via point in this CableSpan.
body	The index of the mobilized body that the via point is attached to.

◆ getViaPointStation()

Vec3 SimTK::CableSpan::getViaPointStation ( CableSpanViaPointIndex ix ) const

Get the station of the via point in body fixed coordinates.

Parameters

ix	The index of the via point in this CableSpan.

Returns: The station of the via point in body fixed coordinates.

◆ setViaPointStation()

void SimTK::CableSpan::setViaPointStation	(	CableSpanViaPointIndex	ix,
		const Vec3 &	station_B
	)

Set the station of the via point in body fixed coordinates.

Parameters

ix	The index of the via point in this CableSpan.
station_B	The station of the via point in body fixed coordinates.

◆ getCurveSegmentAccuracy()

Real SimTK::CableSpan::getCurveSegmentAccuracy ( ) const

Get the accuracy used by the numerical integrator when computing a geodesic over an obstacle.

Note: This does not affect the integrator that is used to propagate the multibody system over time, that is a different integrator.

◆ setCurveSegmentAccuracy()

void SimTK::CableSpan::setCurveSegmentAccuracy ( Real accuracy )

Set the accuracy used by the numerical integrator when computing a geodesic over an obstacle.

Note: This does not affect the integrator that is used to propagate the multibody system over time, that is a different integrator.

◆ getSolverMaxIterations()

int SimTK::CableSpan::getSolverMaxIterations ( ) const

Get the maximum number of solver iterations for finding the optimal path.

◆ setSolverMaxIterations()

void SimTK::CableSpan::setSolverMaxIterations ( int maxIterations )

Set the maximum number of solver iterations for finding the optimal path.

◆ getNumSolverIterations()

int SimTK::CableSpan::getNumSolverIterations ( const State & state ) const

Number of solver iterations used to compute the current cable's path.

State must be realized to Stage::Position. If via points are present in the cable, the sum of the iterations used to compute the path for each cable segment is returned.

Parameters

state System State.

Returns: Number of solver iterations used.

◆ getSmoothnessTolerance()

Real SimTK::CableSpan::getSmoothnessTolerance ( ) const

Get the smoothness tolerance used to compute the optimal path.

The (non) smoothness is defined as the angular discontinuity at the points where straight- and curved-line segments meet, measured in radians. When computing the optimal path this smoothness is optimized, and the solver stops when reaching given tolerance.

◆ setSmoothnessTolerance()

void SimTK::CableSpan::setSmoothnessTolerance ( Real tolerance )

Set the smoothness tolerance used to compute the optimal path.

See CableSpan::getSmoothnessTolerance.

◆ getSmoothness()

Real SimTK::CableSpan::getSmoothness ( const State & state ) const

The smoothness of the current cable's path.

If via points are present in the cable, the maximum smoothness error across all cable segments is returned. See CableSpan::getSmoothnessTolerance. State must be realized to Stage::Position.

◆ setAlgorithm()

void SimTK::CableSpan::setAlgorithm ( CableSpanAlgorithm algorithm )

Set the algorithm used to compute the optimal path.

◆ getUseWarmStart()

bool SimTK::CableSpan::getUseWarmStart ( ) const

Whether the solver uses the previously computed path as a warm start to compute the next path solution.

When true (the default), each path computation is seeded with the previous optimal path, which is typically much faster. When false, the path is always recomputed from each obstacle's initial contact-point hint (see addObstacle and setObstacleContactPointHint) every time the State is realized to Stage::Position.

◆ setUseWarmStart()

void SimTK::CableSpan::setUseWarmStart ( bool useWarmStart )

Set whether the solver uses the previously computed path as a warm start to compute the next path solution.

Note: Changing this setting invalidates the Stage::Topology cache. Therefore, callers should re-realize the system to Stage::Topology and obtain a new State before any new computations.

◆ calcLength()

Real SimTK::CableSpan::calcLength ( const State & state ) const

Get the total cable length.

State must be realized to Stage::Position.

Parameters

state State of the system.

Returns: The total cable length.

◆ calcLengthDot()

Real SimTK::CableSpan::calcLengthDot ( const State & state ) const

Get the derivative of the total cable length.

State must be realized to Stage::Velocity.

Parameters

state State of the system.

Returns: The time derivative of the total cable length.

◆ applyBodyForces()

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

Given a tension > 0 acting uniformly along this cable, compute the resulting forces applied 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::CableSpan::calcCablePower	(	const State &	state,
		Real	tension
	)		const

Compute the cable power.

State must be realized to Stage::Position.

Parameters

state	State of the system.
tension	The tension force in the cable.

Returns: The cable power.

◆ calcDecorativePathPoints()

void SimTK::CableSpan::calcDecorativePathPoints	(	const State &	state,
		const std::function< void(Vec3 point_G)> &	sink
	)		const

Compute points on the path spanned by this cable suitable for visualization purposes.

State must be realized to Stage::Position.

Parameters

state	System State.
sink	Where the path points (in ground frame) will be written to.

◆ calcResampledDecorativePathPoints()

void SimTK::CableSpan::calcResampledDecorativePathPoints	(	const State &	state,
		int	numCurveSegmentSamples,
		const std::function< void(Vec3 point_G)> &	sink
	)		const

Compute numCurveSegmentSamples equally-spaced points for each curve segment along the path spanned by this cable and emit them to sink.

This can be useful for visualization purposes, where it can be important to limit the amount of visualized path points for performance reasons. When an obstacle is not in contact with the cable its decorative path points are emitted at the point on the cable closest to that obstacle. Therefore, the number of emitted points remains constant: the origin and termination points, the via points, and the number of obstacles times numCurveSegmentSamples.

State must be realized to Stage::Position.

Parameters

state	System State.
numCurveSegmentSamples	The number of samples to take per curve segment (minimum is 2).
sink	Where the path points (in ground frame) will be written to.

◆ isInContactWithObstacle()

bool SimTK::CableSpan::isInContactWithObstacle	(	const State &	state,
		CableSpanObstacleIndex	ix
	)		const

Returns true when the cable is in contact with the obstacle.

State must be realized to Stage::Position.

Parameters

state	State of the system.
ix	The index of the obstacle in this CableSpan.

◆ calcCurveSegmentInitialFrenetFrame()

Transform SimTK::CableSpan::calcCurveSegmentInitialFrenetFrame	(	const State &	state,
		CableSpanObstacleIndex	ix
	)		const

Compute the Frenet frame associated with the obstacle's curve segment at the initial contact point on that obstacle.

If the path is not in contact with the obstacle's surface the frame will contain invalid data (NaNs). The Frenet frame is measured relative to ground, with the tangent along the X axis, the surface normal along the Y axis and the binormal along the Z axis. State must be realized to Stage::Position.

Parameters

state	State of the system.
ix	The index of the obstacle in this CableSpan.

Returns: The Frenet frame at the obstacle's initial contact point.

◆ calcCurveSegmentFinalFrenetFrame()

Transform SimTK::CableSpan::calcCurveSegmentFinalFrenetFrame	(	const State &	state,
		CableSpanObstacleIndex	ix
	)		const

Compute the Frenet frame associated with the obstacle's curve segment at the final contact point on that obstacle.

If the path is not in contact with the obstacle's surface the frame will contain invalid data (NaNs). The Frenet frame is measured relative to ground, with the tangent along the X axis, the surface normal along the Y axis and the binormal along the Z axis. State must be realized to Stage::Position.

Parameters

state	State of the system.
ix	The index of the obstacle in this CableSpan.

Returns: The Frenet frame at the obstacle's final contact point.

◆ calcCurveSegmentArcLength()

Real SimTK::CableSpan::calcCurveSegmentArcLength	(	const State &	state,
		CableSpanObstacleIndex	ix
	)		const

Get the arc length of the obstacle's curve segment.

Returns NaN if the obstacle is not in contact with the path. State must be realized to Stage::Position.

Parameters

state	State of the system.
ix	The index of the obstacle in this CableSpan.

Returns: The arc length.

◆ calcCurveSegmentResampledPoints()

void SimTK::CableSpan::calcCurveSegmentResampledPoints	(	const State &	state,
		CableSpanObstacleIndex	ix,
		int	numSamples,
		const std::function< void(Vec3 point_G)> &	sink
	)		const

Compute points along the obstacle's curve segment at equal length intervals.

The first and last contact point of the curve segment are always included. Therefore the minimum allowed number of samples is 2.

For analytic surfaces the resampled points are computed analytically. Otherwise, the points are computed from the internally stored geodesic using Hermite interpolation, generally resulting in a good approximation of the point at the requested arc lengths.

When the curve segment is not in contact with the obstacle there is no geodesic to sample. In that case all numSamples points are emitted coincident at the point on the straight cable segment that lies closest to the obstacle, so that the number of emitted points stays constant.

Parameters

state	State of the system.
ix	The index of the obstacle in this CableSpan.
numSamples	The number of resampling points (minimum is 2).
sink	Where the resampled points (in ground frame) will be written to.

◆ calcCurveSegmentUnitForce()

void SimTK::CableSpan::calcCurveSegmentUnitForce	(	const State &	state,
		CableSpanObstacleIndex	ix,
		SpatialVec &	unitForce_G
	)		const

Calculate the unit force exerted by the cable at the specified obstacle (in ground frame).

The effect of a tensile force applied to the cable can be obtained by multiplying the returned unit force by the cable tension. State must be realized to Stage::Position.

Parameters

	state	State of the system.
	ix	The index of the obstacle in this CableSpan.
[out]	unitForce_G	The resulting unit spatial force in ground frame.

◆ calcViaPointLocation()

Vec3 SimTK::CableSpan::calcViaPointLocation	(	const State &	state,
		CableSpanViaPointIndex	ix
	)		const

Compute the location of a via point in the ground frame.

State must be realized to Stage::Position.

Parameters

state	State of the system.
ix	The index of the via point in this CableSpan.

Returns: The location of the via point in the ground frame.

◆ calcViaPointUnitForce()

void SimTK::CableSpan::calcViaPointUnitForce	(	const State &	state,
		CableSpanViaPointIndex	ix,
		SpatialVec &	unitForce_G
	)		const

Calculate the unit force exerted by the cable at the specified via point (in ground frame).

The effect of a tensile force applied to the cable can be obtained by multiplying the returned unit force by the cable tension. State must be realized to Stage::Position.

Parameters

	state	State of the system.
	ix	The index of the via point in this CableSpan.
[out]	unitForce_G	The resulting unit spatial force in ground frame.

◆ calcViaPointIncomingTangentDirection()

UnitVec3 SimTK::CableSpan::calcViaPointIncomingTangentDirection	(	const State &	state,
		CableSpanViaPointIndex	ix
	)		const

Calculate the incoming tangent direction of the cable span at the specified via point.

The direction points along the path from the origin towards the via point. State must be realized to Stage::Position.

Parameters

state	State of the system.
ix	The index of the via point in this CableSpan.

◆ calcViaPointOutgoingTangentDirection()

UnitVec3 SimTK::CableSpan::calcViaPointOutgoingTangentDirection	(	const State &	state,
		CableSpanViaPointIndex	ix
	)		const

Calculate the outgoing tangent direction of the cable span at the specified via point.

The direction points along the path from the via point towards the termination point. State must be realized to Stage::Position.

Parameters

state	State of the system.
ix	The index of the via point in this CableSpan.

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

CableSpan.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CableSpan() [1/4]

◆ ~CableSpan()

◆ CableSpan() [2/4]

◆ CableSpan() [3/4]

◆ CableSpan() [4/4]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ addObstacle() [1/2]

◆ addObstacle() [2/2]

◆ getNumObstacles()

◆ addViaPoint()

◆ getNumViaPoints()

◆ getIndex()

◆ getOriginBodyIndex()

◆ setOriginBodyIndex()

◆ getTerminationBodyIndex()

◆ setTerminationBodyIndex()

◆ getOriginStation()

◆ setOriginStation()

◆ getTerminationStation()

◆ setTerminationStation()

◆ calcOriginTangentDirection()

◆ calcOriginUnitForce()

◆ calcTerminationTangentDirection()

◆ calcTerminationUnitForce()

◆ getObstacleMobilizedBodyIndex()

◆ setObstacleMobilizedBodyIndex()

◆ getObstacleTransformSurfaceToBody()

◆ setObstacleTransformSurfaceToBody()

◆ getObstacleContactGeometry()

◆ setObstacleContactGeometry()

◆ getObstacleContactPointHint()

◆ setObstacleContactPointHint()

◆ getViaPointMobilizedBodyIndex()

◆ setViaPointMobilizedBodyIndex()

◆ getViaPointStation()

◆ setViaPointStation()

◆ getCurveSegmentAccuracy()

◆ setCurveSegmentAccuracy()

◆ getSolverMaxIterations()

◆ setSolverMaxIterations()

◆ getNumSolverIterations()

◆ getSmoothnessTolerance()

◆ setSmoothnessTolerance()

◆ getSmoothness()

◆ setAlgorithm()

◆ getUseWarmStart()

◆ setUseWarmStart()

◆ calcLength()

◆ calcLengthDot()

◆ applyBodyForces()

◆ calcCablePower()

◆ calcDecorativePathPoints()

◆ calcResampledDecorativePathPoints()

◆ isInContactWithObstacle()

◆ calcCurveSegmentInitialFrenetFrame()

◆ calcCurveSegmentFinalFrenetFrame()

◆ calcCurveSegmentArcLength()

◆ calcCurveSegmentResampledPoints()

◆ calcCurveSegmentUnitForce()

◆ calcViaPointLocation()

◆ calcViaPointUnitForce()

◆ calcViaPointIncomingTangentDirection()

◆ calcViaPointOutgoingTangentDirection()