Turn

Turn  (Quaternion rotation_vector)

Rotation_vector is a unit quaternion , a unit 4-vector of form: [t,x,y,z]  Usually it is obtained as the return value of the quat() function.  If for example, it is the value of

quat(angle, [n1,n2,n3]);

the effect is to apply the rotation about the vector [n1,n2,n3]  (which is automatically normalized) through angle degrees, using the right-hand rule to determine the sense.  This rotation is applied  either to the scene, or to the camera (See below).

The 3 dimensional scene environment takes a certain amount of getting used to.  It is easy to get lost in a graph3D since the familiar cues that we use to move around in our own Three dimensional  world may be absent.  We may find ourselves staring into space, not knowing where we are, or which way we're heading.  For that reason, navigation becomes an important issue for us.  All navigation is done by reference to the global Coordinate Frame which is represented in the Setup Actor.

            This coordinate system is color-coded in the Setup actor.  The red arrow points in the positive x direction (to the right, initially).  The white arrow extends in the positive y direction (up, initially), and the blue arrow points in the positive z direction (out of the screen, towards the viewer initially).  There are two quite different types of motion that are available for navigation.  We may actively transform the scene (apply a Euclidean transformation to everything), or we may move the camera (apply a Euclidean transformation to our "eyes," the camera).  Both types leave the relative positions and orientations of the actors fixed in the scene.  But they are subtly different in the effect they have on our viewpoint.

Active transformations (moving the scene):

            In what follows immediately below, we shall assume "Move the Scene" has been selected, either from the Viewport Menu, or from the selection bar:

            When we described the color-coding of the coordinates above, we said "initially" because if we perform active transformations of the scene, using the global or scene coordinates, then the named arrows will still point in their named directions, but those directions may no longer be to the right, or up, or out.  Let us consider navigation by active transformations of the scene first. 

These will be of two types:  motions from the menu, or motions from commands or scripts.  Active transformations move the entire scene (as a whole with reference to an imaginary fixed background frame) in one of two ways:  They may translate the scene in some direction, or they may rotate the scene about some axis.  Any composition of these rigid motions (the Euclidean affine transformations) will actually be uniquely representable as a rotation about the origin followed by a translation.  This six dimensional group of motions is sometimes called the Euclidean group.  Compositions of these give the only way to move space rigidly.

            We have all of these motions of space available to us if we use programs or commands to navigate.  But if we use the navigation bar (see the picture below) we have six "generators" of that group.  These are the translations in the x,y, and z directions, or rotations (using the right hand rule) about the x,y, and z axes.  These translations and rotations are multiples of a predetermined "step" that you may set using the "timer" button on the menu.  The shorter the delay, the larger the step.  You may also reset the system using the "centering button" below.

The Navigation Bar

            Using the navigation bar, the 6 arrows on the left describe the 6 ways of translating

the scene: ±x, ±y, and ±z.  By themselves, these are easy to understand.   But once rotations are admitted, using the next six buttons (which are color coded), things become a bit more complicated, because the x, y, and z directions have now become mixed together.  Motion in the positive x direction still means motion in the direction of the "red arrow" but now you have to look to see what direction that is.  And new rotations are similarly affected.   The Move command is used to perform the translations (not the rotations) of the Euclidean Group by script.

            Now how do we perform these active rotations by command or by script? 

The Turn Command gives relative, not absolute motions.  Each time it is done, a new motion results. Each time with reference to the current frame. We use the unit quaternions to represent rotations in MathScript, because that makes it easy to work with them algebraically.  A unit quaternion is given by the Quat function whenever we supply an angle t (measured in degrees) and a nonzero 3-vector N.  So Quat( t, N ) is one of the two quaternions that represents the rotation about the unit vector N through t degrees, where the rotation is calculated using the right-hand rule: point your right thumb in the N direction, and the fingers curl in the direction of turning.  The representation is via the adjoint action of the Lie Group S3 on its Lie Algebra (good old R3). You may, of course enter the quaternion as a 4-tuple:

[t, u, v, w ] which is interpreted as:  t*1 + u*i + v*j + w*k.

            Turn takes a single argument, a unit quaternion 4-vector of form: [t,x,y,z]  Usually it is obtained as the return value of the quat() function.  If for example, you type:

turn quat(<angle>, [<n1>,<n2>,<n3>]);

the scene will be rotated about the vector:  [ <n1>, <n2>, <n3> ]  (which is automatically normalized) through <angle> degrees, using the right-hand rule to determine the sense.

Initially, these will coincide with the global background coordinates ("the fixed stars").  Each new Turn command is applied last to the sequence of motions that rotate the scene.  Obviously,  the order of commands is important.

The Turn command accepts products of unit quaternions as argument.  . 

If we say, for example:

Make u quat(30, [1,0,0]);

Make v quat(30, [0,1,0]);

 then the setup frame  is affected in predictable ways by the commands:

Turn u;

Turn v;

But try

Turn u*v;

 and then

Turn v*u:  

Note:  In the Turn Command, quaternions are composed from left to right under multiplication. 

That is:

Turn u*v

means:  First turn u, then turn v.

The amount of turn is of course determined by the angle supplied.

It is easy to see these things if you execute:

Turn u;   then

Turn v;

and then do Turn v*u all at once.

Note:  The commands that rotate actors (Spin, SpinShift, ShiftSpin) use quaternions in the opposite way.  The reason for this is that the latter commands must commute with Turn (and Move) if the motion is to appear narural.

This is the active transformation. We now move to the Camera rotations.

Flying transformations (moving the camera):

            When you select "move the camera," the Turn Command is like "turning your head".  The axis of rotation now passes through the "camera," imaginary though it may be.

All global transformations are done with respect to that origin.  For example, all global (pure) rotations leave the camera fixed.  And the solid frustum is projected on the graph3D window.