quat

Documentation

Overview

Based on code from github.com/go-gl/mathgl: Copyright 2014 The go-gl Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

Index

• type RotationOrder
• type T
  • func BetweenVectors(start, dest vec3.T) T
  • func Euler(x, y, z float32) T
  • func FromAngles(angle1, angle2, angle3 float32, order RotationOrder) T
  • func FromMat4(m mat4.T) T
  • func Ident() T
  • func Lerp(q1, q2 T, amount float32) T
  • func LookAtV(eye, center, up vec3.T) T
  • func Nlerp(q1, q2 T, amount float32) T
  • func Rotate(angle float32, axis vec3.T) T
  • func Slerp(q1, q2 T, amount float32) T
  • func (q1 T) Add(q2 T) T
  • func (q1 T) ApproxEqual(q2 T) bool
  • func (q1 T) Conjugate() T
  • func (q1 T) Dot(q2 T) float32
  • func (q T) Euler() vec3.T
  • func (q1 T) Inverse() T
  • func (q1 T) Len() float32
  • func (q1 T) Mat4() mat4.T
  • func (q1 T) Mul(q2 T) T
  • func (q1 T) Norm() float32
  • func (q1 T) Normalize() T
  • func (q1 T) OrientationEqual(q2 T) bool
  • func (q1 T) OrientationEqualThreshold(q2 T, epsilon float32) bool
  • func (q1 T) Rotate(v vec3.T) vec3.T
  • func (q1 T) Scale(c float32) T
  • func (q1 T) Sub(q2 T) T
  • func (q T) ToAngles(order RotationOrder) vec3.T
  • func (q T) X() float32
  • func (q T) Y() float32
  • func (q T) Z() float32

Types

type RotationOrder

type RotationOrder int

RotationOrder is the order in which rotations will be transformed for the purposes of AnglesToQuat.

const (
	XYX RotationOrder = iota
	XYZ
	XZX
	XZY
	YXY
	YXZ
	YZY
	YZX
	ZYZ
	ZYX
	ZXZ
	ZXY
)

The RotationOrder constants represent a series of rotations along the given axes for the use of AnglesToQuat.

type T

type T struct {
	W float32
	V vec3.T
}

T represents a Quaternion, which is an extension of the imaginary numbers; there's all sorts of interesting theory behind it. In 3D graphics we mostly use it as a cheap way of representing rotation since quaternions are cheaper to multiply by, and easier to interpolate than matrices.

A Quaternion has two parts: W, the so-called scalar component, and "V", the vector component. The vector component is considered to be the part in 3D space, while W (loosely interpreted) is its 4D coordinate.

func BetweenVectors

func BetweenVectors(start, dest vec3.T) T

BetweenVectors calculates the rotation between two vectors

func Euler

func Euler(x, y, z float32) T

func FromAngles

func FromAngles(angle1, angle2, angle3 float32, order RotationOrder) T

FromAngles performs a rotation in the specified order. If the order is not a valid RotationOrder, this function will panic

The rotation "order" is more of an axis descriptor. For instance XZX would tell the function to interpret angle1 as a rotation about the X axis, angle2 about the Z axis, and angle3 about the X axis again.

Based off the code for the Matlab function "angle2quat", though this implementation only supports 3 single angles as opposed to multiple angles.

func FromMat4

func FromMat4(m mat4.T) T

FromMat4 converts a pure rotation matrix into a quaternion

func Ident

func Ident() T

Ident returns the quaternion identity: W=1; V=(0,0,0).

As with all identities, multiplying any quaternion by this will yield the same quaternion you started with.

func Lerp

func Lerp(q1, q2 T, amount float32) T

Lerp is a *L*inear Int*erp*olation between two Quaternions, cheap and simple.

Not excessively useful, but uses can be found.

func LookAtV

func LookAtV(eye, center, up vec3.T) T

LookAtV creates a rotation from an eye vector to a center vector

It assumes the front of the rotated object at Z- and up at Y+

func Nlerp

func Nlerp(q1, q2 T, amount float32) T

Nlerp is a *Normalized* *L*inear Int*erp*olation between two Quaternions. Cheaper than Slerp and usually just as good. This is literally Lerp with Normalize() called on it.

