artisynth.core.inverse
Class TrackingController

java.lang.Object
  extended by artisynth.core.modelbase.ModelComponentBase
      extended by artisynth.core.modelbase.ModelAgentBase
          extended by artisynth.core.modelbase.ControllerMonitorBase
              extended by artisynth.core.modelbase.ControllerBase
                  extended by artisynth.core.inverse.TrackingController
All Implemented Interfaces:
ComponentChangeListener, CompositeComponent, Controller, HasState, IndexedComponentList, ModelAgent, ModelComponent, RenderableComponent, java.lang.Cloneable, HasProperties, HierarchyNode, GLRenderable, GLSelectable, HasRenderProps, Renderable, Scannable

public class TrackingController
extends ControllerBase
implements CompositeComponent, RenderableComponent

"Inverse" controller for computing muscle activations based on a set of kinematic target trajectories.

Terminology:

"Targets"are trajectories of points/frames that we wish our model to follow
"Markers" or "Sources"are the points/frames in the model we want to follow the target trajectories
"Excitation"we actually mean, "activation", since we are currently ignoring the excitation dynamics

Papers:
- Ian Stavness, JE Lloyd, and SS Fels. Automatic Prediction of Tongue Muscle Activations Using a Finite Element Model. Journal of Biomechanics, 45(16):2841-2848, 2012.
- Ian Stavness, AG Hannam, JE Lloyd, and SS Fels. Predicting muscle patterns for hemimandibulectomy models. Computer Methods in Biomechanics and Biomedical Engineering, 13(4):483-491, 2010.

Author:
Ian Stavness, with modifications by Antonio Sanchez

Nested Class Summary
 
Nested classes/interfaces inherited from interface artisynth.core.modelbase.CompositeComponent
CompositeComponent.NavpanelDisplay
 
Nested classes/interfaces inherited from interface artisynth.core.modelbase.ModelComponent
ModelComponent.NavpanelVisibility
 
Field Summary
static double DEFAULT_MAX_EXCITATION_JUMP
           
static boolean DEFAULT_USE_INVERSE_MANAGER
           
static PropertyList myProps
           
 
Fields inherited from class artisynth.core.modelbase.ModelComponentBase
enforceUniqueCompositeNames, enforceUniqueNames, myNumber, NULL_OBJ, useCompactPathNames
 
Fields inherited from interface maspack.render.GLRenderable
TRANSLUCENT, TWO_DIMENSIONAL
 
Constructor Summary
TrackingController()
           
TrackingController(MechSystemBase m)
          Creates a tracking controller for a given mech system
TrackingController(MechSystemBase m, java.lang.String name)
          Creates and names a tracking controller for a given mech system
 
