lin

package
Version: v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2018 License: BSD-2-Clause, Zlib Imports: 2 Imported by: 9

Documentation

Overview

Package lin provides a linear math library that includes vectors, matrices, quaternions, transforms and some utility functions. Linear math operations are useful in 3D applications for describing and transforming virtual objects as well as simulating physics.

Package lin is provided as part of the vu (virtual universe) 3D engine.

Index

Constants

View Source
const (

	// PI and its commonly needed variants.
	PI     float64 = math.Pi
	PIx2   float64 = PI * 2
	HalfPi float64 = PIx2 * 0.25
	DegRad float64 = PIx2 / 360.0 // X degrees * DEG_RAD = Y radians
	RadDeg float64 = 360.0 / PIx2 // Y radians * RAD_DEG = X degrees

	// Convenience numbers.
	Large float64 = math.MaxFloat32
	Sqrt2 float64 = math.Sqrt2
	Sqrt3 float64 = 1.73205

	// Epsilon is used to distinguish when a float is close enough to a number.
	// Wikipedia: "In set theory epsilon is the limit ordinal of the sequence..."
	Epsilon float64 = 0.000001
)

Various linear math constants.

Variables

View Source
var M3I = &M3{
	1, 0, 0,
	0, 1, 0,
	0, 0, 1}

M3I provides a reference identity matrix that can be used in calculations. It should never be changed.

View Source
var M3Z = &M3{
	0, 0, 0,
	0, 0, 0,
	0, 0, 0}

M3Z provides a reference zero matrix that can be used in calculations. It should never be changed.

View Source
var M4I = &M4{
	1, 0, 0, 0,
	0, 1, 0, 0,
	0, 0, 1, 0,
	0, 0, 0, 1}

M4I provides a reference identity matrix that can be used in calculations. It should never be changed.

View Source
var M4Z = &M4{
	0, 0, 0, 0,
	0, 0, 0, 0,
	0, 0, 0, 0,
	0, 0, 0, 0}

M4Z provides a reference zero matrix that can be used in calculations. It should never be changed.

View Source
var QI = &Q{0, 0, 0, 1}

QI provides a reference identity matrix that can be used in calculations. It should never be changed.

Functions

func AbsMax

func AbsMax(a0, a1, a2, a3 float64) int

AbsMax returns the index of the largest absolute value of the 4 given values. The returned index is always from 0-3.

func Aeq

func Aeq(a, b float64) bool

Aeq (~=) almost-equals returns true if the difference between a and b is so small that it doesn't matter.

func AeqZ

func AeqZ(x float64) bool

AeqZ (~=) almost-equals returns true if the difference between x and zero is so small that it doesn't matter.

func Atan2F

func Atan2F(y, x float64) float64

Atan2F is a fast approximation of Atan2. Source was posted at:

http://www.gamedev.net/topic/441464-manually-implementing-atan2-or-atan/

func Clamp

func Clamp(s, lb, ub float64) float64

Clamp returns a scalar value (one of: s, lb, ub) guaranteed to be within the range given by lower bound lb and upper bound ub.

func Deg

func Deg(rad float64) float64

Deg converts radians to degrees.

func Lerp

func Lerp(a, b, ratio float64) float64

Lerp returns the linear interpolation of a to b by the given ratio.

func Max3

func Max3(a, b, c float64) float64

Max3 returns the largest of the 3 numbers.

func Min3

func Min3(a, b, c float64) float64

Min3 returns the smallest of the 3 numbers.

func MultSQ

func MultSQ(x, y, z float64, q *Q) (vx, vy, vz float64)

MultSQ applies rotation q to scalar vector (x,y,z) The updated scalar vector (vx,vy,vz) is returned.

func Nang

func Nang(radians float64) float64

Nang (normalize angle) ensures a rotation angle in radians is within the range [-PI, PI] (2PI*radians is 360 degrees).

func Rad

func Rad(deg float64) float64

Rad converts degrees to radians.

func Round

func Round(val float64, prec int) float64

Round return rounded version of x with prec precision. Special cases are:

Round(±0) = ±0
Round(±Inf) = ±Inf
Round(NaN) = NaN

Types

type M3

type M3 struct {
	Xx, Xy, Xz float64 // indices 0, 1, 2  [00, 01, 02]  X-Axis
	Yx, Yy, Yz float64 // indices 3, 4, 5  [10, 11, 12]  Y-Axis
	Zx, Zy, Zz float64 // indices 6, 7, 8  [20, 21, 22]  Z-Axis
}

M3 is a 3x3 matrix where the matrix elements are individually addressable.

func NewM3

func NewM3() *M3

NewM3 creates a new, all zero, 3x3 matrix.

func NewM3I

func NewM3I() *M3

NewM3I creates a new 3x3 identity matrix.

[ 1 0 0 ]    [ Xx Xy Xz ]
[ 0 1 0 ] => [ Yx Yy Yz ]
[ 0 0 1 ]    [ Zx Zy Zz ]

func (*M3) Abs

func (m *M3) Abs(a *M3) *M3

Abs updates m to be the the absolute (non-negative) element values of the corresponding element values in matrix a. The source matrix a is unchanged. The updated matrix m is returned.

func (*M3) Add

func (m *M3) Add(a, b *M3) *M3

Add (+) adds matrices a and b storing the results in m. Each element of matrix b is added to the corresponding matrix a element. It is safe to use the calling matrix m as one or both of the parameters. For example the plus.equals operation (+=) is

m.Add(m, b)

The updated matrix m is returned.

func (*M3) Adj

func (m *M3) Adj(a *M3) *M3