Unlike Slerp, constant velocity isn't maintained, but it's much faster and Nlerp(q1,q2) and Nlerp(q2,q1) return the same path. You should probably use this more often unless you're suffering from choppiness due to the non-constant velocity problem.

func Rotate

func Rotate(angle float32, axis vec3.T) T

Rotate creates an angle from an axis and an angle relative to that axis.

This is cheaper than HomogRotate3D.

func Slerp

func Slerp(q1, q2 T, amount float32) T

Slerp is *S*pherical *L*inear Int*erp*olation, a method of interpolating between two quaternions. This always takes the straightest path on the sphere between the two quaternions, and maintains constant velocity.

However, it's expensive and Slerp(q1,q2) is not the same as Slerp(q2,q1)

func (T) Add

func (q1 T) Add(q2 T) T

Add adds two quaternions. It's no more complicated than adding their W and V components.

func (T) ApproxEqual

func (q1 T) ApproxEqual(q2 T) bool

ApproxEqual returns whether the quaternions are approximately equal, as if FloatEqual was called on each matching element

func (T) Conjugate

func (q1 T) Conjugate() T

Conjugate returns the conjugate of a quaternion. Equivalent to Quat{q1.W, q1.V.Mul(-1)}.

func (T) Dot

func (q1 T) Dot(q2 T) float32

Dot product between two quaternions, equivalent to if this was a Vec4.

func (T) Euler

func (q T) Euler() vec3.T

func (T) Inverse

func (q1 T) Inverse() T

Inverse of a quaternion. The inverse is equivalent to the conjugate divided by the square of the length.

This method computes the square norm by directly adding the sum of the squares of all terms instead of actually squaring q1.Len(), both for performance and precision.

func (T) Len

func (q1 T) Len() float32

Len gives the Length of the quaternion, also known as its Norm. This is the same thing as the Len of a Vec4.

func (T) Mat4

func (q1 T) Mat4() mat4.T

Mat4 returns the homogeneous 3D rotation matrix corresponding to the quaternion.

func (T) Mul

func (q1 T) Mul(q2 T) T

Mul multiplies two quaternions. This can be seen as a rotation. Note that Multiplication is NOT commutative, meaning q1.Mul(q2) does not necessarily equal q2.Mul(q1).

func (T) Norm

func (q1 T) Norm() float32

Norm is an alias for Len() since both are very common terms.

func (T) Normalize

func (q1 T) Normalize() T

Normalize the quaternion, returning its versor (unit quaternion).

This is the same as normalizing it as a Vec4.

func (T) OrientationEqual

func (q1 T) OrientationEqual(q2 T) bool

OrientationEqual returns whether the quaternions represents the same orientation

Different values can represent the same orientation (q == -q) because quaternions avoid singularities and discontinuities involved with rotation in 3 dimensions by adding extra dimensions

func (T) OrientationEqualThreshold

func (q1 T) OrientationEqualThreshold(q2 T, epsilon float32) bool

OrientationEqualThreshold returns whether the quaternions represents the same orientation with a given tolerence

func (T) Rotate

func (q1 T) Rotate(v vec3.T) vec3.T

Rotate a vector by the rotation this quaternion represents. This will result in a 3D vector. Strictly speaking, this is equivalent to q1.v.q* where the "."" is quaternion multiplication and v is interpreted as a quaternion with W 0 and V v. In code: q1.Mul(Quat{0,v}).Mul(q1.Conjugate()), and then retrieving the imaginary (vector) part.

In practice, we hand-compute this in the general case and simplify to save a few operations.

func (T) Scale

func (q1 T) Scale(c float32) T

Scale every element of the quaternion by some constant factor.

func (T) Sub

func (q1 T) Sub(q2 T) T

Sub subtracts two quaternions. It's no more complicated than subtracting their W and V components.

func (T) ToAngles

func (q T) ToAngles(order RotationOrder) vec3.T

func (T) X

func (q T) X() float32

X is a convenient alias for q.V[0]

func (T) Y

func (q T) Y() float32

Y is a convenient alias for q.V[1]

func (T) Z

func (q T) Z() float32

Z is a convenient alias for q.V[2]