Links make the source object's transform, or position/orientation/scale matrix, the destination object's transform. In addition, Vizard links also allow for some manipulation of the source's transform before it is given to the destination object.
The viz.link(source, destination) command creates a task every frame to copy the transform matrix of the source to the destination.
#Copy main view transform to arrow's
transform every frame
#viz.MainView is source object, arrow is destination object
viz.link(viz.MainView, arrow)
#Called every frame, this function does the same thing as
the link above
def copyTransform(source, destination):
S = source.getMatrix()
destination.setMatrix(S)
vizact.ontimer(.01,
copyTransform, viz.MainView, arrow)
The viz.link command returns a link object that exposes a number of functions for modifying the behavior of the destination object.
By setting the "mask" of the link, the destination takes a specific combination of position, orientation and scale of the source. Below, we create a link that only affects the orientation of the destination.
#Only link orientation
link = viz.link(sensor, arrow)
#only affect the orientation of the arrow
link.setMask(viz.LINK_ORI)
When three or more objects are linked together, the order in which the links are applied matters. Consider if we set up this link structure N1-->N2-->N3 and are moving node N1. Every frame, Vizard will apply the links in some order. If Vizard applies the N2-->N3 link then the N1-->N2 link, N3 will trail behind N2 every frame. To avoid this, the priority of the links should be set. Links with low values for their priorities are executed first, so the N1-->N2 link should be priority 1 and the N2-->N3 link should be priority 2.
Source and destination objects have some object-specific options available to them with the <link>.setDstFlag and <link>.setSrcFlag methods. The specific flags are only applicable to specific linkable types. For example, geometry node objects have a viz.ABS_GLOBAL link flag option. When this flag is set as a source flag with <link>.setSrcFlag, the link retrieves the transform from the source node in absolute world coordinates. When this flag is set as a destination flag with <link>.setDstFlag, the transform is applied in absolute world coordinates. This is useful when an source or destination is a child of another object.
Linking objects to sensors is an easy way to use the position and orientation data provided by tracking devices. This is useful if you want to "zero out," or reset the reference frame of the sensor data. Links have a built-in reference frame setting capability with their <link>.reset command. The reset command can zero the position and orientation of sensors.
#Reset the position of the sensor
link = viz.link(sensor, viz.MainView)
link.reset(viz.RESET_POS)
Position reset works by calling the <link>.setOffset(x,y,z) command. The link offset moves the position of destination in it's parent's reference frame before any operators are applied. Therefore, calls to <link>.setOffset will overwrite position resets. Orientation resets are implemented through the creation of an operator. A call to <link>.reset( viz.RESET_OPERATORS ) will remove the orientation reset.
# This is the reset you might use with
orientation sensors
link = viz.link(sensor, viz.MainView)
link.reset(viz.RESET_ORI_WORLD)
Geometry nodes added to the orthographic screen can link to a position on the screen. This gives orthographic nodes resolution independent positioning. The possible link locations are the corners, the midpoints on each screen side, and the center.
#Put the text in the top right
node = viz.addText('test text', viz.ORTHO)
node.fontSize(18)
node.alignment(viz.TEXT_RIGHT_TOP)
viz.link(viz.RightTop, node)
You can also apply the source orientation data from one object and the position data from another to a destination node. For an example script, see the linkMerge.py script in the examples\linking directory. In this example, the orientation information comes from the blue marker, while the position information is provided by the red marker. The viz.mergeLinkable( positionSource, orientationSource ) command creates a linkable object that gets its position and orientation from two different nodes.
#Combine orientation and position from
two objects
moveAndSpinSource = viz.mergeLinkable(nodeMove, nodeSpin)
#new VizLinkable object
mergedLink = viz.link(moveAndSpinSource, nodeMerge) #link source to nodeMerge
If you would like to setup a "grab" like relationship between nodes, use the viz.grab(handNode, grabbedNode) function. The link created with viz.grab preserves the position and orientation of the grabbed object relative to the hand. An example script, grab.py is in the examples\linking directory.
#Grab the ball with the hand
link = viz.grab(hand, ball)
The <link>.remove command deletes the link object and ends the link relationship. If you just want to temporally suspend the link, then you can use the <link>.disable and <link>.enable functions.
Linking Basics - Introduction to linking.
Operators on Links - More operator examples and implantation discussion.
Link Command Table - List of relevant link commands.
Transform Basics - Introduces the position/orientation/scale matrix associated with all 3D nodes.