msim.model

Class Link

java.lang.Object

msim.model.LinkageNode

msim.model.Link

All Implemented Interfaces:

java.lang.Comparable<LinkageNode>

@ThreadSafe
public class Link
extends LinkageNode

Link node in the MSim model.

See additional description in header doc for Linkage.

Copyright (C) 2008 Marsette A. Vona, III

Author:

Marsette A. Vona, III

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	Link.UserSubFrame Collects properties for a user-added subframe.

Nested classes/interfaces inherited from class msim.model.LinkageNode

LinkageNode.ApplyingNodeHandler, LinkageNode.NodeHandler, LinkageNode.SubFrame

Field Summary

Fields

Modifier and Type	Field and Description
static float	AXES_RADIUS_FACTOR AxesWidget radii relative to LinkageNode.widgetLength
Joint	breadcrumb used in Controller.analyze()
protected double[]	centerOfMass link or subtree center of mass in link frame, default (0, 0, 0)
protected java.util.Set<Joint>	chainClosures The chain closure Joints whose child is this Link, if any.
protected java.util.Map<java.lang.String,Joint>	childJoints Immediate descendents of this Link in the model tree.
static vona.color.ColorScheme	COM_COLOR_SCHEME Color scheme for link and subtree CoM Widgets.
static float	COM_WIDGET_ALPHA alpha for center of mass widgets
protected float	comWidgetRadiusScaleFactor Scale factor taking mass units to units of LinkageNode.widgetLength for the purpose of setting the radii of the center-of-mass widgets.
private static java.lang.String	cvsid
static float	DEF_COM_WIDGET_RADIUS_SCALE_FACTOR default for comWidgetRadiusScaleFactor
protected boolean	linkCoMWidgetEnabled enables for the link and subtree center of mass widgets
static java.lang.String	LW_AXES WP_LINK values
static java.lang.String	LW_LABEL WP_LINK values
static java.lang.String	LW_LINK_COM WP_LINK values
static java.lang.String	LW_SUBFRAME_ROUTES WP_LINK values
static java.lang.String	LW_SUBTREE_COM WP_LINK values
protected double	mass link or subtree mass, NaN if unset (default)
protected Joint	parentJoint The tree Joint leading to this Link.
protected RootJoint	rootJoint The RootJoint associated with this Link.
static java.lang.String	SF_LINK link frame
static float	SUBFRAME_AXES_RADIUS_FACTOR AxesWidget radii relative to LinkageNode.widgetLength
protected double[]	subtreeCenterOfMass link or subtree center of mass in link frame, default (0, 0, 0)
protected boolean	subtreeCoMWidgetEnabled enables for the link and subtree center of mass widgets
protected double	subtreeMass link or subtree mass, NaN if unset (default)
protected vona.math.RX	tempRX workspace
protected double[]	tempV3 workspace
protected float[]	tempV3f workspace
protected java.util.Set<Joint>	unmodifiableChainClosures unmodifiable view of chainClosures
protected java.util.Collection<Joint>	unmodifiableChildJoints unmodifiable view of childJoints
protected java.util.Set<java.lang.String>	unmodifiableUserSubFrameNames unmodifiable view of the key set of userSubFrames
protected java.util.Map<java.lang.String,Link.UserSubFrame>	userSubFrames Current set of Link.UserSubFrames, indexed by name.
static java.lang.String	WN_LINK_AXES Link Widget names
static java.lang.String	WN_LINK_COM Link Widget names
static java.lang.String	WN_LINK_LABEL Link Widget names
static java.lang.String	WN_SUBTREE_COM Link Widget names
static java.lang.String	WP_LINK Widget property identifying a Link widget

Fields inherited from class msim.model.LinkageNode

autoNamed, cmt, DEF_WIDGET_LENGTH, depth, entityClass, explicitlyHidden, explicitlyHighlighted, explicitlyMasked, explicitlyVisible, linkage, name, nextAnonymousWidgetNumber, nodeWidgets, numUserWidgets, propertyMap, SF_CANONICAL, TM_JOINT_TYPE_START, TM_NUM_CLOSURE_JOINTS, TM_NUM_CONSTRAINED_CLOSURE_JOINTS, TM_NUM_DANGLING_JOINTS, TM_NUM_JOINT_WIDGETS, TM_NUM_JOINTS, TM_NUM_LINK_WIDGETS, TM_NUM_LINKAGES, TM_NUM_LINKS, TM_NUM_LOCKED_LINKS, TM_NUM_NODES, TM_NUM_SUPPORTING_TREE_JOINTS, TM_NUM_TREE_JOINTS, TM_NUM_UNCONSTRAINED_CLOSURE_JOINTS, TM_NUM_UNLOCKED_TREE_JOINTS, TM_NUM_WIDGETS, TM_SIZE, unmodifiableWidgets, widgetLength, widgetMap, widgets, widgetsDirty, WP_CACHED_SUBFRAME, WP_EXPLICIT_HIDDEN, WP_EXPLICIT_HIGHLIGHT, WP_EXPLICIT_MASK, WP_EXPLICIT_VISIBLE, WP_FRAME, WP_NAME, WP_NODE, WP_USER_SUBFRAME

Constructor Summary

Constructors

Constructor and Description
Link(Linkage linkage) covers Link(Linkage, String), always auto-named
Link(Linkage linkage, java.lang.String name) Constructs a new Link and adds it to linkage.

Method Summary

Methods

