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

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

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

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

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

	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. More...

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. More...

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. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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. More...

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

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. More...

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

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. More...

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. More...

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

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. More...

Detailed Description

This class represents the path of a frictionless cable from an origin point fixed to a body, over geometric obstacles 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 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 path is computed as an optimization problem using the previous optimal path as the warm start. This is done 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.

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.

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.

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.

◆ 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.

◆ 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.

◆ 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.

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.

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.

◆ 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.

◆ 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.

This function throws an exception if the obstacle is not in contact with the cable. Check isInContactWithObstacle() before calling this function.

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.

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()

◆ getOriginBodyIndex()

◆ setOriginBodyIndex()

◆ getTerminationBodyIndex()

◆ setTerminationBodyIndex()

◆ getOriginStation()

◆ setOriginStation()

◆ getTerminationStation()

◆ setTerminationStation()

◆ getObstacleMobilizedBodyIndex()

◆ setObstacleMobilizedBodyIndex()

◆ getObstacleTransformSurfaceToBody()

◆ setObstacleTransformSurfaceToBody()

◆ getObstacleContactGeometry()

◆ setObstacleContactGeometry()

◆ getObstacleContactPointHint()

◆ setObstacleContactPointHint()

◆ getCurveSegmentAccuracy()

◆ setCurveSegmentAccuracy()

◆ getSolverMaxIterations()

◆ setSolverMaxIterations()

◆ getNumSolverIterations()

◆ getSmoothnessTolerance()

◆ setSmoothnessTolerance()

◆ getSmoothness()

◆ setAlgorithm()

◆ calcLength()

◆ calcLengthDot()

◆ applyBodyForces()

◆ calcCablePower()

◆ calcDecorativePathPoints()

◆ isInContactWithObstacle()

◆ calcCurveSegmentInitialFrenetFrame()

◆ calcCurveSegmentFinalFrenetFrame()

◆ calcCurveSegmentArcLength()

◆ calcCurveSegmentResampledPoints()