The 3d-transforms Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The 3d-transforms Reference Manual

This is the 3d-transforms Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 03:10:35 2022 GMT+0.

Table of Contents


1 Introduction

## 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"(https://shinmera.github.io/3d-vectors) for Vector operations in conjunction with this library.
- "3d-matrices"(https://shinmera.github.io/3d-matrices) for Matrix operations in conjunction with this library.
- "3d-quaternions"(https://shinmera.github.io/3d-quaternions) for Quaternion operations in conjunction with this library.


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 3d-transforms

A utility library implementing a common structure to encapsulate spatial transformations

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

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

Source Control

(GIT https://github.com/Shinmera/3d-transforms.git)

Bug Tracker

https://github.com/Shinmera/3d-transforms/issues

License

zlib

Version

1.0.0

Dependencies
  • documentation-utils (system).
  • 3d-vectors (system).
  • 3d-matrices (system).
  • 3d-quaternions (system).
Source

3d-transforms.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 3d-transforms/3d-transforms.asd

Source

3d-transforms.asd.

Parent Component

3d-transforms (system).

ASDF Systems

3d-transforms.


3.1.2 3d-transforms/package.lisp

Source

3d-transforms.asd.

Parent Component

3d-transforms (system).

Packages

org.shirakumo.flare.transform.


3.1.3 3d-transforms/struct.lisp

Dependency

package.lisp (file).

Source

3d-transforms.asd.

Parent Component

3d-transforms (system).

Public Interface

3.1.4 3d-transforms/ops.lisp

Dependency

struct.lisp (file).

Source

3d-transforms.asd.

Parent Component

3d-transforms (system).

Public Interface
Internals

Previous: , Up: Lisp   [Contents][Index]

3.1.5 3d-transforms/documentation.lisp

Dependency

ops.lisp (file).

Source

3d-transforms.asd.

Parent Component

3d-transforms (system).


4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 org.shirakumo.flare.transform

Source

package.lisp.

Use List
  • 3d-matrices.
  • 3d-vectors.
  • common-lisp.
  • org.shirakumo.flare.quaternion.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

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)

Package

org.shirakumo.flare.transform.

Source

struct.lisp.

Function: nt+ (a b)

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

See T+
See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

Function: t<- (target source)

Copies the transform information into the target from the source.

See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

Function: t= (a b)

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

See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

Function: tfrom-mat (mat)

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

See MAT4 (type)
See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

Reader: tlocation (instance)

Accesses the location or position component of the transform.

See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

struct.lisp.

Target Slot

location.

Writer: (setf tlocation) (instance)
Package

org.shirakumo.flare.transform.

Source

struct.lisp.

Target Slot

location.

Function: tmat4 (a &optional mat)

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

See MAT4 (type)
See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

struct.lisp.

Function: transform-p (object)

Returns true if the given value is a TRANSFORM structure.

See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

struct.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

Reader: trotation (instance)

Accesses the rotational component of the transform.

See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

struct.lisp.

Target Slot

rotation.

Writer: (setf trotation) (instance)
Package

org.shirakumo.flare.transform.

Source

struct.lisp.

Target Slot

rotation.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

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)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.

Reader: tscaling (instance)

Accesses the scaling component of the transform.

See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

struct.lisp.

Target Slot

scaling.

Writer: (setf tscaling) (instance)
Package

org.shirakumo.flare.transform.

Source

struct.lisp.

Target Slot

scaling.

Function: t~= (a b)

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

See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.


5.1.2 Standalone methods

Method: make-load-form ((transform transform) &optional env)
Source

struct.lisp.

Method: print-object ((transform transform) stream)
Source

struct.lisp.


5.1.3 Structures

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 TDQUAT
See TFROM-DQUAT
See TMOVE
See TMOVE-BY
See TOFFSET
See TOFFSET-BY
See TROTATE
See TROTATE-BY
See TSCALE
See TSCALE-BY

Package

org.shirakumo.flare.transform.

Source

struct.lisp.

Direct superclasses

structure-object.

Direct methods
Direct slots
Slot: location
Type

3d-vectors:vec3

Readers

tlocation.

Writers

(setf tlocation).

Slot: scaling
Type

3d-vectors:vec3

Readers

tscaling.

Writers

(setf tscaling).

Slot: rotation
Type

org.shirakumo.flare.quaternion:quat

Readers

trotation.

Writers

(setf trotation).


5.2 Internals


Previous: , Up: Internals   [Contents][Index]

5.2.1 Ordinary functions

Function: tdquat (a &optional dq)
Package

org.shirakumo.flare.transform.

Source

ops.lisp.

Function: tfrom-dquat (dq &optional a)

Returns a transform that represents the same linear transformation as the dual-quaternion.

See DQUAT (type)
See TRANSFORM (type)

Package

org.shirakumo.flare.transform.

Source

ops.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
C   F   M   N   P   T  
Index Entry  Section

(
(setf tlocation): Public ordinary functions
(setf trotation): Public ordinary functions
(setf tscaling): Public ordinary functions

C
copy-transform: Public ordinary functions

F
Function, (setf tlocation): Public ordinary functions
Function, (setf trotation): Public ordinary functions
Function, (setf tscaling): Public ordinary functions
Function, copy-transform: Public ordinary functions
Function, nt+: Public ordinary functions
Function, t*p: Public ordinary functions
Function, t*v: Public ordinary functions
Function, t+: Public ordinary functions
Function, t<-: Public ordinary functions
Function, t=: Public ordinary functions
Function, tdquat: Private ordinary functions
Function, tfrom-dquat: Private ordinary functions
Function, tfrom-mat: Public ordinary functions
Function, tinv: Public ordinary functions
Function, tlocation: Public ordinary functions
Function, tmat4: Public ordinary functions
Function, tmix: Public ordinary functions
Function, tmove: Public ordinary functions
Function, tmove-by: Public ordinary functions
Function, toffset: Public ordinary functions
Function, toffset-by: Public ordinary functions
Function, transform: Public ordinary functions
Function, transform-p: Public ordinary functions
Function, trotate: Public ordinary functions
Function, trotate-by: Public ordinary functions
Function, trotation: Public ordinary functions
Function, tscale: Public ordinary functions
Function, tscale-by: Public ordinary functions
Function, tscaling: Public ordinary functions
Function, t~=: Public ordinary functions

M
make-load-form: Public standalone methods
Method, make-load-form: Public standalone methods
Method, print-object: Public standalone methods

N
nt+: Public ordinary functions

P
print-object: Public standalone methods

T
t*p: Public ordinary functions
t*v: Public ordinary functions
t+: Public ordinary functions
t<-: Public ordinary functions
t=: Public ordinary functions
tdquat: Private ordinary functions
tfrom-dquat: Private ordinary functions
tfrom-mat: Public ordinary functions
tinv: Public ordinary functions
tlocation: Public ordinary functions
tmat4: Public ordinary functions
tmix: Public ordinary functions
tmove: Public ordinary functions
tmove-by: Public ordinary functions
toffset: Public ordinary functions
toffset-by: Public ordinary functions
transform: Public ordinary functions
transform-p: Public ordinary functions
trotate: Public ordinary functions
trotate-by: Public ordinary functions
trotation: Public ordinary functions
tscale: Public ordinary functions
tscale-by: Public ordinary functions
tscaling: Public ordinary functions
t~=: Public ordinary functions

Jump to:   (  
C   F   M   N   P   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   L   R   S  
Index Entry  Section

L
location: Public structures

R
rotation: Public structures

S
scaling: Public structures
Slot, location: Public structures
Slot, rotation: Public structures
Slot, scaling: Public structures

Jump to:   L   R   S