Method Summary
 DampingTerm addDampingTerm()
          Adds and returns a standard damping term on excitations
 DampingTerm addDampingTerm(double w)
          Adds and returns a standard damping term on excitations, weighted by the supplied value
 void addExciter(ExcitationComponent ex)
          Adds an exciter to be used as a free variable in the inverse routine
 void addExciter(ExcitationComponent ex, double gain)
           
 L2RegularizationTerm addL2RegularizationTerm()
          Adds and returns a standard L2 regularization term on excitations
 L2RegularizationTerm addL2RegularizationTerm(double w)
          Adds and returns a standard L2 regularization term on excitations, weighted by the supplied value
 MotionTargetComponent addMotionTarget(MotionTargetComponent source)
          Adds a source for the tracking and creates a corresponding target point or frame object
 MotionTargetComponent addMotionTarget(MotionTargetComponent source, double weight)
          Adds a source for the tracking and creates a corresponding target point or frame object
 void addRegularizationTerms(java.lang.Double w_l2norm, java.lang.Double w_damping)
          Adds both L2 and damping regularization terms with supplied weights
 void addTerm(LeastSquaresTerm term)
          Add another term to the optimization, typically for regularization
 void apply(double t0, double t1)
          Applies the controller, estimating and setting the next set of muscle activations
 void clearExciters()
          Clears all exciters
 void componentChanged(ComponentChangeEvent e)
          Notifies this composite component that a change has occured within one or more of its descendants.
 ControlPanel createInverseControlPanel()
          Creates a control panel for this inverse controller
 void dispose()
          Clears all terms and disposes storage
 ModelComponent findComponent(java.lang.String path)
          Recursively searches for a sub-component of this ModelComponent, identified by a path of component names.
 ModelComponent get(int idx)
          Returns a specific sub-component of this ModelComponent, identified by index.
 ModelComponent get(java.lang.String nameOrNumber)
          Returns a specific sub-component of this ModelComponent, identified by name or string representation of the sub-component's number
 PropertyList getAllPropertyInfo()
          Returns a list giving static information about all properties exported by this object.
 ModelComponent getByNumber(int num)
          Returns a specific sub-component of this ModelComponent, identified by number.
 boolean getDebug()
           
 int getExcitations(VectorNd ex, int idx)
          Fills the supplied ex vector with current excitation values starting at index idx
 ListView<ExcitationComponent> getExciters()
          Gets the list of excitators used as free variables in the inverse routine
 void getForces(VectorNd forces, VectorNd excitations)
          Determines the set of forces given a set of excitations.
 MechSystemSolver.Integrator getIntegrator()
          Returns the integrator used by the mech system
 double getMaxExcitationJump()
          Gets the governor's maximum excitation jump
 MechSystemBase getMech()
          Gets the mechanical system used for computing forces
 java.util.ArrayList<MotionTargetComponent> getMotionSources()
          Returns the set of sources
 java.util.ArrayList<MotionTargetComponent> getMotionTargets()
          Returns the set of targets
 MotionTargetTerm getMotionTargetTerm()
          Returns the motion target term, responsible for trajectory error
 VectorNd getMotionTargetWeights()
          Returns the set of target weights
 MotionTargetTerm getMotionTerm()
          Returns the "motion" term, responsible for tracking error
 MuscleExciter getMuscleExciter()
           
 CompositeComponent.NavpanelDisplay getNavpanelDisplay()
          Returns the DisplayMode for this component.
 int getNumberLimit()
          Returns the current upper limit for numbers among all sub-components in this composite.
 LeastSquaresSolver getSolver()
          Gets the solver object
 boolean getSourcesVisible()
           
 boolean getTargetsVisible()
           
 double getTargetVelocityFactor()
          Gets the velocity factor to use for trajectory tracking.
 ListView<MotionTargetComponent> getTargetView()
           
 java.util.ArrayList<LeastSquaresTerm> getTerms()
          Retrieves a list of all terms, including the tracking error and any regularization terms
 boolean hierarchyContainsReferences()
          Returns true if the component hierarchy formed by this component and its descendents is closed with respect to references.
 int indexOf(ModelComponent comp)
          Returns the index of a specified sub-component, or -1 if that the component is not present.
 void initializeExcitations()
          Initialize the controller with the current excitations in the model, allows for non-zero starting excitations
 boolean isEnabled()
          Returns whether or not the controller is enabled
 boolean isManaged()
          Flag used by InverseManager telling it whether or not to set up and control the targets with probes
 int numComponents()
          Returns the number of components in this CompositeComponent.
 int numExcitations()
          Number of exciters controlled by this controller
 void postscan(java.util.Deque<ScanToken> tokens, CompositeComponent ancestor)
          Performs any required post-scanning for this component.
 void prerender(RenderList list)
          Prepare for rendering, and potentially add itself to a list to be drawn by a GLRenderer.
 void removeMotionTarget(MotionTargetComponent source)
           
 void scan(ReaderTokenizer rtok, java.lang.Object ref)
          Scans this element from a ReaderTokenizer.
 void setDebug(boolean b)
          Puts controller into debug mode, printing messages
 void setEnabled(boolean enabled)
          Enable or disable the controller
 void setExcitationBounds(double lower, double upper)
          Sets bounds for the excitations
 int setExcitations(VectorNd ex, int idx)
          Sets excitations provided in the ex vector starting at index idx.
 void setInitialExcitations(VectorNd init)
          Sets initial excitations to the supplied values
 void setManaged(boolean set)
          Sets a flag used by InverseManager telling it whether or not to set up and control the targets with probes.
 void setMaxExcitationJump(double j)
          For the governor, limits jump in excitation for all exciters to the supplied delta
 void setMech(MechSystemBase m)
          Set the mech system, used by the solver to compute forces
 void setMotionRenderProps(RenderProps targets, RenderProps sources)
          Sets render properties for targets and sources
 void setMotionTargetWeight(MotionTargetComponent comp, double w)
           
 void setSourcesVisible(boolean show)
          Show or hide the sources
 void setTargetsPointRadius(double radius)
          Sets targets to shows a spheres with given radius
 void setTargetsVisible(boolean show)
          Show or hide the targets
 void setTargetVelocityFactor(double k)
          Sets the velocity factor to use for trajectory tracking.
 void updateConstraints(double t)
          Updates constraints in the mech system at time t, including contacts
 void updateNameMap(java.lang.String newName, java.lang.String oldName, ModelComponent comp)
          
 
