Basis

Documentation

Overview

Package Basis is a 3×3 matrix for representing 3D rotation and scale.

Index

• Variables
• func AsEulerAngles(b XYZ, order Angle.Order) Angle.Euler3D
• func AsQuaternion(b XYZ) quaternion
• func Determinant(b XYZ) Float.X
• func IsApproximatelyEqual(a, b XYZ) bool
• func IsConformal(b XYZ) bool
• func IsFinite(b XYZ) bool
• func Scale(b XYZ) Vector3.XYZ
• func Transform(v Vector3.XYZ, m XYZ) Vector3.XYZ
• func TransposedDotX(b XYZ, v Vector3.XYZ) Float.X
• func TransposedDotY(b XYZ, v Vector3.XYZ) Float.X
• func TransposedDotZ(b XYZ, v Vector3.XYZ) Float.X
• type XYZ
  • func Euler(e Angle.Euler3D, order Angle.Order) XYZ
  • func Inverse(b XYZ) XYZ
  • func LookingAt(target, up Vector3.XYZ) XYZ
  • func Mul(a, b XYZ) XYZ
  • func New() XYZ
  • func Orthonormalized(b XYZ) XYZ
  • func Outer(v, with Vector3.XYZ) XYZ
  • func Rotated(b XYZ, axis Vector3.XYZ, angle Angle.Radians) XYZ
  • func RotatesAxisAngle(axis Vector3.XYZ, angle Angle.Radians) XYZ
  • func RotatesScales(q quaternion, s Vector3.XYZ) XYZ
  • func Scaled(b XYZ, scale Vector3.XYZ) XYZ
  • func Scales(scale Vector3.XYZ) XYZ
  • func Slerp[X Float.Any](a, b XYZ, weight X) XYZ
  • func Transposed(m XYZ) XYZ

Variables

var (
	// Identity basis. This is a basis with no rotation, no shear, and its
	// scale being 1. This means that:
	//
	//   - The x points right ([Vector3.Right]);
	//   - The y points up ([Vector3.Up]);
	//   - The z points back ([Vector3.Back]).
	Identity = XYZ{
		X: Vector3.Right,
		Y: Vector3.Up,
		Z: Vector3.Back,
	}

	// FlipX when any basis is multiplied by FlipX, it negates all components
	// of the x axis (the X column).
	//
	// When FlipX is multiplied by any basis, it negates the Vector3.X component
	// of all axes (the X row).
	FlipX = XYZ{
		X: Vector3.Left,
		Y: Vector3.Up,
		Z: Vector3.Back,
	}

	// FlipY when any basis is multiplied by FlipY, it negates all components
	// of the y axis (the Y column).
	//
	// When FlipY is multiplied by any basis, it negates the Vector3.Y component
	// of all axes (the Y row).
	FlipY = XYZ{
		X: Vector3.Right,
		Y: Vector3.Down,
		Z: Vector3.Back,
	}

	// FlipZ when any basis is multiplied by FlipZ, it negates all components
	// of the z axis (the Z column).
	//
	// When FlipZ is multiplied by any basis, it negates the Vector3.Z component
	// of all axes (the Z row).
	FlipZ = XYZ{
		X: Vector3.Right,
		Y: Vector3.Up,
		Z: Vector3.Forward,
	}
)

Functions

func AsEulerAngles

func AsEulerAngles(b XYZ, order Angle.Order) Angle.Euler3D

AsEulerAngles returns the basis's rotation in the form of Euler angles. The Euler order depends on the order parameter, by default it uses the YXZ convention: when decomposing, first Z, then X, and Y last. The returned vector contains the rotation angles in the format (X angle, Y angle, Z angle).

Consider using the [Basis.Quaternion] method instead, which returns a [Quaternion] quaternion instead of [EulerAngles].

func AsQuaternion

func AsQuaternion(b XYZ) quaternion

AsQuaternion returns the basis's rotation in the form of a quaternion. See AsEulerAngles if you need Euler angles, but keep in mind quaternions should generally be preferred to AsEulerAngles.

func Determinant

func Determinant(b XYZ) Float.X

Determinant returns the determinant of the basis matrix. If the basis is uniformly scaled, its determinant is the square of the scale.

A negative determinant means the basis has a negative scale. A zero determinant means the basis isn't invertible, and is usually considered invalid.

func IsApproximatelyEqual

func IsApproximatelyEqual(a, b XYZ) bool

IsApproximatelyEqual returns true if this basis and b are approximately equal, by calling IsApproximatelyEqual on all vector components.

func IsConformal

func IsConformal(b XYZ) bool

IsConformal returns true if the basis is conformal, meaning it preserves angles and distance ratios, and may only be composed of rotation and uniform scale. Returns false if the basis has non-uniform scale or shear/skew. This can be used to validate if the basis is non-distorted, which is important for physics and other use cases.

func IsFinite

func IsFinite(b XYZ) bool

IsFinite returns true if this basis is finite, by calling IsFinite on all vector components.

func Scale

func Scale(b XYZ) Vector3.XYZ

Scale assuming that the matrix is the combination of a rotation and scaling, returns the absolute value of scaling factors along each axis.

func Transform

func Transform(v Vector3.XYZ, m XYZ) Vector3.XYZ

func TransposedDotX

func TransposedDotX(b XYZ, v Vector3.XYZ) Float.X

TransposedDotX returns the transposed dot product with the X axis of the matrix.

func TransposedDotY

func TransposedDotY(b XYZ, v Vector3.XYZ) Float.X

TransposedDotY returns the transposed dot product with the Y axis of the matrix.

func TransposedDotZ

func TransposedDotZ(b XYZ, v Vector3.XYZ) Float.X

TransposedDotZ returns the transposed dot product with the Z axis of the matrix.

Types

type XYZ

type XYZ = struct {

	// The basis's X axis, and the column 0 of the matrix.
	//
	// On the identity basis, this vector points right ([Vector3.Right]).
	X Vector3.XYZ

	// The basis's Y axis, and the column 1 of the matrix.
	//
	// On the identity basis, this vector points up ([Vector3.Up]).
	Y Vector3.XYZ

	// The basis's Z axis, and the column 2 of the matrix.
	//
	// On the identity basis, this vector points back ([Vector3.Back]).
	Z Vector3.XYZ
}

The XYZ type is a 3×3 matrix used to represent 3D rotation, scale, and shear. It is frequently used within a Transform3D.

A Basis is composed by 3 axis vectors, each representing a column of the matrix: x, y, and z. The length of each axis (Vector3.Length) influences the basis's scale, while the direction of all axes influence the rotation. Usually, these axes are perpendicular to one another. However, when you rotate any axis individually, the basis becomes sheared. Applying a sheared basis to a 3D model will make the model appear distorted.

A Basis is orthogonal if its axes are perpendicular to each other. A basis is normalized if the length of every axis is 1. A basis is uniform if all axes share the same length (see get_scale). A basis is orthonormal if it is both orthogonal and normalized, which allows it to only represent rotations. A basis is conformal if it is both orthogonal and uniform, which ensures it is not distorted.

For a general introduction, see the Matrices and transforms tutorial.

Note: GD uses a right-handed coordinate system, which is a common standard. For directions, the convention for built-in types like Camera3D is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the 3D asset direction conventions tutorial.

func Euler

func Euler(e Angle.Euler3D, order Angle.Order) XYZ

Euler constructs a pure rotation Basis matrix from Euler angles in the specified Euler rotation order. By default, use YXZ order (most common). See the EulerOrder enum for possible values.

func Inverse

func Inverse(b XYZ) XYZ

Inverse returns the inverse of the matrix.

func LookingAt

func LookingAt(target, up Vector3.XYZ) XYZ

LookingAt creates a Basis with a rotation such that the forward axis (-Z) points towards the target position.

The up axis (+Y) points as close to the up vector as possible while staying perpendicular to the forward axis. The resulting Basis is orthonormalized. The target and up vectors cannot be zero, and cannot be parallel to each other.

If use_model_front is true, the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the target position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right).

func Mul

func Mul(a, b XYZ) XYZ

func New

func New() XYZ

New constructs a Basis identical to the Identity.

func Orthonormalized

func Orthonormalized(b XYZ) XYZ

Orthonormalized returns the orthonormalized version of the matrix (useful to call from time to time to avoid rounding error for orthogonal matrices). This performs a Gram-Schmidt orthonormalization on the basis of the matrix.

func Outer

func Outer(v, with Vector3.XYZ) XYZ

Outer returns the outer product with with.

func Rotated

func Rotated(b XYZ, axis Vector3.XYZ, angle Angle.Radians) XYZ

Rotated returns a copy of the basis rotated around the given axis by the given angle (in radians). The axis must be a normalized vector.

func RotatesAxisAngle

func RotatesAxisAngle(axis Vector3.XYZ, angle Angle.Radians) XYZ

NewBasisRotatedAround constructs a pure rotation basis matrix, rotated around the given axis by angle (in radians). The axis must be a normalized vector.

func RotatesScales

func RotatesScales(q quaternion, s Vector3.XYZ) XYZ

RotatesScales returns the basis from the given rotation Quaternion with the specified scale applied to it. This is equivalent to multiplying the basis with a scaling matrix.

func Scaled

func Scaled(b XYZ, scale Vector3.XYZ) XYZ

Scaled introduce an additional scaling specified by the given 3D scaling factor.

func Scales

func Scales(scale Vector3.XYZ) XYZ

Scales constructs a pure scale basis matrix with no rotation or shearing. The scale values are set as the diagonal of the matrix, and the other parts of the matrix are zero.

func Slerp

func Slerp[X Float.Any](a, b XYZ, weight X) XYZ

Slerp assuming that the matrix is a proper rotation matrix, slerp performs a spherical-linear interpolation with another rotation matrix.

func Transposed

func Transposed(m XYZ) XYZ

Transposed returns the transposed version of the matrix.