Adj updates m to be the adjoint matrix of matrix a. The adjoint matrix is created by the transpose of the cofactor matrix of the original matrix.

[ a.cof(0,0) a.cof(1,0) a.cof(2,0) ]    [ mXx mXy mXz ]
[ a.cof(0,1) a.cof(1,1) a.cof(2,1) ] => [ mYx mYy mYz ]
[ a.cof(0,2) a.cof(1,2) a.cof(2,2) ]    [ mZx mZy mZz ]

The updated matrix m is returned.

func (*M3) Aeq

func (m *M3) Aeq(a *M3) bool

Aeq (~=) almost equals returns true if all the elements in matrix m have essentially the same value as the corresponding elements in matrix a. Used where equals is unlikely to return true due to float precision.

func (*M3) Cof

func (m *M3) Cof(row, col int) float64

Cof returns one of the possible cofactors of a 3x3 matrix given the input minor (the row and column removed from the calculation). Wikipedia states:

"cofactors [...] are useful for computing both the determinant
 and inverse of square matrices".

func (*M3) Det

func (m *M3) Det() float64

Det returns the determinant of matrix m. Determinants are helpful when calculating the inverse of transform matrices. Wikipedia states:

"The determinant provides important information about [..] a matrix that
 corresponds to a linear transformation of a vector space [..] the transformation
 has an inverse operation exactly when the determinant is nonzero."

func (*M3) Eq

func (m *M3) Eq(a *M3) bool

Eq (==) returns true if all the elements in matrix m have the same value as the corresponding elements in matrix a.

func (*M3) Inv

func (m *M3) Inv(a *M3) *M3

Inv updates m to be the inverse of matrix a. The updated matrix m is returned. Matrix m is not updated if the matrix has no inverse.

func (*M3) Mult

func (m *M3) Mult(l, r *M3) *M3

Mult (*) multiplies matrices l and r storing the results in m.

[ lXx lXy lXz ] [ rXx rXy rXz ]    [ mXx mXy mXz ]
[ lYx lYy lYz ]x[ rYx rYy rYz ] => [ mYx mYy mYz ]
[ lZx lZy lZz ] [ rZx rZy rZz ]    [ mZx mZy mZz ]

It is safe to use the calling matrix m as one or both of the parameters. For example (*=) is

m.Mult(m, r)

The updated matrix m is returned.

func (*M3) MultLtR

func (m *M3) MultLtR(lt, r *M3) *M3

MultLtR multiplies the transpose of matrix l on left of matrix r and stores the result in m. This can be used for saving a method call when calculating inverse transforms.

[ lXx lYx lZx ] [ rXx rXy rXz ]    [ mXx mXy mXz ]
[ lXy lYy lZy ]x[ rYx rYy rYz ] => [ mYx mYy mYz ]
[ lXz lYz lZz ] [ rZx rZy rZz ]    [ mZx mZy mZz ]

It is safe to use the calling matrix m as one or both of the parameters. The updated matrix m is returned.

func (*M3) Scale

func (m *M3) Scale(s float64) *M3

Scale (*) each element of matrix m by the given scalar. The updated matrix m is returned.

func (*M3) ScaleS

func (m *M3) ScaleS(x, y, z float64) *M3

ScaleS (*) scales each column of matrix m using the corresponding scaler elements x, y, z. The updated matrix m is returned.

func (*M3) ScaleSM

func (m *M3) ScaleSM(x, y, z float64) *M3

ScaleSM updates m to be the multiplication of a scale matrix created from x, y, z and itself. The updated matrix m is returned so that it may be immediately used in another operation.

