The 3d-transforms Reference Manual

Table of Contents

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 3.0 "Montgomery Scott" on Sun May 15 03:13:43 2022 GMT+0.


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

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.


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

2 Systems

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


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

2.1 3d-transforms

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

Description

A utility library implementing a common structure to encapsulate spatial transformations

Version

1.0.0

Dependencies
Source

3d-transforms.asd (file)

Components

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

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 files   [Contents][Index]

3.1.1 3d-transforms.asd

Location

3d-transforms.asd

Systems

3d-transforms (system)


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

3.1.2 3d-transforms/package.lisp

Parent

3d-transforms (system)

Location

package.lisp

Packages

org.shirakumo.flare.transform


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

3.1.3 3d-transforms/struct.lisp

Dependency

package.lisp (file)

Parent

3d-transforms (system)

Location

struct.lisp

Exported Definitions

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

3.1.4 3d-transforms/ops.lisp

Dependency

struct.lisp (file)

Parent

3d-transforms (system)

Location

ops.lisp

Exported Definitions
Internal Definitions

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

3.1.5 3d-transforms/documentation.lisp

Dependency

ops.lisp (file)

Parent

3d-transforms (system)

Location

documentation.lisp


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

4 Packages

Packages are listed by definition order.


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

4.1 org.shirakumo.flare.transform

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 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 (file)

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

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

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

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

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

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

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

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

Function: tlocation INSTANCE

Accesses the location or position component of the transform.

See TRANSFORM (type)

Package

org.shirakumo.flare.transform

Source

struct.lisp (file)

Writer

(setf tlocation) (function)

Function: (setf tlocation) VALUE INSTANCE
Package

org.shirakumo.flare.transform

Source

struct.lisp (file)

Reader

tlocation (function)

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

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

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

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

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

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

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

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

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

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

Function: trotation INSTANCE

Accesses the rotational component of the transform.

See TRANSFORM (type)

Package

org.shirakumo.flare.transform

Source

struct.lisp (file)

Writer

(setf trotation) (function)

Function: (setf trotation) VALUE INSTANCE
Package

org.shirakumo.flare.transform

Source

struct.lisp (file)

Reader

trotation (function)

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

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

Function: tscaling INSTANCE

Accesses the scaling component of the transform.

See TRANSFORM (type)

Package

org.shirakumo.flare.transform

Source

struct.lisp (file)

Writer

(setf tscaling) (function)

Function: (setf tscaling) VALUE INSTANCE
Package

org.shirakumo.flare.transform

Source

struct.lisp (file)

Reader

tscaling (function)

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


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 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 (file)

Direct superclasses

structure-object (structure)

Direct methods
  • make-load-form (method)
  • print-object (method)
Direct slots
Slot: location
Type

3d-vectors:vec3

Readers

tlocation (function)

Writers

(setf tlocation) (function)

Slot: scaling
Type

3d-vectors:vec3

Readers

tscaling (function)

Writers

(setf tscaling) (function)

Slot: rotation
Type

org.shirakumo.flare.quaternion:quat

Readers

trotation (function)

Writers

(setf trotation) (function)


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

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: tdquat A &optional DQ
Package

org.shirakumo.flare.transform

Source

ops.lisp (file)

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


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   3  
F   L  
Index Entry  Section

3
3d-transforms.asd: The 3d-transforms․asd file
3d-transforms/documentation.lisp: The 3d-transforms/documentation․lisp file
3d-transforms/ops.lisp: The 3d-transforms/ops․lisp file
3d-transforms/package.lisp: The 3d-transforms/package․lisp file
3d-transforms/struct.lisp: The 3d-transforms/struct․lisp file

F
File, Lisp, 3d-transforms.asd: The 3d-transforms․asd file
File, Lisp, 3d-transforms/documentation.lisp: The 3d-transforms/documentation․lisp file
File, Lisp, 3d-transforms/ops.lisp: The 3d-transforms/ops․lisp file
File, Lisp, 3d-transforms/package.lisp: The 3d-transforms/package․lisp file
File, Lisp, 3d-transforms/struct.lisp: The 3d-transforms/struct․lisp file

L
Lisp File, 3d-transforms.asd: The 3d-transforms․asd file
Lisp File, 3d-transforms/documentation.lisp: The 3d-transforms/documentation․lisp file
Lisp File, 3d-transforms/ops.lisp: The 3d-transforms/ops․lisp file
Lisp File, 3d-transforms/package.lisp: The 3d-transforms/package․lisp file
Lisp File, 3d-transforms/struct.lisp: The 3d-transforms/struct․lisp file

Jump to:   3  
F   L  

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

A.2 Functions

Jump to:   (  
C   F   N   T  
Index Entry  Section

(
(setf tlocation): Exported functions
(setf trotation): Exported functions
(setf tscaling): Exported functions

C
copy-transform: Exported functions

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

N
nt+: Exported functions

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

Jump to:   (  
C   F   N   T  

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

A.3 Variables

Jump to:   L   R   S  
Index Entry  Section

L
location: Exported structures

R
rotation: Exported structures

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

Jump to:   L   R   S  

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

A.4 Data types

Jump to:   3  
O   P   S   T  
Index Entry  Section

3
3d-transforms: The 3d-transforms system

O
org.shirakumo.flare.transform: The org․shirakumo․flare․transform package

P
Package, org.shirakumo.flare.transform: The org․shirakumo․flare․transform package

S
Structure, transform: Exported structures
System, 3d-transforms: The 3d-transforms system

T
transform: Exported structures

Jump to:   3  
O   P   S   T