Methods inherited from class artisynth.core.modelbase.ControllerBase
render
 
Methods inherited from class artisynth.core.modelbase.ControllerMonitorBase
copy, createRenderProps, createState, getInitialState, getInitialState, getRenderHints, getRenderProps, getSelection, getState, hasState, isSelectable, numSelectionQueriesNeeded, setInitialState, setRenderProps, setState, updateBounds
 
Methods inherited from class artisynth.core.modelbase.ModelAgentBase
finalize, getModel, initialize, setModel, setModelFromComponent, write
 
Methods inherited from class artisynth.core.modelbase.ModelComponentBase
checkFlag, checkName, checkNameUniqueness, clearFlag, clone, connectToHierarchy, createTempFlag, disconnectFromHierarchy, getChildren, getGrandParent, getHardReferences, getName, getNameRange, getNavpanelVisibility, getNavpanelVisibility, getNumber, getParent, getProperty, getSoftReferences, hasChildren, isFixed, isMarked, isSelected, isWritable, makeValidName, makeValidName, notifyParentOfChange, printReferences, recursivelyContained, recursivelyContains, removeTempFlag, setFixed, setFlag, setMarked, setName, setNavpanelVisibility, setNavpanelVisibility, setNumber, setParent, setSelected, updateReferences
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface artisynth.core.modelbase.ModelComponent
connectToHierarchy, disconnectFromHierarchy, getHardReferences, getName, getNavpanelVisibility, getNumber, getParent, getSoftReferences, hasState, isFixed, isMarked, isSelected, notifyParentOfChange, setFixed, setMarked, setName, setNumber, setParent, setSelected, updateReferences
 
Methods inherited from interface maspack.properties.HasProperties
getProperty
 
Methods inherited from interface maspack.properties.HierarchyNode
getChildren, hasChildren
 
Methods inherited from interface maspack.util.Scannable
isWritable, write
 
Methods inherited from interface maspack.render.GLSelectable
getSelection, isSelectable, numSelectionQueriesNeeded
 
Methods inherited from interface maspack.render.GLRenderable
getRenderHints, render, updateBounds
 
Methods inherited from interface maspack.render.HasRenderProps
createRenderProps, getRenderProps, setRenderProps
 
Methods inherited from interface artisynth.core.modelbase.ModelAgent
getModel, initialize, setModel
 
Methods inherited from interface artisynth.core.modelbase.HasState
createState, getInitialState, getState, setState
 

Field Detail

DEFAULT_USE_INVERSE_MANAGER

public static final boolean DEFAULT_USE_INVERSE_MANAGER
See Also:
Constant Field Values

DEFAULT_MAX_EXCITATION_JUMP

public static double DEFAULT_MAX_EXCITATION_JUMP

myProps

public static PropertyList myProps
Constructor Detail

TrackingController

public TrackingController()

TrackingController

public TrackingController(MechSystemBase m)
Creates a tracking controller for a given mech system

Parameters:
m - mech system, typically your "MechModel"

TrackingController

