Orientation Use Examples

Orientation is important for directional objects. Several practical examples are explored here to illustrate use of different orientation mode. These examples only display 2D scenarios and set Z axis as vertical upward by default.

Orientation has absolute value and relative value respectively, similar to position and velocity. The default relative value is [(1,0,0),(0,1,0),(0,0,1)]. You can modify the relative orientation value by using MovableObject.fixOrientation(newOrientation).

Example 1: Single Movable Object

In this example, we only consider one movable object in the Emu world.

By default, the orientation mode of this object is OM_VELOCITY.
Suppose this object is stationary at position A. The absolute orientation of this object is showed in Figure 1.1. Notice the arrow represents the X axis of the orientation.

We design a path for this object: A - B - C - A.
The object follows this path and stops at position A eventually. As the orientation mode is OM_VELOCITY, the orientation is changed when the object changes velocity.
The absolute orientation of this object is showed in Figure 1.2.
Notice that when the object stops at A, its orientation is different from the one it starts from A. This is because the last non-zero velocity is used for orientation computation in OM_VELOCITY mode.

We can check the orientation of this node by using MovableObject.getAbsOrientation().
This method call will return the absolute orientation of this object.

The relative orientation value in previous scenarios is the same as the one by default. Now, suppose we need to fix the orientation orthogonal to velocity (eg. counterclockwise) all the time. The relative orientation value is changed by using MovableObject.fixOrientation(newOrientation). The newOrientation is the relative orientation value.
In this case, the newOrientation value should be[(0,1,0),(-1,0,0),(0,0,1)].

We repeat the same path A - B - C - A and display the absolute orientation value again in Figure 1.3.

In this example, we only have one Movable object in the Emu World. Thus this object does not have parents. However, we can still set its orientation in OM_PARENT.
In this case, the parent of this object is NULL. Its absolute orientation value is same as the relative value.
For example, we change the orientation of this object to be OM_PARENT, and set it relative value to be newOrientation([(0,1,0),(-1,0,0),(0,0,1)]):
MovableObject.setOrientationMode(OM_PARENT);
MovableObject.fixOrientation(newOrientation);
We start the same path again. The absolute orientation keeps the same as showed in Figure 1.3.

Example 2: Multiple stationary Objects

This examle consider more than one movable objects in the Emu World. One simple and practical scenario to start with is having one node and one directional Antenna attached to the node.
We keep all the movable objects stationary in this example, and those moving cases will be explored in Example 3.
Suppose we have node equipped with directional antenna as its child. Both of them are movable objects. It would be interesting to explore the proper way to adjust the Antenna's orientation as you need.
Table 2.1 summarizes the parent↔ child relationship for different orientationMode.

Node orientationMode Antenna orientationMode Parent↔Child Pair in node node/antenna Parent↔Child Pair Parent↔Child Pair1 in antenna
Case 1OM_VELOCITYOM_VELOCITY node.dirOrientation ↔ node.orientationnode.orientation ↔ antenna.dirOrientation; antenna.dirOrientation ↔ antenna.orientation
Case 2OM_VELOCITYOM_PARENT node.dirOrientation ↔ node.orientationnode.orientation ↔ antenna.orientation;
Case 3OM_PARENTOM_VELOCITY node.orientation ↔ antenna.dirOrientation; antenna.dirOrientation ↔ antenna.orientation
Case 4OM_PARENTOM_PARENT node.orientation ↔ antenna.orientation;
Table 2.1 Parent↔ Child Pairs For Different Orientation Mode

The dirOrientation is also a spatial attribute of Movable Object which computes the object's relative orientation from its relative velocity in its parent's reference frame.
Again, the last non-zero velocity is used when the object is stationary. Thus all dirOrientations have the same value as default.

Remember that dirOrientation are fixed to be default value since all objects are stationary in this example.

In each case, only node.orientation contributes to the absolute value of node's orientation.
Thus we can use node.fixOrientation(newOrientation) to change the node's absolute orientation.
For the antenna, changes in relative orientation of node (node.orientation) and antenna (antenna.orientation) have impact on antenna's absolute orientation.
Therefore, we need to account both node.fixOrientation() and antenna.fixOrientation for anntena's orientation.

As an example, we show the change in orientation when we call following methods.
The newOrientation is still set as [(0,1,0),(-1,0,0),(0,0,1)].

1. antenna.orientationMode(OM_PARENT);
By default, the node is in OM_VELOCITY mode. This scenario falls into Case 2. See Figure 2.1

2. antenna.fixOrientation(newOrientation);
change the relative orientation value of antenna, referring to the node's frame. See Figure 2.2
3. node.fixOrientation(newOrientation);
change the orientation value of node, referring to its own frame as discussed in Example 1. See Figure 2.3

Example 3: Multiple Moving Objects

This example is similar to Example 2, in addition to here is the moving node.
However, this is the basic scenario for directional antenna and illustrates the most common usage.

Unlike previeus examples, we discuss how to meet the requirements in three scenarios.

Referring to Case 3 and Case 4 in Table 2.1, the antenna.dirOrientation is only difference between OM_PARENT and OM_VELOCITY for antenna. Usually we can assume that the antenna is fixed to the node thus the relative velocity and position value of antenna are zero all the time.
So the antenna's orientation mode does not matter here.

Scenario 1: The antenna's absolute orientation should "point" in the direction that the node is moving.
The orientation depends on the node's velocity in this scenario. Thus we should set node's orientation mode as OM_VELOCITY, which is the same as default.
node.setOrientationMode(OM_VELOCITY);

Scenario 2: Need a fixed angle between antenna's absolute orientation and the direction that the node is moving.
Set the node's orientation mode as OM_VELOCITY, and rotate the antenna:
node.setOrientationMode(OM_VELOCITY);
antenna.fixOrientation(newOrientation);

Scenario 3: The absolute antenna orientation should "point" to a particular point A.
This is tricky since the absolute value is changing all the time. We need to update the orientation periodically.
We provide an example that achieves this goal. User needs to implement the computeOrientation method. node.setOrientationMode(OM_PARENT);
WHILE(TRUE){
WHILE(!TIME_OUT){};
newOrientation = computeOrientation(antenna.getAbsPosition(),pointA);
antenna.fixOrientation(newOrientation);
START timer;
}

Points:
1. Basically, MovableObject.fixOrientation() changes the relative orientation value, which is independent of other spacial attributes (such as velocity and position).