| Title: | Support for Orientation Data |
|---|---|
| Description: | Representations, conversions and display of orientation SO(3) data. See the orientlib help topic for details. |
| Authors: | Duncan Murdoch |
| Maintainer: | Duncan Murdoch <[email protected]> |
| License: | GPL |
| Version: | 0.10.5 |
| Built: | 2024-10-23 05:45:25 UTC |
| Source: | https://github.com/dmurdoch/orientlib |
Draws a stylized sailboat to represent an orientation.
boat3d(orientation, x = 1:length(orientation), y = 0, z = 0, scale = 0.25, col = 'red', add = FALSE, box = FALSE, axes = TRUE, graphics = c('rgl', 'scatterplot3d'), ...)boat3d(orientation, x = 1:length(orientation), y = 0, z = 0, scale = 0.25, col = 'red', add = FALSE, box = FALSE, axes = TRUE, graphics = c('rgl', 'scatterplot3d'), ...)
orientation |
An |
x, y, z
|
Coordinates where boats should be shown. |
scale |
Size of boats |
col |
Colour of boats |
add |
Context in which to continue drawing, or |
box |
Whether to draw a box around the plot |
axes |
Whether to draw axes |
graphics |
Which graphics package to use |
... |
Additional graphics parameters; see Details below |
For the identity orientation, the sailboats will be shown upright. Other orientations are shown as rotations of this glyph.
The (x,y,z) coordinate appears in the middle of the sail, at the top of the gunwales of the boat.
If the rgl package is
installed, it will be used to draw solid faces on the boats which can be moved by the
user. If not, but the scatterplot3d package is
installed, it will be used to draw fixed wireframe boats. This
search order can be changed by modifying the graphics parameter.
Additional graphics parameters may be passed. If scatterplot3d is used, these
are passed to the scatterplot3d function (and ignored
when adding to an existing plot). Extra parameters are not passed to
rgl.
To add to a scatterplot3d plot, you must pass the
return value from the initial plot as the value of add. See
the orientlm function for an example.
A current
plot number for rgl, or a scatterplot3d
drawing context. In any case, an attribute named graphics is added
to indicate the drawing device type.
Requires the rgl or
scatterplot3d package.
Duncan Murdoch
x <- eulerzyx(psi=c(0,pi/4,0,0), theta=c(0,0,pi/4,0), phi=c(0,0,0,pi/4)) # Need a 3D renderer; assume scatterplot3d, but others could be used s <- boat3d(x, 0:3, axes = FALSE, graphics = 'scatterplot3d') text(s$xyz.convert(0:3, rep(-0.5,4), rep(-0.5,4)), label = c('Id','z','y','x')) ## Not run: # if the rgl package is installed, this code will work boat3d(x, 0:3, axes = FALSE, graphics = 'rgl') rgl::bbox3d(xat=0:3,xlab=c('Id','z','y','x'),yat=1,zat=1,color='grey') ## End(Not run)x <- eulerzyx(psi=c(0,pi/4,0,0), theta=c(0,0,pi/4,0), phi=c(0,0,0,pi/4)) # Need a 3D renderer; assume scatterplot3d, but others could be used s <- boat3d(x, 0:3, axes = FALSE, graphics = 'scatterplot3d') text(s$xyz.convert(0:3, rep(-0.5,4), rep(-0.5,4)), label = c('Id','z','y','x')) ## Not run: # if the rgl package is installed, this code will work boat3d(x, 0:3, axes = FALSE, graphics = 'rgl') rgl::bbox3d(xat=0:3,xlab=c('Id','z','y','x'),yat=1,zat=1,color='grey') ## End(Not run)
Coercion methods are provided between all types of orientation
objects, and from matrices to the orientation classes.
Creates an eulerzxz-class object.
eulerzxz(phi, theta, psi)eulerzxz(phi, theta, psi)
phi |
Rotation about Z axis |
theta |
Rotation about X axis |
psi |
Further rotation about Z axis |
The rotations are expressed in radians and applied in the order Z, X, Z.
If theta and psi are missing, phi is taken to be an n x 3 matrix
(or 3 element vector) holding all 3 Euler angles; alternatively, it may be an orientation object.
An eulerzxz-class object.
Duncan Murdoch
eulerzxz-class, eulerzyx-class, rotmatrix, rotvector, quaternion,
skewvector, skewmatrix
x <- eulerzxz(c(1,0,0), c(0,1,0), c(0,0,1)) x rotmatrix(x)x <- eulerzxz(c(1,0,0), c(0,1,0), c(0,0,1)) x rotmatrix(x)
Creates an eulerzyx-class object.
eulerzyx(psi, theta, phi)eulerzyx(psi, theta, phi)
psi |
Rotation about Z axis |
theta |
Rotation about Y axis |
phi |
Rotation about X axis |
The rotations are expressed in radians and applied in the order Z, Y, X.
If theta and phi are missing, psi is taken to be an n x 3 matrix
(or 3 element vector) holding all 3 Euler angles; alternatively, any orientation object
may be used.
An eulerzyx-class object.
Duncan Murdoch
eulerzyx-class, rotmatrix, rotvector, quaternion,
skewvector, skewmatrix
x <- eulerzyx(c(1,0,0), c(0,1,0), c(0,0,1)) x rotmatrix(x)x <- eulerzyx(c(1,0,0), c(0,1,0), c(0,0,1)) x rotmatrix(x)
Methods are defined for indexing all types of orientations.
Single bracket indexing (e.g. x[1:3]) creates a new
orientation object of the same class as the original by selecting the
appropriate entries. Double bracket indexing (e.g. x[[3]]) extracts
the chosen data as a matrix or vector, depending on the class of the orientation.
The generic length() function has methods
for orientations; it counts the number of orientations in the
object.
An orientation represented by 3 x 3 SO(3) matrices or 3 x 3 skew symmetric matrices
Objects can be created by calls of the form rotmatrix(x)
or skewmatrix(x).
The objects store the matrices in a 3 x 3 x n array.
x:3 x 3 x n array holding the matrices.
Class "orientation", directly.
Class "vector", by class "orientation".
Extract or assign to subvector
Extract or assign to an entry
The length of the orientation vector
Coerce methods are defined to convert all orientation descendants
from one to another, and to coerce an appropriately shaped matrix or array to a rotmatrix
Duncan Murdoch
orientation-class, vector-classes, rotmatrix,
skewmatrix
x <- rotmatrix(matrix(c(1,0,0, 0,1,0, 0,0,1), 3, 3)) x skewmatrix(x)x <- rotmatrix(matrix(c(1,0,0, 0,1,0, 0,0,1), 3, 3)) x skewmatrix(x)
Methods are defined for matrix multiplication %*%
transposition t(), and real powers ^. These operate on the orientations
term by term.
The mean function.
the standard mean function
find the nearest SO(3) matrix to the mean rotmatrix-class
representation of the orientations
Converts arbitrary 3 x 3 matrices into the nearest SO(3) or orthogonal matrix.
nearest.SO3(x) nearest.orthog(x)nearest.SO3(x) nearest.orthog(x)
x |
3 x 3 matrices stored in a 3 x 3 x n array) |
Uses Stephens' (1979) algorithm to find the nearest (in entry-wise Euclidean sense) SO(3) or orthogonal matrix to a given matrix.
nearest.SO3 produces an orientation-class object holding the closest orientations.
nearest.orthog produces a 3 x 3 x n array of orthogonal matrices.
Duncan Murdoch
Stephens (1979). Vector correlation. Biometrika 66, 41-48.
x <- matrix(rnorm(9), 3,3) nearest.orthog(x) nearest.SO3(x) x <- -x nearest.orthog(x) nearest.SO3(x)x <- matrix(rnorm(9), 3,3) nearest.orthog(x) nearest.SO3(x) x <- -x nearest.orthog(x) nearest.SO3(x)
Abstract class for vectors of various representations of SO(3) (orientation) objects.
A virtual Class: No objects may be created from it.
Methods are defined to coerce orientation objects to any
concrete descendant class.
%*%Matrix multiplication acts on orientation objects
component by component, producing compositions of the rotations.
^An orientation is raised to a power by multiplying its component rotation angles by that power.
The transpose of an orientation object is its
component by component inverse.
The mean of an orientation object is the nearest SO(3) matrix to
the element-by-element mean of its 3 x 3 rotation matrix representation.
The weighted mean, defined analogously to the mean.
Duncan Murdoch
matrix-classes, vector-classes
x <- rotmatrix(diag(3)) x rotvector(x) eulerzyx(x) eulerzxz(x) quaternion(x)x <- rotmatrix(diag(3)) x rotvector(x) eulerzyx(x) eulerzxz(x) quaternion(x)
Representations, conversions and display of orientation data.
This package contains methods for working with orientation data, i.e.
data from SO(3). The basic abstract class is the orientation;
there are several concrete classes (rotmatrix,
rotvector, eulerzyx, eulerzxz,
quaternion, skewmatrix and skewvector)
storing different
representations of orientations.
Methods are defined to get the length of a vector of orientations, as well as to extract and replace elements, and to multiply orientations and raise them to real powers.
There are also utility functions rotation.distance,
rotation.angle, nearest.orthog,
nearest.SO3.
There is a plotting method boat3d to display orientation data
in a 3D plot, and a linear modelling function orientlm.
Plots require either the rgl
or scatterplot3d package.
Duncan Murdoch
Regression models for matched pairs of orientations.
orientlm(observed, leftformula, trueorient = rotmatrix(diag(3)), rightformula, data = list(), subset, weights, na.action, iterations = 5)orientlm(observed, leftformula, trueorient = rotmatrix(diag(3)), rightformula, data = list(), subset, weights, na.action, iterations = 5)
observed |
Observed orientations |
leftformula |
Formula for “left” model (see below) |
trueorient |
“True” orientation (see below) |
rightformula |
Formula for “right” model (see below) |
data |
Optional data frame for predictors in linear model |
subset |
Optional logical vector indicating subset of data |
weights |
Optional weights |
na.action |
Optional NA function for predictors |
iterations |
How many iterations to use. Ignored unless both
|
The Prentice (1989) model for matched pairs of orientations was
where is the observed orientation, and are orientation matrices,
and is the “true” orientation, and is a constant. It was assumed that
errors were symmetrically distributed about the identity matrix.
This function generalizes this model, allowing and to depend on
regressor variables through leftformula and rightformula respectively.
These formulas should include the predictor variables (right hand side) only, e.g. use
~ x + y + z rather than response ~ x + y + z. Specify the response using
the observed argument. If
both formulas are ~ 1, i.e. intercepts only, then Prentice's original model is
recovered. More general models are fit by coordinatewise linear regression in the rotmatrix
representation of the orientation, with fitted values projected onto SO(3) using the
nearest.SO3 function.
When both left and right models are given, Prentice's iterative approach is used with a fixed number of iterations. Note that Shin (1999) found that Prentice's scheme sometimes fails to find the global minimum; this function presumably suffers from the same failing.
Returns a list containing the following components:
leftfit |
Result of |
rightfit |
Result of |
A1 |
Fitted values of |
A2 |
Fitted values of |
predict |
Fitted values of |
Duncan Murdoch
Prentice, M.J. (1989). Spherical regression on matched pairs of orientation statistics. JRSS B 51, 241-248.
Shin, H.S.H. (1999). Experimental Design for Orientation Models. PhD thesis, Queen's University.
x <- rep(1:10,10) y <- rep(1:10,each=10) A1 <- skewvector(cbind(x/10,y/10,rep(0,100))) A2 <- skewvector(c(1,1,1)) trueorientation <- skewvector(matrix(rnorm(300),100)) noise <- skewvector(matrix(rnorm(300)/10,100)) obs <- t(A1) %*% trueorientation %*% A2 %*% noise fit <- orientlm(obs, ~ x + y, trueorientation, ~ 1) context <- boat3d(A1, x, z=y, col = 'green', graphics='scatterplot3d') boat3d(fit$A1, x, z=y, add=context)x <- rep(1:10,10) y <- rep(1:10,each=10) A1 <- skewvector(cbind(x/10,y/10,rep(0,100))) A2 <- skewvector(c(1,1,1)) trueorientation <- skewvector(matrix(rnorm(300),100)) noise <- skewvector(matrix(rnorm(300)/10,100)) obs <- t(A1) %*% trueorientation %*% A2 %*% noise fit <- orientlm(obs, ~ x + y, trueorientation, ~ 1) context <- boat3d(A1, x, z=y, col = 'green', graphics='scatterplot3d') boat3d(fit$A1, x, z=y, add=context)
Creates a quaternion-class object.
quaternion(m)quaternion(m)
m |
n x 4 matrix or 4 element vector containing a unit quaternion, or an orientation object |
The rows of m are 4 element unit vectors interpreted as
follows: the first 3 (x,y,z) define the axis of rotation,
and the last element gives the cosine of half the angle of
rotation in a counter-clockwise direction when looking down the
axis towards the origin.
A quaternion-class object.
Duncan Murdoch
quaternion-class, rotmatrix, rotvector, eulerzyx,
eulerzxz, skewvector, skewmatrix
x <- quaternion(c(1,0,0,0)) x rotmatrix(x)x <- quaternion(c(1,0,0,0)) x rotmatrix(x)
Calculates the angle (in radians) of the rotation taking one orientation to another.
rotation.angle(x) rotation.distance(x, y)rotation.angle(x) rotation.distance(x, y)
x, y
|
Two orientation objects |
If y is missing in a call to rotation.distance,
it is treated as the identity, i.e.
rotation.angle(x) is calculated.
rotation.distance returns a vector of length max(length(x), length(y))
containing the
angle of the rotation taking corresponding elements of x to y (with the
usual recycling rules if they are different lengths).
rotation.angle is equivalent to calculating the rotation.distance to the
identity matrix.
Duncan Murdoch
orientation-class, rotation.angle
rotation.angle(eulerzyx(1,0,0)) rotation.distance(eulerzyx(1,0,0), eulerzyx(0,1,0))rotation.angle(eulerzyx(1,0,0)) rotation.distance(eulerzyx(1,0,0), eulerzyx(0,1,0))
Creates a rotmatrix-class object.
rotmatrix(a)rotmatrix(a)
a |
A 3 x 3 matrix or 3 x 3 x n array of matrices or an orientation object. |
A rotmatrix-class object.
Duncan Murdoch
rotmatrix-class, rotvector, eulerzyx,
eulerzxz, quaternion, skewvector, skewmatrix
x <- rotmatrix(matrix(c(1,0,0, 0,1,0, 0,0,1), 3, 3)) xx <- rotmatrix(matrix(c(1,0,0, 0,1,0, 0,0,1), 3, 3)) x
Creates a rotvector-class object.
rotvector(m)rotvector(m)
m |
n x 9 matrix or 9 element vector whose rows are vectorized 3x3 matrices, or an orientation object. |
Converts a matrix whose rows are vectorized 3x3 matrices (in column-major form)
into an rotvector-class object.
A rotvector-class object.
Duncan Murdoch
rotvector-class, rotmatrix, eulerzyx,
eulerzxz, quaternion, skewvector, skewmatrix
x <- rotvector(c(0,1,0,-1,0,0,0,0,1)) x rotmatrix(x)x <- rotvector(c(0,1,0,-1,0,0,0,0,1)) x rotmatrix(x)
Creates a skewmatrix-class object.
skewmatrix(a)skewmatrix(a)
a |
3 x 3 x n array or 3 x 3 matrix containing the entries of a skew-symmetric matrix, or an orientation object. |
The entries a[,,i] are 3 x 3 skew-symmetric matrices.
The matrix exponential of these give SO(3) matrices.
A skewmatrix-class object.
Duncan Murdoch
skewvector-class, skewvector, rotmatrix, rotvector, eulerzyx,
eulerzxz, quaternion
x <- skewmatrix(matrix(c(0,1,2,-1,0,3,-2,-3,0),3,3)) x rotmatrix(x) skewvector(x) rotation.angle(x)x <- skewmatrix(matrix(c(0,1,2,-1,0,3,-2,-3,0),3,3)) x rotmatrix(x) skewvector(x) rotation.angle(x)
Creates a skewvector-class object.
skewvector(m)skewvector(m)
m |
n x 3 matrix or 3 element vector containing a the entries of a skew-symmetric matrix, or an orientation object. |
The rows of m are 3 element vectors (x,y,z) interpreted as
follows: the matrix exponential of the matrix ((0, -z, y), (z, 0, -x), (-y, x, 0))
is the SO(3) matrix.
A skewvector-class object.
Duncan Murdoch
skewvector-class, skewmatrix, rotmatrix, rotvector, eulerzyx,
eulerzxz, quaternion
x <- skewvector(c(1,0,0)) x rotmatrix(x) rotation.angle(x)x <- skewvector(c(1,0,0)) x rotmatrix(x) rotation.angle(x)
An vector of orientations, each represented by a vector of numbers.
Each of these types stores orientations as rows of a matrix in slot x.
The eulerzyx class uses 3 Euler angles in the roll-pitch-yaw scheme
(rotation about Z axis, then Y axis, then X axis).
The eulerzxz class uses 3 Euler angles in the X system scheme
(rotation about Z axis, then X axis, then Z axis again).
The rotvector class uses the 9 components of a 3 x 3 rotation matrix, stored
in column-major order.
The quaternion class uses the 4 components of a unit quaternion.
The skewvector class uses the 3 non-zero components of a skew-symmetric matrix,
where (x,y,z) stores the matrix ((0, -z, y), (z, 0, -x), (-y, x, 0)).
Objects of each class can be created by calls to the corresponding constructor
functions: eulerzyx, eulerzxz, rotvector,
quaternion, skewmatrix and skewvector.
x:An n x m matrix object holding the vector representations, where
m is 3, 4, or 9.
Class "orientation", directly.
Class "vector", by class "orientation".
Extract or assign to subvector
Extract or assign to an entry
The length of the orientation vector
Coerce methods are defined to convert all orientation descendants
from one to another, and to coerce an appropriately shaped matrix or array to a rotmatrix
Duncan Murdoch
Constructor and coercion functions rotmatrix, eulerzyx, eulerzxz, rotvector,
quaternion, and skewvector.
Classes matrix-classes, orientation-class.
x <- eulerzyx(0,pi/4,0) x eulerzxz(x) rotmatrix(x) rotvector(x) quaternion(x) skewvector(x)x <- eulerzyx(0,pi/4,0) x eulerzxz(x) rotmatrix(x) rotvector(x) quaternion(x) skewvector(x)
The weighted mean function.
The weighted mean for orientations is the nearest SO(3) matrix to the entrywise weighted mean
of the rotmatrix-class matrices.
the standard stats::weighted.mean
weighted mean for orientations