public TrackingController(MechSystemBase m,
                          java.lang.String name)
Creates and names a tracking controller for a given mech system

Parameters:
m - mech system, typically your "MechModel"
name - name to give the controller
Method Detail

getAllPropertyInfo

public PropertyList getAllPropertyInfo()
Description copied from interface: HasProperties
Returns a list giving static information about all properties exported by this object.

Specified by:
getAllPropertyInfo in interface HasProperties
Overrides:
getAllPropertyInfo in class ModelComponentBase
Returns:
static information for all exported properties

getMotionTerm

public MotionTargetTerm getMotionTerm()
Returns the "motion" term, responsible for tracking error

Returns:
motion term for tracking error

apply

public void apply(double t0,
                  double t1)
Applies the controller, estimating and setting the next set of muscle activations

Specified by:
apply in interface Controller

dispose

public void dispose()
Clears all terms and disposes storage

Specified by:
dispose in interface ModelAgent
Overrides:
dispose in class ModelAgentBase

addTerm

public void addTerm(LeastSquaresTerm term)
Add another term to the optimization, typically for regularization

Parameters:
term - the term to add

getTerms

public java.util.ArrayList<LeastSquaresTerm> getTerms()
Retrieves a list of all terms, including the tracking error and any regularization terms


isEnabled

public boolean isEnabled()
Returns whether or not the controller is enabled


setEnabled

public void setEnabled(boolean enabled)
Enable or disable the controller


setMech

public void setMech(MechSystemBase m)
Set the mech system, used by the solver to compute forces


getMech

public MechSystemBase getMech()
Gets the mechanical system used for computing forces


getIntegrator

public MechSystemSolver.Integrator getIntegrator()
Returns the integrator used by the mech system


getSolver

public LeastSquaresSolver getSolver()
Gets the solver object


setExcitationBounds

public void setExcitationBounds(double lower,
                                double upper)
Sets bounds for the excitations

Parameters:
lower - lower-bound (typically 0)
upper - upper-bound (typically 1)

getForces

public void getForces(VectorNd forces,
                      VectorNd excitations)
Determines the set of forces given a set of excitations. Note: this actually sets the excitations in the model

Parameters:
forces - output from the mech system
excitations - input muscle excitations

updateConstraints

public void updateConstraints(double t)
Updates constraints in the mech system at time t, including contacts


setExcitations

public int setExcitations(VectorNd ex,
                          int idx)
Sets excitations provided in the ex vector starting at index idx.

Parameters:
ex - vector of excitations to use
idx - start index
Returns:
current index in the ex buffer idx+numExcitations()

getExciters

public ListView<ExcitationComponent> getExciters()
Gets the list of excitators used as free variables in the inverse routine


getMuscleExciter

public MuscleExciter getMuscleExciter()

addExciter

public void addExciter(ExcitationComponent ex)
Adds an exciter to be used as a free variable in the inverse routine

Parameters:
ex -

addExciter

public void addExciter(ExcitationComponent ex,
                       double gain)

clearExciters

public void clearExciters()
Clears all exciters


numExcitations

public int numExcitations()
Number of exciters controlled by this controller


getExcitations

public int getExcitations(VectorNd ex,
                          int idx)
Fills the supplied ex vector with current excitation values starting at index idx

Parameters:
ex - vector of excitations to fill
idx - starting index
Returns:
next index to use idx+numExcitations()

addMotionTarget

public MotionTargetComponent addMotionTarget(MotionTargetComponent source)
Adds a source for the tracking and creates a corresponding target point or frame object

Parameters:
source - point or frame to track
Returns:
the created target point/frame

removeMotionTarget

public void removeMotionTarget(MotionTargetComponent source)

addMotionTarget

public MotionTargetComponent addMotionTarget(MotionTargetComponent source,
                                             double weight)
Adds a source for the tracking and creates a corresponding target point or frame object

Parameters:
source - point or frame to track
weight - the weight by which to scale this target's contribution
Returns:
the created target point/frame

addL2RegularizationTerm

public L2RegularizationTerm addL2RegularizationTerm()
Adds and returns a standard L2 regularization term on excitations


