Advanced linking

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.

How Links Work

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)

Position, Orientation, or Scale Only Links

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)

Chains of Linked Objects

If you want to use the destination object of a link as the source object of another link, use the link object instead. For example, take the chain of objects tracker > node1 > node2. First the link is established between tracker and node1:

link1 = viz.link(tracker,node1)

#Incorrect code
link2 = viz.link(node1,node2)

#Correct code
link2 = viz.link(link1,node2)

The example code below demonstrates the correct method for creating a chain of links:

soccerball = viz.addChild('soccerball.osgb',pos=[0,1.8,3])
basketball = viz.addChild('basketball.osgb')
volleyball = viz.addChild('volleyball.osgb')

#Use link1 as the source of link2
link1 = viz.link(soccerball,basketball,offset=(-0.5,0,0))
link2 = viz.link(link1,volleyball,offset=(0,0.5,0))

#Move soccerball with left/right arrow keys
vizact.whilekeydown(viz.KEY_RIGHT,soccerball.setPosition,vizact.elapsed(3),0,0,viz.REL_GLOBAL)
vizact.whilekeydown(viz.KEY_LEFT,soccerball.setPosition,vizact.elapsed(-3),0,0,viz.REL_GLOBAL)

Special Options for Specific Linkable Types

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 a source or destination is a child of another object.

Linking with Sensors

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)

Linking with Orthographic Screen Geometry

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)

Position and Orientation from two Source Objects

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 \examples\linking\mergeLinking.py script. 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

Grab Links

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 is located at \examples\linking\grabbing.py.

#Grab the ball with the hand
link = viz.grab(hand, ball)

Ending Links

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.