Documentation
¶
Overview ¶
package ms3 is a 32bit 3D math package based around the Vec type.
This is a different take compared to mgl32, a package that treats all data equally by giving them their own namespace with methods. This package is more similar to gonum's take on spatial operations where package-level functions like `Add` are reserved specifically for vector operations, which tend to be the most common. This aids in readability since long string of operations using methods can be remarkably hard to follow.
The name roughly stands for (m)ath for (s)hort floats in (3)D. "short" since there are no native 16 bit floats in Go.
Index ¶
- func Cos(p, q Vec) float32
- func Divergence(p, step Vec, field func(Vec) Vec) float32
- func Dot(p, q Vec) float32
- func EqualElem(a, b Vec, tol float32) bool
- func EqualMat3(a, b Mat3, tolerance float32) bool
- func EqualMat4(a, b Mat4, tolerance float32) bool
- func Norm(p Vec) float32
- func Norm2(p Vec) float32
- func Sort(a, b, c float32) (l1, l2, l3 float32)
- type Box
- func (a Box) Add(v Vec) Box
- func (a Box) Canon() Box
- func (a Box) Center() Vec
- func (a Box) Contains(point Vec) bool
- func (a Box) Diagonal() float32
- func (a Box) Empty() bool
- func (a Box) Equal(b Box, tol float32) bool
- func (a Box) IncludePoint(point Vec) Box
- func (a Box) Intersect(b Box) (intersect Box)
- func (a Box) Scale(scale Vec) Box
- func (a Box) ScaleCentered(scale Vec) Box
- func (a Box) Size() Vec
- func (a Box) Union(b Box) Box
- func (a Box) Vertices() [8]Vec
- func (a Box) Volume() float32
- type Line
- type Mat3
- func (m Mat3) Array() (rowmajor [9]float32)
- func (m Mat3) AsMat4() Mat4
- func (a Mat3) Determinant() float32
- func (a Mat3) Inverse() Mat3
- func (m Mat3) Put(b []float32)
- func (b Mat3) QRDecomposition() (q, r Mat3)
- func (a Mat3) SVD() (U, S, V Mat3)
- func (a Mat3) Transpose() Mat3
- func (m Mat3) VecCol(j int) Vec
- func (m Mat3) VecDiag() Vec
- func (m Mat3) VecRow(i int) Vec
- type Mat4
- type Quat
- func AnglesToQuat(angle1, angle2, angle3 float32, order RotationOrder) Quat
- func QuatIdent() Quat
- func QuatLerp(q1, q2 Quat, amount float32) Quat
- func QuatLookAt(eye, center, upDir Vec) Quat
- func QuatNlerp(q1, q2 Quat, amount float32) Quat
- func QuatSlerp(q1, q2 Quat, amount float32) Quat
- func RotationBetweenVecsQuat(start, dest Vec) Quat
- func RotationQuat(angle float32, axis Vec) Quat
- func (q1 Quat) Add(q2 Quat) Quat
- func (q1 Quat) Conjugate() Quat
- func (q1 Quat) Dot(q2 Quat) float32
- func (q Quat) IJK() Vec
- func (q1 Quat) Inverse() Quat
- func (q1 Quat) Mul(q2 Quat) Quat
- func (q1 Quat) Norm() float32
- func (q1 Quat) Rotate(v Vec) Vec
- func (q Quat) RotationMat3() Mat3
- func (q1 Quat) Scale(c float32) Quat
- func (q1 Quat) Sub(q2 Quat) Quat
- func (q1 Quat) Unit() Quat
- func (q Quat) WithIJK(ijk Vec) Quat
- type RotationOrder
- type Triangle
- type Vec
- func AbsElem(a Vec) Vec
- func Add(p, q Vec) Vec
- func AddScalar(f float32, v Vec) Vec
- func AppendGrid(dst []Vec, bounds Box, nx, ny, nz int) []Vec
- func CeilElem(a Vec) Vec
- func ClampElem(v, Min, Max Vec) Vec
- func CosElem(a Vec) Vec
- func Cross(p, q Vec) Vec
- func DivElem(a, b Vec) Vec
- func FloorElem(a Vec) Vec
- func Gradient(p, step Vec, field func(Vec) float32) Vec
- func InterpElem(x, y, a Vec) Vec
- func MaxElem(a, b Vec) Vec
- func MinElem(a, b Vec) Vec
- func MulElem(a, b Vec) Vec
- func MulMatVec(m Mat3, v Vec) (result Vec)
- func MulMatVecTrans(m Mat3, v Vec) (result Vec)
- func RoundElem(a Vec) Vec
- func Scale(f float32, p Vec) Vec
- func SignElem(a Vec) Vec
- func SinElem(a Vec) Vec
- func SincosElem(a Vec) (s, c Vec)
- func SmoothStepElem(e0, e1, x Vec) Vec
- func Sub(p, q Vec) Vec
- func Unit(p Vec) Vec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Divergence ¶
Divergence returns the divergence of the vector field at the point p, approximated using finite differences with the given step sizes.
Types ¶
type Box ¶
type Box struct {
Min, Max Vec
}
Box is a 3D bounding box. Well formed Boxes Min components are smaller than Max components. Max is the most positive/largest vertex, Min is the most negative/smallest vertex.
func NewBox ¶
NewBox is shorthand for Box{Min:Vec{x0,y0,z0}, Max:Vec{x1,y1,z1}}. The sides are swapped so that the resulting Box is well formed.
func NewCenteredBox ¶
NewCenteredBox returns a box centered around center with size dimensions.
func (Box) Add ¶
Add adds v to the bounding box components. It is the equivalent of translating the Box by v.
func (Box) Canon ¶
Canon returns the canonical version of a. The returned Box has minimum and maximum coordinates swapped if necessary so that it is well-formed.
func (Box) Empty ¶
IsEmpty returns true if a Box's volume is zero or if a Min component is greater than its Max component.
func (Box) Equal ¶
Equal returns true if a and b are within tol of eachother for each box limit component.
func (Box) IncludePoint ¶
IncludePoint returns a box containing both the receiver and the argument point.
func (Box) Scale ¶
Scale scales the box dimensions and positions in 3 directions. Does not preserve box center. Negative elements of scale can be used to mirror box dimension.
func (Box) ScaleCentered ¶
ScaleCentered returns a new Box scaled by a size vector around its center. The scaling is done element wise which is to say the Box's X dimension is scaled by scale.X. Negative elements of scale are interpreted as zero.
func (Box) Vertices ¶
Vertices returns a slice of the 8 vertices corresponding to each of the Box's corners.
Ordering of vertices 0-3 is CCW in the XY plane starting at box minimum. Ordering of vertices 4-7 is CCW in the XY plane starting at box minimum for X and Y values and maximum Z value.
Edges for the box can be constructed with the following indices:
edges := [12][2]int{
{0, 1}, {1, 2}, {2, 3}, {3, 0},
{4, 5}, {5, 6}, {6, 7}, {7, 4},
{0, 4}, {1, 5}, {2, 6}, {3, 7},
}
type Line ¶
type Line [2]Vec
Line is an infinite 3D line defined by two points on the line.
func (Line) Distance ¶
Distance returns the minimum euclidean Distance of point p to the infinite line.
func (Line) Interpolate ¶
Interpolate takes a value between 0 and 1 to linearly interpolate a point on the line.
Interpolate(0) returns l[0] Interpolate(1) returns l[1]
type Mat3 ¶
type Mat3 struct {
// contains filtered or unexported fields
}
Mat3 is a 3x3 matrix.
func NewMat3 ¶
NewMat3 instantiates a new matrix from the first 9 floats, row major order. If v is of insufficient length NewMat3 panics.
func RotatingMat3 ¶
RotatingMat3 returns a 3×3 rotation matrix corresponding to the receiver. It may be used to perform rotations on a 3-vector or to apply the rotation to a 3×n matrix of column vectors. If the receiver is not a unit quaternion, the returned matrix will not be a pure rotation.
func Skew ¶
Skew returns the 3×3 skew symmetric matrix (right hand system) of v.
⎡ 0 -z y⎤
Skew({x,y,z}) = ⎢ z 0 -x⎥
⎣-y x 0⎦
func (Mat3) AsMat4 ¶
AsMat4 expands the Mat3 to fill the first rows and columns of a Mat4 and sets the last diagonal element of the Mat4 to 1.
func (Mat3) Determinant ¶
Determinant returns the determinant of a 3x3 matrix.
func (Mat3) Put ¶
Put stores the matrix values into slice b in row major order. If b is not of length 9 or greater Put panics.
func (Mat3) QRDecomposition ¶
QRDecomposition performs QR decomposition of a 3x3 matrix using Mat3 type.
type Mat4 ¶
type Mat4 struct {
// contains filtered or unexported fields
}
Mat4 is a 4x4 matrix.
func NewMat4 ¶
NewMat4 instantiates a new 4x4 Mat4 matrix from the first 16 values in row major order. If v is shorter than 16 NewMat4 panics.
func RotatingBetweenVecsMat4 ¶
RotatingBetweenVecsMat4 returns the rotation matrix that transforms "start" onto the same direction as "dest".
func RotatingMat4 ¶
RotatingMat4 returns an orthographic 4x4 rotation matrix (right hand rule).
func ScalingMat4 ¶
ScalingMat4 returns a 4x4 scaling matrix. Scaling does not preserve distance. See: ScaleUniform3D()
func TranslatingMat4 ¶
TranslatingMat4 returns a 4x4 translation matrix.
func (Mat4) Determinant ¶
Determinant returns the determinant of a 4x4 matrix.
func (Mat4) MulPosition ¶
MulPosition multiplies a r3.Vec position with a rotate/translate matrix.
type Quat ¶
Quat 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.
The imaginary V part is guaranteed to have an offset of zero in the Quat struct:
unsafe.Offsetof(q.V) // == 0
func AnglesToQuat ¶
func AnglesToQuat(angle1, angle2, angle3 float32, order RotationOrder) Quat
AnglesToQuat 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 QuatIdent ¶
func QuatIdent() Quat
QuatIdent 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 QuatLerp ¶
QuatLerp is a *L*inear Int*erp*olation between two Quaternions, cheap and simple.
Not excessively useful, but uses can be found.
func QuatLookAt ¶
QuatLookAt creates a rotation from an eye point to a center point.
It assumes the front of the rotated object at Z- and up at Y+
func QuatNlerp ¶
QuatNlerp 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 QuatSlerp ¶
QuatSlerp is Spherical Linear intERPolation, 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 QuatSlerp(q1,q2) is not the same as QuatSlerp(q2,q1)
func RotationBetweenVecsQuat ¶
RotationBetweenVecsQuat calculates the rotation between start and dest.
func RotationQuat ¶
RotationQuat creates a rotation quaternion that rotates an angle relative an axis. Call Rotate method on Quat to apply rotation.
func (Quat) Add ¶
Add adds two quaternions. It's no more complicated than adding their W and V components.
func (Quat) Conjugate ¶
Conjugate returns the conjugate of a quaternion. Equivalent to Quat{q1.W, q1.V.Mul(-1)}.
func (Quat) Inverse ¶
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 (Quat) Mul ¶
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 (Quat) Rotate ¶
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 (Quat) RotationMat3 ¶
RotationMat3 returns a rotation 3x3 matrix.
func (Quat) Sub ¶
Sub subtracts two quaternions. It's no more complicated than subtracting their W and V components.
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 Triangle ¶
type Triangle [3]Vec
Triangle represents a triangle in 3D space and is composed by 3 vectors corresponding to the position of each of the vertices. Ordering of these vertices decides the "normal" direction. Inverting ordering of two vertices inverts the resulting direction.
func (Triangle) Centroid ¶
Centroid returns the intersection of the three medians of the triangle as a point in space.
func (Triangle) IsDegenerate ¶
IsDegenerate returns true if all of triangle's vertices are within tol distance of its longest side.
type Vec ¶
type Vec struct {
X, Y, Z float32
// contains filtered or unexported fields
}
Vec is a 3D vector. It is composed of 3 float32 fields for x, y, and z values in that order. Padding is added to reach 16 byte size for use with OpenGL with 1-to-1 mapping with vec3 and dvec3 types.
func AppendGrid ¶
AppendGrid splits the argument bounds Box x,y,z axes by nx,ny,nz, respectively and generates points on the vertices generated by the division and appends them to dst, returning the result.
Indexing is x-major, y-second-major:
grid := ms3.AppendGrid(nil, bb, nx, ny, nz) ix, iy, iz := 1, 0, 3 pos := grid[iz*(nx+ny) + iy*nx + ix]
func DivElem ¶
DivElem returns the Hadamard product between vector a and the inverse components of vector b.
v = {a.X/b.X, a.Y/b.Y, a.Z/b.Z}
func Gradient ¶
Gradient returns the gradient of the scalar field at the point p, approximated using finite differences with the given step sizes.
func InterpElem ¶
InterpElem performs a linear interpolation between x and y's elements, mapping with a's values in interval [0,1]. This function is also known as "mix" in OpenGL.
func MulElem ¶
MulElem returns the Hadamard product between vectors a and b.
v = {a.X*b.X, a.Y*b.Y, a.Z*b.Z}
func MulMatVecTrans ¶
MulMatVecTrans Performs transposed matrix multiplication on v:
result = Mᵀ * v
func SignElem ¶
Sign returns sign function applied to each individual component of a. If a component is zero then zero is returned.
func SincosElem ¶
SincosElem returns (sin(a), cos(a)). Is more efficient than calling both SinElem and CosElem.
func SmoothStepElem ¶
SmoothStepElem performs element-wise smooth cubic hermite interpolation between 0 and 1 when e0 < x < e1.
func Unit ¶
Unit returns the unit vector colinear to p. Unit returns {NaN,NaN,NaN} for the zero vector.
func (Vec) AllNonzero ¶
AllNonzero returns true if all elements of a are nonzero.
Source Files