addL2RegularizationTerm

public L2RegularizationTerm addL2RegularizationTerm(double w)
Adds and returns a standard L2 regularization term on excitations, weighted by the supplied value


addDampingTerm

public DampingTerm addDampingTerm()
Adds and returns a standard damping term on excitations


addDampingTerm

public DampingTerm addDampingTerm(double w)
Adds and returns a standard damping term on excitations, weighted by the supplied value


addRegularizationTerms

public void addRegularizationTerms(java.lang.Double w_l2norm,
                                   java.lang.Double w_damping)
Adds both L2 and damping regularization terms with supplied weights


setMaxExcitationJump

public void setMaxExcitationJump(double j)
For the governor, limits jump in excitation for all exciters to the supplied delta


getMaxExcitationJump

public double getMaxExcitationJump()
Gets the governor's maximum excitation jump


setTargetsVisible

public void setTargetsVisible(boolean show)
Show or hide the targets


setSourcesVisible

public void setSourcesVisible(boolean show)
Show or hide the sources


setTargetsPointRadius

public void setTargetsPointRadius(double radius)
Sets targets to shows a spheres with given radius


getSourcesVisible

public boolean getSourcesVisible()

getTargetsVisible

public boolean getTargetsVisible()

setDebug

public void setDebug(boolean b)
Puts controller into debug mode, printing messages


getDebug

public boolean getDebug()

isManaged

public boolean isManaged()
Flag used by InverseManager telling it whether or not to set up and control the targets with probes


setManaged

public void setManaged(boolean set)
Sets a flag used by InverseManager telling it whether or not to set up and control the targets with probes. If true, the InverseManager expects certain probes to be defined. Otherwise, you must manually control target positions.


createInverseControlPanel

public ControlPanel createInverseControlPanel()
Creates a control panel for this inverse controller


getTargetView

public ListView<MotionTargetComponent> getTargetView()

getMotionTargetTerm

public MotionTargetTerm getMotionTargetTerm()
Returns the motion target term, responsible for trajectory error


getMotionTargets

public java.util.ArrayList<MotionTargetComponent> getMotionTargets()
Returns the set of targets


getMotionSources

public java.util.ArrayList<MotionTargetComponent> getMotionSources()
Returns the set of sources


setMotionRenderProps

public void setMotionRenderProps(RenderProps targets,
                                 RenderProps sources)
Sets render properties for targets and sources

Parameters:
targets -
sources -

setTargetVelocityFactor

public void setTargetVelocityFactor(double k)
Sets the velocity factor to use for trajectory tracking. See MotionTargetTerm.setTargetVelocityFactor(double).

Parameters:
k -

getTargetVelocityFactor

public double getTargetVelocityFactor()
Gets the velocity factor to use for trajectory tracking. See MotionTargetTerm.setTargetVelocityFactor(double).


getMotionTargetWeights

public VectorNd getMotionTargetWeights()
Returns the set of target weights


setMotionTargetWeight

public void setMotionTargetWeight(MotionTargetComponent comp,
                                  double w)

initializeExcitations

public void initializeExcitations()
Initialize the controller with the current excitations in the model, allows for non-zero starting excitations


setInitialExcitations

public void setInitialExcitations(VectorNd init)
Sets initial excitations to the supplied values


prerender

public void prerender(RenderList list)
Description copied from interface: GLRenderable
Prepare for rendering, and potentially add itself to a list to be drawn by a GLRenderer.

Specified by:
prerender in interface GLRenderable
Overrides:
prerender in class ControllerMonitorBase

get

public ModelComponent get(java.lang.String nameOrNumber)
Returns a specific sub-component of this ModelComponent, identified by name or string representation of the sub-component's number

Specified by:
get in interface CompositeComponent
Parameters:
nameOrNumber - name or number of the sub-component
Returns:
named sub-component, or null if the component does not exist.

get

public ModelComponent get(int idx)
Returns a specific sub-component of this ModelComponent, identified by index.

