API  4.1
For C++ developers
OpenSim::AbstractInput Class Referenceabstract

A specialized Socket that connects to an Output signal is an Input. More...

+ Inheritance diagram for OpenSim::AbstractInput:

Public Member Functions

virtual ~AbstractInput ()
 
AbstractInputclone () const override=0
 Create a dynamically-allocated copy. More...
 
void connect (const Object &object) override
 Connect this Socket to the provided connectee object. More...
 
virtual void connect (const AbstractOutput &output, const std::string &alias="")=0
 TODO. More...
 
virtual void connect (const AbstractChannel &channel, const std::string &alias="")=0
 Connect this Input to a single output channel. More...
 
virtual const std::string & getAlias () const =0
 Get the alias for a Channel. More...
 
virtual const std::string & getAlias (unsigned index) const =0
 Get the alias for the Channel indicated by the provided index. More...
 
virtual void setAlias (const std::string &alias)=0
 Set the alias for a Channel. More...
 
virtual void setAlias (unsigned index, const std::string &alias)=0
 Set the alias for the Channel indicated by the provided index. More...
 
virtual std::string getLabel () const =0
 Get the label for this Channel. More...
 
virtual std::string getLabel (unsigned index) const =0
 Get the label for the Channel indicated by the provided index. More...
 
- Public Member Functions inherited from OpenSim::AbstractSocket
virtual ~AbstractSocket ()
 
const std::string & getName () const
 
SimTK::Stage getConnectAtStage () const
 Get the system Stage when the connection should be made. More...
 
bool isListSocket () const
 Can this Socket have more than one connectee? More...
 
unsigned getNumConnectees () const
 The number of slots to fill in order to satisfy this socket. More...
 
virtual bool isConnected () const =0
 Derived classes must satisfy this Interface. More...
 
virtual std::string getConnecteeTypeName () const =0
 Get the type of object this socket connects to. More...
 
virtual const ObjectgetConnecteeAsObject () const
 Generic access to the connectee. More...
 
virtual void findAndConnect (const ComponentPath &connectee)
 Find the connectee using a search with a partial path. More...
 
void findAndConnect (const std::string &connectee)
 Same as findAndConnect(const ComponentPath&), but using a string argument. More...
 
virtual void finalizeConnection (const Component &root)
 Connect this Socket according to its connectee path property given a root Component to search its subcomponents for the connect_to Component. More...
 
virtual void disconnect ()=0
 Clear references to connectees. More...
 
void setConnecteePath (const std::string &name)
 Set connectee path. More...
 
void setConnecteePath (const std::string &name, unsigned ix)
 Set connectee path of a connectee among a list of connectees. More...
 
const std::string & getConnecteePath () const
 Get connectee path. More...
 
const std::string & getConnecteePath (unsigned ix) const
 Get connectee path of a connectee among a list of connectees. More...
 
void appendConnecteePath (const std::string &name)
 
void clearConnecteePath ()
 Clear all connectee paths in the connectee path property. More...
 
const ComponentgetOwner () const
 Get owner component of this socket. More...
 

Static Public Member Functions

static bool parseConnecteePath (const std::string &connecteePath, std::string &componentPath, std::string &outputName, std::string &channelName, std::string &alias)
 Break up a connectee path into its output path, channel name (empty for single-value outputs), and alias. More...
 
static std::string composeConnecteePath (const std::string &componentPath, const std::string &outputName, const std::string &channelName, const std::string &alias)
 Compose the connectee path from its constituents. More...
 

Protected Member Functions

 AbstractInput (const std::string &name, const PropertyIndex &connecteePathIndex, const SimTK::Stage &connectAtStage, Component &owner)
 Create an AbstractInput (Socket) that connects only to an AbstractOutput specified by name and stage at which it should be connected. More...
 
- Protected Member Functions inherited from OpenSim::AbstractSocket
 AbstractSocket (const std::string &name, const PropertyIndex &connecteePathIndex, const SimTK::Stage &connectAtStage, Component &owner)
 Create a Socket with specified name and stage at which it should be connected. More...
 
void setOwner (Component &o)
 Set an internal pointer to the Component that contains this Socket. More...
 
bool hasOwner () const
 This will be false immediately after copy construction or assignment. More...
 