Modifier and Type	Method and Description
int	addConnectableJointTypes(java.lang.String name, Joint.Type... types) Add one or more entries to the Link.UserSubFrame.connectableJointTypes set for the indicated user subframe, consing it if initially null.
int	addConnectableSubFrameTypes(java.lang.String name, java.lang.String... types) Add one or more entries to the Link.UserSubFrame.connectableSubFrameTypes set for the indicated user subframe, consing it if initially null.
void	addUserSubFrame(java.lang.String name, vona.math.RX rx) Add a user subframe.
boolean	checkName(java.lang.String name) Extends superclass impl to verify corresp RootJoint name unique.
int	cullDanglingChainClosures() cull all chain closures on this Link that have no no parent
int	cullDanglingChildJoints() cull all child Joints with no children of their own
int	cullDanglingJoints() cullDanglingChildJoints() and cullDanglingChainClosures().
void	dumpSubFrames(java.io.PrintStream s) Dump all available subframes.
protected void	dumpTree(java.lang.String prefix, java.io.PrintStream s) impl of LinkageNode.dumpTree(PrintStream)
void	dumpUserSubFrame(java.lang.String name) dumpUserSubFrame(String, PrintStream) to System.out
void	dumpUserSubFrame(java.lang.String name, java.io.PrintStream s) dump details of a user subframe
void	dumpUserSubFrames() dumpUserSubFrames(PrintStream) to System.out
void	dumpUserSubFrames(java.io.PrintStream s) dump all available user subframes
void	enableLinkCoMWidget(boolean enable) enable the link center of mass widget
void	enableLinkCoMWidgetRecursively(boolean enable) enableLinkCoMWidget(boolean) in recursive DFS pre-order from this node.
void	enableSubtreeCoMWidget(boolean enable) enable the subtree center of mass widget
void	enableSubtreeCoMWidgetRecursively(boolean enable) enableSubtreeCoMWidget(boolean) in recursive DFS pre-order from this node.
double[]	getCenterOfMass() covers getCenterOfMass(double[]), conses
double[]	getCenterOfMass(double[] centerOfMass) get the location of the center of mass in link frame, default (0,0,0)
java.util.Set<Joint>	getChainClosures() returns an unmodifiable view of chainClosures
LinkageNode	getChild(java.lang.String name) this impl covers getChildJoint(java.lang.String)
Joint	getChildJoint(java.lang.String name) Get the named immediate descendent of this Link, or null if not found.
java.util.Collection<Joint>	getChildJoints() returns an unmodifiable view of childJoints
java.util.Collection<? extends LinkageNode>	getChildren() this impl returns an unmodifiable view of childJoints
float	getCoMWidgetRadiusScaleFactor() get comWidgetRadiusScaleFactor
Joint.Type[]	getConnectableJointTypes(java.lang.String name) Get a copy of the current set of connectable Joint types for the indicated user subframe name, empty if none, null if unrestricted.
java.lang.String[]	getConnectableSubFrameTypes(java.lang.String name) Get a copy of the current set of connectable subframe types for the indicated user subframe frame, empty if none, null if unrestricted.
Joint	getJointAttachedToUserSubFrame(java.lang.String name) Get the Joint attached to the named user subframe, or null if none.
double	getMass() get the current link mass or NaN if unset
protected java.lang.String	getNodeWidgetProperty() Return the Widget property name that indicates an internal (i.e.
LinkageNode	getParent() this impl returns parentJoint
Joint	getParentJoint() returns parentJoint
vona.math.RX	getPose() getPose(RX), conses
vona.math.RX	getPose(vona.math.RX rx) Get the pose of this Link relative to the Linkage.groundLink.
RootJoint	getRootJoint() get a reference to this Link's RootJoint
LinkageNode.SubFrame	getSubFrame(java.lang.String name) Hook to get or cons the indicated LinkageNode.SubFrame of this LinkageNode.
vona.math.RX	getSubFrameRX(java.lang.String name, vona.math.RX rx) Get the transform taking coordinates in a sub-frame to the canonical (i.e.
double[]	getSubtreeCenterOfMass() covers getSubtreeCenterOfMass(double[]), conses
double[]	getSubtreeCenterOfMass(double[] centerOfMass) Get the location of the subtree center of mass in link frame, default (0,0,0).
double	getSubtreeMass() get subtreeMass
java.util.Set<java.lang.String>	getUserSubFrameNames() Get a live but unmodifiable view of the set of names of all user subframes of this link.
java.lang.String	getUserSubFrameType(java.lang.String name) Get the current Link.UserSubFrame.type for the indicated user subframe name.
boolean	hasChildren() check whether this node has any children
boolean	hasSubFrame(java.lang.String name) Check if the named subframe is present.
boolean	hasTargetPose() check if a target pose is currently set (see setTargetPose(vona.math.RX))
boolean	hasUserSubFrame(java.lang.String name) check if the named user subname is present
java.lang.String	isConnectableToJoint(java.lang.String name, Joint joint) isConnectableToJoint(String, Joint, Link), no replacing
java.lang.String	isConnectableToJoint(java.lang.String name, Joint joint, Link replacing) Check if the user subframe name on this Link is connectable to the given joint.
boolean	isConnectableToJointType(java.lang.String name, Joint.Type type) Check if the user subframe name on this Link is connectable to a joint with the given type.
boolean	isConnectableToSubFrameType(java.lang.String name, java.lang.String type) Check if the user subframe name on this Link is connectable to a subframe with the given type.
boolean	isGroundLink() check if this is the Linkage.groundLink in LinkageNode.linkage
boolean	isInternalFrame(java.lang.String name) Check if frame is an internal (i.e.
boolean	isLinkCoMWidgetEnabled() check if the link center of mass widget is enabled
boolean	isLocked() check if this node is locked
boolean	isMassSet() check if the current link mass is not NaN
boolean	isRootLink() check if this Link's parentJoint is its rootJoint
boolean	isSubtreeCoMWidgetEnabled() check if the subtree center of mass widget is enabled
boolean	isSubtreeMassSet() check if subtreeMass is not NaN
boolean	isUltimateGroundLink() check if isGroundLink() and rootJoint has no parent
boolean	isUserSubFrameAttached(java.lang.String name) Check if the indicated user subframe is currently attached to any Joint.
Link	makeGroundLink() Ensure this is the LinkageNode.linkage Linkage.groundLink.
Link	makeRootLink() Ensure that this Link is a root, i.e., that it's parentJoint is its rootJoint.
protected java.lang.String	makeUniqueChildName(java.lang.String tryName) Make a unique name for a child Joint.
void	remove() Remove this node from the Linkage tree.
int	removeConnectableJointTypes(java.lang.String name, Joint.Type... types) Remove one or more entries from the Link.UserSubFrame.connectableJointTypes set for the indicated user subframe.
int	removeConnectableSubFrameTypes(java.lang.String name, java.lang.String... types) Remove one or more entries from the Link.UserSubFrame.connectableSubFrameTypes set for the indicated user subframe.
vona.math.RX	removeUserSubFrame(java.lang.String name) Remove a user subframe.
boolean	setCenterOfMass(double... centerOfMass) Set the location of the center of mass in link frame.
void	setCoMWidgetRadiusScaleFactor(float scaleFactor) set comWidgetRadiusScaleFactor
void	setCoMWidgetRadiusScaleFactorRecursively(float scaleFactor) setCoMWidgetRadiusScaleFactor(float) in recursive DFS pre-order from this node.
LinkageNode	setLocked(boolean locked) lock the state of this node
double	setMass(double mass) Set the link mass.
java.lang.String	setName(java.lang.String name) Set the name of this Link.
Link	setPose(Joint joint) Set the pose of this link as if it were the child of joint.
Link	setPose(Link link) Set the pose of this Link to be the same as that of link.
Link	setPose(vona.math.RX rx) Set the pose of this Link relative to the Linkage.groundLink.
Link	setTargetPose(vona.math.RX rx) Set the target pose of this Link relative to the Linkage.groundLink.
void	setUserSubFrameRX(java.lang.String name, vona.math.RX rx) Update the subframe transform of a user subframe.
java.lang.String	setUserSubFrameType(java.lang.String name, java.lang.String type) Set the current Link.UserSubFrame.type for the indicated user subframe name.
Joint	split() Insert a new Joint and Link in the model tree between this Link and its current parent Joint.
java.lang.String	toString(boolean details) returns a short human-readable identifying string for this Link
void	unrestrictConnectableJointTypes(java.lang.String name) Set Link.UserSubFrame.connectableJointTypes to null for the indicated user subframe name, which means unrestricted.
void	unrestrictConnectableSubFrameTypes(java.lang.String name) Set Link.UserSubFrame.connectableSubFrameTypes to null for the indicated user subframe name, which means unrestricted.
double	unsetMass() setMass(double) NaN
Link	unsetTargetPose() setTargetPose(vona.math.RX) to null
void	updateCMTs() Update this node's LinkageNode.cmt based on its parent's LinkageNode.cmt.
void	updateCMTsRecursively() LinkageNode.updateCMTs() in recursive tree DFS pre-order from this node
protected void	updateCoMWidget(java.lang.String name, java.lang.String id, double mass, double[] center, java.awt.Color color) Called by updateWidgetsImpl() to handle the link and subtree center of mass widgets.
void	updateSubtreeCoM() Update subtreeCenterOfMass and subtreeMass based on those of this Link's grandchildren (i.e.
void	updateSubtreeCoMsRecursively() updateSubtreeCoM() in recursive tree DFS post-order from this node.
protected void	updateWidgetsImpl() Hook for lazy LinkageNode.widgetMap update.

Methods inherited from class msim.model.LinkageNode

addWidget, addWidget, addWidget, addWidget, addWidget, addWidget, checkNamePattern, collectTreeMetrics, collectTreeMetrics, compareTo, dump, dump, dumpSubFrames, dumpTree, dumpTree, dumpTreeMetrics, dumpTreeMetrics, enableDBGNormals, enableDBGNormalsRecursively, enableDBGSpheres, enableDBGSpheresRecursively, findImpl, findJoint, findJoint, findJoints, findJoints, findLink, findLink, findLinks, findLinks, findMultipleImpl, findNode, findNode, findNodes, findNodes, getCMT, getCMT, getDepth, getName, getNumUserWidgets, getNumWidgets, getProperty, getSubFrame, getSubFrameCMT, getSubFrameCMT, getSubFrameCMT, getSubFrameCMT, getSubFrameName, getSubFrameRX, getSubFrameRX, getSubFrameRX, getWidget, getWidgetLength, getWidgets, hasDescendant, hasProperty, hasWidgets, isAutoNamed, isExplicitlyHidden, isExplicitlyHighlighted, isExplicitlyMasked, isExplicitlyVisible, isLive, isTreeLeaf, isUserWidget, lock, removeAllWidgets, removeProperty, removeWidget, removeWidget, renameWidget, reparentUserWidgets, reparentUserWidgets, reparentWidget, reparentWidget, reparentWidgetImpl, reparentWidgets, reparentWidgets, setAllTreeJointsToGoal, setAllTreeJointsToHighestPrioritySoftGoal, setAllTreeJointsToPosture, setAllTreeJointsToTarget, setExplicitlyHidden, setExplicitlyHighlighted, setExplicitlyMasked, setExplicitlyVisible, setLockedRecursively, setProperty, setProperty, setWidgetLength, setWidgetLength, setWidgetLengthRecursively, setWidgetLengthRecursively, suppressTreeDump, toString, traverseTree, unlock, updateWidgets, updateWidgetsRecursively

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

cvsid

private static final java.lang.String cvsid

See Also:

Constant Field Values

WP_LINK

public static final java.lang.String WP_LINK

Widget property identifying a Link widget

See Also:

Constant Field Values

LW_AXES

public static final java.lang.String LW_AXES

WP_LINK values

See Also:

Constant Field Values

LW_LABEL

public static final java.lang.String LW_LABEL

WP_LINK values

See Also:

Constant Field Values

LW_LINK_COM

public static final java.lang.String LW_LINK_COM

WP_LINK values

See Also:

Constant Field Values

LW_SUBTREE_COM

public static final java.lang.String LW_SUBTREE_COM

WP_LINK values

See Also:

Constant Field Values

LW_SUBFRAME_ROUTES

public static final java.lang.String LW_SUBFRAME_ROUTES

WP_LINK values

See Also:

Constant Field Values

WN_LINK_AXES

public static final java.lang.String WN_LINK_AXES

Link Widget names

See Also:

Constant Field Values

WN_LINK_LABEL

public static final java.lang.String WN_LINK_LABEL

Link Widget names

See Also:

Constant Field Values

WN_LINK_COM

public static final java.lang.String WN_LINK_COM

Link Widget names

See Also:

Constant Field Values

WN_SUBTREE_COM

public static final java.lang.String WN_SUBTREE_COM

Link Widget names

See Also:

Constant Field Values

AXES_RADIUS_FACTOR

public static final float AXES_RADIUS_FACTOR

AxesWidget radii relative to LinkageNode.widgetLength

See Also:

Constant Field Values

SUBFRAME_AXES_RADIUS_FACTOR

public static final float SUBFRAME_AXES_RADIUS_FACTOR

AxesWidget radii relative to LinkageNode.widgetLength

See Also:

Constant Field Values

DEF_COM_WIDGET_RADIUS_SCALE_FACTOR

public static final float DEF_COM_WIDGET_RADIUS_SCALE_FACTOR

default for comWidgetRadiusScaleFactor

See Also:

Constant Field Values

SF_LINK

public static final java.lang.String SF_LINK

link frame

See Also:

Constant Field Values

COM_COLOR_SCHEME

public static final vona.color.ColorScheme COM_COLOR_SCHEME

Color scheme for link and subtree CoM Widgets.

• link CoM: related color
• subtree CoM: compliment related color

COM_WIDGET_ALPHA

public static final float COM_WIDGET_ALPHA

alpha for center of mass widgets

See Also:

Constant Field Values

parentJoint

protected Joint parentJoint

The tree Joint leading to this Link.

Except for the Linkage.groundLink, Links always have a parent. Links that are not otherwise parented are automatically re-parented to the Linkage.groundLink by their rootJoint.

See Linkage class header doc for additional info.

rootJoint

protected final RootJoint rootJoint

The RootJoint associated with this Link.

childJoints

protected java.util.Map<java.lang.String,Joint> childJoints

Immediate descendents of this Link in the model tree.

unmodifiableChildJoints

protected final java.util.Collection<Joint> unmodifiableChildJoints

unmodifiable view of childJoints

chainClosures

protected java.util.Set<Joint> chainClosures

The chain closure Joints whose child is this Link, if any.

Chain closures whose parent is this Link are included in childJoints.

unmodifiableChainClosures

protected java.util.Set<Joint> unmodifiableChainClosures

unmodifiable view of chainClosures

mass

protected double mass

link or subtree mass, NaN if unset (default)

subtreeMass

protected double subtreeMass

link or subtree mass, NaN if unset (default)

centerOfMass

protected double[] centerOfMass

link or subtree center of mass in link frame, default (0, 0, 0)

subtreeCenterOfMass

protected double[] subtreeCenterOfMass

link or subtree center of mass in link frame, default (0, 0, 0)

tempV3

protected double[] tempV3

workspace

tempV3f

protected float[] tempV3f

workspace

tempRX

protected vona.math.RX tempRX

workspace

breadcrumb

public Joint breadcrumb

used in Controller.analyze()

comWidgetRadiusScaleFactor

protected float comWidgetRadiusScaleFactor

Scale factor taking mass units to units of LinkageNode.widgetLength for the purpose of setting the radii of the center-of-mass widgets.

Initially set from the corresponding value on the LinkageNode.linkage ground link, which itself defaults to DEF_COM_WIDGET_RADIUS_SCALE_FACTOR.

linkCoMWidgetEnabled

protected boolean linkCoMWidgetEnabled

enables for the link and subtree center of mass widgets

subtreeCoMWidgetEnabled

protected boolean subtreeCoMWidgetEnabled

enables for the link and subtree center of mass widgets

userSubFrames

protected java.util.Map<java.lang.String,Link.UserSubFrame> userSubFrames

Current set of Link.UserSubFrames, indexed by name.

unmodifiableUserSubFrameNames

protected final java.util.Set<java.lang.String> unmodifiableUserSubFrameNames

unmodifiable view of the key set of userSubFrames

Constructor Detail

Link

public Link(Linkage linkage,
    java.lang.String name)

Constructs a new Link and adds it to linkage.

The new Link is initially attached to the Linkage.groundLink through its rootJoint.

Parameters:

name - Link name or null to auto-name

Throws:

java.lang.IllegalArgumentException - if name is non-null and fails checkName(java.lang.String), in this case the new Link is not added to linkage

Link

public Link(Linkage linkage)

covers Link(Linkage, String), always auto-named

Method Detail

setName

public java.lang.String setName(java.lang.String name)

Set the name of this Link.

Has no effect if the new name equals the old.

Also sets a corresponding name on rootJoint (see RootJoint.makeRootJointName(java.lang.String)).

Specified by:

setName in class LinkageNode

Parameters:

name - Link name or null to auto-name

Returns:

the old name

Throws:

java.lang.IllegalArgumentException - if name fails checkName(java.lang.String), in this case the name is not changed

checkName

public boolean checkName(java.lang.String name)

Extends superclass impl to verify corresp RootJoint name unique.

Overrides:

checkName in class LinkageNode

getParent

public LinkageNode getParent()

this impl returns parentJoint

Specified by:

getParent in class LinkageNode

getChild

public LinkageNode getChild(java.lang.String name)

this impl covers getChildJoint(java.lang.String)

Specified by:

getChild in class LinkageNode

getChildren

public java.util.Collection<? extends LinkageNode> getChildren()

this impl returns an unmodifiable view of childJoints

Specified by:

getChildren in class LinkageNode

hasChildren

public boolean hasChildren()

check whether this node has any children

This impl checks if childJoints is not empty.

Overrides:

hasChildren in class LinkageNode

updateCMTs

public void updateCMTs()

Update this node's LinkageNode.cmt based on its parent's LinkageNode.cmt.

Implementations may also compute and cache other CMT-related state in this call, such as CMTs for sub-frames.

For details on the semantics of CMTs see the Linkage class header doc.

Specified by:

updateCMTs in class LinkageNode

updateCMTsRecursively

public void updateCMTsRecursively()

LinkageNode.updateCMTs() in recursive tree DFS pre-order from this node

This impl also {Joint#updateCMTs} on any attached chainClosures with no parent.

Overrides:

updateCMTsRecursively in class LinkageNode

remove

public void remove()

Remove this node from the Linkage tree.

All adjacent Joint endpoints are dangled.

Once a node has been removed it cannot be re-added.

All connected child tree Joints must first be disconnected or converted to chain closures. Any attached dangling Joints are culled, and any attached connected Joints are dangled.

Removing a ground link other than the ultimate ground is equivalent to removing its Linkage.

Specified by:

remove in class LinkageNode

Throws:

java.lang.IllegalStateException - if isUltimateGroundLink() or if there are any connected tree child joints

cullDanglingChildJoints

public int cullDanglingChildJoints()

cull all child Joints with no children of their own

cullDanglingChainClosures

public int cullDanglingChainClosures()

cull all chain closures on this Link that have no no parent

cullDanglingJoints

public int cullDanglingJoints()

cullDanglingChildJoints() and cullDanglingChainClosures().

getRootJoint

public RootJoint getRootJoint()

get a reference to this Link's RootJoint

split

public Joint split()

Insert a new Joint and Link in the model tree between this Link and its current parent Joint.

The model topology changes from

parent Joint <- this Link

to

parent Joint <- new Link <- new Joint <- this Link

With the exception that if this was a root link then the new Link is also a root link (which means that its parent Joint will be a different RootJoint than the original parent Joint of this Link; otherwise the parent Joint of the new Link will always be the previous parent Joint of this Link).

The new Joint is initially locked and Joint.Type.GENERAL with identity joint transform, which means that the new Link is initially coincident with this Link, and that this Link does not change its global pose.

This Link always retains its current set of child Joints, chain closure Joints, and user widgets.

If this Link was locked then it is unlocked and the new Link is locked instead.

See also Joint.merge(boolean, boolean).

Returns:

the new Joint, its parent is the new Link, and its child is this Link

Throws:

java.lang.IllegalStateException - if isGroundLink()

isRootLink

public boolean isRootLink()

check if this Link's parentJoint is its rootJoint

isGroundLink

public boolean isGroundLink()

check if this is the Linkage.groundLink in LinkageNode.linkage

isUltimateGroundLink

public boolean isUltimateGroundLink()

check if isGroundLink() and rootJoint has no parent

getParentJoint

public Joint getParentJoint()

returns parentJoint

getChildJoint

public Joint getChildJoint(java.lang.String name)

Get the named immediate descendent of this Link, or null if not found.

getChildJoints

public java.util.Collection<Joint> getChildJoints()

returns an unmodifiable view of childJoints

getChainClosures

public java.util.Set<Joint> getChainClosures()

returns an unmodifiable view of chainClosures

makeRootLink

public Link makeRootLink()

Ensure that this Link is a root, i.e., that it's parentJoint is its rootJoint.

This is very different from makeGroundLink().

Has no effect if this Link is already a root. Otherwise, any existing parent joint is made a closure and the root joint is made a tree joint.

The link always holds its absolute pose.

makeGroundLink

public Link makeGroundLink()

Ensure this is the LinkageNode.linkage Linkage.groundLink.

This is very different from makeRootLink().

Has no effect if this Link is already the ground link. Otherwise the behavior depends on whether this is a root link. If not, chains to Joint.invert() on parentJoint. If so,

1. the prior ground link is made a root, since the only outgoing tree joint from a sublinkage must be attached to the sublinkage ground link
2. the parent of our rootJoint is set to the parent of the root joint of the prior ground link, which will either be the ground link of the superlinkage or null if the prior ground link was the ultimate ground.
3. the parent of the prior ground link's root joint is set to this link
4. all other RootJoints that were previously children of the prior ground link are re-parented to this link

All links always hold absolute pose.

setTargetPose

public Link setTargetPose(vona.math.RX rx)

Set the target pose of this Link relative to the Linkage.groundLink.

Defers to Joint.setSoftGoal(int, vona.math.RX) on rootJoint.

Parameters:

rx - the target pose, or null to un-set

unsetTargetPose

public Link unsetTargetPose()

setTargetPose(vona.math.RX) to null

hasTargetPose

public boolean hasTargetPose()

check if a target pose is currently set (see setTargetPose(vona.math.RX))

setPose

public Link setPose(vona.math.RX rx)

Set the pose of this Link relative to the Linkage.groundLink.

Defers to Joint.setMobility(vona.math.RX) on rootJoint.

getPose

public vona.math.RX getPose(vona.math.RX rx)

Get the pose of this Link relative to the Linkage.groundLink.

Defers to Joint.getMobility(vona.math.RX) on rootJoint.

getPose

public vona.math.RX getPose()

getPose(RX), conses

setPose

public Link setPose(Joint joint)

Set the pose of this link as if it were the child of joint.

Defers to Joint.setMobility(vona.math.RX) on rootJoint.

setPose

public Link setPose(Link link)

Set the pose of this Link to be the same as that of link.

Defers to Joint.setMobility(vona.math.RX) on rootJoint.

setLocked

public LinkageNode setLocked(boolean locked)

lock the state of this node

This impl sets the state of parentJoint.

Specified by:

setLocked in class LinkageNode

isLocked

public boolean isLocked()

check if this node is locked

This impl checks the state of parentJoint.

Specified by:

isLocked in class LinkageNode

setMass

public double setMass(double mass)

Set the link mass.

NaN is equivalent to unsetMass().

Returns:

the old value

Throws:

java.lang.IllegalArgumentException - if mass is negative

unsetMass

public double unsetMass()

setMass(double) NaN

getMass

public double getMass()

get the current link mass or NaN if unset

isMassSet

public boolean isMassSet()

check if the current link mass is not NaN

setCenterOfMass

public boolean setCenterOfMass(double... centerOfMass)

Set the location of the center of mass in link frame.

Returns:

true if the CoM changed

getCenterOfMass

public double[] getCenterOfMass(double[] centerOfMass)

get the location of the center of mass in link frame, default (0,0,0)

getCenterOfMass

public double[] getCenterOfMass()

covers getCenterOfMass(double[]), conses

updateSubtreeCoM

public void updateSubtreeCoM()

Update subtreeCenterOfMass and subtreeMass based on those of this Link's grandchildren (i.e. its nearest descendant Links).

updateSubtreeCoMsRecursively

public void updateSubtreeCoMsRecursively()

updateSubtreeCoM() in recursive tree DFS post-order from this node.

getSubtreeCenterOfMass

public double[] getSubtreeCenterOfMass(double[] centerOfMass)

Get the location of the subtree center of mass in link frame, default (0,0,0).

getSubtreeCenterOfMass

public double[] getSubtreeCenterOfMass()

covers getSubtreeCenterOfMass(double[]), conses

getSubtreeMass

public double getSubtreeMass()

get subtreeMass

isSubtreeMassSet

public boolean isSubtreeMassSet()

check if subtreeMass is not NaN

makeUniqueChildName

protected java.lang.String makeUniqueChildName(java.lang.String tryName)

Make a unique name for a child Joint.

Parameters:

tryName - the first name to try, or null to generate one

dumpTree

protected void dumpTree(java.lang.String prefix,
            java.io.PrintStream s)

impl of LinkageNode.dumpTree(PrintStream)

This impl overrides generic impl to also dump any orphan joints which have this link as their child.

Overrides:

dumpTree in class LinkageNode

toString

public java.lang.String toString(boolean details)

returns a short human-readable identifying string for this Link

Specified by:

toString in class LinkageNode

getNodeWidgetProperty

protected java.lang.String getNodeWidgetProperty()

Return the Widget property name that indicates an internal (i.e. non-user) Widget.

This impl returns WP_LINK.

Specified by:

getNodeWidgetProperty in class LinkageNode

updateWidgetsImpl

protected void updateWidgetsImpl()

Hook for lazy LinkageNode.widgetMap update.

Default impl updates all widgets to current LinkageNode.widgetLength, sets their EntityClass.WP_ENTITY_CLASS, and updates existing dbg geometry iff enabled.

This impl adds AxesWidgets for the link and any user subframes, and link and subtree CoM widgets as necessary.

Overrides:

updateWidgetsImpl in class LinkageNode

updateCoMWidget

protected void updateCoMWidget(java.lang.String name,
                   java.lang.String id,
                   double mass,
                   double[] center,
                   java.awt.Color color)

Called by updateWidgetsImpl() to handle the link and subtree center of mass widgets.

setCoMWidgetRadiusScaleFactor

public void setCoMWidgetRadiusScaleFactor(float scaleFactor)

set comWidgetRadiusScaleFactor

setCoMWidgetRadiusScaleFactorRecursively

public void setCoMWidgetRadiusScaleFactorRecursively(float scaleFactor)

setCoMWidgetRadiusScaleFactor(float) in recursive DFS pre-order from this node.

getCoMWidgetRadiusScaleFactor

public float getCoMWidgetRadiusScaleFactor()

get comWidgetRadiusScaleFactor

enableLinkCoMWidget

public void enableLinkCoMWidget(boolean enable)

enable the link center of mass widget

isLinkCoMWidgetEnabled

public boolean isLinkCoMWidgetEnabled()

check if the link center of mass widget is enabled

enableLinkCoMWidgetRecursively

public void enableLinkCoMWidgetRecursively(boolean enable)

enableLinkCoMWidget(boolean) in recursive DFS pre-order from this node.

enableSubtreeCoMWidget

public void enableSubtreeCoMWidget(boolean enable)

enable the subtree center of mass widget

isSubtreeCoMWidgetEnabled

public boolean isSubtreeCoMWidgetEnabled()

check if the subtree center of mass widget is enabled

enableSubtreeCoMWidgetRecursively

public void enableSubtreeCoMWidgetRecursively(boolean enable)

enableSubtreeCoMWidget(boolean) in recursive DFS pre-order from this node.

addUserSubFrame

public void addUserSubFrame(java.lang.String name,
                   vona.math.RX rx)

Add a user subframe.

Parameters:

name - the name of the user subframe, must be unique in this Link

rx - the initial transform taking subframe coordinates to link frame coordinates

Throws:

java.lang.IllegalArgumentException - if name is not unique

removeUserSubFrame

public vona.math.RX removeUserSubFrame(java.lang.String name)

Remove a user subframe.

Returns:

the last value of the subframe transform, or null if not found

Throws:

java.lang.IllegalStateException - if any widgets or joints are still referencing name

hasUserSubFrame

public boolean hasUserSubFrame(java.lang.String name)

check if the named user subname is present

getUserSubFrameNames

public java.util.Set<java.lang.String> getUserSubFrameNames()

Get a live but unmodifiable view of the set of names of all user subframes of this link.

The set is synchronized by Controller.LOCK.

setUserSubFrameRX

public void setUserSubFrameRX(java.lang.String name,
                     vona.math.RX rx)

Update the subframe transform of a user subframe.

getJointAttachedToUserSubFrame

public Joint getJointAttachedToUserSubFrame(java.lang.String name)

Get the Joint attached to the named user subframe, or null if none.

isUserSubFrameAttached

public boolean isUserSubFrameAttached(java.lang.String name)

Check if the indicated user subframe is currently attached to any Joint.

setUserSubFrameType

public java.lang.String setUserSubFrameType(java.lang.String name,
                                   java.lang.String type)

Set the current Link.UserSubFrame.type for the indicated user subframe name.

Parameters:

type - the new type, must satisfy LinkageNode.checkNamePattern(java.lang.String)

Returns:

the previous type or null if previously unset

Throws:

java.lang.IllegalStateException - if name is currently attached (see isUserSubFrameAttached(java.lang.String))

getUserSubFrameType

public java.lang.String getUserSubFrameType(java.lang.String name)

Get the current Link.UserSubFrame.type for the indicated user subframe name.

Returns:

the type or null if currently unset

addConnectableSubFrameTypes

public int addConnectableSubFrameTypes(java.lang.String name,
                              java.lang.String... types)

Add one or more entries to the Link.UserSubFrame.connectableSubFrameTypes set for the indicated user subframe, consing it if initially null.

Parameters:

types - the types to add (each may or may not initially be present), each must satisfy LinkageNode.checkNamePattern(java.lang.String)

Returns:

the number of types actually added

Throws:

java.lang.IllegalStateException - if name is currently attached (see isUserSubFrameAttached(java.lang.String))

addConnectableJointTypes

public int addConnectableJointTypes(java.lang.String name,
                           Joint.Type... types)

Add one or more entries to the Link.UserSubFrame.connectableJointTypes set for the indicated user subframe, consing it if initially null.

Parameters:

types - the types to add (each may or may not initially be present)

Returns:

the number of types actually added

Throws:

java.lang.IllegalStateException - if name is currently attached (see isUserSubFrameAttached(java.lang.String))

removeConnectableSubFrameTypes

public int removeConnectableSubFrameTypes(java.lang.String name,
                                 java.lang.String... types)

Remove one or more entries from the Link.UserSubFrame.connectableSubFrameTypes set for the indicated user subframe.

Note that if removing all types does not null the set (and make connection unrestricted), for that see unrestrictConnectableSubFrameTypes(java.lang.String).

Parameters:

types - the types to remove (each may or may not initially be present)

Returns:

the number of types actually removed

Throws:

java.lang.IllegalStateException - if name is currently attached (see isUserSubFrameAttached(java.lang.String))

removeConnectableJointTypes

public int removeConnectableJointTypes(java.lang.String name,
                              Joint.Type... types)

Remove one or more entries from the Link.UserSubFrame.connectableJointTypes set for the indicated user subframe.

Note that if removing all types does not null the set (and make connection unrestricted), for that see unrestrictConnectableJointTypes(java.lang.String).

Parameters:

types - the types to remove (each may or may not initially be present)

Returns:

the number of types actually removed

Throws:

java.lang.IllegalStateException - if name is currently attached (see isUserSubFrameAttached(java.lang.String))

unrestrictConnectableSubFrameTypes

public void unrestrictConnectableSubFrameTypes(java.lang.String name)

Set Link.UserSubFrame.connectableSubFrameTypes to null for the indicated user subframe name, which means unrestricted.

Throws:

java.lang.IllegalStateException - if name is currently attached (see isUserSubFrameAttached(java.lang.String))

unrestrictConnectableJointTypes

public void unrestrictConnectableJointTypes(java.lang.String name)

Set Link.UserSubFrame.connectableJointTypes to null for the indicated user subframe name, which means unrestricted.

Throws:

java.lang.IllegalStateException - if frame is currently attached (see isUserSubFrameAttached(java.lang.String))

getConnectableSubFrameTypes

public java.lang.String[] getConnectableSubFrameTypes(java.lang.String name)

Get a copy of the current set of connectable subframe types for the indicated user subframe frame, empty if none, null if unrestricted.

getConnectableJointTypes

public Joint.Type[] getConnectableJointTypes(java.lang.String name)

Get a copy of the current set of connectable Joint types for the indicated user subframe name, empty if none, null if unrestricted.

isConnectableToSubFrameType

public boolean isConnectableToSubFrameType(java.lang.String name,
                                  java.lang.String type)

Check if the user subframe name on this Link is connectable to a subframe with the given type.

isConnectableToJointType

public boolean isConnectableToJointType(java.lang.String name,
                               Joint.Type type)

Check if the user subframe name on this Link is connectable to a joint with the given type.

Parameters:

name - the name of the user subframe on this Link, or null to indicate connection directly to the link (no subframe)

isConnectableToJoint

public java.lang.String isConnectableToJoint(java.lang.String name,
                                    Joint joint,
                                    Link replacing)

Check if the user subframe name on this Link is connectable to the given joint.

This takes into account both the type of joint and its current connection status. Specifically:

• joint is not connectable if it is already fully connected
• joint is not connectable if name has non-null Link.UserSubFrame.connectableJointTypes and that set does not contain the current type of joint
• If joint is already connected at one side then this method checks if it would be valid to connect to name at the other side. Specifically, let other be the other subframe, or null if none
  • joint is connectable if both name is null (no local subframe) and other is null (no remote subframe). If exactly one is null then joint is connectable iff the other has null Link.UserSubFrame.connectableJointTypes.
  • If both name and other are not null then joint is connectable iff the Link.UserSubFrame.type of each is found within the Link.UserSubFrame.connectableSubFrameTypes of the other (if that set is null then the test also passes).

Parameters:

name - the name of the user subframe on this Link, or null to indicate connection directly to the link (no subframe)

joint - the joint to check, not null

replacing - the link that this link would replace. If specified, replacing must be currently connected to joint. If replacing is null then the opposite joint endpoint will be automatically determined iff joint currently has exactly one endpoint

Returns:

null iff joint can be connected to name on this Link, else reason

isConnectableToJoint

public java.lang.String isConnectableToJoint(java.lang.String name,
                                    Joint joint)

isConnectableToJoint(String, Joint, Link), no replacing

dumpUserSubFrame

public void dumpUserSubFrame(java.lang.String name,
                    java.io.PrintStream s)

dump details of a user subframe

dumpUserSubFrame

public void dumpUserSubFrame(java.lang.String name)

dumpUserSubFrame(String, PrintStream) to System.out

dumpUserSubFrames

public void dumpUserSubFrames(java.io.PrintStream s)

dump all available user subframes

dumpUserSubFrames

public void dumpUserSubFrames()

dumpUserSubFrames(PrintStream) to System.out

getSubFrameRX

public vona.math.RX getSubFrameRX(java.lang.String name,
                         vona.math.RX rx)

Get the transform taking coordinates in a sub-frame to the canonical (i.e. LinkageNode.cmt) frame of this LinkageNode.

This impl adds handling for user subframes.

Overrides:

getSubFrameRX in class LinkageNode

Parameters:

name - the sub-frame or null to imply LinkageNode.SF_CANONICAL

rx - the transform is written here on return, consing if null

Returns:

a reference to rx

hasSubFrame

public boolean hasSubFrame(java.lang.String name)

Check if the named subframe is present.

Default impl just checks for LinkageNode.SF_CANONICAL.

This impl checks for SF_LINK and hasUserSubFrame(java.lang.String).

Overrides:

hasSubFrame in class LinkageNode

dumpSubFrames

public void dumpSubFrames(java.io.PrintStream s)

Dump all available subframes.

Default impl just dumps LinkageNode.SF_CANONICAL.

This dumps SF_LINK and user subframes.

Overrides:

dumpSubFrames in class LinkageNode

isInternalFrame

public boolean isInternalFrame(java.lang.String name)

Check if frame is an internal (i.e. non-user) subframe.

Default impl checks LinkageNode.SF_CANONICAL.

This impl extends superclass to also check SF_LINK.

Overrides:

isInternalFrame in class LinkageNode

getSubFrame

public LinkageNode.SubFrame getSubFrame(java.lang.String name)

Hook to get or cons the indicated LinkageNode.SubFrame of this LinkageNode.

Extends superclass impl to handle user subframes.

Overrides:

getSubFrame in class LinkageNode