Specified by:
get in interface CompositeComponent
Specified by:
get in interface IndexedComponentList
Parameters:
idx - index of the sub-component
Returns:
indexed sub-component, or null if the component does not exist.

getByNumber

public ModelComponent getByNumber(int num)
Returns a specific sub-component of this ModelComponent, identified by number.

Specified by:
getByNumber in interface CompositeComponent
Parameters:
num - number of the sub-component
Returns:
specified sub-component, or null if the component does not exist.

numComponents

public int numComponents()
Returns the number of components in this CompositeComponent.

Specified by:
numComponents in interface CompositeComponent
Specified by:
numComponents in interface IndexedComponentList
Returns:
number of sub-components

indexOf

public int indexOf(ModelComponent comp)
Returns the index of a specified sub-component, or -1 if that the component is not present.

Specified by:
indexOf in interface CompositeComponent
Returns:
indexed sub-component

findComponent

public ModelComponent findComponent(java.lang.String path)
Recursively searches for a sub-component of this ModelComponent, identified by a path of component names.

Specified by:
findComponent in interface CompositeComponent
Parameters:
path - path leading to the sub-component
Returns:
named sub-component, or null if the component does not exist.

getNumberLimit

public int getNumberLimit()
Returns the current upper limit for numbers among all sub-components in this composite. This is one greater than the maximum sub-component number currently assigned. A value of 0 means that there are no sub-components. This method is useful for creating and sizing arrays whose contents are indexed by component numbers.

Specified by:
getNumberLimit in interface CompositeComponent
Returns:
upper limit for numbers among all sub-components

getNavpanelDisplay

public CompositeComponent.NavpanelDisplay getNavpanelDisplay()
Returns the DisplayMode for this component. This specifies how the component should be displayed in a navigation panel.

Specified by:
getNavpanelDisplay in interface CompositeComponent
Returns:
display mode for this component

componentChanged

public void componentChanged(ComponentChangeEvent e)
Notifies this composite component that a change has occured within one or more of its descendants. When this occurs, the composite may need to invalidate cached information that depends on the descendants.

This method should propagate the notification up the component hierarchy by calling notifyParentOfChange.

Specified by:
componentChanged in interface ComponentChangeListener
Specified by:
componentChanged in interface CompositeComponent
Parameters:
e - optional argument giving specific information about the change

updateNameMap

public void updateNameMap(java.lang.String newName,
                          java.lang.String oldName,
                          ModelComponent comp)

Specified by:
updateNameMap in interface CompositeComponent

hierarchyContainsReferences

public boolean hierarchyContainsReferences()
Returns true if the component hierarchy formed by this component and its descendents is closed with respect to references. In other words, all components referenced by components within the hierarchy are themselves components within the hierarchy.

In particular, this means that one does not need to search outside the hierarchy when looking for dependencies.

Specified by:
hierarchyContainsReferences in interface CompositeComponent
Returns:
true if this component's hierarchy is closed with respect to references.

scan

public void scan(ReaderTokenizer rtok,
                 java.lang.Object ref)
          throws java.io.IOException
Description copied from class: ModelComponentBase
Scans this element from a ReaderTokenizer. The expected text format is assumed to be compatible with that produced by write.

Specified by:
scan in interface ModelComponent
Specified by:
scan in interface Scannable
Overrides:
scan in class ModelComponentBase
Parameters:
rtok - Tokenizer from which to scan the element
ref - optional reference object which can be used for resolving references to other objects
Throws:
java.io.IOException - if an I/O or formatting error occured

postscan

public void postscan(java.util.Deque<ScanToken> tokens,
                     CompositeComponent ancestor)
              throws java.io.IOException
Description copied from interface: ModelComponent
Performs any required post-scanning for this component. This involves handling any information whose processing was deferred during the scan() method and stored in the token queue. The most common use of this method is to resolve the paths of component references, which may not have been created at the time of the initial scan() call.

Specified by:
postscan in interface ModelComponent
Overrides:
postscan in class ModelComponentBase
Parameters:
tokens - token information that was stored during scan().
ancestor - ancestor component with respect to which reference component paths are defined.
Throws:
java.io.IOException