3d transforms

1.0.0

A utility library implementing a common structure to encapsulate spatial transformations

About 3d-transforms

This is a library that uses the other 3d-* math libraries to present an encapsulation for a spatial transformation. It offers convenience functions for operating on such transformations and for converting between them and the alternative 4x4 matrix representation.

Typically you will want a transform representation like this rather than a direct matrix representation, as it preserves the components of the transform and avoids issues like gimbal lock through the use of quaternions.

How To

Load it through ASDF or Quicklisp

(ql:quickload :3d-transforms)
(use-package :org.shirakumo.flare.transform)

Create a transform:

(transform)

And then move it around

(tmove-by * 1 2 3)
(tscale-by * 2 1 1)
(trotate-by * 3d-vectors:+vy+ PI)

If you would then like to transform a point from the space local to the transform to the global space, you can use t*p

(t*p * (vec 1 2 3))

Alternatively if you need a matrix representation in order to, say, upload to the GPU, you can use tmat4. If you need to stack transforms, you can do so by adding them together via t+ or nt+.

Underneath a transform is just a combination of a tlocation vector, a tscaling vector, and a trotation quaternion. You can access and directly manipulate these values as well if needed.

Also See

3d-vectors for Vector operations in conjunction with this library.
3d-matrices for Matrix operations in conjunction with this library.
3d-quaternions for Quaternion operations in conjunction with this library.

System Information

Version: 1.0.0

Dependencies:

Author: Nicolas Hafner

License: zlib

Homepage: https://Shinmera.github.io/3d-transforms/

Sources: https://github.com/Shinmera/3d-transforms.git

Definition Index

ORG.SHIRAKUMO.FLARE.TRANSFORM

No documentation provided.

EXTERNAL STRUCTURE

TRANSFORM

Encapsulation of a spatial transform.

A transform holds a translation, rotation, and scaling.
By nesting transforms you can create relative coordinate systems.

A transform is readable and dumpable, meaning it can be inlined at
compile-time and printed and read back.

See TRANSFORM (function)
See TRANSFORM-P
See COPY-TRANSFORM
See TLOCATION
See TSCALING
See TROTATION
See T+
See NT+
See T=
See T~=
See T*V
See T*P
See TINV
See TMIX
See TMAT4
See TFROM-MAT
See TMOVE
See TMOVE-BY
See TOFFSET
See TOFFSET-BY
See TROTATE
See TROTATE-BY
See TSCALE
See TSCALE-BY

EXTERNAL FUNCTION

COPY-TRANSFORM

A

Creates a deep copy of the transform.

The returned transform does NOT share its location, scale, or rotation
components.

See TRANSFORM (type)

EXTERNAL FUNCTION

NT+

A
B

Modifies the first transform such that it encompasses the transform B on top of itself.


See T+
See TRANSFORM (type)

EXTERNAL FUNCTION

T*P

A
V

Applies the transform to the given point.

This transforms the point completely by the coordinate system
represented by the transform.

See T*P
See VEC3 (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

T*V

A
V

Applies the transform to the given vector.

This scales and rotates the vector, but does not translate it.

See T*P
See VEC3 (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

T+

A
B

Returns a transform that encompasses the combination of transform B on top of A.

This is particularly important in regard to the location expressed by
the transform, as the rotation has to be taken into account properly.

See NT+
See TRANSFORM (type)

EXTERNAL FUNCTION

T=

A
B

Compares both transforms component-wise and returns true if each component is v=/q=.

See TRANSFORM (type)

EXTERNAL FUNCTION

TFROM-MAT

MAT

Returns a transform that represents the same linear transformation as the matrix, if possible.

See MAT4 (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

TINV

A

Returns the inverses of the given transform.

This is not a precise inversion, instead performing an approximation
for speed.

See TRANSFORM (type)

EXTERNAL FUNCTION

TLOCATION

INSTANCE

Accesses the location or position component of the transform.

See TRANSFORM (type)

EXTERNAL FUNCTION
(SETF TLOCATION)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

TMAT4

A

Returns a 4x4 matrix that encompasses the same transformation as the transform's components encompass.

See MAT4 (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

TMIX

FROM
TO
X

Returns a new transform that is the linear interpolation between the two at the given point.

X should be a REAL in the range of [0,1].

See TRANSFORM (type)

EXTERNAL FUNCTION

TMOVE

A
V

Moves the transform space by the given vector.

This is equivalent to

  (nt+ a (transform v))

Note that as a consequence, this is relative to the rotation
encompassed by the transform.

See TMOVE-BY
See TOFFSET
See VEC3 (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

TMOVE-BY

A
X
Y
Z

Moves the transform space by the given amount in each axis.

This is equivalent to

  (nt+ a (transform (vec x y z)))

Note that as a consequence, this is relative to the rotation
encompassed by the transform.

See TMOVE
See TOFFSET-BY
See VEC3 (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

TOFFSET

A
V

Offsets the transform in the basic cartesian space by the given vector.

This is equivalent to

  (nv+ (tlocation a) v)

Note that as a consequence, this is NOT relative to the rotation
encompassed by the transform.

See TMOVE
See TOFFSET-BY
See VEC3 (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

TOFFSET-BY

A
X
Y
Z

Offsets the transform in the basic cartesian space by the given amount in each axis.

This is equivalent to

  (nv+ (tlocation a) (vec x y z))

Note that as a consequence, this is NOT relative to the rotation
encompassed by the transform.

See TMOVE
See TOFFSET-BY
See VEC3 (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

TRANSFORM

&OPTIONAL
LOCATION
SCALING
ROTATION

Creates a new transform.

Note that the given location, scale, and rotation are shared and NOT
copied. Any change to them will thus reflect within the transform.

If not passed, they default to "neutral" values, meaning:
  0,0,0 for location,
  1,1,1 for scale,
  0,0,0,1 for rotation

See TRANSFORM (type)

EXTERNAL FUNCTION

TRANSFORM-P

OBJECT

Returns true if the given value is a TRANSFORM structure.

See TRANSFORM (type)

EXTERNAL FUNCTION

TROTATE

A
Q

Rotates the transform space by the given quaternion.

This is equivalent to

  (nq* (trotation a) q)

See TROTATE-BY
See QUAT (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

TROTATE-BY

A
AXIS
ANGLE

Rotates the transform space around the given axis by the given angle.

This is equivalent to

  (nq* (trotation a) (qfrom-angle axis angle))

See TROTATE
See QUAT (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

TROTATION

INSTANCE

Accesses the rotational component of the transform.

See TRANSFORM (type)

EXTERNAL FUNCTION
(SETF TROTATION)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

TSCALE

A
V

Scales the transform space by the given vector.

This is equivalent to

  (nv+ (tscaling a) v)

See TSCALE-BY
See VEC3 (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

TSCALE-BY

A
X
Y
Z

Scales the transform space by the given amount in each axis.

This is equivalent to

  (nv+ (tscaling a) (vec x y z))

See TSCALE
See VEC3 (type)
See TRANSFORM (type)

EXTERNAL FUNCTION

TSCALING

INSTANCE

Accesses the scaling component of the transform.

See TRANSFORM (type)

EXTERNAL FUNCTION
(SETF TSCALING)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

T~=

A
B

Compares both transforms component-wise and returns true if each component is v~=/qequal.

See TRANSFORM (type)