void checkConnecteePathProperty ()
 Check if entries of the connectee path property's value is valid (if it contains spaces, etc.); if so, print out a warning. More...
 
const Property< std::string > & getConnecteePathProp () const
 Const access to the connectee path property from the Component in which this Socket resides. More...
 
Property< std::string > & updConnecteePathProp ()
 Writable access to the connectee path property from the Component in which this Socket resides. More...
 

Detailed Description

A specialized Socket that connects to an Output signal is an Input.

An AbstractInput enables maintenance of a list of unconnected Inputs. An Input can either be a single-value Input or a list Input. A list Input can connect to multiple (Output) Channels.

XML Syntax of a connectee path

For every Input that a component has, the XML representation of the component contains an element named input_<input_name>. For example, a component that has an Input named desired_angle might look like the following in XML:

<MyComponent name="my_comp">
<input_desired_angle>
../foo/angle
</input_desired_angle>
...
</MyComponent>

You use this field to specify the outputs/channels that should be connected to this input (that is, the connectees). The syntax for the connectee path property is as follows:

<path/to/component>|<output_name>[:<channel_name>][(<alias>)]

Angle brackets indicate fields that one would fill in, and square brackets indicate optional fields. The <path/to/component> can be relative or absolute, and describes the location of the Component that contains the desired Output relative to the location of the Component that contains this Input. The <path/to/component> and <output_name> must always be specified. The <channel_name> should only be specified if the Output is a list output (i.e., it has multiple channels). The <alias> is a name for the output/channel that is specific to this input, and it is optional. All fields should contain only letters, numbers, and underscores (the path to the component can contain slashes and periods); fields must not contain spaces. Here are some examples:

  • ../marker_data|column:left_ankle: The TableSourceVec3 component ../marker_data has a list output column, and we want to connect to its left_ankle channel.
  • ../averager|output(knee_joint_center): The component ../averager (presumably a component that averages its inputs) has an output named output, and we are aliasing this output as knee_joint_center.
  • /leg_model/soleus|activation: This connectee path uses the absolute path to component soleus, which has an output named activation.

List inputs can contain multiple entries in its connectee path, with the entries separated by a space. For example:

<input_experimental_markers>
../marker_data|column:left_ankle ../marker_data|column:right_ankle ../averager|output(knee_joint_center)
</input_experimental_markers>

Constructor & Destructor Documentation

◆ ~AbstractInput()

virtual OpenSim::AbstractInput::~AbstractInput ( )
inlinevirtual

◆ AbstractInput()

OpenSim::AbstractInput::AbstractInput ( const std::string &  name,
const PropertyIndex &  connecteePathIndex,
const SimTK::Stage &  connectAtStage,
Component owner 
)
inlineprotected

Create an AbstractInput (Socket) that connects only to an AbstractOutput specified by name and stage at which it should be connected.

Only Component should ever construct this class.

Parameters
namename of the dependent (Abstract)Output.
connecteePathIndexIndex of the property in the containing Component that holds this Input's connectee path(s).
connectAtStageStage at which Input should be connected.
ownerThe component that contains this input.

Member Function Documentation

◆ clone()

AbstractInput* OpenSim::AbstractInput::clone ( ) const
overridepure virtual

Create a dynamically-allocated copy.

You must manage the memory for the returned pointer. This function exists to facilitate the use of SimTK::ClonePtr<AbstractSocket>.

Implements OpenSim::AbstractSocket.

Implemented in OpenSim::Input< T >.

◆ composeConnecteePath()

static std::string OpenSim::AbstractInput::composeConnecteePath ( const std::string &  componentPath,
const std::string &  outputName,
const std::string &  channelName,
const std::string &  alias 
)
inlinestatic

Compose the connectee path from its constituents.

This is the opposite operation of parseConnecteePath(). Example:

 if inputs are
   componentPath --> "/foo/bar"
   outputName    --> "output"
   channelName   --> "channel"
   alias         --> "baz"
 then result --> /foo/bar|output:channel(baz)

◆ connect() [1/3]

void OpenSim::AbstractInput::connect ( const Object connectee)
inlineoverridevirtual

Connect this Socket to the provided connectee object.

If this is a list socket, the connectee is appended to the list of connectees; otherwise, the provided connectee replaces the single connectee.