[ x 0 0 ]   [ mXx mXy mXz ]    [ mXx' mXy' mXz' ]
[ 0 y 0 ] x [ mYx mYy mYz ] => [ mYx' mYy' mYz' ]
[ 0 0 z ]   [ mZx mZy mZz ]    [ mZx' mZy' mZz' ]

Be sure to pick the correct scale (SM or MS) when doing transforms.

func (*M3) ScaleV

func (m *M3) ScaleV(v *V3) *M3

ScaleV (*) scales each column of matrix m using the given vector v for elements for x, y, z. The updated matrix m is returned.

func (*M3) Set

func (m *M3) Set(a *M3) *M3

Set (=) assigns all the scaler values from matrix a to the corresponding scaler values in matrix m. The source matrix a is unchanged. The updated matrix m is returned.

func (*M3) SetAa

func (m *M3) SetAa(ax, ay, az, ang float64) *M3

SetAa set axis-angle, updates m to be a rotation matrix from the given axis (ax, ay, az) and angle (in radians). See:

http://en.wikipedia.org/wiki/Rotation_matrix#Rotation_matrix_from_axis_and_angle
http://web.archive.org/web/20041029003853/...
...http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q38 (*note column order)

The updated matrix m is returned.

func (*M3) SetM4

func (m *M3) SetM4(a *M4) *M3

SetM4 (=) updates calling matrix m to be the 3x3 matrix from the top left corner of the given 4x4 matrix m4. The source matrix a is unchanged. The updated matrix m is returned.

[ Xx Xy Xz Xw ]    [ Xx Xy Xz ]
[ Yx Yy Yz Yw ] => [ Yx Yy Yz ]
[ Zx Zy Zz Zw ]    [ Zx Zy Zz ]
[ Wx Wy Wz Ww ]

func (*M3) SetQ

func (m *M3) SetQ(q *Q) *M3

SetQ converts a quaternion rotation representation to a matrix rotation representation. SetQ updates matrix m to be the rotation matrix representing the rotation described by unit-quaternion q.

                   [ mXx mXy mXz ]
[ qx qy qz qw ] => [ mYx mYy mYz ]
                   [ mZx mZy mZz ]

The parameter q is unchanged. The updated matrix m is returned.

func (*M3) SetS

func (m *M3) SetS(Xx, Xy, Xz, Yx, Yy, Yz, Zx, Zy, Zz float64) *M3

SetS (=) explicitly sets the matrix scaler values using the given scalers. The source matrix a is unchanged. The updated matrix m is returned.

Xx, Xy, Xz is the X Axis.
Yx, Yy, Yz is the Y Axis.
Zx, Zy, Zz is the Z Axis.

func (*M3) SetSkewSym

func (m *M3) SetSkewSym(v *V3) *M3

SetSkewSym sets the matrix m to be a skew-symetric matrix based on the elements of vector v. Wikipedia states:

"A skew-symmetric matrix is a square matrix
 whose transpose is also its negative."

func (*M3) Sub

func (m *M3) Sub(a, b *M3) *M3

Sub (-) subtracts matrices b from a storing the results in m. Each element of matrix b is subtracted from the corresponding matrix a element. It is safe to use the calling matrix m as one or both of the parameters. For example the minus.equals operation (-=) is

m.Sub(m, b)

The updated matrix m is returned.

func (*M3) Transpose

func (m *M3) Transpose(a *M3) *M3

Transpose updates m to be the reflection of matrix a over its diagonal. This essentially changes row-major order to column-major order or vice-versa.

[ Xx Xy Xz ]    [ Xx Yx Zx ]
[ Yx Yy Yz ] => [ Xy Yy Zy ]
[ Zx Zy Zz ]    [ Xz Yz Zz ]

The input matrix a is not changed. Matrix m may be used as the input parameter. The updated matrix m is returned.

type M4

type M4 struct {
	Xx, Xy, Xz, Xw float64 // indices 0, 1, 2, 3  [00, 01, 02, 03] X-Axis
	Yx, Yy, Yz, Yw float64 // indices 4, 5, 6, 7  [10, 11, 12, 13] Y-Axis
	Zx, Zy, Zz, Zw float64 // indices 8, 9, a, b  [20, 21, 22, 23] Z-Axis
	Wx, Wy, Wz, Ww float64 // indices c, d, e, f  [30, 31, 32, 33]
}

M4 is a 4x4 matrix where the matrix elements are individually addressable.

func NewM4

func NewM4() *M4

NewM4 creates a new, all zero, 4x4 matrix.

func NewM4I

func NewM4I() *M4

NewM4I creates a new 4x4 identity matrix.

[ 1 0 0 0 ]    [ Xx Xy Xz Xw ]
[ 0 1 0 0 ] => [ Yx Yy Yz Yw ]
[ 0 0 1 0 ]    [ Zx Zy Zz Zw ]
[ 0 0 0 1 ]    [ Wx Wy Wz Ww ]

func (*M4) Add

func (m *M4) Add(a, b *M4) *M4

Add (+) adds matrices a and b storing the results in m. Same behaviour as M3.Add()

func (*M4) Aeq

func (m *M4) Aeq(a *M4) bool

Aeq (~=) almost equals returns true if all the elements in matrix m have essentially the same value as the corresponding elements in matrix a. Same as M3.Aeq().

func (*M4) Eq

func (m *M4) Eq(a *M4) bool

Eq (==) returns true if all the elements in matrix m have the same value as the corresponding elements in matrix a.

func (*M4) Mult

func (m *M4) Mult(l, r *M4) *M4

Mult updates matrix m to be the multiplication of input matrices l, r.

[ lXx lXy lXz lXw ] [ rXx rXy rXz rXw ]    [ mXx mXy mXz mXw ]
[ lYx lYy lYz lYw ]x[ rYx rYy rYz rYw ] => [ mYx mYy mYz mYw ]
[ lZx lZy lZz lZw ] [ rZx rZy rZz rZw ]    [ mZx mZy mZz mZw ]
[ lWx lWy lWz lWw ] [ rWx rWy rWz rWw ]    [ mWx mWy mWz mWw ]

Same behaviour as M3.Mult()

func (*M4) Ortho

func (m *M4) Ortho(left, right, bottom, top, near, far float64) *M4

Ortho sets matrix m with projection values needed to transform a 3 dimensional model to a 2 dimensional plane. Orthographic projection ignores depth. The input arguments are:

left, right:  Vertical clipping planes.
bottom, top:  Horizontal clipping planes.
near, far  :  Depth clipping planes. The depth values are
              negative if the plane is to be behind the viewer

An orthographic matrix fills the following matrix locations:

[ a 0 0 0 ]    [ Xx Xy Xz Xw ]
[ 0 b 0 0 ] => [ Yx Yy Yz Yw ]
[ 0 0 c 0 ]    [ Zx Zy Zz Zw ]
[ d e f 1 ]    [ Wx Wy Wz Ww ]

func (*M4) Persp

func (m *M4) Persp(fov, aspect, near, far float64) *M4

Persp sets matrix m with projection values needed to transform a 3 dimensional model to a 2 dimensional plane. Objects that are further away from the viewer will appear smaller. The input arguments are:

fov        An amount in degrees indicating how much of the
           scene is visible.
aspect     The ratio of height to width of the model.
near, far  The depth clipping planes. The depth values are
           negative if the plane is to be behind the viewer

A perspective projection matrix fills the following matrix locations:

[ a 0 0 0 ]    [ Xx Xy Xz Xw ]
[ 0 b 0 0 ] => [ Yx Yy Yz Yw ]
[ 0 0 c d ]    [ Zx Zy Zz Zw ]
[ 0 0 e 0 ]    [ Wx Wy Wz Ww ]

func (*M4) PerspInv

func (m *M4) PerspInv(fov, aspect, near, far float64) *M4

PerspInv sets matrix m to be a new inverse matrix of the given perspective matrix values (see NewPersp()).

[ a' 0  0  0 ] where a' = 1/a     d' = 1/e    [ Xx Xy Xz Xw ]
[ 0  b' 0  0 ]       b' = 1/b     e' = 1/d => [ Yx Yy Yz Yw ]
[ 0  0  0  d']       c' = -(c/de)             [ Zx Zy Zz Zw ]
[ 0  0  e' c']                                [ Wx Wy Wz Ww ]

This is used when going from screen x,y coordinates to 3D coordinates. as in the case when creating a picking ray from a mouse location.

func (*M4) Scale

func (m *M4) Scale(s float64) *M4

Scale (*) each element of matrix m by the given scalar. The updated matrix m is returned.

func (*M4) ScaleMS

func (m *M4) ScaleMS(x, y, z float64) *M4

ScaleMS updates m to be the multiplication of m and a scale matrix created from x, y, z. The updated matrix m is returned so that it may be immediately used in another operation.

[ mXx mXy mXz mXw ]   [ x 0 0 0 ]    [ mXx' mXy' mXz' mXw ]
[ mYx mYy mYz mYw ] x [ 0 y 0 0 ] => [ mYx' mYy' mYz' mYw ]
[ mZx mZy mZz mZw ]   [ 0 0 z 0 ]    [ mZx' mZy' mZz' mZw ]
[ mWx mWy mWz mWw ]   [ 0 0 0 1 ]    [ mWx' mWy' mWz' mWw ]

Be sure to pick the correct scale (SM or MS) when doing transforms.

func (*M4) ScaleSM

func (m *M4) ScaleSM(x, y, z float64) *M4

ScaleSM updates m to be the multiplication of a scale matrix created from x, y, z and itself. Same behaviours as M3.ScaleSM.

[ x 0 0 0 ]   [ mXx mXy mXz mXw ]    [ mXx' mXy' mXz' mXw' ]
[ 0 y 0 0 ] x [ mYx mYy mYz mYw ] => [ mYx' mYy' mYz' mYw' ]
[ 0 0 z 0 ]   [ mZx mZy mZz mZw ]    [ mZx' mZy' mZz' mZw' ]
[ 0 0 0 1 ]   [ mWx mWy mWz mWw ]    [ mWx  mWy  mWz  mWw  ]

func (*M4) Set

func (m *M4) Set(a *M4) *M4

Set (=) assigns all the elements values from matrix a to the corresponding element values in matrix m. The source matrix a is unchanged. The updated matrix m is returned.

func (*M4) SetQ

func (m *M4) SetQ(q *Q) *M4

SetQ converts a quaternion rotation representation to a matrix rotation representation. SetQ updates matrix m to be the rotation matrix representing the rotation described by unit-quaternion q.

                   [ mXx mXy mXz 0 ]
[ qx qy qz qw ] => [ mYx mYy mYz 0 ]
                   [ mZx mZy mZz 0 ]
                   [  0   0   0  1 ]

The parameter q is unchanged. The updated matrix m is returned.

func (*M4) TranslateMT

func (m *M4) TranslateMT(x, y, z float64) *M4

TranslateMT updates m to be the multiplication of itself and a translation matrix created from x, y, z. The updated matrix m is returned.

[ mXx mXy mXz mXw ]   [ 1 0 0 0 ]    [ mXx' mXy' mXz' mXw ]
[ mYx mYy mYz mYw ] x [ 0 1 0 0 ] => [ mYx' mYy' mYz' mYw ]
[ mZx mZy mZz mZw ]   [ 0 0 1 0 ]    [ mZx' mZy' mZz' mZw ]
[ mWx mWy mWz mWw ]   [ x y z 1 ]    [ mWx' mWy' mWz' mWw ]

Be sure to pick the correct translate (TM or MT) when doing transforms.

func (*M4) TranslateTM

func (m *M4) TranslateTM(x, y, z float64) *M4

TranslateTM updates m to be the multiplication of a translation matrix T created from x, y, z, and itself. The updated matrix m is returned.

[ 1 0 0 0 ]   [ mXx mXy mXz mXw ]     [ mXx  mXy  mXz  mXw  ]
[ 0 1 0 0 ] x [ mYx mYy mYz mYw ]  => [ mYx  mYy  mYz  mYw  ]
[ 0 0 1 0 ]   [ mZx mZy mZz mZw ]     [ mZx  mZy  mZz  mZw  ]
[ x y z 1 ]   [ mWx mWy mWz mWw ]     [ mWx' mWy' mWz' mWw' ]

Be sure to pick the correct translate (TM or MT) when doing transforms.

func (*M4) Transpose

func (m *M4) Transpose(a *M4) *M4

Transpose updates m to be the reflection of matrix a over its diagonal.

[ Xx Xy Xz Xw ]    [ Xx Yx Zx Wx ]
[ Yx Yy Yz Yw ] => [ Xy Yy Zy Wy ]
[ Zx Zy Zz Zw ]    [ Xz Yz Zz Wz ]
[ Wx Wy Wz Ww ]    [ Xw Yw Zw Ww ]

Same behaviour as M3.Transpose()

type Q

type Q struct {
	X float64 // X component of direction vector.
	Y float64 // Y component of direction vector.
	Z float64 // Z component of direction vector.
	W float64 // Angle of rotation.
}

Q is a unit length quaternion representing an angle of rotation. Q is used to track/manipulate 3D object rotations. Quaternions behave nicely for mathematical operations other than they are not commutative.

func NewQ

func NewQ() *Q

NewQ creates a new, all zero, quaternion.

func NewQI

func NewQI() *Q

NewQI creates a new identity quaternion.

func (*Q) Aa

func (q *Q) Aa() (ax, ay, az, angle float64)

Aa gets the rotation of quaternion q as an axis and angle. The axis (x, y, z) and the angle in radians is returned. The return elements will be zero if the length of the quaternion is 0. See:

http://web.archive.org/web/20041029003853/...
...http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q57

func (*Q) Add

func (q *Q) Add(r, s *Q) *Q

Add (+) quaternions r and s returning the result in quaternion q.

func (*Q) Aeq

func (q *Q) Aeq(r *Q) bool

Aeq (~=) almost-equals returns true if all the elements in quaternion q have essentially the same value as the corresponding elements in quaternion r. Used where a direct comparison is unlikely to return true due to floats.

func (*Q) Ang

func (q *Q) Ang(r *Q) float64

Ang returns the angle in radians between quaternions q and r. See

http://math.stackexchange.com/questions/90081/quaternion-distance

for the formula to calculate angles between quaternions, i.e.:

angle = Acos(2⟨q dot r⟩(q dot r)−1)

func (*Q) Div

func (q *Q) Div(s float64) *Q

Div (/= inverse-scale) divides each element in q by the given scalar value The updated q is returned. Scale values of zero are logged as an error and q is not scaled.

func (*Q) Dot

func (q *Q) Dot(r *Q) float64

Dot returns the dot product of the quaternions q and r. Quaternion q may be used as the input parameter. For example (Dot=), the length squared, is

q.Dot(q)

func (*Q) Eq

func (q *Q) Eq(r *Q) bool

Eq (==) returns true if each element in the quaternion q has the same value as the corresponding element in quaterion r.

func (*Q) GetS

func (q *Q) GetS() (x, y, z, w float64)

GetS returns the component parts of a quaternion.

func (*Q) Inv

func (q *Q) Inv(r *Q) *Q

Inv updates q to be inverse of quaternion r. The updated q is returned. The inverse of a quaternion is the same as the conjugate, as long as the quaternion is unit-length.

func (*Q) Len

func (q *Q) Len() float64

Len returns the length of the quaternion q.

func (*Q) Mult

func (q *Q) Mult(r, s *Q) *Q

Mult (*) multiplies quaternions r and s returning the result in q. This applies the rotation of s to r giving q, leaving r and s unchanged. It is safe to use the calling quaternion q as one or both of the parameters. For example (*=) is

q.Mult(q, s)

The updated calling quaternion q is returned.

func (*Q) MultQV

func (q *Q) MultQV(r *Q, v *V3) *Q

MultQV multiplies quaternion r and vector v and returns the result in quaternion q. The upated quaternion q is returned.

func (*Q) Neg

func (q *Q) Neg() *Q

Neg (-) returns the negative of quaternion q where each element is negated. The updated q is returned.

func (*Q) Nlerp

func (q *Q) Nlerp(r, s *Q, ratio float64) *Q

Nlerp updates q to be the normalized linear interpolation between quaternions r and s where ratio is expected to be between 0 and 1. The input quaternions r and s are not changed. See:

http://keithmaggio.wordpress.com/2011/02/15/math-magician-lerp-slerp-and-nlerp/
http://number-none.com/product/Understanding Slerp, Then Not Using It/

The updated calling quaternion q is returned.

func (*Q) Scale

func (q *Q) Scale(s float64) *Q

Scale (*=) quaternion q by s returning the result in quaternion q.

func (*Q) Set

func (q *Q) Set(r *Q) *Q

Set (=) assigns all the elements values from quaternion r to the corresponding element values in quaternion q. The updated quaternion q is returned.

func (*Q) SetAa

func (q *Q) SetAa(ax, ay, az, angle float64) *Q

SetAa set axis-angle, updates q to have the rotation of the given axis (ax, ay, az) and angle (in radians). See:

http://web.archive.org/web/20041029003853/...
...http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q56

The updated quaternion q is returned. The quaternion q is set to 0,0,0,1 if the axis length is 0.

Ensure SetAa returns quaternions consistent with SetM3. Convention 5 from "Consistent Representations of and Conversions Between 3D Rotations":

"The rotation angle ω is limited to the interval [0, π].
 For angles in the range ]π, 2π[, the sign of the unit axis vector nˆ
 must be reversed, and ω replaced by 2π − ω. For angles outside the range
 [0, 2π[, the angle must first be reduced to the interval [0, 2π[ by
 adding or subtracting the appropriate integer multiple of 2π."

func (*Q) SetM3 added in v0.9.0

func (q *Q) SetM3(m *M3) *Q

SetM3 updates quaternion q to be the rotation of matrix m. See

http://www.flipcode.com/documents/matrfaq.html#Q55
http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/
https://d3cw3dd2w32x2b.cloudfront.net/wp-content/uploads/2015/01/matrix-to-quat.pdf

The updated q is returned.

SetM3 outputs quaternions that are consistent with SetAa.

func (*Q) SetS

func (q *Q) SetS(x, y, z, w float64) *Q

SetS (=) explicitly sets each of the quaternion values to the given values. The updated quaternion q is returned.

func (*Q) SetT

func (q *Q) SetT(t *T) *Q

SetT updates quaternion q to have the rotation in transform t. The updated quaternion q is returned.

func (*Q) Sub

func (q *Q) Sub(r, s *Q) *Q

Sub (-) subtracts quaternion s from r returning the difference in quaternion q.

func (*Q) Unit

func (q *Q) Unit() *Q

Unit normalizes quaternion q to have length 1. The normalized (unit length) q is returned. Quaternion q is not updated if the length of quaternion q is zero.

type T

type T struct {
	Loc *V3 // Location (translation, origin).
	Rot *Q  // Rotation (direction, orientation).
}

T is a 3D transform for rotation and translation. It excludes scaling and shear information. T is used as a simplification and optimization instead of keeping all transform information in a 4x4 matrix.

T supports linear algebra operations that are similar to those supported by V3, V4, M3, M4, and Q. The main ones are:

Multiply two transforms together to produce a composite transform.
Apply a transform or inverse transform to a vector.

func NewT

func NewT() *T

NewT creates and returns a transform at the origin with no rotation.

func (*T) Aeq

func (t *T) Aeq(a *T) bool

Aeq (~=) almost-equals returns true if all the elements in transform t have essentially the same value as the corresponding elements in transform a. Used where a direct comparison is unlikely to return true due to floats.

func (*T) App

func (t *T) App(v *V3) *V3

App applies its transform to vector v. The updated vector v is returned.

func (*T) AppR

func (t *T) AppR(x, y, z float64) (vx, vy, vz float64)

AppR applies just the transform rotation to input vector (x,y,z) returning the rotated vector (vx,vy,vz)

func (*T) AppS

func (t *T) AppS(x, y, z float64) (vx, vy, vz float64)

AppS applies transform t, rotation then translation, to input scalar vector (x,y,z) returning the transformed scalar vector (vx,vy,vz).

func (*T) Eq

func (t *T) Eq(a *T) bool

Eq (==) returns true of all elements of transform t have the same value as the corresponding element of transform a.

func (*T) Integrate

func (t *T) Integrate(a *T, linv, angv *V3, dt float64) *T

Integrate updates transform t to be the linear integration of transform a with the given linear velocity linv, and angular velocity angv over the given amount of time dt. Transforms t and a must be distinct. The input vectors linv, angv are not changed. The updated transform t is returned.

Based on bullet physics: btTransformUtil::integrateTransform.

func (*T) Inv

func (t *T) Inv(v *V3) *V3

Inv updates vector v to be the inverse transform t applied to vector a. The updated vector v is returned.

func (*T) InvS

func (t *T) InvS(x, y, z float64) (vx, vy, vz float64)

InvS applies the inverse transform t, inverse translation, then inverse rotation, to input vector (x,y,z) returning the transformed vector (vx,vy,vz).

func (*T) Mult

func (t *T) Mult(a, b *T) *T

Mult (*) updates the transform t to be the product of the transforms a and b. Transform t may be used as one or both of the input transforms. The updated transform t is returned.

func (*T) Set

func (t *T) Set(a *T) *T

Set (=, copy, clone) assigns all the elements values from transform a to the corresponding element values in transform t. The updated transform t is returned.

func (*T) SetAa

func (t *T) SetAa(ax, ay, az, ang float64) *T

SetAa updates transform t to have the rotation specified by the given axis and angle in radians. The updated transform t is returned.

func (*T) SetI

func (t *T) SetI() *T

SetI updates transform t to be the identity transform. The updated transform t is returned.

func (*T) SetLoc

func (t *T) SetLoc(lx, ly, lz float64) *T

SetLoc updates transform t to have the location speccified by lx, ly, lz. The updated transform t is returned.

func (*T) SetRot

func (t *T) SetRot(x, y, z, w float64) *T

SetRot updates transform t to have the rotation specified by x, y, z, w. The updated transform t is returned.

func (*T) SetVQ

func (t *T) SetVQ(loc *V3, rot *Q) *T

SetVQ (=) sets the transform t based on the given quaternion rotation and translation location. The updated transform t is returned.

type V3

type V3 struct {
	X float64 // increments as X moves to the right.
	Y float64 // increments as Y moves up from bottom left.
	Z float64 // increments as Z moves out of the screen (right handed view space).
}

V3 is a 3 element vector. This can also be used as a point.

func NewV3

func NewV3() *V3

NewV3 creates a new, all zero, 3D vector.

func NewV3S

func NewV3S(x, y, z float64) *V3

NewV3S creates a new 3D vector using the given scalars.

func (*V3) Abs

func (v *V3) Abs() *V3

Abs updates vector v to have the absolute value of the elements of vector a. The updated vector v is returned.

func (*V3) Add

func (v *V3) Add(a, b *V3) *V3

Add (+) adds vectors a and b storing the results of the addition in v. Vector v may be used as one or both of the parameters. For example (+=) is

v.Add(v, b)

The updated vector v is returned.

func (*V3) Aeq

func (v *V3) Aeq(a *V3) bool

Aeq (~=) almost-equals returns true if all the elements in vector v have essentially the same value as the corresponding elements in vector a. Used where a direct comparison is unlikely to return true due to floats.

func (*V3) AeqZ

func (v *V3) AeqZ() bool

AeqZ (~=) almost equals zero returns true if the square length of the vector is close enough to zero that it makes no difference.

func (*V3) Ang

func (v *V3) Ang(a *V3) float64

Ang returns the angle in radians between vector v and input vector a. Ang returns 0 if the magnitude of the two vectors is 0.

func (*V3) AppT

func (v *V3) AppT(t *T, a *V3) *V3

AppT updates vector v to be the transform t applied to vector a. Vector a is unchanged. The updated vector v is returned.

func (*V3) Cross

func (v *V3) Cross(a, b *V3) *V3

Cross updates v to be the cross product of vectors a and b. A cross product vector is a vector that is perpendicular to both input vectors. This is only meaningful in 3 (or 7) dimensions. Input vectors a and b are unchanged. Vector v may be used as either input parameter.The updated vector v is returned.

func (*V3) Dist

func (v *V3) Dist(a *V3) float64

Dist returns the distance between vector end-points v and a Both vectors (points) v and a are unchanged.

func (*V3) DistSqr

func (v *V3) DistSqr(a *V3) float64

DistSqr returns the distance squared between vector end-points v and a. Both vectors (points) v and a are unchanged.

func (*V3) Div

func (v *V3) Div(s float64) *V3

Div (/= inverse-scale) divides each element in v by the given scalar value. The updated vector v is returned. Vector v is not changed if scalar s is zero.

func (*V3) Dot

func (v *V3) Dot(a *V3) float64

Dot vector v with input vector a. Both vectors v and a are unchanged. Wikipedia states:

"This operation can be defined either algebraically or geometrically.
 Algebraically, it is the sum of the products of the corresponding
 entries of the two sequences of numbers. Geometrically, it is the
 product of the magnitudes of the two vectors and the cosine of
 the angle between them."

func (*V3) Eq

func (v *V3) Eq(a *V3) bool

Eq (==) returns true if each element in the vector v has the same value as the corresponding element in vector a.

func (*V3) GetS

func (v *V3) GetS() (x, y, z float64)

GetS returns the float64 values of the vector.

func (*V3) Len

func (v *V3) Len() float64

Len returns the length of vector v. Vector length is the square root of the dot product. The calling vector v is unchanged.

func (*V3) LenSqr

func (v *V3) LenSqr() float64

LenSqr returns the length of vector v squared. The calling vector v is unchanged.

func (*V3) Lerp

func (v *V3) Lerp(a, b *V3, fraction float64) *V3

Lerp updates vector v to be a fraction of the distance (linear interpolation) between the input vectors a and b. The input ratio is not verified, but is expected to be between 0 and 1. Vector v may be used as one of the parameters.

func (*V3) Max

func (v *V3) Max(a, b *V3) *V3

Max updates the vector v elements to be the maxiumum of the corresponding elements from either vectors a or b. The updated vector v is returned.

func (*V3) Min

func (v *V3) Min(a, b *V3) *V3

Min updates the vector v elements to be the minimum of the corresponding elements from either vectors a or b. The updated vector v is returned.

func (*V3) Mult

func (v *V3) Mult(a, b *V3) *V3

Mult (*) multiplies the elements of vectors a and b storing the result in v. Vector v may be used as one or both of the parameters. For example (*=) is For example (*=) is

v.Mult(v, b)

The updated vector v is returned.

func (*V3) MultMv

func (v *V3) MultMv(m *M3, cv *V3) *V3

MultMv updates vector v to be the multiplication of matrix m and column vector cv. Vector v may be used as the input vector cv. The updated vector v is returned.

[ Xx Xy Xz ]   [ vx ]   [ vx' ]
[ Yx Yy Yz ] x [ vy ] = [ vx' ]
[ Zx Zy Zz ]   [ vz ]   [ vz' ]

func (*V3) MultQ

func (v *V3) MultQ(a *V3, q *Q) *V3

MultQ (*) multiplies a vector by quaternion, effectively applying the rotation of quaternion q to vector a and storing the result in v. The input vector a, and quaternion q are unchanged.

func (*V3) MultvM

func (v *V3) MultvM(rv *V3, m *M3) *V3

MultvM updates vector v to be the multiplication of row vector rv and matrix m. Vector v may be used as the input vector rv. The updated vector v is returned.

               [ Xx Xy Xz ]
[ vx vy vz ] x [ Yx Yy Yz ] = [ vx' vy' vz' ]
               [ Zx Zy Zz ]

func (*V3) Neg

func (v *V3) Neg(a *V3) *V3

Neg (-) sets vector v to be the negative values of vector a. Vector v may be used as the input parameter. The updated vector v is returned.

func (*V3) Nlerp

func (v *V3) Nlerp(a, b *V3, ratio float64) *V3

Nlerp updates vector v to be a normalized vector that is the linerar interpolation between a and b. See:

http://keithmaggio.wordpress.com/2011/02/15/math-magician-lerp-slerp-and-nlerp/
http://number-none.com/product/Understanding%20Slerp,%20Then%20Not%20Using%20It/

The calling vector v may be used as either or both of the input parameters.

func (*V3) Plane

func (v *V3) Plane(p, q *V3)

Plane generates 2 vectors perpendicular to normal vector v. The perpendicular vectors and are returned as values of vectors p and q.

Based on bullet physics: btVector3::btPlaneSpace1

func (*V3) Scale

func (v *V3) Scale(a *V3, s float64) *V3

Scale (*=) updates the elements in vector v by multiplying the corresponding elements in vector a by the given scalar value. Vector v may be used as one or both of the vector parameters. The updated vector v is returned.

func (*V3) Set

func (v *V3) Set(a *V3) *V3

Set (=, copy, clone) sets the elements of vector v to have the same values as the elements of vector a. The updated vector v is returned.

func (*V3) SetS

func (v *V3) SetS(x, y, z float64) *V3

SetS (=) sets the vector elements to the given values. The updated vector v is returned.

func (*V3) Sub

func (v *V3) Sub(a, b *V3) *V3

Sub (-) subtracts vectors b from a storing the results of the subtraction in v. Vector v may be used as one or both of the parameters. For example (-=) is

v.Sub(v, b)

The updated vector v is returned.

func (*V3) Swap

func (v *V3) Swap(a *V3) *V3

Swap exchanges the element values of vectors v and a. The updated vector v is returned. Vector a is also updated.

func (*V3) Unit

func (v *V3) Unit() *V3

Unit updates vector v such that its length is 1. Calling vector v is unchanged if its length is zero. The updated vector v is returned.

type V4

type V4 struct {
	X float64 // increments as X moves to the right.
	Y float64 // increments as Y moves up from bottom left.
	Z float64 // increments as Z moves out of the screen (right handed view space).
	W float64 // fourth dimension makes for nice 3D matrix math.
}

V4 is a 4 element vector. It can be used for points and directions where, as a point it would have W:1, and as a direction it would have W:0.

func NewV4

func NewV4() *V4

NewV4 creates a new, all zero, 4D vector.

func NewV4S

func NewV4S(x, y, z, w float64) *V4

NewV4S creates a new 3D vector using the given scalars.

func (*V4) Abs

func (v *V4) Abs() *V4

Abs updates vector v to have the absolute value of the elements of vector a. Same behaviour as V3.Abs().

func (*V4) Add

func (v *V4) Add(a, b *V4) *V4

Add (+) adds vectors a and b storing the results of the addition in v. Same behaviour as V3.Add().

func (*V4) AeqZ

func (v *V4) AeqZ() bool

AeqZ (~=) almost equals zero returns true if the square length of the vector is close enough to zero that it makes no difference.

func (*V4) Div

func (v *V4) Div(s float64) *V4

Div (/= inverse-scale) divides each element in v by the given scalar value. Same behaviour as V3.Div().

func (*V4) Dot

func (v *V4) Dot(a *V4) float64

Dot vector v with input vector a. Same behaviour as V3.Dot()

func (*V4) Eq

func (v *V4) Eq(a *V4) bool

Eq (==) returns true if each element in the vector v has the same value as the corresponding element in vector a.

func (*V4) GetS

func (v *V4) GetS() (x, y, z, w float64)

GetS returns the float64 values of the vector.

func (*V4) Len

func (v *V4) Len() float64

Len returns the length of vector v. Same behaviour as V3.Len()

func (*V4) LenSqr

func (v *V4) LenSqr() float64

LenSqr returns the length of vector v squared. Same behaviour as V3.LenSqr()

func (*V4) Lerp

func (v *V4) Lerp(a, b *V4, ratio float64) *V4

Lerp updates vector v to be a fraction of the distance (linear interpolation) between the input vectors a and b. Same behaviour as V3.Lerp()

func (*V4) Max

func (v *V4) Max(a, b *V4) *V4

Max updates the vector v elements to be the maximum of the corresponding elements from either vectors a or b. Same behaviour as V3.Max().

func (*V4) Min

func (v *V4) Min(a, b *V4) *V4

Min updates the vector v elements to be the minimum of the corresponding elements from either vectors a or b. Same behaviour as V3.Min().

func (*V4) Mult

func (v *V4) Mult(a, b *V4) *V4

Mult (*) multiplies the elements of vectors a and b storing the result in v. Same behaviour as V3.Mult().

func (*V4) MultMv

func (v *V4) MultMv(m *M4, cv *V4) *V4

MultMv updates vector v to be the multiplication of matrix m and column vector cv. Same behaviour as V3.MultMv().

[ Xx Xy Xz Xw ]   [ vx ]   [ vx' ]
[ Yx Yy Yz Yw ] x [ vy ] = [ vy' ]
[ Zx Zy Zz Zw ]   [ vz ]   [ vz' ]
[ Wx Wy Wz Ww ]   [ vw ]   [ vw' ]

func (*V4) MultvM

func (v *V4) MultvM(rv *V4, m *M4) *V4

MultvM updates vector v to be the multiplication of row vector rv and matrix m. Same behaviour as V4.MultvM().

                  [ Xx Xy Xz Xw ]
[ vx vy vz vw ] x [ Yx Yy Yz Yw ] = [ vx' vy' vz' vw']
                  [ Zx Zy Zz Zw ]
                  [ Wx Wy Wz Ww ]

func (*V4) Neg

func (v *V4) Neg(a *V4) *V4

Neg (-) sets vector v to be the negative values of vector a. Same behaviour as V3.Neg().

func (*V4) Nlerp

func (v *V4) Nlerp(a, b *V4, ratio float64) *V4

Nlerp updates vector v to be a normalized vector that is the linerar interpolation between a and b. Same behaviour as V3.Lerp()

func (*V4) Scale

func (v *V4) Scale(a *V4, s float64) *V4

Scale (*=) updates the elements in vector v by multiplying the corresponding elements in vector a by the given scalar value. Same behaviour as V3.Scale().

func (*V4) Set

func (v *V4) Set(a *V4) *V4

Set (=, copy, clone) sets the elements of vector v to have the same values as the elements of vector a. The updated vector v is returned.

func (*V4) SetS

func (v *V4) SetS(x, y, z, w float64) *V4

SetS (=) sets the vector elements to the given values. The updated vector v is returned.

func (*V4) Sub

func (v *V4) Sub(a, b *V4) *V4

Sub (-) subtracts vectors b from a storing the results of the subtraction in v. Same behaviour as V3.Sub().

func (*V4) Swap

func (v *V4) Swap(a *V4) *V4

Swap exchanges the element values of vectors v and a. Same behaviour as V3.Swap().

func (*V4) Unit

func (v *V4) Unit() *V4

Unit updates vector v such that its length is 1. Same behaviour as V3.Unit()

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL