History: Euler Angle Class Mogre
Source of version: 22 (current)
Copy to clipboard
__The Euler class allows you to directly set/get absolute pitch, yaw or roll values without affecting each other__, for example setting the orientation to face east while preserving the pitch and roll.
Further information you find on the ((Euler Angle Class)) page.
It contains an elaborate description, an API reference and examples.
{maketoc}
!.NET Port of Euler Angle Class
The following code is a C# port of the Euler Angle Class for usage with ((Mogre)). Also a VB code is available (created by a converter).
%help% If you have problems, report it in this [http://www.ogre3d.org/addonforums/viewtopic.php?f=8&t=29262|forum topic].
Thanks to user Kojack for the C++ class and the C# port. (published in 2012)
!!Differences to the C++ version
There are several changes to make it follow the style of Mogre instead of Ogre.
* Methods use pascal case (eg. LimitYaw) instead of camel case (eg. limitYaw).
* The methods __getYaw()__, __setYaw()__, __getPitch()__, __setPitch()__, __getRoll()__ and __setRoll()__ are replaced by the properties __Yaw__, __Pitch__ and __Roll__.
* The methods __yaw__, __pitch__ and __roll__ are replaced by __AddYaw()__, __AddPitch()__ and __AddRoll()__.
* The methods __GetForward()__, __GetRight()__ and __GetUp()__ are replaced with the properties __Forward__, __Right__ and __Up__ (read only).
* Chaining is currently removed, because methods don't return a self reference.
* Created XML documentation for all members and parameters (including modified and additional text)
* Renamed some parameter names (y, p, r,v, lhs, ...) for a better overview
* new constructor: public __Euler(Quaternion oriantation)__
* new: public String __ToAxisString()__
* new: public String __ToYawPitchRollString()__
* new: public static Euler __ParseStringYawPitchRoll(__String valueString__)__ ... NOT TESTED
* new: public static Euler __ParseStringAxisXYZ(__String valueString__)__ ... NOT TESTED
* new helper: private static Single[] __Parse3Params(__String valueString__)__ ... NOT TESTED
* new: Overloaded versions of __AddYaw()__, __AddPitch()__, __AddRoll()__ for parameter type Degree
* new: Embedded helper method __Matrix3ToEulerAnglesYXZ()__ as workaround for the buggy method ''Mogre.Matrix3.ToEulerAnglesYXZ()''. %beginsmall%(The Mogre source code is fixed now, but older binaries still contain the "NaN bug". The helper method is used by the Euler constuctor with a Quaternion as parameter.)%endsmall%
!!Further notes
The __output__ value range (co-domain) of the Euler class is:
{CODE(wrap="1", colors="c#")}
Yaw -180 .. 180
Pitch -89.99 .. 89.99
Roll -180 .. 180 {CODE}
__Be distrustfully__ when __Pitch = +/- 90__. (((-Gimbal Lock|Gimbal Lock)) case)
In this case the Pitch value is correct, but the returned Yaw and Roll values can be wrong.
%info% __The best is to keep Pitch in the range -89.99 up to +89.99 degree. __ For lower/higher values it could work fine, but also could cause a "180 degree flip" of axes.
!!Testing
A __code snippet for tests__ you find in [http://www.ogre3d.org/addonforums/viewtopic.php?p=98163#p98163|this forum post]. You can modify it for your custom test cases. Perhaps it's useful for somebody.
Description:
{CODE(wrap="1")}
To check the result of the Euler class this method uses these conversion steps:
EulerAngles --> Quaternion --> EulerClass --> EulerAngles
Then the input angles and output angles will be compared.
{CODE}
!Source code C#
Source: http://www.ogre3d.org/addonforums/viewtopic.php?p=98163#p98163 (23th January 2012)
{CODE(wrap="1", colors="c#")}
using System;
using System.Collections.Generic;
using System.Text;
using System.Text.RegularExpressions;
using Mogre;
using Math = Mogre.Math;
namespace MogreEulerAngles
{
// ABOUT THIS CODE:
//
// Developed by user Kojack in January 2012
// Extended by Beauty and Tubulii
//
// Detailed information about usage:
// http://www.ogre3d.org/tikiwiki/Euler+Angle+Class
//
// "official place" of C# version:
// http://www.ogre3d.org/tikiwiki/Euler+Angle+Class+Mogre
//
// For questions and bug reports use this forum topic:
// viewtopic.php?f=8&t=29262
//
/// <summary>
/// This struct manages rotations by use of Euler Angles.
/// The rotation will be applied in the order Yaw-Pitch-Roll, which are related to the axis order Y-X-Z.
/// It's fully compatible with Ogre::Matrix3::FromEulerAnglesYXZ and Ogre::Matrix3::ToEulerAnglesYXZ.
/// For the Yaw angle the standard anticlockwise right handed rotation is used (as common in Ogre).
/// The Yaw-Pitch-Roll ordering is most convenient for upright character controllers and cameras.
/// </summary>
public struct Euler
{
/// <summary>Get or set the Yaw angle.</summary>
public Radian Yaw
{
get { return mYaw; }
set
{
mYaw = value;
mChanged = true;
}
}
/// <summary>Get or set the Pitch angle.</summary>
public Radian Pitch
{
get { return mPitch; }
set
{
mPitch = value;
mChanged = true;
}
}
/// <summary>Get or set the Roll angle.</summary>
public Radian Roll
{
get { return mRoll; }
set
{
mRoll = value;
mChanged = true;
}
}
/// <summary>
/// Constructor to create a new Euler Angle struct from angle values.
/// The rotation will be applied in the order Yaw-Pitch- Roll, which are related to the axis order Y-X-Z.
/// </summary>
public Euler(Radian yaw, Radian pitch, Radian roll)
{
mYaw = yaw;
mPitch = pitch;
mRoll = roll;
mChanged = true;
mCachedQuaternion = Quaternion.IDENTITY;
}
/// <summary>
/// Constructor which calculates the Euler Angles from a quaternion.
/// </summary>
public Euler(Quaternion oriantation)
{
Matrix3 rotMat;
rotMat = oriantation.ToRotationMatrix();
// BUGGY METHOD (NaN return in some cases)
// rotMat.ToEulerAnglesYXZ(out mYaw, out mPitch, out mRoll);
// WORKAROUND
Boolean isUnique;
Matrix3ToEulerAnglesYXZ(rotMat, out mYaw, out mPitch, out mRoll, out isUnique);
mChanged = true;
mCachedQuaternion = Quaternion.IDENTITY;
}
/// <summary>
/// Apply a relative yaw. (Adds the angle to the current yaw value)
/// </summary>
/// <param name="yaw">Yaw value as radian</param>
public void AddYaw(Radian yaw)
{
mYaw += yaw;
mChanged = true;
}
/// <summary>
/// Apply a relative pitch. (Adds the angle to the current pitch value)
/// </summary>
/// <param name="pitch">Pitch value as radian</param>
public void AddPitch(Radian pitch)
{
mPitch += pitch;
mChanged = true;
}
/// <summary>
/// Apply a relative roll. (Adds the angle to the current roll value)
/// </summary>
/// <param name="roll">Roll value as radian</param>
public void AddRoll(Radian roll)
{
mRoll += roll;
mChanged = true;
}
/// <summary>
/// Apply a relative yaw. (Adds the angle to the current yaw value)
/// </summary>
/// <param name="yaw">Yaw value as degree</param>
public void AddYaw(Degree yaw)
{
mYaw += yaw;
mChanged = true;
}
/// <summary>
/// Apply a relative pitch. (Adds the angle to the current pitch value)
/// </summary>
/// <param name="pitch">Pitch value as degree</param>
public void AddPitch(Degree pitch)
{
mPitch += pitch;
mChanged = true;
}
/// <summary>
/// Apply a relative roll. (Adds the angle to the current roll value)
/// </summary>
/// <param name="roll">Roll value as degree</param>
public void AddRoll(Degree roll)
{
mRoll += roll;
mChanged = true;
}
/// <summary>Get a vector pointing forwards. </summary>
public Vector3 Forward
{
get { return ToQuaternion() * Vector3.NEGATIVE_UNIT_Z; }
}
/// <summary>Get a vector pointing to the right.</summary>
public Vector3 Right
{
get { return ToQuaternion() * Vector3.UNIT_X; }
}
/// <summary> Get a vector pointing up.</summary>
public Vector3 Up
{
get { return ToQuaternion() * Vector3.UNIT_Y; }
}
/// <summary>
/// Calculate the quaternion of the euler object.
/// The result is cached. It will only be recalculated when the component euler angles are changed.
/// </summary>
public Quaternion ToQuaternion()
{
if(mChanged)
{
mCachedQuaternion = new Quaternion(mYaw, Vector3.UNIT_Y) * new Quaternion(mPitch, Vector3.UNIT_X) * new Quaternion(mRoll, Vector3.UNIT_Z);
mChanged = false;
}
return mCachedQuaternion;
}
/// <summary>
/// Return a String with degree values of the axis rotations (human readable style).
/// For example "X-axis: 0° Y-axis: 36° Z-axis: 90°"
/// </summary>
public String ToAxisString()
{
return String.Format("X: {0:00}° Y: {1:00}° Z: {2:00}°",
Pitch.ValueDegrees, Yaw.ValueDegrees, Roll.ValueDegrees);
}
/// <summary>
/// Return a String with degree values in the applied rotation order (human readable style).
/// For example "Yaw: 0° Pitch: 36° Roll: 90°"
/// </summary>
public String ToYawPitchRollString()
{
return String.Format("Yaw: {0:00}° Pitch: {1:00}° Roll: {2:00}°",
Yaw.ValueDegrees, Pitch.ValueDegrees, Roll.ValueDegrees);
}
/// <summary>
/// Try to parse 3 floating point values from a string, which are seperated by spaces or tabulators.
/// Input order for rotation values:: Yaw, Pitch, Roll (all in degree)
/// If success, an Euler struct will be returned.
/// If parsing failed, a FormatException will be thrown.
/// Example: "111 .99 -66"
/// </summary>
/// <param name="valueString">String which contains 3 floating point values</param>
/// <remarks>
/// Multiple and mixed usage of space/tabulator/commas are possible.
/// As decimal seperator a dot "." is expected.
/// </remarks>
/// <returns>Returns an Euler struct or a FormatException</returns>
public static Euler ParseStringYawPitchRoll(String valueString)
{
Single[] values = Parse3Params(valueString);
if (values == null)
throw new FormatException(String.Format("Can't parse floating point values of string '{0}'", valueString));
return new Euler(new Degree(values[0]), new Degree(values[1]), new Degree(values[2]));
}
/// <summary>
/// Try to parse 3 floating point values from a string, which are seperated by spaces or tabulators or comma.
/// Input order for rotation values: X-axis, Y-axis, Z-axis (all in degree)
/// If success, an Euler struct will be returned.
/// If parsing failed, a FormatException will be thrown.
/// Example: "111 .99 -66"
/// </summary>
/// <param name="valueString">String which contains 3 floating point values</param>
/// <remarks>
/// Multiple and mixed usage of space/tabulator/commas are possible.
/// As decimal seperator a dot "." is expected.
/// </remarks>
/// <returns>Returns an Euler struct or a FormatException</returns>
public static Euler ParseStringAxisXYZ(String valueString)
{
Single[] values = Parse3Params(valueString);
if (values == null)
throw new FormatException(String.Format("Can't parse floating point values of string '{0}'", valueString));
return new Euler(new Degree(values[1]), new Degree(values[0]), new Degree(values[2]));
}
/// <summary>
/// Try to parse 3 floating point values from a string, which are seperated by spaces or tabulators or comma.
/// If parsing failed, null will be returned.
/// Example: "111 .99 -66"
/// </summary>
/// <param name="valueString">String which contains 3 floating point values</param>
/// <remarks>
/// Multiple and mixed usage of space/tabulator/commas are possible.
/// As decimal seperator a dot "." is expected.
/// </remarks>
/// <returns>Returns 3 Single values or null</returns>
private static Single[] Parse3Params(String valueString)
{
// Some Regex explanation:
//
// The "@" prefix in front of the String means:
// Backslash are processed as Text instead of special symbols.
// Advantage: Just write "\" instead of "\\" for each backslash
//
// "^" at first position means: No text is allowed before
// "$" at the end means: No text is allowed after that
//
// Floating point values are matched
// Expression: "-?\d*\.?\d+"
// Examples: "111", "0.111", ".99", "-66"
//
// Seperator can be tabs or spaces or commas (at least one symbol; mixing is possible)
// Expression: "[, \t]+"
String val = @"[-\d\.]+"; // simplified (faster) floating point pattern (exact pattern would be @"-?\d*\.?\d+" )
String sep = @"[, \t]+"; // seperator pattern
// build target pattern
String searchPattern = "^(" + val + ")" + sep + "(" + val + ")" + sep + "(" + val + ")$";
Match match = Regex.Match(valueString, searchPattern);
try
{
if (match.Success)
{
// Force to parse "." as decimal char. (Can be different with other culture settings. E.g. German culture expect "," instad of ".")
System.Globalization.CultureInfo englishCulture = new System.Globalization.CultureInfo("en-US");
Single[] result = new Single[3];
result[0] = Convert.ToSingle(match.Groups[1].Value, englishCulture);
result[1] = Convert.ToSingle(match.Groups[2].Value, englishCulture);
result[2] = Convert.ToSingle(match.Groups[3].Value, englishCulture);
return result;
}
else
return null;
}
catch (FormatException) { return null; }
catch (OverflowException) { return null; }
} // Parse3Params()
/// <summary>
/// Return the Euler rotation state as quaternion.
/// </summary>
/// <param name="e">Euler Angle state</param>
/// <returns>Rotation state as Quaternion</returns>
public static implicit operator Quaternion(Euler e)
{
return e.ToQuaternion();
}
/// <summary>
/// Set the yaw and pitch to face in the given direction.
/// The direction doesn't need to be normalised.
/// Roll is always unaffected.
/// </summary>
/// <param name="directionVector">Vector which points to the wanted direction</param>
/// <param name="setYaw">if false, the yaw isn't changed.</param>
/// <param name="setPitch">if false, the pitch isn't changed.</param>
public void SetDirection(Vector3 directionVector, Boolean setYaw, Boolean setPitch)
{
Vector3 d = directionVector.NormalisedCopy;
if(setPitch)
mPitch = Math.ASin(d.y);
if(setYaw)
mYaw = Math.ATan2(-d.x, -d.z);//+Math.PI/2.0;
mChanged = setYaw || setPitch;
}
/// <summary>
/// Normalise the selected rotations to be within the +/-180 degree range.
/// The normalise uses a wrap around, so for example a yaw of 360 degrees becomes 0 degrees,
/// and -190 degrees becomes 170.
/// By the parameters it's possible to choose which angles should be normalised.
/// </summary>
/// <param name="normYaw">If true, the angle will be normalised.</param>
/// <param name="normPitch">If true, the angle will be normalised.</param>
/// <param name="normRoll">If true, the angle will be normalised.</param>
/// <remarks></remarks>
public void Normalise(Boolean normYaw, Boolean normPitch, Boolean normRoll)
{
if(normYaw)
{
Single yaw = mYaw.ValueRadians;
if(yaw < -Math.PI)
{
yaw = (Single)System.Math.IEEERemainder(yaw, Math.PI * 2.0);
if(yaw < -Math.PI)
{
yaw += Math.PI * 2.0f;
}
mYaw = yaw;
mChanged = true;
}
else if(yaw > Math.PI)
{
yaw = (Single)System.Math.IEEERemainder(yaw, Math.PI * 2.0f);
if(yaw > Math.PI)
{
yaw -= Math.PI * 2.0f;
}
mYaw = yaw;
mChanged = true;
}
}
if(normPitch)
{
Single pitch = mPitch.ValueRadians;
if(pitch < -Math.PI)
{
pitch = (Single)System.Math.IEEERemainder(pitch, Math.PI * 2.0f);
if(pitch < -Math.PI)
{
pitch += Math.PI * 2.0f;
}
mPitch = pitch;
mChanged = true;
if (Single.IsNaN(mPitch.ValueDegrees)) // DEBUGGING
{
} // add breakpoint here
}
else if(pitch > Math.PI)
{
pitch = (Single)System.Math.IEEERemainder(pitch, Math.PI * 2.0f);
if(pitch > Math.PI)
{
pitch -= Math.PI * 2.0f;
}
mPitch = pitch;
mChanged = true;
if (Single.IsNaN(mPitch.ValueDegrees)) // DEBUGGING
{
} // add breakpoint here
}
}
if(normRoll)
{
Single roll= mRoll.ValueRadians;
if(roll < -Math.PI)
{
roll = (Single)System.Math.IEEERemainder(roll, Math.PI * 2.0f);
if(roll < -Math.PI)
{
roll += Math.PI * 2.0f;
}
mRoll = roll;
mChanged = true;
}
else if(roll > Math.PI)
{
roll = (Single)System.Math.IEEERemainder(roll, Math.PI * 2.0f);
if(roll > Math.PI)
{
roll -= Math.PI * 2.0f;
}
mRoll = roll;
mChanged = true;
}
}
} // Normalise()
/// <summary>
/// Return the relative euler angles required to rotate from the current forward direction to the specified direction vector.
/// The result euler can then be added to the current euler to immediately face dir.
/// Rotation is found to face the correct direction. For example, when false a yaw of 1000 degrees and a dir of
/// (0,0,-1) will return a -1000 degree yaw. When true, the same yaw and dir would give 80 degrees (1080 degrees faces
/// the same way as (0,0,-1).
/// The rotation won't flip upside down then roll instead of a 180 degree yaw.
/// </summary>
/// <param name="direction">...TODO...</param>
/// <param name="shortest">If false, the full value of each angle is used. If true, the angles are normalised and the shortest rotation is found to face the correct direction.</param>
/// <param name="setYaw">If true the angles are calculated. If false, the angle is set to 0. </param>
/// <param name="setPitch">If true the angles are calculated. If false, the angle is set to 0. </param>
public Euler GetRotationTo(Vector3 direction, Boolean setYaw, Boolean setPitch, Boolean shortest)
{
Euler t1 = Euler.IDENTITY;
Euler t2;
t1.SetDirection(direction, setYaw, setPitch);
t2 = t1 - this;
if(shortest && setYaw)
{
t2.Normalise(true, true, true);
}
return t2;
}
/// <summary>
/// Clamp the yaw angle to a range of +/-limit.
/// </summary>
/// <param name="limit">Wanted co-domain for the Yaw angle.</param>
public void LimitYaw(Radian limit)
{
if (mYaw > limit)
{
mYaw = limit;
mChanged = true;
}
else if (mYaw < -limit)
{
mYaw = -limit;
mChanged = true;
}
}
/// <summary>
/// Clamp the pitch angle to a range of +/-limit.
/// </summary>
/// <param name="limit">Wanted co-domain for the Pitch angle.</param>
public void LimitPitch(Radian limit)
{
if (mPitch > limit)
{
mPitch = limit;
mChanged = true;
}
else if (mPitch < -limit)
{
mPitch = -limit;
mChanged = true;
}
}
/// <summary>
/// Clamp the roll angle to a range of +/-limit.
/// </summary>
/// <param name="limit">Wanted co-domain for the Roll angle.</param>
public void LimitRoll(Radian limit)
{
if (mRoll > limit)
{
mRoll = limit;
mChanged = true;
}
else if (mRoll < -limit)
{
mRoll = -limit;
mChanged = true;
}
}
/// <summary>
/// Port of method <c>Matrix3.ToEulerAnglesYXZ()</c>, from MogreMatrix3.cpp as a workaround for a bug in the Math class.
/// (The bug was fixed, but is not present in common used binary files.)
/// </summary>
/// <param name="matrix">Rotation matrix</param>
/// <param name="isUnique">If false, the orientation can be described by different angle combinations.
/// In this case the returned angle values can be different than expected.</param>
public static void Matrix3ToEulerAnglesYXZ(Matrix3 matrix,
out Radian rfYAngle, out Radian rfPAngle, out Radian rfRAngle, out Boolean isUnique)
{
rfPAngle = Mogre.Math.ASin(-matrix.m12);
if (rfPAngle < new Radian(Math.HALF_PI))
{
if (rfPAngle > new Radian(-Math.HALF_PI))
{
rfYAngle = Math.ATan2(matrix.m02, matrix.m22);
rfRAngle = Math.ATan2(matrix.m10, matrix.m11);
isUnique = true;
return;
}
else
{
// WARNING. Not a unique solution.
Radian fRmY = Math.ATan2(-matrix.m01, matrix.m00);
rfRAngle = new Radian(0f); // any angle works
rfYAngle = rfRAngle - fRmY;
isUnique = false;
return;
}
}
else
{
// WARNING. Not a unique solution.
Radian fRpY = Math.ATan2(-matrix.m01, matrix.m00);
rfRAngle = new Radian(0f); // any angle works
rfYAngle = fRpY - rfRAngle;
isUnique = false;
return;
}
// "Original" CODE FROM CLASS Matrix3.ToEulerAnglesYXZ()
//rfPAngle = Mogre::Math::ASin(-m12);
//if ( rfPAngle < Radian(Math::HALF_PI) )
//{
// if ( rfPAngle > Radian(-Math::HALF_PI) )
// {
// rfYAngle = System::Math::Atan2(m02,m22);
// rfRAngle = System::Math::Atan2(m10,m11);
// return true;
// }
// else
// {
// // WARNING. Not a unique solution.
// Radian fRmY = System::Math::Atan2(-m01,m00);
// rfRAngle = Radian(0.0); // any angle works
// rfYAngle = rfRAngle - fRmY;
// return false;
// }
//}
//else
//{
// // WARNING. Not a unique solution.
// Radian fRpY = System::Math::Atan2(-m01,m00);
// rfRAngle = Radian(0.0); // any angle works
// rfYAngle = fRpY - rfRAngle;
// return false;
//}
} // Matrix3ToEulerAnglesYXZ()
/// <summary>
/// Add two euler objects.
/// </summary>
/// <returns>Calculation result</returns>
public static Euler operator +(Euler lhs, Euler rhs)
{
return new Euler(lhs.Yaw + rhs.Yaw, lhs.Pitch + rhs.Pitch, lhs.Roll + rhs.Roll);
}
/// <summary>
/// Subtract two euler objects. This finds the difference as relative angles.
/// </summary>
/// <returns>Calculation result</returns>
public static Euler operator-(Euler lhs, Euler rhs)
{
return new Euler(lhs.Yaw - rhs.Yaw, lhs.Pitch - rhs.Pitch, lhs.Roll - rhs.Roll);
}
/// <summary>
/// Interpolate each euler angle by the given factor.
/// (Each angle will be multiplied with the factor.)
/// </summary>
/// <returns>Calculation result</returns>
public static Euler operator *(Euler lhs, Single factor)
{
return new Euler(lhs.Yaw * factor, lhs.Pitch * factor, lhs.Roll * factor);
}
/// <summary>
/// Interpolate the euler angles by lhs.
/// (Each angle will be multiplied with the factor.)
/// </summary>
/// <returns>Calculation result</returns>
public static Euler operator *(Single factor, Euler rhs)
{
return new Euler(factor * rhs.Yaw, factor * rhs.Pitch, factor * rhs.Roll);
}
/// <summary>
/// Apply the euler rotation to the vector rhs.
/// The calculation is equal to: quaternion*vector
/// </summary>
/// <returns>Calculation result</returns>
public static Vector3 operator *(Euler lhs, Vector3 rhs)
{
return lhs.ToQuaternion() * rhs;
}
/// <summary>Base settings (all angles are 0)</summary>
public static Euler IDENTITY = new Euler(new Radian(0), new Radian(0), new Radian(0));
/// <summary>Rotation around the Y axis.</summary>
private Radian mYaw;
/// <summary>Rotation around the X axis.</summary>
private Radian mPitch;
/// <summary>Rotation around the Z axis.</summary>
private Radian mRoll;
/// <summary>Is the cached quaternion out of date?</summary>
private bool mChanged;
/// <summary>Cached quaternion equivalent of this euler object.</summary>
private Quaternion mCachedQuaternion;
} // struct Euler
} // namespace
{CODE}
%%%
%%%
!Source code Visual Basic
Converted by [http://www.developerfusion.com/tools/convert/csharp-to-vb|C#<->VB Converter] of developerfusion.com.
In a quick test the converter had no errors. If the VB code really works, wasn't tested yet. (Please give us a report after testing.)
{CODE(wrap="1", colors="vb.net")}
Imports System.Collections.Generic
Imports System.Text
Imports System.Text.RegularExpressions
Imports Mogre
Imports Math = Mogre.Math
Namespace MogreEulerAngles
' ABOUT THIS CODE:
'
' Developed by user Kojack in January 2012
' Extended by Beauty and Tubulii
'
' Detailed information about usage:
' http://www.ogre3d.org/tikiwiki/Euler+Angle+Class
'
' "official place" of C# version:
' http://www.ogre3d.org/tikiwiki/Euler+Angle+Class+Mogre
'
' For questions and bug reports use this forum topic:
' viewtopic.php?f=8&t=29262
'
''' <summary>
''' This struct manages rotations by use of Euler Angles.
''' The rotation will be applied in the order Yaw-Pitch-Roll, which are related to the axis order Y-X-Z.
''' It's fully compatible with Ogre::Matrix3::FromEulerAnglesYXZ and Ogre::Matrix3::ToEulerAnglesYXZ.
''' For the Yaw angle the standard anticlockwise right handed rotation is used (as common in Ogre).
''' The Yaw-Pitch-Roll ordering is most convenient for upright character controllers and cameras.
''' </summary>
Public Structure Euler
''' <summary>Get or set the Yaw angle.</summary>
Public Property Yaw() As Radian
Get
Return mYaw
End Get
Set
mYaw = value
mChanged = True
End Set
End Property
''' <summary>Get or set the Pitch angle.</summary>
Public Property Pitch() As Radian
Get
Return mPitch
End Get
Set
mPitch = value
mChanged = True
End Set
End Property
''' <summary>Get or set the Roll angle.</summary>
Public Property Roll() As Radian
Get
Return mRoll
End Get
Set
mRoll = value
mChanged = True
End Set
End Property
''' <summary>
''' Constructor to create a new Euler Angle struct from angle values.
''' The rotation will be applied in the order Yaw-Pitch- Roll, which are related to the axis order Y-X-Z.
''' </summary>
Public Sub New(yaw As Radian, pitch As Radian, roll As Radian)
mYaw = yaw
mPitch = pitch
mRoll = roll
mChanged = True
mCachedQuaternion = Quaternion.IDENTITY
End Sub
''' <summary>
''' Constructor which calculates the Euler Angles from a quaternion.
''' </summary>
Public Sub New(oriantation As Quaternion)
Dim rotMat As Matrix3
rotMat = oriantation.ToRotationMatrix()
' BUGGY METHOD (NaN return in some cases)
' rotMat.ToEulerAnglesYXZ(out mYaw, out mPitch, out mRoll);
' WORKAROUND
Dim isUnique As [Boolean]
Matrix3ToEulerAnglesYXZ(rotMat, mYaw, mPitch, mRoll, isUnique)
mChanged = True
mCachedQuaternion = Quaternion.IDENTITY
End Sub
''' <summary>
''' Apply a relative yaw. (Adds the angle to the current yaw value)
''' </summary>
''' <param name="yaw">Yaw value as radian</param>
Public Sub AddYaw(yaw As Radian)
mYaw += yaw
mChanged = True
End Sub
''' <summary>
''' Apply a relative pitch. (Adds the angle to the current pitch value)
''' </summary>
''' <param name="pitch">Pitch value as radian</param>
Public Sub AddPitch(pitch As Radian)
mPitch += pitch
mChanged = True
End Sub
''' <summary>
''' Apply a relative roll. (Adds the angle to the current roll value)
''' </summary>
''' <param name="roll">Roll value as radian</param>
Public Sub AddRoll(roll As Radian)
mRoll += roll
mChanged = True
End Sub
''' <summary>
''' Apply a relative yaw. (Adds the angle to the current yaw value)
''' </summary>
''' <param name="yaw">Yaw value as degree</param>
Public Sub AddYaw(yaw As Degree)
mYaw += yaw
mChanged = True
End Sub
''' <summary>
''' Apply a relative pitch. (Adds the angle to the current pitch value)
''' </summary>
''' <param name="pitch">Pitch value as degree</param>
Public Sub AddPitch(pitch As Degree)
mPitch += pitch
mChanged = True
End Sub
''' <summary>
''' Apply a relative roll. (Adds the angle to the current roll value)
''' </summary>
''' <param name="roll">Roll value as degree</param>
Public Sub AddRoll(roll As Degree)
mRoll += roll
mChanged = True
End Sub
''' <summary>Get a vector pointing forwards. </summary>
Public ReadOnly Property Forward() As Vector3
Get
Return ToQuaternion() * Vector3.NEGATIVE_UNIT_Z
End Get
End Property
''' <summary>Get a vector pointing to the right.</summary>
Public ReadOnly Property Right() As Vector3
Get
Return ToQuaternion() * Vector3.UNIT_X
End Get
End Property
''' <summary> Get a vector pointing up.</summary>
Public ReadOnly Property Up() As Vector3
Get
Return ToQuaternion() * Vector3.UNIT_Y
End Get
End Property
''' <summary>
''' Calculate the quaternion of the euler object.
''' The result is cached. It will only be recalculated when the component euler angles are changed.
''' </summary>
Public Function ToQuaternion() As Quaternion
If mChanged Then
mCachedQuaternion = New Quaternion(mYaw, Vector3.UNIT_Y) * New Quaternion(mPitch, Vector3.UNIT_X) * New Quaternion(mRoll, Vector3.UNIT_Z)
mChanged = False
End If
Return mCachedQuaternion
End Function
''' <summary>
''' Return a String with degree values of the axis rotations (human readable style).
''' For example "X-axis: 0° Y-axis: 36° Z-axis: 90°"
''' </summary>
Public Function ToAxisString() As [String]
Return [String].Format("X: {0:00}° Y: {1:00}° Z: {2:00}°", Pitch.ValueDegrees, Yaw.ValueDegrees, Roll.ValueDegrees)
End Function
''' <summary>
''' Return a String with degree values in the applied rotation order (human readable style).
''' For example "Yaw: 0° Pitch: 36° Roll: 90°"
''' </summary>
Public Function ToYawPitchRollString() As [String]
Return [String].Format("Yaw: {0:00}° Pitch: {1:00}° Roll: {2:00}°", Yaw.ValueDegrees, Pitch.ValueDegrees, Roll.ValueDegrees)
End Function
''' <summary>
''' Try to parse 3 floating point values from a string, which are seperated by spaces or tabulators.
''' Input order for rotation values:: Yaw, Pitch, Roll (all in degree)
''' If success, an Euler struct will be returned.
''' If parsing failed, a FormatException will be thrown.
''' Example: "111 .99 -66"
''' </summary>
''' <param name="valueString">String which contains 3 floating point values</param>
''' <remarks>
''' Multiple and mixed usage of space/tabulator/commas are possible.
''' As decimal seperator a dot "." is expected.
''' </remarks>
''' <returns>Returns an Euler struct or a FormatException</returns>
Public Shared Function ParseStringYawPitchRoll(valueString As [String]) As Euler
Dim values As [Single]() = Parse3Params(valueString)
If values Is Nothing Then
Throw New FormatException([String].Format("Can't parse floating point values of string '{0}'", valueString))
End If
Return New Euler(New Degree(values(0)), New Degree(values(1)), New Degree(values(2)))
End Function
''' <summary>
''' Try to parse 3 floating point values from a string, which are seperated by spaces or tabulators or comma.
''' Input order for rotation values: X-axis, Y-axis, Z-axis (all in degree)
''' If success, an Euler struct will be returned.
''' If parsing failed, a FormatException will be thrown.
''' Example: "111 .99 -66"
''' </summary>
''' <param name="valueString">String which contains 3 floating point values</param>
''' <remarks>
''' Multiple and mixed usage of space/tabulator/commas are possible.
''' As decimal seperator a dot "." is expected.
''' </remarks>
''' <returns>Returns an Euler struct or a FormatException</returns>
Public Shared Function ParseStringAxisXYZ(valueString As [String]) As Euler
Dim values As [Single]() = Parse3Params(valueString)
If values Is Nothing Then
Throw New FormatException([String].Format("Can't parse floating point values of string '{0}'", valueString))
End If
Return New Euler(New Degree(values(1)), New Degree(values(0)), New Degree(values(2)))
End Function
''' <summary>
''' Try to parse 3 floating point values from a string, which are seperated by spaces or tabulators or comma.
''' If parsing failed, null will be returned.
''' Example: "111 .99 -66"
''' </summary>
''' <param name="valueString">String which contains 3 floating point values</param>
''' <remarks>
''' Multiple and mixed usage of space/tabulator/commas are possible.
''' As decimal seperator a dot "." is expected.
''' </remarks>
''' <returns>Returns 3 Single values or null</returns>
Private Shared Function Parse3Params(valueString As [String]) As [Single]()
' Some Regex explanation:
'
' The "@" prefix in front of the String means:
' Backslash are processed as Text instead of special symbols.
' Advantage: Just write "\" instead of "\\" for each backslash
'
' "^" at first position means: No text is allowed before
' "$" at the end means: No text is allowed after that
'
' Floating point values are matched
' Expression: "-?\d*\.?\d+"
' Examples: "111", "0.111", ".99", "-66"
'
' Seperator can be tabs or spaces or commas (at least one symbol; mixing is possible)
' Expression: "[, \t]+"
Dim val As [String] = "[-\d\.]+"
' simplified (faster) floating point pattern (exact pattern would be @"-?\d*\.?\d+" )
Dim sep As [String] = "[, \t]+"
' seperator pattern
' build target pattern
Dim searchPattern As [String] = "^(" & val & ")" & sep & "(" & val & ")" & sep & "(" & val & ")$"
Dim match As Match = Regex.Match(valueString, searchPattern)
Try
If match.Success Then
' Force to parse "." as decimal char. (Can be different with other culture settings. E.g. German culture expect "," instad of ".")
Dim englishCulture As New System.Globalization.CultureInfo("en-US")
Dim result As [Single]() = New [Single](2) {}
result(0) = Convert.ToSingle(match.Groups(1).Value, englishCulture)
result(1) = Convert.ToSingle(match.Groups(2).Value, englishCulture)
result(2) = Convert.ToSingle(match.Groups(3).Value, englishCulture)
Return result
Else
Return Nothing
End If
Catch generatedExceptionName As FormatException
Return Nothing
Catch generatedExceptionName As OverflowException
Return Nothing
End Try
End Function
' Parse3Params()
''' <summary>
''' Return the Euler rotation state as quaternion.
''' </summary>
''' <param name="e">Euler Angle state</param>
''' <returns>Rotation state as Quaternion</returns>
Public Shared Widening Operator CType(e As Euler) As Quaternion
Return e.ToQuaternion()
End Operator
''' <summary>
''' Set the yaw and pitch to face in the given direction.
''' The direction doesn't need to be normalised.
''' Roll is always unaffected.
''' </summary>
''' <param name="directionVector">Vector which points to the wanted direction</param>
''' <param name="setYaw">if false, the yaw isn't changed.</param>
''' <param name="setPitch">if false, the pitch isn't changed.</param>
Public Sub SetDirection(directionVector As Vector3, setYaw As [Boolean], setPitch As [Boolean])
Dim d As Vector3 = directionVector.NormalisedCopy
If setPitch Then
mPitch = Math.ASin(d.y)
End If
If setYaw Then
mYaw = Math.ATan2(-d.x, -d.z)
End If
'+Math.PI/2.0;
mChanged = setYaw OrElse setPitch
End Sub
''' <summary>
''' Normalise the selected rotations to be within the +/-180 degree range.
''' The normalise uses a wrap around, so for example a yaw of 360 degrees becomes 0 degrees,
''' and -190 degrees becomes 170.
''' By the parameters it's possible to choose which angles should be normalised.
''' </summary>
''' <param name="normYaw">If true, the angle will be normalised.</param>
''' <param name="normPitch">If true, the angle will be normalised.</param>
''' <param name="normRoll">If true, the angle will be normalised.</param>
''' <remarks></remarks>
Public Sub Normalise(normYaw As [Boolean], normPitch As [Boolean], normRoll As [Boolean])
If normYaw Then
Dim yaw As [Single] = mYaw.ValueRadians
If yaw < -Math.PI Then
yaw = CType(System.Math.IEEERemainder(yaw, Math.PI * 2.0), [Single])
If yaw < -Math.PI Then
yaw += Math.PI * 2F
End If
mYaw = yaw
mChanged = True
ElseIf yaw > Math.PI Then
yaw = CType(System.Math.IEEERemainder(yaw, Math.PI * 2F), [Single])
If yaw > Math.PI Then
yaw -= Math.PI * 2F
End If
mYaw = yaw
mChanged = True
End If
End If
If normPitch Then
Dim pitch As [Single] = mPitch.ValueRadians
If pitch < -Math.PI Then
pitch = CType(System.Math.IEEERemainder(pitch, Math.PI * 2F), [Single])
If pitch < -Math.PI Then
pitch += Math.PI * 2F
End If
mPitch = pitch
mChanged = True
If [Single].IsNaN(mPitch.ValueDegrees) Then
' DEBUGGING
' add breakpoint here
End If
ElseIf pitch > Math.PI Then
pitch = CType(System.Math.IEEERemainder(pitch, Math.PI * 2F), [Single])
If pitch > Math.PI Then
pitch -= Math.PI * 2F
End If
mPitch = pitch
mChanged = True
If [Single].IsNaN(mPitch.ValueDegrees) Then
' DEBUGGING
' add breakpoint here
End If
End If
End If
If normRoll Then
Dim roll As [Single] = mRoll.ValueRadians
If roll < -Math.PI Then
roll = CType(System.Math.IEEERemainder(roll, Math.PI * 2F), [Single])
If roll < -Math.PI Then
roll += Math.PI * 2F
End If
mRoll = roll
mChanged = True
ElseIf roll > Math.PI Then
roll = CType(System.Math.IEEERemainder(roll, Math.PI * 2F), [Single])
If roll > Math.PI Then
roll -= Math.PI * 2F
End If
mRoll = roll
mChanged = True
End If
End If
End Sub
' Normalise()
''' <summary>
''' Return the relative euler angles required to rotate from the current forward direction to the specified direction vector.
''' The result euler can then be added to the current euler to immediately face dir.
''' Rotation is found to face the correct direction. For example, when false a yaw of 1000 degrees and a dir of
''' (0,0,-1) will return a -1000 degree yaw. When true, the same yaw and dir would give 80 degrees (1080 degrees faces
''' the same way as (0,0,-1).
''' The rotation won't flip upside down then roll instead of a 180 degree yaw.
''' </summary>
''' <param name="direction">...TODO...</param>
''' <param name="shortest">If false, the full value of each angle is used. If true, the angles are normalised and the shortest rotation is found to face the correct direction.</param>
''' <param name="setYaw">If true the angles are calculated. If false, the angle is set to 0. </param>
''' <param name="setPitch">If true the angles are calculated. If false, the angle is set to 0. </param>
Public Function GetRotationTo(direction As Vector3, setYaw As [Boolean], setPitch As [Boolean], shortest As [Boolean]) As Euler
Dim t1 As Euler = Euler.IDENTITY
Dim t2 As Euler
t1.SetDirection(direction, setYaw, setPitch)
t2 = t1 - Me
If shortest AndAlso setYaw Then
t2.Normalise(True, True, True)
End If
Return t2
End Function
''' <summary>
''' Clamp the yaw angle to a range of +/-limit.
''' </summary>
''' <param name="limit">Wanted co-domain for the Yaw angle.</param>
Public Sub LimitYaw(limit As Radian)
If mYaw > limit Then
mYaw = limit
mChanged = True
ElseIf mYaw < -limit Then
mYaw = -limit
mChanged = True
End If
End Sub
''' <summary>
''' Clamp the pitch angle to a range of +/-limit.
''' </summary>
''' <param name="limit">Wanted co-domain for the Pitch angle.</param>
Public Sub LimitPitch(limit As Radian)
If mPitch > limit Then
mPitch = limit
mChanged = True
ElseIf mPitch < -limit Then
mPitch = -limit
mChanged = True
End If
End Sub
''' <summary>
''' Clamp the roll angle to a range of +/-limit.
''' </summary>
''' <param name="limit">Wanted co-domain for the Roll angle.</param>
Public Sub LimitRoll(limit As Radian)
If mRoll > limit Then
mRoll = limit
mChanged = True
ElseIf mRoll < -limit Then
mRoll = -limit
mChanged = True
End If
End Sub
''' <summary>
''' Port of method <c>Matrix3.ToEulerAnglesYXZ()</c>, from MogreMatrix3.cpp as a workaround for a bug in the Math class.
''' (The bug was fixed, but is not present in common used binary files.)
''' </summary>
''' <param name="matrix">Rotation matrix</param>
''' <param name="isUnique">If false, the orientation can be described by different angle combinations.
''' In this case the returned angle values can be different than expected.</param>
Public Shared Sub Matrix3ToEulerAnglesYXZ(matrix As Matrix3, ByRef rfYAngle As Radian, ByRef rfPAngle As Radian, ByRef rfRAngle As Radian, ByRef success As [Boolean])
rfPAngle = Mogre.Math.ASin(-matrix.m12)
If rfPAngle < New Radian(Math.HALF_PI) Then
If rfPAngle > New Radian(-Math.HALF_PI) Then
rfYAngle = Math.ATan2(matrix.m02, matrix.m22)
rfRAngle = Math.ATan2(matrix.m10, matrix.m11)
success = True
Return
Else
' WARNING. Not a unique solution.
Dim fRmY As Radian = Math.ATan2(-matrix.m01, matrix.m00)
rfRAngle = New Radian(0F)
' any angle works
rfYAngle = rfRAngle - fRmY
success = False
Return
End If
Else
' WARNING. Not a unique solution.
Dim fRpY As Radian = Math.ATan2(-matrix.m01, matrix.m00)
rfRAngle = New Radian(0F)
' any angle works
rfYAngle = fRpY - rfRAngle
success = False
Return
End If
' "Original" CODE FROM CLASS Matrix3.ToEulerAnglesYXZ()
'rfPAngle = Mogre::Math::ASin(-m12);
'if ( rfPAngle < Radian(Math::HALF_PI) )
'{
' if ( rfPAngle > Radian(-Math::HALF_PI) )
' {
' rfYAngle = System::Math::Atan2(m02,m22);
' rfRAngle = System::Math::Atan2(m10,m11);
' return true;
' }
' else
' {
' // WARNING. Not a unique solution.
' Radian fRmY = System::Math::Atan2(-m01,m00);
' rfRAngle = Radian(0.0); // any angle works
' rfYAngle = rfRAngle - fRmY;
' return false;
' }
'}
'else
'{
' // WARNING. Not a unique solution.
' Radian fRpY = System::Math::Atan2(-m01,m00);
' rfRAngle = Radian(0.0); // any angle works
' rfYAngle = fRpY - rfRAngle;
' return false;
'}
End Sub
' Matrix3ToEulerAnglesYXZ()
''' <summary>
''' Add two euler objects.
''' </summary>
''' <returns>Calculation result</returns>
Public Shared Operator +(lhs As Euler, rhs As Euler) As Euler
Return New Euler(lhs.Yaw + rhs.Yaw, lhs.Pitch + rhs.Pitch, lhs.Roll + rhs.Roll)
End Operator
''' <summary>
''' Subtract two euler objects. This finds the difference as relative angles.
''' </summary>
''' <returns>Calculation result</returns>
Public Shared Operator -(lhs As Euler, rhs As Euler) As Euler
Return New Euler(lhs.Yaw - rhs.Yaw, lhs.Pitch - rhs.Pitch, lhs.Roll - rhs.Roll)
End Operator
''' <summary>
''' Interpolate each euler angle by the given factor.
''' (Each angle will be multiplied with the factor.)
''' </summary>
''' <returns>Calculation result</returns>
Public Shared Operator *(lhs As Euler, factor As [Single]) As Euler
Return New Euler(lhs.Yaw * factor, lhs.Pitch * factor, lhs.Roll * factor)
End Operator
''' <summary>
''' Interpolate the euler angles by lhs.
''' (Each angle will be multiplied with the factor.)
''' </summary>
''' <returns>Calculation result</returns>
Public Shared Operator *(factor As [Single], rhs As Euler) As Euler
Return New Euler(factor * rhs.Yaw, factor * rhs.Pitch, factor * rhs.Roll)
End Operator
''' <summary>
''' Apply the euler rotation to the vector rhs.
''' The calculation is equal to: quaternion*vector
''' </summary>
''' <returns>Calculation result</returns>
Public Shared Operator *(lhs As Euler, rhs As Vector3) As Vector3
Return lhs.ToQuaternion() * rhs
End Operator
''' <summary>Base settings (all angles are 0)</summary>
Public Shared IDENTITY As New Euler(New Radian(0), New Radian(0), New Radian(0))
''' <summary>Rotation around the Y axis.</summary>
Private mYaw As Radian
''' <summary>Rotation around the X axis.</summary>
Private mPitch As Radian
''' <summary>Rotation around the Z axis.</summary>
Private mRoll As Radian
''' <summary>Is the cached quaternion out of date?</summary>
Private mChanged As Boolean
''' <summary>Cached quaternion equivalent of this euler object.</summary>
Private mCachedQuaternion As Quaternion
End Structure
' struct Euler
End Namespace
' namespace
{CODE}
%%%
%%%
!Examples
Making and using a euler object:
{CODE(wrap="1", colors="c++")}Euler euler = new Euler(new Radian(Math.PI), new Radian(0), new Radian(0));
sceneNode.Orientation = euler; // Euler auto converts to a quaternion if you use it where Mogre expects a quaternion.{CODE}
Make a scene node face the camera (both yaw and pitch):
{CODE(wrap="1", colors="c++")}Euler euler = new Euler();
euler.SetDirection(camera.Position - sceneNode.Position, true, true); // SetDirection normalises the vector
sceneNode.Orientation = euler;{CODE}
Make a scene node face the camera using only the yaw (good for character controllers):
{CODE(wrap="1", colors="c++")}Euler euler = new Euler();
euler.SetDirection(camera.Position - sceneNode.Position, true, false); // the bools control whether the yaw or pitch are changed
sceneNode.Orientation = euler;{CODE}
Make a scene node face the camera with a limit of +/-45 degrees on the pitch and unlimited yaw:
{CODE(wrap="1", colors="c++")}Euler euler = new Euler();
euler.SetDirection(camera.Position - sceneNode.Position);
euler.LimitPitch(new Degree(45));
sceneNode.Orientation = euler;{CODE}
Perform a corkscrew motion (move vertical as the yaw increases:
{CODE(wrap="1", colors="c++")}sceneNode.Orientation = euler;
Vector3 pos = sceneNode.Position;
pos.y = euler.Yaw.ValueRadians;
sceneNode.Position = pos;{CODE}
Move forward using the euler direction:
{CODE(wrap="1", colors="c++")}sceneNode.Position = (sceneNode.Position + euler.Forward);{CODE}
Cancel out excess rotations (return all angles to the +-180 degree range):
{CODE(wrap="1", colors="c++")}euler.Normalise();{CODE}
Rotate the head of the Sinbad mesh to face the camera, with slow head turning and pitch/yaw constraints:
(This is using a modified version of the Sinbad mesh which is 2m tall and faces -Z. If your bone does not face -Z when it is not affected by any keyframes, this code might have problems. For example, if your bone faces +Z instead, you will need to negate the "lookat" vector before you use it in the "GetRotationTo" method)
{CODE(wrap="1", colors="c++")}
//In the initialisation:
Bone bone = entity.Skeleton.GetBone("Head");
bone.SetManuallyControlled(true);
Euler headFacing = new Euler(new Radian(0), new Radian(0), new Radian(0));
// In the update logic:
Vector3 lookat = sinbadNode.ConvertWorldToLocalPosition(camera.Position) - new Vector3(0.0f, 1.9f, 0.0f);
Euler temp = headFacing.GetRotationTo(lookat, true, true, true); // temp is how much you need to rotate to get from the current orientation to the new orientation
temp.LimitYaw(new Radian(deltaT*3.0f)); // limit the offset so the head turns at a maximum of 3.0 radians per second
temp.LimitPitch(new Radian(deltaT*3.0f));
headFacing = headFacing + temp; // add the offset to the current orientation
headFacing.LimitYaw(new Degree(60.0f)); // make sure the head doesn't turn too far. Clamp it to +/- 60 degrees of yaw and pitch.
headFacing.LimitPitch(new Degree(60.0f));
bone.Orientation = headFacing;
{CODE}
Sinbad's current orientation is taken into account by the ConvertWorldToLocalPosition call, so you can rotate him in any direction and he will still try to turn his head to the camera (if the limits allow).
---