MotionTargetTerm (Artisynth API documentation)

java.lang.Object
- artisynth.core.modelbase.ModelComponentBase
- - artisynth.core.inverse.QPTermBase
  - - artisynth.core.inverse.QPCostTermBase
    - - artisynth.core.inverse.LeastSquaresTermBase
      - artisynth.core.inverse.MotionTargetTerm

All Implemented Interfaces:

LeastSquaresTerm, QPConstraintTerm, QPCostTerm, QPTerm, ComponentChangeListener, CompositeComponent, IndexedComponentList, ModelComponent, PostScannable, java.lang.Cloneable, HasProperties, HierarchyNode, Scannable
```
public class MotionTargetTerm
extends LeastSquaresTermBase
```
Cost term that minimizes the tracking error for one or more motion targets. Can also be employed as a constraint term.

Author:

Ian Stavness, Antonio Sanchez, John E Lloyd TODO Fix the jacobian TODO See if a similar issue exists for frame-based tracking

Nested Class Summary
- Nested classes/interfaces inherited from interface artisynth.core.inverse.QPTerm
  QPTerm.Type
- Nested classes/interfaces inherited from interface artisynth.core.modelbase.ModelComponent
  ModelComponent.FilePathSaveType, ModelComponent.NavpanelVisibility
- Nested classes/interfaces inherited from interface artisynth.core.modelbase.CompositeComponent
  CompositeComponent.NavpanelDisplay

Field Summary

Fields
Modifier and Type	Field and Description
`static double`	`DEFAULT_CHASE_TIME`
`static boolean`	`DEFAULT_ESTIMATE_TARGET_VELOCITY`
`static double`	`DEFAULT_Kd`
`static double`	`DEFAULT_Kp`
`static boolean`	`DEFAULT_LEGACY_CONTROL`
`static double`	`DEFAULT_PD_DAMPING_RATIO`
`static double`	`DEFAULT_PD_TIME_CONSTANT`
`static boolean`	`DEFAULT_USE_PD_CONTROL`
`static boolean`	`keepVelocityJacobianConstant`
`boolean`	`myLegacyControl`
`static PropertyList`	`myProps`

Fields inherited from class artisynth.core.inverse.QPTermBase
DEFAULT_ENABLED, DEFAULT_WEIGHT

Fields inherited from class artisynth.core.modelbase.ModelComponentBase
enforceUniqueCompositeNames, enforceUniqueNames, myNumber, NULL_OBJ, useCompactPathNames

Constructor Summary

Constructors
Constructor and Description

MotionTargetTerm()

MotionTargetTerm(TrackingController controller)

