quat

Documentation

Overview

Package quat provides the quaternion numeric type and functions.

For a good treatment of uses and behaviors of quaternions, see the interactive videos by Ben Eater and Grant Sanderson here https://eater.net/quaternions.

Example (Rotate)

Rotate a cube 120° around the diagonal vector [1, 1, 1].

package main

import (
	"fmt"
	"math"

	"gonum.org/v1/gonum/floats/scalar"
	"gonum.org/v1/gonum/num/quat"
)

// point is a 3-dimensional point/vector.
type point struct {
	x, y, z float64
}

// raise raises the dimensionality of a point to a quaternion.
func raise(p point) quat.Number {
	return quat.Number{Imag: p.x, Jmag: p.y, Kmag: p.z}
}

// rotate performs the quaternion rotation of p by the given quaternion
// and scaling by the scale factor.
func rotate(p point, by quat.Number, scale float64) point {
	// Ensure the modulus of by is correctly scaled.
	if len := quat.Abs(by); len != scale {
		by = quat.Scale(math.Sqrt(scale)/len, by)
	}

	// Perform the rotation/scaling.
	pp := quat.Mul(quat.Mul(by, raise(p)), quat.Conj(by))

	// Extract the point.
	return point{x: pp.Imag, y: pp.Jmag, z: pp.Kmag}
}

// Rotate a cube 120° around the diagonal vector [1, 1, 1].
func main() {
	alpha := 2 * math.Pi / 3
	q := raise(point{1, 1, 1})
	scale := 1.0

	q = quat.Scale(math.Sin(alpha/2)/quat.Abs(q), q)
	q.Real += math.Cos(alpha / 2)

	for i, p := range []point{
		{x: 0, y: 0, z: 0},
		{x: 0, y: 0, z: 1},
		{x: 0, y: 1, z: 0},
		{x: 0, y: 1, z: 1},
		{x: 1, y: 0, z: 0},
		{x: 1, y: 0, z: 1},
		{x: 1, y: 1, z: 0},
		{x: 1, y: 1, z: 1},
	} {
		pp := rotate(p, q, scale)

		// Clean up floating point error for clarity.
		pp.x = scalar.Round(pp.x, 2)
		pp.y = scalar.Round(pp.y, 2)
		pp.z = scalar.Round(pp.z, 2)

		fmt.Printf("%d %+v -> %+v\n", i, p, pp)
	}

}

Output:


0 {x:0 y:0 z:0} -> {x:0 y:0 z:0}
1 {x:0 y:0 z:1} -> {x:1 y:0 z:0}
2 {x:0 y:1 z:0} -> {x:0 y:0 z:1}
3 {x:0 y:1 z:1} -> {x:1 y:0 z:1}
4 {x:1 y:0 z:0} -> {x:0 y:1 z:0}
5 {x:1 y:0 z:1} -> {x:1 y:1 z:0}
6 {x:1 y:1 z:0} -> {x:0 y:1 z:1}
7 {x:1 y:1 z:1} -> {x:1 y:1 z:1}

Index

• func Abs(q Number) float64
• func IsInf(q Number) bool
• func IsNaN(q Number) bool
• type Number
  • func Acos(q Number) Number
  • func Acosh(q Number) Number
  • func Add(x, y Number) Number
  • func Asin(q Number) Number
  • func Asinh(q Number) Number
  • func Atan(q Number) Number
  • func Atanh(q Number) Number
  • func Conj(q Number) Number
  • func Cos(q Number) Number
  • func Cosh(q Number) Number
  • func Exp(q Number) Number
  • func Inf() Number
  • func Inv(q Number) Number
  • func Log(q Number) Number
  • func Mul(x, y Number) Number
  • func NaN() Number
  • func Parse(s string) (Number, error)
  • func Pow(q, r Number) Number
  • func Scale(f float64, q Number) Number
  • func Sin(q Number) Number
  • func Sinh(q Number) Number
  • func Sqrt(q Number) Number
  • func Sub(x, y Number) Number
  • func Tan(q Number) Number
  • func Tanh(q Number) Number
  • func (q Number) Format(fs fmt.State, c rune)

Examples

• Package (Rotate)

Functions

func Abs

func Abs(q Number) float64

Abs returns the absolute value (also called the modulus) of q.

func IsInf

func IsInf(q Number) bool

IsInf returns true if any of real(q), imag(q), jmag(q), or kmag(q) is an infinity.

func IsNaN

func IsNaN(q Number) bool

IsNaN returns true if any of real(q), imag(q), jmag(q), or kmag(q) is NaN and none are an infinity.

Types

type Number

type Number struct {
	Real, Imag, Jmag, Kmag float64
}

Number is a float64 precision quaternion.

func Acos

func Acos(q Number) Number

Acos returns the inverse cosine of q.

func Acosh

func Acosh(q Number) Number

Acosh returns the inverse hyperbolic cosine of q.

func Add

func Add(x, y Number) Number

Add returns the sum of x and y.

func Asin

func Asin(q Number) Number

Asin returns the inverse sine of q.

func Asinh

func Asinh(q Number) Number

Asinh returns the inverse hyperbolic sine of q.

func Atan

func Atan(q Number) Number

Atan returns the inverse tangent of q.

func Atanh

func Atanh(q Number) Number

Atanh returns the inverse hyperbolic tangent of q.

func Conj

func Conj(q Number) Number

Conj returns the quaternion conjugate of q.

func Cos

func Cos(q Number) Number

Cos returns the cosine of q.

func Cosh

func Cosh(q Number) Number

Cosh returns the hyperbolic cosine of q.

func Exp

func Exp(q Number) Number

Exp returns e**q, the base-e exponential of q.

func Inf

func Inf() Number

Inf returns a quaternion infinity, quaternion(+Inf, +Inf, +Inf, +Inf).

func Inv

func Inv(q Number) Number

Inv returns the quaternion inverse of q.

func Log

func Log(q Number) Number

Log returns the natural logarithm of q.

func Mul

func Mul(x, y Number) Number

Mul returns the Hamiltonian product of x and y.

func NaN

func NaN() Number

NaN returns a quaternion “not-a-number” value.

func Parse

func Parse(s string) (Number, error)

Parse converts the string s to a Number. The string may be parenthesized and has the format [±]N±Ni±Nj±Nk. The order of the components is not strict.

func Pow

func Pow(q, r Number) Number

Pow return q**r, the base-q exponential of r. For generalized compatibility with math.Pow:

Pow(0, ±0) returns 1+0i+0j+0k
Pow(0, c) for real(c)<0 returns Inf+0i+0j+0k if imag(c), jmag(c), kmag(c) are zero,
    otherwise Inf+Inf i+Inf j+Inf k.

func Scale

func Scale(f float64, q Number) Number

Scale returns q scaled by f.

func Sin

func Sin(q Number) Number

Sin returns the sine of q.

func Sinh

func Sinh(q Number) Number

Sinh returns the hyperbolic sine of q.

func Sqrt

func Sqrt(q Number) Number

Sqrt returns the square root of q.

func Sub

func Sub(x, y Number) Number

Sub returns the difference of x and y, x-y.

func Tan

func Tan(q Number) Number

Tan returns the tangent of q.

func Tanh

func Tanh(q Number) Number

Tanh returns the hyperbolic tangent of q.

func (Number) Format

func (q Number) Format(fs fmt.State, c rune)

Format implements fmt.Formatter.