Rotation of 3d objects — rotate,matrix-method • icosa

Multiple implementations of rotations for coordinate transformation.

Usage

# S4 method for class 'matrix'
rotate(
  x,
  angles = "random",
  long = 0,
  lat = 0,
  reflong = NULL,
  pivot = c(0, 0, 0),
  radius = authRadius,
  output = "polar"
)

# S4 method for class 'data.frame'
rotate(x, coords = NULL, ...)

rotate

# S4 method for class 'trigrid'
rotate(x, angles = "random", pivot = NA, projnote = TRUE)

Format

An object of class standardGeneric of length 1.

Arguments

x: (matrix, trigrid, hexagrid) Input coordinates or grid.
angles: (numeric): The vector of rotation in radians (three values in each dimension). If set to "random", the rotation will be random (default). Rotations are executed in X-Y-Z order.
long: (numeric) Rotation in degrees longitude. If given, angles will be ignored. (see Method 2 description for details!)
lat: (numeric) Rotation in degrees latitude at reflong. If given, angles will be ignored. (see Method 2 description for details!)
reflong: (numeric) Reference longitude. If not given it will default to the centroid of the points as given by surfacecentroid. (see Method 2 description for details!)
pivot: (numeric): The pivot point of the rotation, vector of xyz coordinates. For trigrid-methods it defaults to NA indicating that the rotation will be around the center of the grid.
radius: The radius of the sphere, relevant only if the output="cartesian" and x is a longitude-latitude matrix.
output: The output format of the rotations, either "polar" or cartesian.
coords: (character) Rotation in degrees longitude. If given, angles will be ignored. (see Method 2 description for details!)
...: Arguments passed to class-specific methods.
projnote: (logical): Should messages be shown to remind users to regenerate grid projections with 'sf' and 'sp'?

Value

Same class object as x.

Details

The function implements 3D rotations of various class of objects, that are ultimately reduced to individual points. Internally, point rotation is implemented with 3-axis rotations (Method 1), that are implemented in the X-Y-Z order (note that 3d rotations are not commutative!). For this reason it is not recommended to re-rotate an already rotated object, unless the purpose is to achieve random orientation.

Method 2 parametrizes rotation with three arguments (long, lat, reflong), that can be easier to control. Longitudinal rotations are invariant to the position of the object, but latitudinal rotation is not. An axis in the equatorial plane will be set perpendicular to the reference longitude (reflong)for latitude-based rotation (i.e. the latitude difference will equal the latitudinal rotation value only at the reference longitude). If this is not given, then the reference longitude will be that of the centroid of the point cloud. Note that latitudinal rotation is executed first and only then are the points rotated longitudinally.