Orientation Tracking

Orientation tracking applies to balls, clumps, and walls. Orientation tracking is enabled with the model orientation-tracking command. For balls and clumps, the orientations may be visualized as an oriented stripe (see the Ball and Clump descriptions for details). For instance, the figures below show the orientations of balls as they roll down an inclined slope.

Figure 1: Initial state of the system.

Figure 2: State of the system after 0.5 s.

Figure 3: State of the system after 0.75 s.

In 2D, the clockwise angular displacement is accumulated and can be accessed or set via the rotation keyword given with the ball attribute, clump attribute, and wall attribute commands. This quantity can also be accessed via the ball.rotation, clump.rotation, and wall.rotation FISH functions.

In 3D, a quaternion is stored and updated whenever the bodies rotate. One can access or set the orientation of each body via Euler angles following the X,Y,Z convention (e.g., rotation about the x-axis followed by rotation about the y’-axis followed by rotation about the z’‘-axis) with the euler keyword of the ball attribute, clump attribute, and wall attribute commands. This quantity can also be accessed via the ball.euler, clump.euler, and wall.euler FISH functions. The following math utilities are provided to assist with the manipulation of the Euler angles: math.aangle.to.euler, math.euler.to.aangle, matrix.from.euler, and matrix.to.euler.