Constructors
Constructor and Description
`MotionTargetTerm()`
`MotionTargetTerm(TrackingController controller)`

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`TargetFrame`	`addFrameTarget(Frame source)` Adds a frame target to track with weight 1
`TargetFrame`	`addFrameTarget(Frame source, double weight)` Adds a frame target to track
`TargetPoint`	`addPointTarget(Point source)` Adds a point target to track with weight 1
`TargetPoint`	`addPointTarget(Point source, double weight)` Adds a point target to track
`MotionTargetComponent`	`addTarget(MotionTargetComponent target)` Deprecated. Use `addPointTarget(Point)` or `addFrameTarget(Frame)` instead.
`MotionTargetComponent`	`addTarget(MotionTargetComponent source, double weight)` Deprecated. Use `addPointTarget(Point,double)` or `addFrameTarget(Frame,double)` instead.
`void`	`clearTargets()` Removes targets
`PropertyList`	`getAllPropertyInfo()` Returns a list giving static information about all properties exported by this object.
`VectorNd`	`getB()`
`double`	`getChaseTime()` Queries the chase time.
`boolean`	`getEstimateTargetVelocity()` Queries whether target velocity estimation is enabled.
`MatrixNd`	`getH()`
`double`	`getKd()` Returns the Derivative gain for PD controller.
`double`	`getKp()` Returns the Proportional gain for PD controller.
`boolean`	`getLegacyControl()`
`double`	`getPdDampingRatio()` Queries the PD control damping ratio, given by `Kd/(2 sqrt(Kp))`.
`double`	`getPdTimeConstant()` Queries the PD control time constant, given by `1/sqrt(Kp)`.
`double`	`getPositionError()`
`void`	`getQP(MatrixNd Q, VectorNd p, double t0, double t1)` Adds the contribution of this term to the quadratic cost components Q and p.
`Frame`	`getSourceFrame(int idx)`
`Point`	`getSourcePoint(int idx)`
`RenderProps`	`getSourceRenderProps()` Render props for the sources
`java.util.ArrayList<MotionTargetComponent>`	`getSources()` Returns list of source points/frames that are part of the model that will move to the targets
`RenderableComponentList<TargetFrame>`	`getTargetFrames()`
`PointList<TargetPoint>`	`getTargetPoints()`
`RenderProps`	`getTargetRenderProps()` Render props for targets
`java.util.ArrayList<MotionTargetComponent>`	`getTargets()` Returns list of target points/frames
`VectorNd`	`getTargetVel(double t0, double t1)`
`void`	`getTargetWeights(VectorNd weights)` Gets weights for targets.
`int`	`getTerm(MatrixNd A, VectorNd b, int rowoff, double t0, double t1)` Fills `H` and `b` with this motion term
`boolean`	`getUsePDControl()`
`double`	`getVelocityError()`
`void`	`initSourceRenderProps()`
`void`	`initTargetRenderProps(TrackingController controller)`
`int`	`numConstraints(int qpsize)` Returns the number of constraints associated with this term.
`void`	`setChaseTime(double t)` Sets the chase time `T`.
`void`	`setEstimateTargetVelocity(boolean enable)` Enables estimation of the target velocities.
`void`	`setKd(double k)` Sets the derivative gain `Kd` for PD control.
`void`	`setKp(double k)` Sets the proportional gain `Kp` for PD control.
`void`	`setLegacyControl(boolean enable)`
`void`	`setPdDampingRatio(double zeta)` Sets the PD control damping ratio `zeta`, by setting `Kd = 2 zeta sqrt(Kp)` while leaving `Kp` unchanged.
`void`	`setPdTimeConstant(double T)` Sets the PD control gains `Kp` and `Kd` from a time constant `T`, keeping the current damping ratio `zeta` (see `setPdDampingRatio(double)`), according to
`void`	`setSourceRenderProps(RenderProps rend)` Sets render props for sources
`void`	`setTargetRenderProps(RenderProps rend)` Sets render props for the target points/frames
`void`	`setTargetsPointRadius(double rad)`
`void`	`setTargetWeights(VectorNd weights)` Sets weights for targets.
`void`	`setUsePDControl(boolean usePD)`
`void`	`setWeight(double w)` Weight used to scale the contribution of this term in the quadratic optimization problem
`void`	`storeTargetVelocity(VectorNd vel)`
`void`	`updateHb(TrackingController controller, double t0, double t1)`
`void`	`updateSourceVelocity(VectorNd vel)`
`void`	`updateTarget(double t0, double t1)`
`void`	`updateTargetVelocity(VectorNd vel)`
`void`	`updateVelocityError(VectorNd verror)`

Methods inherited from class artisynth.core.inverse.LeastSquaresTermBase
componentChanged, findComponent, get, get, getByNumber, getChildren, getNavpanelDisplay, getNumberLimit, getType, hasChildren, hierarchyContainsReferences, indexOf, iterator, numComponents, postscan, scan, setDisplayMode, setType, updateNameMap

Methods inherited from class artisynth.core.inverse.QPTermBase
getController, getProperty, getWeight, isEnabled, isInternal, setEnabled, setInternal

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface artisynth.core.inverse.QPTerm
getController, getWeight, isEnabled

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, setWritable, updateReferences

Methods inherited from interface maspack.properties.HasProperties
getProperty

Methods inherited from interface maspack.util.Scannable
isWritable, write

Methods inherited from interface artisynth.core.modelbase.CompositeComponent
recursivelyFind

- Field Detail
  - keepVelocityJacobianConstant
```
public static boolean keepVelocityJacobianConstant
```
  - DEFAULT_LEGACY_CONTROL
```
public static final boolean DEFAULT_LEGACY_CONTROL
```
    See Also:
    
    Constant Field Values
  - myLegacyControl
```
public boolean myLegacyControl
```
  - DEFAULT_USE_PD_CONTROL
```
public static final boolean DEFAULT_USE_PD_CONTROL
```
    See Also:
    
    Constant Field Values
  - DEFAULT_CHASE_TIME
```
public static double DEFAULT_CHASE_TIME
```
  - DEFAULT_ESTIMATE_TARGET_VELOCITY
```
public static boolean DEFAULT_ESTIMATE_TARGET_VELOCITY
```
  - DEFAULT_Kd
```
public static double DEFAULT_Kd
```
  - DEFAULT_Kp
```
public static double DEFAULT_Kp
```
  - DEFAULT_PD_TIME_CONSTANT
```
public static double DEFAULT_PD_TIME_CONSTANT
```
  - DEFAULT_PD_DAMPING_RATIO
