org.instantreality.InstantIO
Class Rotation

java.lang.Object
  org.instantreality.InstantIO.Rotation

public class Rotation
extends java.lang.Object

Helper class for exchanging Rotations/Orientations.

Rotation is a basic helper class for exchanging rotations resp. orientations between different software components. It does not contain any means for rotation arithmetics, only methods for setting and getting the rotation. It is not meant to be used directly by software components for rotation representation. Instead, software components should use their own, appropriate classes for handling rotations. Only when sending rotations to an OutSlot, or when receiving rotations from an InSlot, the internal representation of rotations should be converted to Rotation's. This ensures the interoperability between different software components that use different internal representations for rotations.

Rotations are internally stored as quaternions. You can access these quaternions directly, or you can use methods that convert a rotation axis and a rotation angle to and from the quaternions.

The following example creates a Rotation object that represents a rotation of 90 degrees around the y axis, and prints its quaternion components to the console:

 Rotation rot = new Rotation(new Vec3f(0.0f, 1.0f, 0.0f), (float)(90.0 / 180.0 * Math.PI));
 System.out.println("q1 component = " + rot.getQ1());
 System.out.println("q2 component = " + rot.getQ2());
 System.out.println("q3 component = " + rot.getQ3());
 System.out.println("q4 component = " + rot.getQ4());
 

Author:

Patrick Dähne

Field Summary

static Rotation

NULL The null rotation <0,0,0,0>.

Constructor Summary

Rotation(float[] quat)
Constructor that initializes the Rotation with the values of a given float array.

Rotation(float q1, float q2, float q3, float q4)
Constructor that initializes the Rotation with the given quaternions.

Rotation(Rotation rot)
Constructor that initializes the Rotation with another Rotation object.

Rotation(Vec3f axis, float angle)
Constructor that initializes the Rotation with a rotation axis and a rotation angle.

Method Summary

boolean	equals(java.lang.Object obj) Compares the rotation to another object.
void	get(float[] quat) Returns the quaternions of the rotation.
float	getAngle() Returns the rotation angle.
Vec3f	getAxis() Returns the rotation axis.
float	getQ1() Returns the first quaternion of the rotation.
float	getQ2() Returns the second quaternion of the rotation.
float	getQ3() Returns the third quaternion of the rotation.
float	getQ4() Returns the fourth quaternion of the rotation.
java.lang.String	toString() Converts the rotation to a string.
static Rotation	valueOf(java.lang.String str) Converts a string to a Rotation object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NULL

public static final Rotation NULL

The null rotation <0,0,0,0>.

Constructor Detail

Rotation

public Rotation(float q1,
                float q2,
                float q3,
                float q4)

Constructor that initializes the Rotation with the given quaternions.

Parameters:

q1 - The first quaternion

q2 - The second quaternion

q3 - The third quaternion

q4 - The fourth quaternion

Rotation

public Rotation(float[] quat)

Constructor that initializes the Rotation with the values of a given float array.

Parameters:

quat - An array of at least four float values. The first four values must contain the quaternions that specify the rotation.

Rotation

public Rotation(Rotation rot)

Constructor that initializes the Rotation with another Rotation object.

The following example demonstrates how to create a Rotation object that is an exact copy of another Rotation object:

 Rotation given_rotation = ...;
 Rotation rotation = new Rotation(given_rotation);
 

Parameters:

rot - The other Rotation object used to initialize this Rotation object.

Rotation

public Rotation(Vec3f axis,
                float angle)

Constructor that initializes the Rotation with a rotation axis and a rotation angle.

The following example creates a Rotation object that represents a rotation of 90 degrees around the y axis:

 Vec3f axis = new Vec3f(0.0f, 1.0f, 0.0f);
 float angle = (float)(90.0 / 180.0 * Math.PI);
 Rotation rot = new Rotation(axis, angle);
 

Parameters:

axis - The rotation axis

angle - The rotation angle in radians

Method Detail

getQ1

public final float getQ1()

Returns the first quaternion of the rotation.

The following example demonstrates how to print the first quaternion of a Rotation object to the console:

 Rotation rot = ...;
 System.out.println("q1 component = " + rot.getQ1());
 

Returns:

The first quaternion.

getQ2

public final float getQ2()

Returns the second quaternion of the rotation.

The following example demonstrates how to print the second quaternion of a Rotation object to the console:

 Rotation rot = ...;
 System.out.println("q2 component = " + rot.getQ2());
 

Returns:

The second quaternion.

getQ3

public final float getQ3()

Returns the third quaternion of the rotation.

The following example demonstrates how to print the third quaternion of a Rotation object to the console:

 Rotation rot = ...;
 System.out.println("q3 component = " + rot.getQ3());
 

Returns:

The third quaternion.

getQ4

public final float getQ4()

Returns the fourth quaternion of the rotation.

The following example demonstrates how to print the fourth quaternion of a Rotation object to the console:

 Rotation rot = ...;
 System.out.println("q4 component = " + rot.getQ4());
 

Returns:

The fourth quaternion.

get

public final void get(float[] quat)

Returns the quaternions of the rotation.

The following example prints the components of a Rotation object to the console:

 Rotation rot = ...;
 float[] rotation_components = new float[4];
 rot.get(rotation_components);
 System.out.println("q1 component = " + rotation_components[0]);
 System.out.println("q2 component = " + rotation_components[1]);
 System.out.println("q3 component = " + rotation_components[2]);
 System.out.println("q4 component = " + rotation_components[3]);
 

Parameters:

quat - An array of at least four float values that gets filled with the quaternions of the rotation.

getAxis

public final Vec3f getAxis()

Returns the rotation axis.

The following example prints the rotation axis to the console:

 Rotation rot = ...;
 Vec3f axis = rot.getAxis();
 System.out.println("Rotation axis = " + axis);
 

Returns:

The rotation axis.

getAngle

public final float getAngle()

Returns the rotation angle.

The following example prints the rotation angle to the console:

 Rotation rot = ...;
 float angle = (float)(rot.getAngle() * 180.0 / Math.PI);
 System.out.println("Rotation angle = " + angle);
 

Returns:

The rotation angle in radians.

equals

public final boolean equals(java.lang.Object obj)

Compares the rotation to another object. The result is true if the object is not null and is a Rotation object and the quaternions of the other Rotation object are the same as the quaternions of this rotation.

The following example compares two rotations and prints the result to the console:

 Rotation rot1 = ...;
 Rotation rot2 = ...;
 System.out.println("Rotation are the same: " + rot1.equals(rot2));
 

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare the rotation to

Returns:

true when the rotations are equal, false otherwise

toString

public final java.lang.String toString()

Converts the rotation to a string. The string representation consists of the four quaternions, separated by space characters.

The following example prints the string representation of a Rotation object to the console:

 Rotation rot = ...;
 System.out.println("Rotation = " + rot.toString());
 

Overrides:

toString in class java.lang.Object

Returns:

A string representation of the rotation

valueOf

public static final Rotation valueOf(java.lang.String str)

Converts a string to a Rotation object. The string must consist of the four quaternions, separated by space characters.

The following example creates a new Rotation object:

 Rotation rotation = Rotation.valueOf("0.0 0.0 0.0 0.0");
 

Parameters:

str - The string representation of the rotation.

Returns:

The new Rotation object, parsed from the string.