Implements OpenSim::AbstractSocket.

References OpenSim::Exception::Exception().

◆ connect() [2/3]

virtual void OpenSim::AbstractInput::connect ( const AbstractOutput output,
const std::string &  alias = "" 
)
pure virtual

TODO.

Connect this Input to a single-valued (single-channel) Output or, if this is a list Input and the Output is a list Output, connect to all the channels of the Output. You can optionally provide an alias that will be used by the Component owning this Input to refer to the Output. If this method connects to multiple channels, the alias will be used for all channels.

Implemented in OpenSim::Input< T >.

◆ connect() [3/3]

virtual void OpenSim::AbstractInput::connect ( const AbstractChannel channel,
const std::string &  alias = "" 
)
pure virtual

Connect this Input to a single output channel.

This method can be used with both single-valued and list Inputs. You can optionally provide an alias that will be used by the Component owning this Input to refer to the Channel.

Implemented in OpenSim::Input< T >.

◆ getAlias() [1/2]

virtual const std::string& OpenSim::AbstractInput::getAlias ( ) const
pure virtual

Get the alias for a Channel.

An alias is a description for a Channel that is specific to how the Input will use the Channel. For example, the Component that owns this Input might expect the aliases to be the names of markers in the model. This method can be used only for non-list Inputs; for list Inputs, use the overload that takes an index. You must finalize connections (Component::finalizeConnections()) first.

Implemented in OpenSim::Input< T >.

◆ getAlias() [2/2]

virtual const std::string& OpenSim::AbstractInput::getAlias ( unsigned  index) const
pure virtual

Get the alias for the Channel indicated by the provided index.

An alias is a description for a Channel that is specific to how the Input will use the Channel. For example, the Component that owns this Input might expect the aliases to be the names of markers in the model. You must finalize connections (Component::finalizeConnections()) first.

Implemented in OpenSim::Input< T >.

◆ getLabel() [1/2]

virtual std::string OpenSim::AbstractInput::getLabel ( ) const
pure virtual

Get the label for this Channel.

If an alias has been set, the label is the alias; otherwise, the label is the full path of the Output that has been connected to this Input. This method can be used only for non-list Inputs; for list Inputs, use the single-argument overload. You must finalize connections (Component::finalizeConnections()) first.

Implemented in OpenSim::Input< T >.

◆ getLabel() [2/2]

virtual std::string OpenSim::AbstractInput::getLabel ( unsigned  index) const
pure virtual

Get the label for the Channel indicated by the provided index.

If an alias has been set, the label is the alias; otherwise, the label is the full path of the Channel that has been connected to this Input. You must finalize connections (Component::finalizeConnections()) first.

Implemented in OpenSim::Input< T >.

◆ parseConnecteePath()

static bool OpenSim::AbstractInput::parseConnecteePath ( const std::string &  connecteePath,
std::string &  componentPath,
std::string &  outputName,
std::string &  channelName,
std::string &  alias 
)
inlinestatic

Break up a connectee path into its output path, channel name (empty for single-value outputs), and alias.

This function writes to the passed-in outputPath, channelName, and alias.

Examples:

/foo/bar|output
outputPath is "/foo/bar/output"
channelName is ""
alias is ""

/foo/bar|output:channel
outputPath is "/foo/bar/output"
channelName is "channel"
alias is ""

/foo/bar|output(baz)
outputPath is "/foo/bar/output"
channelName is ""
alias is "baz"

/foo/bar|output:channel(baz)
outputPath is "/foo/bar|output"
channelName is "channel"
alias is "baz"

◆ setAlias() [1/2]

virtual void OpenSim::AbstractInput::setAlias ( const std::string &  alias)
pure virtual

Set the alias for a Channel.

If this is a list Input, the aliases of all Channels will be set to the provided string. If you wish to set the alias of only one Channel, use the two-argument overload. You must finalize connections (Component::finalizeConnections()) first.

Implemented in OpenSim::Input< T >.

◆ setAlias() [2/2]

virtual void OpenSim::AbstractInput::setAlias ( unsigned  index,
const std::string &  alias 
)
pure virtual

Set the alias for the Channel indicated by the provided index.

You must finalize connections (Component::finalizeConnections()) first.

Implemented in OpenSim::Input< T >.


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