Version: v0.10.0 Latest Latest Go to latest
Published: Sep 4, 2018 License: BSD-2-Clause, Zlib

## 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.

### Constants ¶

View Source
```const (

// PI and its commonly needed variants.
PI     float64 = math.Pi
PIx2   float64 = PI * 2
HalfPi float64 = PIx2 * 0.25

// 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`

#### 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(deg float64) float64`

#### 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 (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 (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 (m *M4) Add(a, b *M4) *M4`

#### 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 *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/
```

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 (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 (v *V4) Add(a, b *V4) *V4`

#### 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()