```
public static double DEFAULT_PD_DAMPING_RATIO
```
  - myProps
```
public static PropertyList myProps
```
- Constructor Detail
  - MotionTargetTerm
```
public MotionTargetTerm()
```
  - MotionTargetTerm
```
public MotionTargetTerm(TrackingController controller)
```
- Method Detail
  - getAllPropertyInfo
```
public PropertyList getAllPropertyInfo()
```
    Description copied from class: QPTermBase
    
    Returns a list giving static information about all properties exported by this object.
    
    Specified by:
    
    getAllPropertyInfo in interface HasProperties
    
    Overrides:
    
    getAllPropertyInfo in class QPTermBase
    
    Returns:
    
    static information for all exported properties
  - setTargetsPointRadius
```
public void setTargetsPointRadius(double rad)
```
  - getTargetPoints
```
public PointList<TargetPoint> getTargetPoints()
```
  - getTargetFrames
```
public RenderableComponentList<TargetFrame> getTargetFrames()
```
  - updateTarget
```
public void updateTarget(double t0,
                         double t1)
```
  - getPositionError
```
public double getPositionError()
```
  - getVelocityError
```
public double getVelocityError()
```
  - updateVelocityError
```
public void updateVelocityError(VectorNd verror)
```
  - updateSourceVelocity
```
public void updateSourceVelocity(VectorNd vel)
```
  - updateTargetVelocity
```
public void updateTargetVelocity(VectorNd vel)
```
  - storeTargetVelocity
```
public void storeTargetVelocity(VectorNd vel)
```
  - initTargetRenderProps
```
public void initTargetRenderProps(TrackingController controller)
```
  - initSourceRenderProps
```
public void initSourceRenderProps()
```
  - addTarget
```
public MotionTargetComponent addTarget(MotionTargetComponent source,
                                       double weight)
```
    Deprecated. Use addPointTarget(Point,double) or addFrameTarget(Frame,double) instead.
  - addTarget
```
public MotionTargetComponent addTarget(MotionTargetComponent target)
```
    Deprecated. Use addPointTarget(Point) or addFrameTarget(Frame) instead.
  - addPointTarget
```
public TargetPoint addPointTarget(Point source,
                                  double weight)
```
    Adds a point target to track
    
    Parameters:
    
    source - point in the model you wish to drive to a target position
    
    weight - used in error tracking
    
    Returns:
    
    the created point that will be used as a target
  - addPointTarget
```
public TargetPoint addPointTarget(Point source)
```
    Adds a point target to track with weight 1
    
    Parameters:
    
    source - point in the model you wish to drive to a target position
    
    Returns:
    
    the created point that will be used as a target
  - addFrameTarget
```
public TargetFrame addFrameTarget(Frame source,
                                  double weight)
```
    Adds a frame target to track
    
    Parameters:
    
    source - frame in the model you wish to drive to a target position
    
    weight - used in error tracking
    
    Returns:
    
    the created frame that will be used as a target
  - addFrameTarget
```
public TargetFrame addFrameTarget(Frame source)
```
    Adds a frame target to track with weight 1
    
    Parameters:
    
    source - frame in the model you wish to drive to a target position
    
    Returns:
    
    the created frame that will be used as a target
  - clearTargets
```
public void clearTargets()
```
    Removes targets
  - getTargets
```
public java.util.ArrayList<MotionTargetComponent> getTargets()
```
    Returns list of target points/frames
  - getSources
```
public java.util.ArrayList<MotionTargetComponent> getSources()
```
    Returns list of source points/frames that are part of the model that will move to the targets
  - getSourcePoint
```
public Point getSourcePoint(int idx)
```
  - getSourceFrame
```
public Frame getSourceFrame(int idx)
```
  - getTargetVel
```
public VectorNd getTargetVel(double t0,
                             double t1)
```
  - getTerm
```
public int getTerm(MatrixNd A,
                   VectorNd b,
                   int rowoff,
                   double t0,
                   double t1)
```
    Fills H and b with this motion term
    
    Parameters:
    
    A - LHS matrix to fill
    
    b - RHS vector to fill
    
    rowoff - row offset to start filling term
    
    t0 - starting time of time step
    
    t1 - ending time of time step
    
    Returns:
    
    next row offset
  - updateHb
```
public void updateHb(TrackingController controller,
                     double t0,
                     double t1)
```
  - getH
```
public MatrixNd getH()
```
  - getB
```
public VectorNd getB()
```
  - setWeight
```
public void setWeight(double w)
```
    Weight used to scale the contribution of this term in the quadratic optimization problem
    
    Specified by:
    
    setWeight in interface QPTerm
    
    Overrides:
    
    setWeight in class QPTermBase
    
    Parameters:
    
    w - weight for the term
  - setTargetWeights
```
public void setTargetWeights(VectorNd weights)
```
    Sets weights for targets. This allows you to weight more heavily the points you deem to be more important. If wgts.size() equals the number of targets, each target will use a single weight. If wgts.size() equals the full size of the target velocity vector, then this directly scales the rows of H (allows you to scale x,y,z components of velocity separately).
    
    Parameters:
    
    weights - weights vector
  - getTargetWeights
```
public void getTargetWeights(VectorNd weights)
```
    Gets weights for targets. If weights.size() equals the number of targets, returns the set of single weights used per target. If weights.size() equals the full size of the target velocity vector, then returns the direct scaling vector.
    
    Parameters:
    
    weights - weights vector
  - getTargetRenderProps
```
public RenderProps getTargetRenderProps()
```
    Render props for targets
  - setTargetRenderProps
```
public void setTargetRenderProps(RenderProps rend)
```
    Sets render props for the target points/frames
  - getSourceRenderProps
```
public RenderProps getSourceRenderProps()
```
    Render props for the sources
  - setSourceRenderProps
```
public void setSourceRenderProps(RenderProps rend)
```
    Sets render props for sources
  - setChaseTime
```
public void setChaseTime(double t)
```
    Sets the chase time T. If not using PD control, this is the time over which the controller tries to make the source catch up to the target. A value <= 0 (the default) causes T to be set to the simulation step size h, which places the source on the target at the end of each step. Values less than h are treated as h, since these would overshoot the target. Values greater than h give smoother excitations, but cause the source to lag the target by about (T-h) times the target velocity, unless target velocities are either supplied or estimated (see setEstimateTargetVelocity(boolean)).
    
    Parameters:
    
    t - new chase time
  - getChaseTime
```
public double getChaseTime()
```
    Queries the chase time. See setChaseTime(double) for details.
    
    Returns:
    
    chase time
  - setEstimateTargetVelocity
```
public void setEstimateTargetVelocity(boolean enable)
```
    Enables estimation of the target velocities. If enabled, then for each target whose velocity has not been explicitly set (via its setVelocity() method, which is also used when setting its velocity property from a probe) since the previous time step, the target velocity is estimated from the target positions at the start and end of the step, using a backward difference. Otherwise, the target velocity is taken from the target's velocity state, which will be 0 unless explicitly set. Without either explicit setting or estimation, the source will lag the target when using PD control or a chase time greater than the step size. Velocity information has no effect for chase control with a chase time equal to the step size. Target positions should be smooth (e.g., using cubic interpolation for probe data) to avoid noise in the estimate. Estimation is not used when legacy control is enabled. Estimation is enabled by default.
    
    Parameters:
    
    enable - if true, enables target velocity estimation
  - getEstimateTargetVelocity
```
public boolean getEstimateTargetVelocity()
```
    Queries whether target velocity estimation is enabled. See setEstimateTargetVelocity(boolean).
    
    Returns:
    
    true if target velocity estimation is enabled
  - setKp
```
public void setKp(double k)
```
    Sets the proportional gain Kp for PD control. For a source that tracks the desired velocity exactly, the position error e obeys e'' + Kd e' + Kp e = 0, so that sqrt(Kp) is the natural frequency and Kd/(2 sqrt(Kp)) the damping ratio. For critical damping with time constant T, use Kp = 1/T^2 and Kd = 2/T. Both h Kd and h sqrt(Kp), where h is the step size, should be less than about 1.
    
    Parameters:
    
    k - proportional gain
  - getKp
```
public double getKp()
```
    Returns the Proportional gain for PD controller. See setKp(double).
    
    Returns:
    
    proportional error gain
  - setKd
```
public void setKd(double k)
```
    Sets the derivative gain Kd for PD control. See setKp(double) for details.
    
    Parameters:
    
    k - derivative gain
  - getKd
```
public double getKd()
```
    Returns the Derivative gain for PD controller. See setKd(double).
    
    Returns:
    
    derivative error gain
  - setPdTimeConstant
```
public void setPdTimeConstant(double T)
```
    Sets the PD control gains Kp and Kd from a time constant T, keeping the current damping ratio zeta (see setPdDampingRatio(double)), according to
```
 Kp = 1/T^2,  Kd = 2 zeta/T.
 
```
    1/T is the natural frequency of the error dynamics. For critical damping (zeta = 1), the position error after a step decays as (1 + t/T) exp(-t/T), reaching 10% of its initial value after about 3.9 T. T should be at least the step size h. If the current damping ratio is undefined (because Kp = 0), a damping ratio of 1 is used.
    Parameters:
    
    T - PD control time constant (must be positive)
  - getPdTimeConstant
```
public double getPdTimeConstant()
```
    Queries the PD control time constant, given by 1/sqrt(Kp). See setPdTimeConstant(double). Returns infinity if Kp = 0.
    
    Returns:
    
    PD control time constant
  - setPdDampingRatio
```
public void setPdDampingRatio(double zeta)
```
    Sets the PD control damping ratio zeta, by setting Kd = 2 zeta sqrt(Kp) while leaving Kp unchanged. A value of 1 gives critical damping. See setPdTimeConstant(double).
    
    Parameters:
    
    zeta - PD control damping ratio (must be non-negative)
  - getPdDampingRatio
```
public double getPdDampingRatio()
```
    Queries the PD control damping ratio, given by Kd/(2 sqrt(Kp)). See setPdDampingRatio(double). Returns infinity if Kp = 0 and Kd > 0.
    
    Returns:
    
    PD control damping ratio
  - getQP
```
public void getQP(MatrixNd Q,
                  VectorNd p,
                  double t0,
                  double t1)
```
    Description copied from interface: QPCostTerm
    
    Adds the contribution of this term to the quadratic cost components Q and p.
    
    Parameters:
    
    Q - quadratic term
    
    p - proportional term
    
    t0 - time at start of step
    
    t1 - time at end of step
  - numConstraints
```
public int numConstraints(int qpsize)
```
    Description copied from interface: QPConstraintTerm
    
    Returns the number of constraints associated with this term.
    
    Parameters:
    
    qpsize - size of the quadratic program. For the tracking controller, this is the number of excitation values being used,
  - setUsePDControl
```
public void setUsePDControl(boolean usePD)
```
  - getUsePDControl
```
public boolean getUsePDControl()
```
  - setLegacyControl
```
public void setLegacyControl(boolean enable)
```
  - getLegacyControl
```
public boolean getLegacyControl()
```

Class MotionTargetTerm

Nested Class Summary

Nested classes/interfaces inherited from interface artisynth.core.inverse.QPTerm

Nested classes/interfaces inherited from interface artisynth.core.modelbase.ModelComponent

Nested classes/interfaces inherited from interface artisynth.core.modelbase.CompositeComponent

Field Summary

Fields inherited from class artisynth.core.inverse.QPTermBase

Fields inherited from class artisynth.core.modelbase.ModelComponentBase

Constructor Summary

Method Summary

Methods inherited from class artisynth.core.inverse.LeastSquaresTermBase

Methods inherited from class artisynth.core.inverse.QPTermBase

Methods inherited from class artisynth.core.modelbase.ModelComponentBase

Methods inherited from class java.lang.Object

Methods inherited from interface artisynth.core.inverse.QPTerm

Methods inherited from interface artisynth.core.modelbase.ModelComponent

Methods inherited from interface maspack.properties.HasProperties

Methods inherited from interface maspack.util.Scannable

Methods inherited from interface artisynth.core.modelbase.CompositeComponent

Field Detail

keepVelocityJacobianConstant

DEFAULT_LEGACY_CONTROL

myLegacyControl

DEFAULT_USE_PD_CONTROL

DEFAULT_CHASE_TIME

DEFAULT_ESTIMATE_TARGET_VELOCITY

DEFAULT_Kd

DEFAULT_Kp

DEFAULT_PD_TIME_CONSTANT

DEFAULT_PD_DAMPING_RATIO

myProps

Constructor Detail

MotionTargetTerm

MotionTargetTerm

Method Detail

getAllPropertyInfo

setTargetsPointRadius

getTargetPoints

getTargetFrames

updateTarget

getPositionError

getVelocityError

updateVelocityError

updateSourceVelocity

updateTargetVelocity

storeTargetVelocity

initTargetRenderProps

initSourceRenderProps

addTarget

addTarget

addPointTarget

addPointTarget

addFrameTarget

addFrameTarget

clearTargets

getTargets

getSources

getSourcePoint

getSourceFrame

getTargetVel

getTerm

updateHb

getH

getB

setWeight

setTargetWeights

getTargetWeights

getTargetRenderProps

setTargetRenderProps

getSourceRenderProps

setSourceRenderProps

setChaseTime

getChaseTime

setEstimateTargetVelocity

getEstimateTargetVelocity

setKp

getKp

setKd

getKd

setPdTimeConstant